@mindees/data 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { Clock, ClockOptions, Hlc, compareHlc, createClock, decodeHlc, encodeHlc
 import { LwwMap, LwwRegister, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, mergeLwwMap, mergeRegister } from "./lww.js";
 import { OrSet, emptyOrSet, mergeOrSet, orAdd, orHas, orRemove, orValues } from "./or-set.js";
 import { Cursor, MutationLog, Op, SyncEngine, SyncEngineOptions, SyncSnapshot, SyncTransport, createMemoryHub, createMutationLog, createSyncEngine } from "./sync.js";
-import { Persistence, PersistentEngineOptions, WebStorageLike, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine } from "./persist.js";
+import { IndexedDbFactoryLike, IndexedDbPersistenceOptions, Persistence, PersistentEngineOptions, WebStorageLike, createIndexedDbPersistence, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine } from "./persist.js";
 import { VersionVector, vvDominates, vvEquals, vvGet, vvMerge, vvObserve } from "./version-vector.js";
 import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@mindees/core";
 
@@ -13,7 +13,7 @@ import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@min
 /** The npm package name. */
 declare const name = "@mindees/data";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-declare const VERSION = "0.20.0";
+declare const VERSION = "0.22.0";
 /** Current maturity of this package. See the repository `STATUS.md`. */
 declare const maturity: Maturity;
 /**
@@ -23,5 +23,5 @@ declare const maturity: Maturity;
  */
 declare const info: PackageInfo;
 //#endregion
-export { type Clock, type ClockOptions, type Collection, type CollectionOptions, type Counter, type Cursor, DataError, type DataErrorCode, type Hlc, type Id, type LwwMap, type LwwRegister, type Maturity, type MutationLog, NotImplementedError, type Op, type OptimisticChange, type OrSet, type PackageInfo, type Persistence, type PersistentEngineOptions, type SyncEngine, type SyncEngineOptions, type SyncSnapshot, type SyncTransport, VERSION, type VersionVector, type WebStorageLike, compareHlc, counterDec, counterInc, counterValue, createClock, createCollection, createMemoryHub, createMemoryPersistence, createMutationLog, createPersistentEngine, createSyncEngine, createWebStoragePersistence, decodeHlc, emptyCounter, emptyOrSet, encodeHlc, info, loadSnapshot, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeCounter, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, persistEngine, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
+export { type Clock, type ClockOptions, type Collection, type CollectionOptions, type Counter, type Cursor, DataError, type DataErrorCode, type Hlc, type Id, type IndexedDbFactoryLike, type IndexedDbPersistenceOptions, type LwwMap, type LwwRegister, type Maturity, type MutationLog, NotImplementedError, type Op, type OptimisticChange, type OrSet, type PackageInfo, type Persistence, type PersistentEngineOptions, type SyncEngine, type SyncEngineOptions, type SyncSnapshot, type SyncTransport, VERSION, type VersionVector, type WebStorageLike, compareHlc, counterDec, counterInc, counterValue, createClock, createCollection, createIndexedDbPersistence, createMemoryHub, createMemoryPersistence, createMutationLog, createPersistentEngine, createSyncEngine, createWebStoragePersistence, decodeHlc, emptyCounter, emptyOrSet, encodeHlc, info, loadSnapshot, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeCounter, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, persistEngine, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -5,14 +5,14 @@ import { compareHlc, createClock, decodeHlc, encodeHlc } from "./hlc.js";
 import { lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, mergeLwwMap, mergeRegister } from "./lww.js";
 import { emptyOrSet, mergeOrSet, orAdd, orHas, orRemove, orValues } from "./or-set.js";
 import { createMemoryHub, createMutationLog, createSyncEngine } from "./sync.js";
-import { createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine } from "./persist.js";
+import { createIndexedDbPersistence, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine } from "./persist.js";
 import { vvDominates, vvEquals, vvGet, vvMerge, vvObserve } from "./version-vector.js";
 import { NotImplementedError, notImplemented } from "@mindees/core";
 //#region src/index.ts
 /** The npm package name. */
 const name = "@mindees/data";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-const VERSION = "0.20.0";
+const VERSION = "0.22.0";
 /** Current maturity of this package. See the repository `STATUS.md`. */
 const maturity = "experimental";
 /**
@@ -26,6 +26,6 @@ const info = Object.freeze({
 	maturity
 });
 //#endregion
-export { DataError, NotImplementedError, VERSION, compareHlc, counterDec, counterInc, counterValue, createClock, createCollection, createMemoryHub, createMemoryPersistence, createMutationLog, createPersistentEngine, createSyncEngine, createWebStoragePersistence, decodeHlc, emptyCounter, emptyOrSet, encodeHlc, info, loadSnapshot, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeCounter, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, persistEngine, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
+export { DataError, NotImplementedError, VERSION, compareHlc, counterDec, counterInc, counterValue, createClock, createCollection, createIndexedDbPersistence, createMemoryHub, createMemoryPersistence, createMutationLog, createPersistentEngine, createSyncEngine, createWebStoragePersistence, decodeHlc, emptyCounter, emptyOrSet, encodeHlc, info, loadSnapshot, lwwDelete, lwwGet, lwwHas, lwwKeys, lwwSet, maturity, mergeCounter, mergeLwwMap, mergeOrSet, mergeRegister, name, notImplemented, orAdd, orHas, orRemove, orValues, persistEngine, vvDominates, vvEquals, vvGet, vvMerge, vvObserve };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/data` (Continuum) — local-first reactive store + sync.\n *\n * Phase 10 ships the **reactive document store**: {@link createCollection}, a\n * signals-native, in-memory collection with fine-grained reactive reads\n * (`get`/`has`/`all`/`where`/`size`), atomic mutations (`insert`/`upsert`/`update`/\n * `delete`/`clear`/`tx`), and {@link Collection.optimistic optimistic} changes that can\n * be rolled back. Built on `@mindees/core` signals only. Hybrid-logical-clock causality,\n * CRDT conflict resolution, the local-first sync engine, a reference sync server on the\n * `@mindees/data/server` subpath, and a persistence contract/export/restore path build\n * on this. Native durable adapters, production sync hardening, and CRDT-library/rich-text\n * interop remain research tracks.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** The npm package name. */\nexport const name = '@mindees/data'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.20.0'\n\n/** Current maturity of this package. See the repository `STATUS.md`. */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport {\n  type Collection,\n  type CollectionOptions,\n  createCollection,\n  type Id,\n  type OptimisticChange,\n} from './collection'\nexport {\n  type Counter,\n  counterDec,\n  counterInc,\n  counterValue,\n  emptyCounter,\n  mergeCounter,\n} from './counter'\nexport { DataError, type DataErrorCode } from './errors'\nexport {\n  type Clock,\n  type ClockOptions,\n  compareHlc,\n  createClock,\n  decodeHlc,\n  encodeHlc,\n  type Hlc,\n} from './hlc'\nexport {\n  type LwwMap,\n  type LwwRegister,\n  lwwDelete,\n  lwwGet,\n  lwwHas,\n  lwwKeys,\n  lwwSet,\n  mergeLwwMap,\n  mergeRegister,\n} from './lww'\nexport {\n  emptyOrSet,\n  mergeOrSet,\n  type OrSet,\n  orAdd,\n  orHas,\n  orRemove,\n  orValues,\n} from './or-set'\nexport {\n  createMemoryPersistence,\n  createPersistentEngine,\n  createWebStoragePersistence,\n  loadSnapshot,\n  type Persistence,\n  type PersistentEngineOptions,\n  persistEngine,\n  type WebStorageLike,\n} from './persist'\nexport {\n  type Cursor,\n  createMemoryHub,\n  createMutationLog,\n  createSyncEngine,\n  type MutationLog,\n  type Op,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n  type SyncTransport,\n} from './sync'\nexport {\n  type VersionVector,\n  vvDominates,\n  vvEquals,\n  vvGet,\n  vvMerge,\n  vvObserve,\n} from './version-vector'\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;;AAoBA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;AAGvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/data` (Continuum) — local-first reactive store + sync.\n *\n * Phase 10 ships the **reactive document store**: {@link createCollection}, a\n * signals-native, in-memory collection with fine-grained reactive reads\n * (`get`/`has`/`all`/`where`/`size`), atomic mutations (`insert`/`upsert`/`update`/\n * `delete`/`clear`/`tx`), and {@link Collection.optimistic optimistic} changes that can\n * be rolled back. Built on `@mindees/core` signals only. Hybrid-logical-clock causality,\n * CRDT conflict resolution, the local-first sync engine, a reference sync server on the\n * `@mindees/data/server` subpath, and a persistence contract/export/restore path build\n * on this. Native durable adapters, production sync hardening, and CRDT-library/rich-text\n * interop remain research tracks.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** The npm package name. */\nexport const name = '@mindees/data'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.22.0'\n\n/** Current maturity of this package. See the repository `STATUS.md`. */\nexport const maturity: Maturity = 'experimental'\n\n/**\n * Static identity + maturity metadata for this package. Frozen so the\n * self-reported identity tooling introspects cannot be mutated at runtime,\n * matching the `readonly` fields of {@link PackageInfo}.\n */\nexport const info: PackageInfo = Object.freeze({ name, version: VERSION, maturity })\n\nexport {\n  type Collection,\n  type CollectionOptions,\n  createCollection,\n  type Id,\n  type OptimisticChange,\n} from './collection'\nexport {\n  type Counter,\n  counterDec,\n  counterInc,\n  counterValue,\n  emptyCounter,\n  mergeCounter,\n} from './counter'\nexport { DataError, type DataErrorCode } from './errors'\nexport {\n  type Clock,\n  type ClockOptions,\n  compareHlc,\n  createClock,\n  decodeHlc,\n  encodeHlc,\n  type Hlc,\n} from './hlc'\nexport {\n  type LwwMap,\n  type LwwRegister,\n  lwwDelete,\n  lwwGet,\n  lwwHas,\n  lwwKeys,\n  lwwSet,\n  mergeLwwMap,\n  mergeRegister,\n} from './lww'\nexport {\n  emptyOrSet,\n  mergeOrSet,\n  type OrSet,\n  orAdd,\n  orHas,\n  orRemove,\n  orValues,\n} from './or-set'\nexport {\n  createIndexedDbPersistence,\n  createMemoryPersistence,\n  createPersistentEngine,\n  createWebStoragePersistence,\n  type IndexedDbFactoryLike,\n  type IndexedDbPersistenceOptions,\n  loadSnapshot,\n  type Persistence,\n  type PersistentEngineOptions,\n  persistEngine,\n  type WebStorageLike,\n} from './persist'\nexport {\n  type Cursor,\n  createMemoryHub,\n  createMutationLog,\n  createSyncEngine,\n  type MutationLog,\n  type Op,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n  type SyncTransport,\n} from './sync'\nexport {\n  type VersionVector,\n  vvDominates,\n  vvEquals,\n  vvGet,\n  vvMerge,\n  vvObserve,\n} from './version-vector'\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;;AAoBA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;AAGvB,MAAa,WAAqB;;;;;;AAOlC,MAAa,OAAoB,OAAO,OAAO;CAAE;CAAM,SAAS;CAAS;AAAS,CAAC"}

package/dist/persist.d.ts

@@ -44,6 +44,49 @@ interface PersistentEngineOptions<T> extends Omit<SyncEngineOptions<T>, 'snapsho
  * survives restart.
  */
 declare function createPersistentEngine<T>(options: PersistentEngineOptions<T>): Promise<SyncEngine<T>>;
+interface IdbRequestLike<T> {
+  result: T;
+  error: unknown;
+  onsuccess: (() => void) | null;
+  onerror: (() => void) | null;
+}
+interface IdbOpenRequestLike extends IdbRequestLike<IdbDatabaseLike> {
+  onupgradeneeded: (() => void) | null;
+}
+interface IdbObjectStoreLike {
+  get(key: string): IdbRequestLike<unknown>;
+  put(value: string, key: string): IdbRequestLike<unknown>;
+}
+interface IdbTransactionLike {
+  objectStore(name: string): IdbObjectStoreLike;
+}
+interface IdbDatabaseLike {
+  objectStoreNames: {
+    contains(name: string): boolean;
+  };
+  createObjectStore(name: string): unknown;
+  transaction(storeNames: string, mode: 'readonly' | 'readwrite'): IdbTransactionLike;
+}
+/** The minimal IndexedDB factory surface (a structural subset of the DOM `IDBFactory`). */
+interface IndexedDbFactoryLike {
+  open(name: string, version?: number): IdbOpenRequestLike;
+}
+/** Options for {@link createIndexedDbPersistence}. */
+interface IndexedDbPersistenceOptions {
+  /** Database name (default `'mindees'`). */
+  readonly databaseName?: string;
+  /** Object-store name (default `'continuum'`). */
+  readonly storeName?: string;
+  /** The IndexedDB factory; defaults to `globalThis.indexedDB`. Inject (e.g. `fake-indexeddb`) elsewhere. */
+  readonly factory?: IndexedDbFactoryLike;
+}
+/**
+ * A durable {@link Persistence} backed by IndexedDB — large, asynchronous browser storage (beyond
+ * `localStorage`'s synchronous ~5MB cap), a better home for a growing Continuum op log/snapshot. The
+ * database + object store open lazily on first use and are reused. Inject `factory` to run outside a
+ * browser (tests, or a custom environment); throws if none is available.
+ */
+declare function createIndexedDbPersistence(options?: IndexedDbPersistenceOptions): Persistence;
 //#endregion
-export { Persistence, PersistentEngineOptions, WebStorageLike, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine };
+export { IndexedDbFactoryLike, IndexedDbPersistenceOptions, Persistence, PersistentEngineOptions, WebStorageLike, createIndexedDbPersistence, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine };
 //# sourceMappingURL=persist.d.ts.map

package/dist/persist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persist.d.ts","names":[],"sources":["../src/persist.ts"],"mappings":";;;;UAqBiB,WAAA;EAI0B;EAFzC,IAAA,CAAK,GAAA,WAAc,OAAA;EAMkB;EAJrC,IAAA,CAAK,GAAA,UAAa,KAAA,WAAgB,OAAO;AAAA;AAIW;AAAA,iBAAtC,uBAAA,IAA2B,WAAW;;UAYrC,cAAA;EACf,OAAA,CAAQ,GAAA;EACR,OAAA,CAAQ,GAAA,UAAa,KAAA;AAAA;;;;;AAAa;iBAQpB,2BAAA,CAA4B,OAAA,EAAS,cAAA,GAAiB,WAAW;;iBAW3D,YAAA,IACpB,WAAA,EAAa,WAAA,EACb,GAAA,WACC,OAAA,CAAQ,YAAA,CAAa,CAAA;;;;;;AAdyD;AAWjF;iBAqBgB,aAAA,IACd,MAAA,EAAQ,UAAA,CAAW,CAAA,GACnB,WAAA,EAAa,WAAA,EACb,GAAA,WACC,UAAA,CAAW,CAAA;;UA+BG,uBAAA,YAAmC,IAAA,CAAK,iBAAA,CAAkB,CAAA;EArDnD;EAAA,SAuDb,WAAA,EAAa,WAAA;EAvDrB;EAAA,SAyDQ,GAAA;AAAA;;;;;;iBAQW,sBAAA,IACpB,OAAA,EAAS,uBAAA,CAAwB,CAAA,IAChC,OAAA,CAAQ,UAAA,CAAW,CAAA"}
+{"version":3,"file":"persist.d.ts","names":[],"sources":["../src/persist.ts"],"mappings":";;;;UAqBiB,WAAA;EAI0B;EAFzC,IAAA,CAAK,GAAA,WAAc,OAAA;EAMkB;EAJrC,IAAA,CAAK,GAAA,UAAa,KAAA,WAAgB,OAAO;AAAA;AAIW;AAAA,iBAAtC,uBAAA,IAA2B,WAAW;;UAYrC,cAAA;EACf,OAAA,CAAQ,GAAA;EACR,OAAA,CAAQ,GAAA,UAAa,KAAA;AAAA;;;;;AAAa;iBAQpB,2BAAA,CAA4B,OAAA,EAAS,cAAA,GAAiB,WAAW;;iBAW3D,YAAA,IACpB,WAAA,EAAa,WAAA,EACb,GAAA,WACC,OAAA,CAAQ,YAAA,CAAa,CAAA;;;;;;AAdyD;AAWjF;iBAqBgB,aAAA,IACd,MAAA,EAAQ,UAAA,CAAW,CAAA,GACnB,WAAA,EAAa,WAAA,EACb,GAAA,WACC,UAAA,CAAW,CAAA;;UA+BG,uBAAA,YAAmC,IAAA,CAAK,iBAAA,CAAkB,CAAA;EArDnD;EAAA,SAuDb,WAAA,EAAa,WAAA;EAvDrB;EAAA,SAyDQ,GAAA;AAAA;;;;;;iBAQW,sBAAA,IACpB,OAAA,EAAS,uBAAA,CAAwB,CAAA,IAChC,OAAA,CAAQ,UAAA,CAAW,CAAA;AAAA,UAaZ,cAAA;EACR,MAAA,EAAQ,CAAC;EACT,KAAA;EACA,SAAA;EACA,OAAA;AAAA;AAAA,UAEQ,kBAAA,SAA2B,cAAc,CAAC,eAAA;EAClD,eAAA;AAAA;AAAA,UAEQ,kBAAA;EACR,GAAA,CAAI,GAAA,WAAc,cAAA;EAClB,GAAA,CAAI,KAAA,UAAe,GAAA,WAAc,cAAc;AAAA;AAAA,UAEvC,kBAAA;EACR,WAAA,CAAY,IAAA,WAAe,kBAAkB;AAAA;AAAA,UAErC,eAAA;EACR,gBAAA;IAAoB,QAAA,CAAS,IAAA;EAAA;EAC7B,iBAAA,CAAkB,IAAA;EAClB,WAAA,CAAY,UAAA,UAAoB,IAAA,6BAAiC,kBAAkB;AAAA;AA7EtE;AAAA,UAgFE,oBAAA;EACf,IAAA,CAAK,IAAA,UAAc,OAAA,YAAmB,kBAAkB;AAAA;;UAIzC,2BAAA;EApDO;EAAA,SAsDb,YAAA;EAxD6C;EAAA,SA0D7C,SAAA;EA1D8B;EAAA,SA4D9B,OAAA,GAAU,oBAAoB;AAAA;;;;;;AAxD3B;iBAiEE,0BAAA,CAA2B,OAAA,GAAS,2BAAA,GAAmC,WAAW"}

package/dist/persist.js

@@ -91,7 +91,41 @@ async function createPersistentEngine(options) {
 		snapshot
 	} : syncOptions), persistence, key);
 }
