README.md

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)]

Loading

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;

Loading

---

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