@aws-amplify/datastore

What is @aws-amplify/datastore?

@aws-amplify/datastore is a library that provides a programming model for leveraging shared and distributed data without writing additional code for offline and online scenarios. It is part of the AWS Amplify framework and is designed to work seamlessly with AWS AppSync for real-time and offline-first data access.

What are @aws-amplify/datastore's main functionalities?

Model Definition

Defines the data model schema for the application. This is the first step in setting up DataStore, where you define the structure of your data.

const { initSchema } = require('@aws-amplify/datastore');
const { schema } = require('./schema');

const { Post } = initSchema(schema);

CRUD Operations

Provides basic CRUD (Create, Read, Update, Delete) operations for interacting with the data models. This allows developers to easily manage their data.

const { DataStore } = require('@aws-amplify/datastore');

// Create
await DataStore.save(new Post({ title: 'New Post', content: 'This is a new post' }));

// Read
const posts = await DataStore.query(Post);

// Update
const original = await DataStore.query(Post, '123');
await DataStore.save(Post.copyOf(original, updated => {
  updated.title = 'Updated Title';
}));

// Delete
await DataStore.delete(Post, '123');

Real-time and Offline Sync

Enables real-time data synchronization and offline capabilities. DataStore automatically syncs data between the local store and the cloud, ensuring data consistency.

const { DataStore } = require('@aws-amplify/datastore');

DataStore.observe(Post).subscribe(msg => {
  console.log(msg.model, msg.opType, msg.element);
});

Conflict Resolution

Handles conflict resolution when data changes occur both locally and in the cloud. Developers can define custom conflict resolution strategies.

const { DataStore, syncExpression } = require('@aws-amplify/datastore');

DataStore.configure({
  syncExpressions: [
    syncExpression(Post, () => {
      return post => post.status('eq', 'published');
    })
  ]
});

Other packages similar to @aws-amplify/datastore

redux-persist

redux-persist is a library that allows you to save the Redux store in persistent storage, such as local storage. It provides offline capabilities but lacks the real-time synchronization and conflict resolution features of @aws-amplify/datastore.

dexie

Dexie is a wrapper for IndexedDB, providing a more straightforward API for managing local databases. While it offers offline storage, it does not provide built-in real-time synchronization or integration with cloud services like @aws-amplify/datastore.

pouchdb

PouchDB is an open-source JavaScript database that syncs with CouchDB. It offers offline-first capabilities and real-time synchronization, similar to @aws-amplify/datastore, but requires a CouchDB server for cloud synchronization.

README

AWS Amplify DataStore Docs

Amplify DataStore provides a programming model for leveraging shared and distributed data without writing additional code for offline and online scenarios, which makes working with distributed, cross-user data just as simple as working with local-only data.

---

package	version	open issues	closed issues
@aws-amplify/datastore

---

👋 Note For Contributers: 👋

Please update these docs any time you find something that is incorrect or lacking. In particular, if a line in the docs prompts a question, take a moment to figure out the answer, then update the docs with the necessary detail.

---

Getting Started

Before you start reading through these docs, take a moment to understand how DataStore works at a high level. Additionally, we recommend first reading through docs.amplify.aws. The purpose of these docs is to dive deep into the codebase itself and understand the inner workings of DataStore for the purpose of contributing. Understanding these docs is not necessary for using DataStore. Lastly, before reading, take a look at the diagrams below.

---

Docs

• Conflict Resolution
• Contributing
• DataStore Lifecycle Events ("Start", "Stop", "Clear")
  • This explains how DataStore fundementally works, and is a great place to start.
• Getting Started (Running against a sample app, etc.)
• Namespaces
• How DataStore uses Observables
• Schema Changes
• Storage
• Sync Engine
• "Unsupported hacks" / workarounds

---

Diagrams

Note: relationships with dotted lines are explained more in a separate diagram.

How the DataStore API and Storage Engine Interact

flowchart TD
  %% API and Storage
  api[[DS API]]-- observe -->storage{Storage Engine}
  storage-- next -->adapter[[Adapter]]
  adapter-->db[[Local DB]]
  db-->api
  sync[[Sync Engine*]]-.-storage
  sync-.-appSync[(AppSync)]

How the Sync Engine Observes Changes in Storage and AppSync

Note: All green nodes belong to the Sync Engine.

* Merger first checks outbox

** Outbox sends outgoing messages to AppSync

flowchart TD

  subgraph SyncEngine
  index{index.ts}-- observe -->reach[Core reachability]

  subgraph processors
  mp[Mutation Processor]
  sp[Subscription Processor]
  syp[Sync Processor]
  end

  reach--next-->mp[Mutation Processor]
  reach--next-->sp[Subscription Processor]
  reach--next-->syp[Sync Processor]

  subgraph outbox / merger
  outbox[Outbox]
  merger[Merger]
  outbox---merger
  end

  end

  api[DS API]-.->storage
  mp-- 1. observe -->storage{Storage Engine}
  storage-- 2. next -->merger[merger*]-- next -->storage


  sp-- observe -->appsync[(AppSync)]
  appsync-- next -->sp

  syp---appsync

  mp-->outbox[outbox**]

  appsync<--->outbox
  %% styling
  classDef syncEngineClass fill:#8FB,stroke:#333,stroke-width:4px,color:#333;
  class index,mp,sp,syp,merger,outbox syncEngineClass;

---

Project Structure

amplify-js/packages/datastore/src
├── authModeStrategies
│   └── defaultAuthStraegy.ts
│   └── index.ts
│   └── multiAuthStrategy.ts
├── datastore
│   └── datastore.ts # Entry point for DataStore
├── predicates
│   └── index.ts
│   └── sort.ts
├── ssr
├── storage # Storage Engine
│   └── adapter # Platform-specific Storage Adapters
│      └── getDefaultAdapter
│      └── AsyncStorageAdapter.ts
│      └── AsyncStorageDatabase.ts
│      └── index.ts
│      └── IndexedDBAdapter.ts
│      └── InMemoryStore.native.ts
│      └── InMemoryStore.ts
│   └── storage.ts # Entry point for Storage
├── sync # Sync Engine
│   └── dataStoreReachability
│      └── index.native.ts
│      └── index.ts
│   └── processors # Sync Engine Processors
│      └── mutation.ts
│      └── subscription.ts
│      └── sync.ts
│   └── datastoreConnectivity.ts # Subscribe to reachability monitor
│   └── index.ts # Entry point for Sync Engine
│   └── merger.ts # doc
│   └── outbox.ts # doc

---

Other Resources:

• High-level overview of how DataStore works
• DataStore Docs
• re:Invent talk