@tanstack/db-sqlite-persistence-core 0.1.2

package/README.md

@@ -0,0 +1,95 @@
+# @tanstack/db-sqlite-persistence-core
+
+Shared SQLite persistence primitives for TanStack DB. Runtime-specific wrappers
+(Node, Electron, React Native, Cloudflare Durable Objects) build on top of this
+package.
+
+## What this package provides
+
+- Generic persisted collection wrapper utilities
+- Shared persistence/coordinator protocol types
+- SQLite core persistence adapter (`createSQLiteCorePersistenceAdapter`)
+- Validation and storage key helpers
+- Shared error types
+
+This package intentionally does **not** include a concrete SQLite engine
+binding. Provide a runtime `SQLiteDriver` implementation from a wrapper package.
+
+## Exported API (complete)
+
+### Persisted wrapper and protocol APIs
+
+- `PersistedMutationEnvelope`
+- `ProtocolEnvelope<TPayload>`
+- `LeaderHeartbeat`
+- `TxCommitted`
+- `EnsureRemoteSubsetRequest`
+- `EnsureRemoteSubsetResponse`
+- `ApplyLocalMutationsRequest`
+- `ApplyLocalMutationsResponse`
+- `PullSinceRequest`
+- `PullSinceResponse`
+- `CollectionReset`
+- `PersistedIndexSpec`
+- `PersistedTx<T, TKey>`
+- `PersistenceAdapter<T, TKey>`
+- `SQLiteDriver`
+- `PersistedCollectionCoordinator`
+- `PersistedCollectionPersistence<T, TKey>`
+- `PersistedCollectionMode`
+- `PersistedCollectionLeadershipState`
+- `PersistedCollectionUtils`
+- `PersistedSyncWrappedOptions<T, TKey, TSchema, TUtils>`
+- `PersistedLocalOnlyOptions<T, TKey, TSchema, TUtils>`
+- `SingleProcessCoordinator`
+- `validatePersistedCollectionCoordinator(...)`
+- `persistedCollectionOptions(...)`
+- `encodePersistedStorageKey(...)`
+- `decodePersistedStorageKey(...)`
+- `createPersistedTableName(...)`
+
+`PersistedCollectionPersistence` can optionally implement:
+
+- `resolvePersistenceForMode(mode)` (legacy mode-aware resolution)
+- `resolvePersistenceForCollection({ collectionId, mode, schemaVersion })`
+  (collection-aware resolution)
+
+`persistedCollectionOptions(...)` now supports `schemaVersion` per collection
+and resolves persistence using:
+
+- collection id
+- inferred mode (`sync-present` or `sync-absent`)
+- optional `schemaVersion`
+
+This lets runtime wrappers expose one shared persistence instance per database
+while still handling per-collection schema versions correctly.
+
+### SQLite core adapter APIs
+
+- `SQLiteCoreAdapterOptions`
+- `SQLitePullSinceResult<TKey>`
+- `SQLiteCorePersistenceAdapter<T, TKey>`
+- `createSQLiteCorePersistenceAdapter<T, TKey>(...)`
+
+### Error APIs
+
+- `PersistedCollectionCoreError`
+- `InvalidPersistedCollectionConfigError`
+- `InvalidSyncConfigError`
+- `InvalidPersistedCollectionCoordinatorError`
+- `InvalidPersistenceAdapterError`
+- `InvalidPersistedStorageKeyError`
+- `InvalidPersistedStorageKeyEncodingError`
+- `PersistenceUnavailableError`
+
+## Typical usage (via runtime wrappers)
+
+In most applications, use a runtime package directly:
+
+- `@tanstack/node-db-sqlite-persistence`
+- `@tanstack/browser-db-sqlite-persistence`
+- `@tanstack/electron-db-sqlite-persistence`
+- `@tanstack/react-native-db-sqlite-persistence`
+- `@tanstack/cloudflare-durable-objects-db-sqlite-persistence`
+
+Those packages provide concrete drivers and runtime wiring.

