@homeostate/core

Sync engine that keeps a store in sync with a CRDT document. Pair it with a store adapter (@homeostate/store-*) and a CRDT backend such as @homeostate/crdt-yjs.

Install

npm install @homeostate/core @homeostate/crdt-yjs yjs

Usage

import { createSyncEngine } from "@homeostate/core";
import { createYjsBackend } from "@homeostate/crdt-yjs";

const engine = createSyncEngine(createYjsBackend(doc, "shared"), adapter, {
  omit: ["draft"],
  seed: "if-empty",
});
engine.connect();

omit keeps the keys it names on this device; functions stay local by default. On connect(), keys the backend already holds win over the store's values, so a peer joining a populated room adopts it. Keys only the store has are written to the backend (seed: "if-empty", the default) or left for the next local change (seed: "never"). A reconnect adopts the backend again, so edits made while disconnected to keys it holds are dropped.

Remote changes are applied to the store as they arrive. Pass schedule: (flush) => queueMicrotask(flush) to apply a burst of them with one store update.

createPersistence keeps the CRDT document in browser storage so it survives reloads; see the persistence guide. @homeostate/core/testing exports in-memory doubles for tests.

See Concepts for the full connect rules and the documentation for the options and for writing a custom backend.

License

MIT — see LICENSE. Includes code derived from zustand-middleware-yjs; see THIRD_PARTY_NOTICES.md.