+/**
+* A durable {@link Persistence} backed by IndexedDB — large, asynchronous browser storage (beyond
+* `localStorage`'s synchronous ~5MB cap), a better home for a growing Continuum op log/snapshot. The
+* database + object store open lazily on first use and are reused. Inject `factory` to run outside a
+* browser (tests, or a custom environment); throws if none is available.
+*/
+function createIndexedDbPersistence(options = {}) {
+	const dbName = options.databaseName ?? "mindees";
+	const storeName = options.storeName ?? "continuum";
+	const factory = options.factory ?? globalThis.indexedDB;
+	if (!factory) throw new Error("createIndexedDbPersistence: IndexedDB is unavailable; pass `factory`.");
+	let dbPromise;
+	const openDb = () => {
+		if (!dbPromise) dbPromise = new Promise((resolve, reject) => {
+			const request = factory.open(dbName, 1);
+			request.onupgradeneeded = () => {
+				const db = request.result;
+				if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName);
+			};
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("IndexedDB open failed"));
+		});
+		return dbPromise;
+	};
+	const run = (mode, op) => openDb().then((db) => new Promise((resolve, reject) => {
+		const request = op(db.transaction(storeName, mode).objectStore(storeName));
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("IndexedDB request failed"));
+	}));
+	return {
+		load: (key) => run("readonly", (store) => store.get(key)).then((value) => value === void 0 || value === null ? null : String(value)),
+		save: (key, value) => run("readwrite", (store) => store.put(value, key)).then(() => void 0)
+	};
+}
 //#endregion