package/dist/cjs/errors.cjs

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const db = require("@tanstack/db");
+class PersistedCollectionCoreError extends db.TanStackDBError {
+  constructor(message) {
+    super(message);
+    this.name = `PersistedCollectionCoreError`;
+  }
+}
+class InvalidPersistedCollectionConfigError extends PersistedCollectionCoreError {
+  constructor(message) {
+    super(message);
+    this.name = `InvalidPersistedCollectionConfigError`;
+  }
+}
+class InvalidSyncConfigError extends InvalidPersistedCollectionConfigError {
+  constructor(details) {
+    super(
+      details ? `Invalid sync config: ${details}` : `Invalid sync config: expected an object with a callable sync function`
+    );
+    this.name = `InvalidSyncConfigError`;
+  }
+}
+class InvalidPersistedCollectionCoordinatorError extends InvalidPersistedCollectionConfigError {
+  constructor(methodName) {
+    super(
+      `Invalid persisted collection coordinator: missing required "${methodName}" method`
+    );
+    this.name = `InvalidPersistedCollectionCoordinatorError`;
+  }
+}
+class InvalidPersistenceAdapterError extends InvalidPersistedCollectionConfigError {
+  constructor(methodName) {
+    super(
+      `Invalid persistence adapter: missing required "${methodName}" method`
+    );
+    this.name = `InvalidPersistenceAdapterError`;
+  }
+}
+class InvalidPersistedStorageKeyError extends InvalidPersistedCollectionConfigError {
+  constructor(key) {
+    super(
+      `Invalid persisted storage key "${String(key)}": numeric keys must be finite`
+    );
+    this.name = `InvalidPersistedStorageKeyError`;
+  }
+}
+class InvalidPersistedStorageKeyEncodingError extends InvalidPersistedCollectionConfigError {
+  constructor(encoded) {
+    super(
+      `Invalid persisted storage key encoding "${encoded}": expected prefix "n:" or "s:"`
+    );
+    this.name = `InvalidPersistedStorageKeyEncodingError`;
+  }
+}
+class PersistenceUnavailableError extends PersistedCollectionCoreError {
+  constructor(details) {
+    super(
+      details ? `Persistence unavailable: ${details}` : `Persistence unavailable in this runtime`
+    );
+    this.name = `PersistenceUnavailableError`;
+  }
+}
+exports.InvalidPersistedCollectionConfigError = InvalidPersistedCollectionConfigError;
+exports.InvalidPersistedCollectionCoordinatorError = InvalidPersistedCollectionCoordinatorError;
+exports.InvalidPersistedStorageKeyEncodingError = InvalidPersistedStorageKeyEncodingError;
+exports.InvalidPersistedStorageKeyError = InvalidPersistedStorageKeyError;
+exports.InvalidPersistenceAdapterError = InvalidPersistenceAdapterError;
+exports.InvalidSyncConfigError = InvalidSyncConfigError;
+exports.PersistedCollectionCoreError = PersistedCollectionCoreError;
+exports.PersistenceUnavailableError = PersistenceUnavailableError;
+//# sourceMappingURL=errors.cjs.map

package/dist/cjs/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from '@tanstack/db'\n\nexport class PersistedCollectionCoreError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `PersistedCollectionCoreError`\n  }\n}\n\nexport class InvalidPersistedCollectionConfigError extends PersistedCollectionCoreError {\n  constructor(message: string) {\n    super(message)\n    this.name = `InvalidPersistedCollectionConfigError`\n  }\n}\n\nexport class InvalidSyncConfigError extends InvalidPersistedCollectionConfigError {\n  constructor(details?: string) {\n    super(\n      details\n        ? `Invalid sync config: ${details}`\n        : `Invalid sync config: expected an object with a callable sync function`,\n    )\n    this.name = `InvalidSyncConfigError`\n  }\n}\n\nexport class InvalidPersistedCollectionCoordinatorError extends InvalidPersistedCollectionConfigError {\n  constructor(methodName: string) {\n    super(\n      `Invalid persisted collection coordinator: missing required \"${methodName}\" method`,\n    )\n    this.name = `InvalidPersistedCollectionCoordinatorError`\n  }\n}\n\nexport class InvalidPersistenceAdapterError extends InvalidPersistedCollectionConfigError {\n  constructor(methodName: string) {\n    super(\n      `Invalid persistence adapter: missing required \"${methodName}\" method`,\n    )\n    this.name = `InvalidPersistenceAdapterError`\n  }\n}\n\nexport class InvalidPersistedStorageKeyError extends InvalidPersistedCollectionConfigError {\n  constructor(key: string | number) {\n    super(\n      `Invalid persisted storage key \"${String(key)}\": numeric keys must be finite`,\n    )\n    this.name = `InvalidPersistedStorageKeyError`\n  }\n}\n\nexport class InvalidPersistedStorageKeyEncodingError extends InvalidPersistedCollectionConfigError {\n  constructor(encoded: string) {\n    super(\n      `Invalid persisted storage key encoding \"${encoded}\": expected prefix \"n:\" or \"s:\"`,\n    )\n    this.name = `InvalidPersistedStorageKeyEncodingError`\n  }\n}\n\nexport class PersistenceUnavailableError extends PersistedCollectionCoreError {\n  constructor(details?: string) {\n    super(\n      details\n        ? `Persistence unavailable: ${details}`\n        : `Persistence unavailable in this runtime`,\n    )\n    this.name = `PersistenceUnavailableError`\n  }\n}\n"],"names":["TanStackDBError"],"mappings":";;;AAEO,MAAM,qCAAqCA,GAAAA,gBAAgB;AAAA,EAChE,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,8CAA8C,6BAA6B;AAAA,EACtF,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,+BAA+B,sCAAsC;AAAA,EAChF,YAAY,SAAkB;AAC5B;AAAA,MACE,UACI,wBAAwB,OAAO,KAC/B;AAAA,IAAA;AAEN,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,mDAAmD,sCAAsC;AAAA,EACpG,YAAY,YAAoB;AAC9B;AAAA,MACE,+DAA+D,UAAU;AAAA,IAAA;AAE3E,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,uCAAuC,sCAAsC;AAAA,EACxF,YAAY,YAAoB;AAC9B;AAAA,MACE,kDAAkD,UAAU;AAAA,IAAA;AAE9D,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,wCAAwC,sCAAsC;AAAA,EACzF,YAAY,KAAsB;AAChC;AAAA,MACE,kCAAkC,OAAO,GAAG,CAAC;AAAA,IAAA;AAE/C,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,gDAAgD,sCAAsC;AAAA,EACjG,YAAY,SAAiB;AAC3B;AAAA,MACE,2CAA2C,OAAO;AAAA,IAAA;AAEpD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,oCAAoC,6BAA6B;AAAA,EAC5E,YAAY,SAAkB;AAC5B;AAAA,MACE,UACI,4BAA4B,OAAO,KACnC;AAAA,IAAA;AAEN,SAAK,OAAO;AAAA,EACd;AACF;;;;;;;;;"}

