@aws-amplify/datastore

INTERNAL USE ONLY

This package contains the AWS Amplify DataStore category and is intended for internal use only. To integrate Amplify into your app, please use aws-amplify.

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

Similar packages

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.