-export { createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine };
+export { createIndexedDbPersistence, createMemoryPersistence, createPersistentEngine, createWebStoragePersistence, loadSnapshot, persistEngine };
 
 //# sourceMappingURL=persist.js.map

package/dist/persist.js.map

@@ -1 +1 @@
-{"version":3,"file":"persist.js","names":[],"sources":["../src/persist.ts"],"sourcesContent":["/**\n * Persistence (10F) — a minimal async key/value capability so a Continuum replica\n * survives restart (mirrors the CLI's `FileSystem` / Pulse's `UpdateStorage`). Persist a\n * sync engine's {@link \"./sync\".SyncEngine.export snapshot} through any `Persistence`\n * and restore it on next launch, so `seq` survives and op ids never collide.\n *\n * `createMemoryPersistence` is the reference; `createWebStoragePersistence` adapts a Web Storage\n * (`localStorage`/`sessionStorage`); {@link persistEngine} wires auto-save + restore so a replica is\n * durable with one call. See `docs/adr/0016-continuum-server-persistence.md`.\n *\n * @module\n */\n\nimport {\n  createSyncEngine,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n} from './sync'\n\n/** A minimal async key/value store for persisting Continuum state. */\nexport interface Persistence {\n  /** Read a value, or `null` if absent. */\n  load(key: string): Promise<string | null>\n  /** Write a value. */\n  save(key: string, value: string): Promise<void>\n}\n\n/** An in-memory reference {@link Persistence} for tests and as a contract example. */\nexport function createMemoryPersistence(): Persistence {\n  const store = new Map<string, string>()\n  return {\n    load: (key) => Promise.resolve(store.get(key) ?? null),\n    save: (key, value) => {\n      store.set(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n\n/** The synchronous Web Storage shape (`localStorage`/`sessionStorage`), injected so this stays DOM-free. */\nexport interface WebStorageLike {\n  getItem(key: string): string | null\n  setItem(key: string, value: string): void\n}\n\n/**\n * Adapt a Web Storage (`localStorage`/`sessionStorage`) to {@link Persistence}. Inject the storage\n * (`createWebStoragePersistence(localStorage)`) rather than reaching for a global, so it runs in any\n * environment and tests. Storage is synchronous; the async contract is satisfied trivially.\n */\nexport function createWebStoragePersistence(storage: WebStorageLike): Persistence {\n  return {\n    load: (key) => Promise.resolve(storage.getItem(key)),\n    save: (key, value) => {\n      storage.setItem(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n\n/** Load + parse a persisted {@link SyncSnapshot}, or `undefined` if absent / unparseable. */\nexport async function loadSnapshot<T>(\n  persistence: Persistence,\n  key: string,\n): Promise<SyncSnapshot<T> | undefined> {\n  const raw = await persistence.load(key)\n  if (raw === null) return undefined\n  try {\n    return JSON.parse(raw) as SyncSnapshot<T>\n  } catch {\n    // A corrupt/partial blob must not wedge startup — start fresh rather than throw.\n    return undefined\n  }\n}\n\n/**\n * Wrap a {@link SyncEngine} so every mutation (`set`/`delete`) and `sync()` auto-saves its snapshot\n * to `persistence` under `key`. Saves are SERIALIZED (chained) so a burst of edits can't write an\n * older snapshot last, and failures are swallowed (best-effort durability never breaks a mutation).\n * To RESTORE on next launch, pass `snapshot: await loadSnapshot(...)` into the engine first —\n * {@link createPersistentEngine} does both.\n */\nexport function persistEngine<T>(\n  engine: SyncEngine<T>,\n  persistence: Persistence,\n  key: string,\n): SyncEngine<T> {\n  let chain: Promise<void> = Promise.resolve()\n  const save = (): void => {\n    const snapshot = JSON.stringify(engine.export())\n    chain = chain\n      .then(() => persistence.save(key, snapshot))\n      .then(\n        () => undefined,\n        () => undefined,\n      )\n  }\n  return {\n    ...engine,\n    set(collection, recordId, value) {\n      const op = engine.set(collection, recordId, value)\n      save()\n      return op\n    },\n    delete(collection, recordId) {\n      const op = engine.delete(collection, recordId)\n      save()\n      return op\n    },\n    async sync(signal) {\n      await engine.sync(signal)\n      save()\n    },\n  }\n}\n\n/** Options for {@link createPersistentEngine}: a {@link SyncEngineOptions} minus `snapshot` (loaded here). */\nexport interface PersistentEngineOptions<T> extends Omit<SyncEngineOptions<T>, 'snapshot'> {\n  /** Where to persist. */\n  readonly persistence: Persistence\n  /** The storage key for this replica's snapshot. */\n  readonly key: string\n}\n\n/**\n * Create a durable {@link SyncEngine}: restore the persisted snapshot (so `seq`/HLC survive and op\n * ids never collide across restarts), then auto-save on every change. One call for a replica that\n * survives restart.\n */\nexport async function createPersistentEngine<T>(\n  options: PersistentEngineOptions<T>,\n): Promise<SyncEngine<T>> {\n  const { persistence, key, ...syncOptions } = options\n  const snapshot = await loadSnapshot<T>(persistence, key)\n  const engine = createSyncEngine<T>(snapshot ? { ...syncOptions, snapshot } : syncOptions)\n  return persistEngine(engine, persistence, key)\n}\n"],"mappings":";;;;;;;;;;;;;;;AA6BA,SAAgB,0BAAuC;CACrD,MAAM,wBAAQ,IAAI,IAAoB;CACtC,OAAO;EACL,OAAO,QAAQ,QAAQ,QAAQ,MAAM,IAAI,GAAG,KAAK,IAAI;EACrD,OAAO,KAAK,UAAU;GACpB,MAAM,IAAI,KAAK,KAAK;GACpB,OAAO,QAAQ,QAAQ;EACzB;CACF;AACF;;;;;;AAaA,SAAgB,4BAA4B,SAAsC;CAChF,OAAO;EACL,OAAO,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,GAAG,CAAC;EACnD,OAAO,KAAK,UAAU;GACpB,QAAQ,QAAQ,KAAK,KAAK;GAC1B,OAAO,QAAQ,QAAQ;EACzB;CACF;AACF;;AAGA,eAAsB,aACpB,aACA,KACsC;CACtC,MAAM,MAAM,MAAM,YAAY,KAAK,GAAG;CACtC,IAAI,QAAQ,MAAM,OAAO,KAAA;CACzB,IAAI;EACF,OAAO,KAAK,MAAM,GAAG;CACvB,QAAQ;EAEN;CACF;AACF;;;;;;;;AASA,SAAgB,cACd,QACA,aACA,KACe;CACf,IAAI,QAAuB,QAAQ,QAAQ;CAC3C,MAAM,aAAmB;EACvB,MAAM,WAAW,KAAK,UAAU,OAAO,OAAO,CAAC;EAC/C,QAAQ,MACL,WAAW,YAAY,KAAK,KAAK,QAAQ,CAAC,EAC1C,WACO,KAAA,SACA,KAAA,CACR;CACJ;CACA,OAAO;EACL,GAAG;EACH,IAAI,YAAY,UAAU,OAAO;GAC/B,MAAM,KAAK,OAAO,IAAI,YAAY,UAAU,KAAK;GACjD,KAAK;GACL,OAAO;EACT;EACA,OAAO,YAAY,UAAU;GAC3B,MAAM,KAAK,OAAO,OAAO,YAAY,QAAQ;GAC7C,KAAK;GACL,OAAO;EACT;EACA,MAAM,KAAK,QAAQ;GACjB,MAAM,OAAO,KAAK,MAAM;GACxB,KAAK;EACP;CACF;AACF;;;;;;AAeA,eAAsB,uBACpB,SACwB;CACxB,MAAM,EAAE,aAAa,KAAK,GAAG,gBAAgB;CAC7C,MAAM,WAAW,MAAM,aAAgB,aAAa,GAAG;CAEvD,OAAO,cADQ,iBAAoB,WAAW;EAAE,GAAG;EAAa;CAAS,IAAI,WACnD,GAAG,aAAa,GAAG;AAC/C"}
+{"version":3,"file":"persist.js","names":[],"sources":["../src/persist.ts"],"sourcesContent":["/**\n * Persistence (10F) — a minimal async key/value capability so a Continuum replica\n * survives restart (mirrors the CLI's `FileSystem` / Pulse's `UpdateStorage`). Persist a\n * sync engine's {@link \"./sync\".SyncEngine.export snapshot} through any `Persistence`\n * and restore it on next launch, so `seq` survives and op ids never collide.\n *\n * `createMemoryPersistence` is the reference; `createWebStoragePersistence` adapts a Web Storage\n * (`localStorage`/`sessionStorage`); {@link persistEngine} wires auto-save + restore so a replica is\n * durable with one call. See `docs/adr/0016-continuum-server-persistence.md`.\n *\n * @module\n */\n\nimport {\n  createSyncEngine,\n  type SyncEngine,\n  type SyncEngineOptions,\n  type SyncSnapshot,\n} from './sync'\n\n/** A minimal async key/value store for persisting Continuum state. */\nexport interface Persistence {\n  /** Read a value, or `null` if absent. */\n  load(key: string): Promise<string | null>\n  /** Write a value. */\n  save(key: string, value: string): Promise<void>\n}\n\n/** An in-memory reference {@link Persistence} for tests and as a contract example. */\nexport function createMemoryPersistence(): Persistence {\n  const store = new Map<string, string>()\n  return {\n    load: (key) => Promise.resolve(store.get(key) ?? null),\n    save: (key, value) => {\n      store.set(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n\n/** The synchronous Web Storage shape (`localStorage`/`sessionStorage`), injected so this stays DOM-free. */\nexport interface WebStorageLike {\n  getItem(key: string): string | null\n  setItem(key: string, value: string): void\n}\n\n/**\n * Adapt a Web Storage (`localStorage`/`sessionStorage`) to {@link Persistence}. Inject the storage\n * (`createWebStoragePersistence(localStorage)`) rather than reaching for a global, so it runs in any\n * environment and tests. Storage is synchronous; the async contract is satisfied trivially.\n */\nexport function createWebStoragePersistence(storage: WebStorageLike): Persistence {\n  return {\n    load: (key) => Promise.resolve(storage.getItem(key)),\n    save: (key, value) => {\n      storage.setItem(key, value)\n      return Promise.resolve()\n    },\n  }\n}\n\n/** Load + parse a persisted {@link SyncSnapshot}, or `undefined` if absent / unparseable. */\nexport async function loadSnapshot<T>(\n  persistence: Persistence,\n  key: string,\n): Promise<SyncSnapshot<T> | undefined> {\n  const raw = await persistence.load(key)\n  if (raw === null) return undefined\n  try {\n    return JSON.parse(raw) as SyncSnapshot<T>\n  } catch {\n    // A corrupt/partial blob must not wedge startup — start fresh rather than throw.\n    return undefined\n  }\n}\n\n/**\n * Wrap a {@link SyncEngine} so every mutation (`set`/`delete`) and `sync()` auto-saves its snapshot\n * to `persistence` under `key`. Saves are SERIALIZED (chained) so a burst of edits can't write an\n * older snapshot last, and failures are swallowed (best-effort durability never breaks a mutation).\n * To RESTORE on next launch, pass `snapshot: await loadSnapshot(...)` into the engine first —\n * {@link createPersistentEngine} does both.\n */\nexport function persistEngine<T>(\n  engine: SyncEngine<T>,\n  persistence: Persistence,\n  key: string,\n): SyncEngine<T> {\n  let chain: Promise<void> = Promise.resolve()\n  const save = (): void => {\n    const snapshot = JSON.stringify(engine.export())\n    chain = chain\n      .then(() => persistence.save(key, snapshot))\n      .then(\n        () => undefined,\n        () => undefined,\n      )\n  }\n  return {\n    ...engine,\n    set(collection, recordId, value) {\n      const op = engine.set(collection, recordId, value)\n      save()\n      return op\n    },\n    delete(collection, recordId) {\n      const op = engine.delete(collection, recordId)\n      save()\n      return op\n    },\n    async sync(signal) {\n      await engine.sync(signal)\n      save()\n    },\n  }\n}\n\n/** Options for {@link createPersistentEngine}: a {@link SyncEngineOptions} minus `snapshot` (loaded here). */\nexport interface PersistentEngineOptions<T> extends Omit<SyncEngineOptions<T>, 'snapshot'> {\n  /** Where to persist. */\n  readonly persistence: Persistence\n  /** The storage key for this replica's snapshot. */\n  readonly key: string\n}\n\n/**\n * Create a durable {@link SyncEngine}: restore the persisted snapshot (so `seq`/HLC survive and op\n * ids never collide across restarts), then auto-save on every change. One call for a replica that\n * survives restart.\n */\nexport async function createPersistentEngine<T>(\n  options: PersistentEngineOptions<T>,\n): Promise<SyncEngine<T>> {\n  const { persistence, key, ...syncOptions } = options\n  const snapshot = await loadSnapshot<T>(persistence, key)\n  const engine = createSyncEngine<T>(snapshot ? { ...syncOptions, snapshot } : syncOptions)\n  return persistEngine(engine, persistence, key)\n}\n\n// --- IndexedDB persistence (durable browser storage; large + async, beyond localStorage's sync ~5MB) ---\n//\n// A minimal structural subset of the DOM IndexedDB types, declared here so @mindees/data stays\n// DOM-lib-free (mirrors WebStorageLike). The real `globalThis.indexedDB` and `fake-indexeddb` are\n// structurally assignable to IndexedDbFactoryLike.\n\ninterface IdbRequestLike<T> {\n  result: T\n  error: unknown\n  onsuccess: (() => void) | null\n  onerror: (() => void) | null\n}\ninterface IdbOpenRequestLike extends IdbRequestLike<IdbDatabaseLike> {\n  onupgradeneeded: (() => void) | null\n}\ninterface IdbObjectStoreLike {\n  get(key: string): IdbRequestLike<unknown>\n  put(value: string, key: string): IdbRequestLike<unknown>\n}\ninterface IdbTransactionLike {\n  objectStore(name: string): IdbObjectStoreLike\n}\ninterface IdbDatabaseLike {\n  objectStoreNames: { contains(name: string): boolean }\n  createObjectStore(name: string): unknown\n  transaction(storeNames: string, mode: 'readonly' | 'readwrite'): IdbTransactionLike\n}\n/** The minimal IndexedDB factory surface (a structural subset of the DOM `IDBFactory`). */\nexport interface IndexedDbFactoryLike {\n  open(name: string, version?: number): IdbOpenRequestLike\n}\n\n/** Options for {@link createIndexedDbPersistence}. */\nexport interface IndexedDbPersistenceOptions {\n  /** Database name (default `'mindees'`). */\n  readonly databaseName?: string\n  /** Object-store name (default `'continuum'`). */\n  readonly storeName?: string\n  /** The IndexedDB factory; defaults to `globalThis.indexedDB`. Inject (e.g. `fake-indexeddb`) elsewhere. */\n  readonly factory?: IndexedDbFactoryLike\n}\n\n/**\n * A durable {@link Persistence} backed by IndexedDB — large, asynchronous browser storage (beyond\n * `localStorage`'s synchronous ~5MB cap), a better home for a growing Continuum op log/snapshot. The\n * database + object store open lazily on first use and are reused. Inject `factory` to run outside a\n * browser (tests, or a custom environment); throws if none is available.\n */\nexport function createIndexedDbPersistence(options: IndexedDbPersistenceOptions = {}): Persistence {\n  const dbName = options.databaseName ?? 'mindees'\n  const storeName = options.storeName ?? 'continuum'\n  const factory = options.factory ?? (globalThis as { indexedDB?: IndexedDbFactoryLike }).indexedDB\n  if (!factory) {\n    throw new Error('createIndexedDbPersistence: IndexedDB is unavailable; pass `factory`.')\n  }\n\n  let dbPromise: Promise<IdbDatabaseLike> | undefined\n  const openDb = (): Promise<IdbDatabaseLike> => {\n    if (!dbPromise) {\n      dbPromise = new Promise<IdbDatabaseLike>((resolve, reject) => {\n        const request = factory.open(dbName, 1)\n        request.onupgradeneeded = () => {\n          const db = request.result\n          if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName)\n        }\n        request.onsuccess = () => resolve(request.result)\n        request.onerror = () => reject(request.error ?? new Error('IndexedDB open failed'))\n      })\n    }\n    return dbPromise\n  }\n\n  const run = <T>(\n    mode: 'readonly' | 'readwrite',\n    op: (store: IdbObjectStoreLike) => IdbRequestLike<T>,\n  ): Promise<T> =>\n    openDb().then(\n      (db) =>\n        new Promise<T>((resolve, reject) => {\n          const request = op(db.transaction(storeName, mode).objectStore(storeName))\n          request.onsuccess = () => resolve(request.result)\n          request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed'))\n        }),\n    )\n\n  return {\n    load: (key) =>\n      run('readonly', (store) => store.get(key)).then((value) =>\n        value === undefined || value === null ? null : String(value),\n      ),\n    save: (key, value) => run('readwrite', (store) => store.put(value, key)).then(() => undefined),\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindees/data",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "MindeesNative Continuum - local-first reactive store and sync: a signals-native document store with fine-grained reactive queries, optimistic updates, CRDT conflict resolution, and delta sync.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -27,9 +27,10 @@
     "directory": "packages/data"
   },
   "dependencies": {
-    "@mindees/core": "0.20.0"
+    "@mindees/core": "0.22.0"
   },
   "devDependencies": {
+    "fake-indexeddb": "6.0.0",
     "fast-check": "4.8.0"
   },
   "scripts": {