package/dist/cjs/errors.d.cts

@@ -0,0 +1,25 @@
+import { TanStackDBError } from '@tanstack/db';
+export declare class PersistedCollectionCoreError extends TanStackDBError {
+    constructor(message: string);
+}
+export declare class InvalidPersistedCollectionConfigError extends PersistedCollectionCoreError {
+    constructor(message: string);
+}
+export declare class InvalidSyncConfigError extends InvalidPersistedCollectionConfigError {
+    constructor(details?: string);
+}
+export declare class InvalidPersistedCollectionCoordinatorError extends InvalidPersistedCollectionConfigError {
+    constructor(methodName: string);
+}
+export declare class InvalidPersistenceAdapterError extends InvalidPersistedCollectionConfigError {
+    constructor(methodName: string);
+}
+export declare class InvalidPersistedStorageKeyError extends InvalidPersistedCollectionConfigError {
+    constructor(key: string | number);
+}
+export declare class InvalidPersistedStorageKeyEncodingError extends InvalidPersistedCollectionConfigError {
+    constructor(encoded: string);
+}
+export declare class PersistenceUnavailableError extends PersistedCollectionCoreError {
+    constructor(details?: string);
+}

package/dist/cjs/index.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const persisted = require("./persisted.cjs");
+const errors = require("./errors.cjs");
+const sqliteCoreAdapter = require("./sqlite-core-adapter.cjs");
+exports.SingleProcessCoordinator = persisted.SingleProcessCoordinator;
+exports.createPersistedTableName = persisted.createPersistedTableName;
+exports.decodePersistedStorageKey = persisted.decodePersistedStorageKey;
+exports.encodePersistedStorageKey = persisted.encodePersistedStorageKey;
+exports.persistedCollectionOptions = persisted.persistedCollectionOptions;
+exports.validatePersistedCollectionCoordinator = persisted.validatePersistedCollectionCoordinator;
+exports.InvalidPersistedCollectionConfigError = errors.InvalidPersistedCollectionConfigError;
+exports.InvalidPersistedCollectionCoordinatorError = errors.InvalidPersistedCollectionCoordinatorError;
+exports.InvalidPersistedStorageKeyEncodingError = errors.InvalidPersistedStorageKeyEncodingError;
+exports.InvalidPersistedStorageKeyError = errors.InvalidPersistedStorageKeyError;
+exports.InvalidPersistenceAdapterError = errors.InvalidPersistenceAdapterError;
+exports.InvalidSyncConfigError = errors.InvalidSyncConfigError;
+exports.PersistedCollectionCoreError = errors.PersistedCollectionCoreError;
+exports.PersistenceUnavailableError = errors.PersistenceUnavailableError;
+exports.SQLiteCorePersistenceAdapter = sqliteCoreAdapter.SQLiteCorePersistenceAdapter;
+exports.createSQLiteCorePersistenceAdapter = sqliteCoreAdapter.createSQLiteCorePersistenceAdapter;
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -0,0 +1,3 @@
+export * from './persisted.cjs';
+export * from './errors.cjs';
+export * from './sqlite-core-adapter.cjs';