@tanstack/db-sqlite-persistence-core 0.4.4 → 0.4.7

package/dist/esm/sqlite-value.d.ts

@@ -8,3 +8,15 @@ export type SerializedSQLiteBigInt = {
 };
 export declare function assertSQLiteBigIntInRange(value: bigint): bigint;
 export declare function serializeSQLiteBigInt(value: bigint): SerializedSQLiteBigInt;
+type SQLiteTemporalKind = `Temporal.Instant` | `Temporal.PlainDate`;
+export type SerializedSQLiteTemporal = {
+    [PERSISTED_TYPE_TAG]: SQLiteTemporalKind;
+    [PERSISTED_VALUE_TAG]: string;
+    order: string;
+};
+export declare function sqliteTemporalKind(value: unknown): SQLiteTemporalKind | undefined;
+export declare function reviveSQLiteTemporal(kind: SQLiteTemporalKind, value: string): unknown;
+/** Registered prototype methods validate the brand; user toString is ignored. */
+export declare function serializeSQLiteTemporal(value: unknown): SerializedSQLiteTemporal | undefined;
+export declare function sqliteTemporalIdentity(value: SerializedSQLiteTemporal): string;
+export {};

package/dist/esm/sqlite-value.js

@@ -1,4 +1,4 @@
-import { SQLiteBigIntOutOfRangeError } from "./errors.js";
+import { SQLiteBigIntOutOfRangeError, InvalidPersistedCollectionConfigError } from "./errors.js";
 const SQLITE_BIGINT_MIN = -9223372036854775808n;
 const SQLITE_BIGINT_MAX = 9223372036854775807n;
 const PERSISTED_TYPE_TAG = `__tanstack_db_persisted_type__`;
@@ -20,12 +20,63 @@ function serializeSQLiteBigInt(value) {
     [PERSISTED_VALUE_TAG]: value.toString()
   };
 }
+function sqliteTemporalKind(value) {
+  if (value === null || typeof value !== `object`) return;
+  const tag = value[Symbol.toStringTag];
+  if (tag === `Temporal.Instant` || tag === `Temporal.PlainDate`) return tag;
+  return void 0;
+}
+function requireSQLiteTemporalConstructor(kind) {
+  const name = kind.slice(`Temporal.`.length);
+  const constructor = globalThis.Temporal?.[name];
+  if (typeof constructor?.from !== `function` || typeof constructor.prototype.toString !== `function`) {
+    throw new InvalidPersistedCollectionConfigError(
+      `Missing global ${kind} constructor for SQLite persistence`
+    );
+  }
+  return constructor;
+}
+function reviveSQLiteTemporal(kind, value) {
+  return requireSQLiteTemporalConstructor(kind).from(value);
+}
+function serializeSQLiteTemporal(value) {
+  if (value === null || typeof value !== `object`) return;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === null || prototype === Object.prototype) return;
+  const tag = value[Symbol.toStringTag];
+  if (typeof tag !== `string` || !tag.startsWith(`Temporal.`)) return;
+  const kind = sqliteTemporalKind(value);
+  if (!kind)
+    throw new InvalidPersistedCollectionConfigError(
+      `Unsupported ${tag} value for SQLite persistence`
+    );
+  const constructor = requireSQLiteTemporalConstructor(kind);
+  let text;
+  try {
+    text = constructor.prototype.toString.call(value);
+  } catch {
+    throw new InvalidPersistedCollectionConfigError(
+      `Invalid ${kind} value for the registered global constructor`
+    );
+  }
+  const native = constructor.from(text);
+  const iso = kind === `Temporal.PlainDate` ? native.withCalendar(`iso8601`) : void 0;
+  const order = iso ? `${String(iso.year + 1e6).padStart(7, `0`)}${String(iso.month).padStart(2, `0`)}${String(iso.day).padStart(2, `0`)}` : (native.epochNanoseconds + 10000000000000000000000n).toString().padStart(23, `0`);
+  return { [PERSISTED_TYPE_TAG]: kind, [PERSISTED_VALUE_TAG]: text, order };
+}
+function sqliteTemporalIdentity(value) {
+  return `${value[PERSISTED_TYPE_TAG]}:${value[PERSISTED_VALUE_TAG]}`;
+}
 export {
   PERSISTED_TYPE_TAG,
   PERSISTED_VALUE_TAG,
   SQLITE_BIGINT_MAX,
   SQLITE_BIGINT_MIN,
   assertSQLiteBigIntInRange,
-  serializeSQLiteBigInt
+  reviveSQLiteTemporal,
+  serializeSQLiteBigInt,
+  serializeSQLiteTemporal,
+  sqliteTemporalIdentity,
+  sqliteTemporalKind
 };
 //# sourceMappingURL=sqlite-value.js.map

package/dist/esm/sqlite-value.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-value.js","sources":["../../src/sqlite-value.ts"],"sourcesContent":["import { SQLiteBigIntOutOfRangeError } from './errors'\n\nexport const SQLITE_BIGINT_MIN = -9_223_372_036_854_775_808n\nexport const SQLITE_BIGINT_MAX = 9_223_372_036_854_775_807n\nexport const PERSISTED_TYPE_TAG = `__tanstack_db_persisted_type__`\nexport const PERSISTED_VALUE_TAG = `value`\n\nexport type SerializedSQLiteBigInt = {\n  [PERSISTED_TYPE_TAG]: `bigint`\n  [PERSISTED_VALUE_TAG]: string\n}\n\nexport function assertSQLiteBigIntInRange(value: bigint): bigint {\n  if (value < SQLITE_BIGINT_MIN || value > SQLITE_BIGINT_MAX) {\n    throw new SQLiteBigIntOutOfRangeError(\n      value,\n      SQLITE_BIGINT_MIN,\n      SQLITE_BIGINT_MAX,\n    )\n  }\n  return value\n}\n\nexport function serializeSQLiteBigInt(value: bigint): SerializedSQLiteBigInt {\n  assertSQLiteBigIntInRange(value)\n  return {\n    [PERSISTED_TYPE_TAG]: `bigint`,\n    [PERSISTED_VALUE_TAG]: value.toString(),\n  }\n}\n"],"names":[],"mappings":";AAEO,MAAM,oBAAoB,CAAC;AAC3B,MAAM,oBAAoB;AAC1B,MAAM,qBAAqB;AAC3B,MAAM,sBAAsB;AAO5B,SAAS,0BAA0B,OAAuB;AAC/D,MAAI,QAAQ,qBAAqB,QAAQ,mBAAmB;AAC1D,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;AAEO,SAAS,sBAAsB,OAAuC;AAC3E,4BAA0B,KAAK;AAC/B,SAAO;AAAA,IACL,CAAC,kBAAkB,GAAG;AAAA,IACtB,CAAC,mBAAmB,GAAG,MAAM,SAAA;AAAA,EAAS;AAE1C;"}
+{"version":3,"file":"sqlite-value.js","sources":["../../src/sqlite-value.ts"],"sourcesContent":["import {\n  InvalidPersistedCollectionConfigError,\n  SQLiteBigIntOutOfRangeError,\n} from './errors'\n\nexport const SQLITE_BIGINT_MIN = -9_223_372_036_854_775_808n\nexport const SQLITE_BIGINT_MAX = 9_223_372_036_854_775_807n\nexport const PERSISTED_TYPE_TAG = `__tanstack_db_persisted_type__`\nexport const PERSISTED_VALUE_TAG = `value`\n\nexport type SerializedSQLiteBigInt = {\n  [PERSISTED_TYPE_TAG]: `bigint`\n  [PERSISTED_VALUE_TAG]: string\n}\n\nexport function assertSQLiteBigIntInRange(value: bigint): bigint {\n  if (value < SQLITE_BIGINT_MIN || value > SQLITE_BIGINT_MAX) {\n    throw new SQLiteBigIntOutOfRangeError(\n      value,\n      SQLITE_BIGINT_MIN,\n      SQLITE_BIGINT_MAX,\n    )\n  }\n  return value\n}\n\nexport function serializeSQLiteBigInt(value: bigint): SerializedSQLiteBigInt {\n  assertSQLiteBigIntInRange(value)\n  return {\n    [PERSISTED_TYPE_TAG]: `bigint`,\n    [PERSISTED_VALUE_TAG]: value.toString(),\n  }\n}\n\ntype SQLiteTemporalKind = `Temporal.Instant` | `Temporal.PlainDate`\ntype SQLiteTemporal = {\n  epochNanoseconds: bigint\n  year: number\n  month: number\n  day: number\n  withCalendar: (calendar: string) => SQLiteTemporal\n}\ntype TemporalConstructor = {\n  from: (value: string) => SQLiteTemporal\n  prototype: { toString: () => string }\n}\n\nexport type SerializedSQLiteTemporal = {\n  [PERSISTED_TYPE_TAG]: SQLiteTemporalKind\n  [PERSISTED_VALUE_TAG]: string\n  order: string\n}\n\nexport function sqliteTemporalKind(\n  value: unknown,\n): SQLiteTemporalKind | undefined {\n  if (value === null || typeof value !== `object`) return\n  const tag = (value as { [Symbol.toStringTag]?: unknown })[Symbol.toStringTag]\n  if (tag === `Temporal.Instant` || tag === `Temporal.PlainDate`) return tag\n  return undefined\n}\n\nfunction requireSQLiteTemporalConstructor(\n  kind: SQLiteTemporalKind,\n): TemporalConstructor {\n  const name = kind.slice(`Temporal.`.length)\n  const constructor = (\n    globalThis as { Temporal?: Record<string, TemporalConstructor> }\n  ).Temporal?.[name]\n  if (\n    typeof constructor?.from !== `function` ||\n    typeof constructor.prototype.toString !== `function`\n  ) {\n    throw new InvalidPersistedCollectionConfigError(\n      `Missing global ${kind} constructor for SQLite persistence`,\n    )\n  }\n  return constructor\n}\n\nexport function reviveSQLiteTemporal(\n  kind: SQLiteTemporalKind,\n  value: string,\n): unknown {\n  return requireSQLiteTemporalConstructor(kind).from(value)\n}\n\n/** Registered prototype methods validate the brand; user toString is ignored. */\nexport function serializeSQLiteTemporal(\n  value: unknown,\n): SerializedSQLiteTemporal | undefined {\n  if (value === null || typeof value !== `object`) return\n  const prototype = Object.getPrototypeOf(value)\n  if (prototype === null || prototype === Object.prototype) return\n  const tag = (value as { [Symbol.toStringTag]?: unknown })[Symbol.toStringTag]\n  if (typeof tag !== `string` || !tag.startsWith(`Temporal.`)) return\n  const kind = sqliteTemporalKind(value)\n  if (!kind)\n    throw new InvalidPersistedCollectionConfigError(\n      `Unsupported ${tag} value for SQLite persistence`,\n    )\n  const constructor = requireSQLiteTemporalConstructor(kind)\n  let text: string\n  try {\n    text = constructor.prototype.toString.call(value)\n  } catch {\n    throw new InvalidPersistedCollectionConfigError(\n      `Invalid ${kind} value for the registered global constructor`,\n    )\n  }\n  const native = constructor.from(text)\n  const iso =\n    kind === `Temporal.PlainDate` ? native.withCalendar(`iso8601`) : undefined\n  // Text keys avoid both floating-point precision loss and SQLite's int64 cap.\n  const order = iso\n    ? `${String(iso.year + 1_000_000).padStart(7, `0`)}${String(iso.month).padStart(2, `0`)}${String(iso.day).padStart(2, `0`)}`\n    : (native.epochNanoseconds + 10_000_000_000_000_000_000_000n)\n        .toString()\n        .padStart(23, `0`)\n  return { [PERSISTED_TYPE_TAG]: kind, [PERSISTED_VALUE_TAG]: text, order }\n}\n\nexport function sqliteTemporalIdentity(\n  value: SerializedSQLiteTemporal,\n): string {\n  return `${value[PERSISTED_TYPE_TAG]}:${value[PERSISTED_VALUE_TAG]}`\n}\n"],"names":[],"mappings":";AAKO,MAAM,oBAAoB,CAAC;AAC3B,MAAM,oBAAoB;AAC1B,MAAM,qBAAqB;AAC3B,MAAM,sBAAsB;AAO5B,SAAS,0BAA0B,OAAuB;AAC/D,MAAI,QAAQ,qBAAqB,QAAQ,mBAAmB;AAC1D,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;AAEO,SAAS,sBAAsB,OAAuC;AAC3E,4BAA0B,KAAK;AAC/B,SAAO;AAAA,IACL,CAAC,kBAAkB,GAAG;AAAA,IACtB,CAAC,mBAAmB,GAAG,MAAM,SAAA;AAAA,EAAS;AAE1C;AAqBO,SAAS,mBACd,OACgC;AAChC,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU;AACjD,QAAM,MAAO,MAA6C,OAAO,WAAW;AAC5E,MAAI,QAAQ,sBAAsB,QAAQ,qBAAsB,QAAO;AACvE,SAAO;AACT;AAEA,SAAS,iCACP,MACqB;AACrB,QAAM,OAAO,KAAK,MAAM,YAAY,MAAM;AAC1C,QAAM,cACJ,WACA,WAAW,IAAI;AACjB,MACE,OAAO,aAAa,SAAS,cAC7B,OAAO,YAAY,UAAU,aAAa,YAC1C;AACA,UAAM,IAAI;AAAA,MACR,kBAAkB,IAAI;AAAA,IAAA;AAAA,EAE1B;AACA,SAAO;AACT;AAEO,SAAS,qBACd,MACA,OACS;AACT,SAAO,iCAAiC,IAAI,EAAE,KAAK,KAAK;AAC1D;AAGO,SAAS,wBACd,OACsC;AACtC,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU;AACjD,QAAM,YAAY,OAAO,eAAe,KAAK;AAC7C,MAAI,cAAc,QAAQ,cAAc,OAAO,UAAW;AAC1D,QAAM,MAAO,MAA6C,OAAO,WAAW;AAC5E,MAAI,OAAO,QAAQ,YAAY,CAAC,IAAI,WAAW,WAAW,EAAG;AAC7D,QAAM,OAAO,mBAAmB,KAAK;AACrC,MAAI,CAAC;AACH,UAAM,IAAI;AAAA,MACR,eAAe,GAAG;AAAA,IAAA;AAEtB,QAAM,cAAc,iCAAiC,IAAI;AACzD,MAAI;AACJ,MAAI;AACF,WAAO,YAAY,UAAU,SAAS,KAAK,KAAK;AAAA,EAClD,QAAQ;AACN,UAAM,IAAI;AAAA,MACR,WAAW,IAAI;AAAA,IAAA;AAAA,EAEnB;AACA,QAAM,SAAS,YAAY,KAAK,IAAI;AACpC,QAAM,MACJ,SAAS,uBAAuB,OAAO,aAAa,SAAS,IAAI;AAEnE,QAAM,QAAQ,MACV,GAAG,OAAO,IAAI,OAAO,GAAS,EAAE,SAAS,GAAG,GAAG,CAAC,GAAG,OAAO,IAAI,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,GAAG,OAAO,IAAI,GAAG,EAAE,SAAS,GAAG,GAAG,CAAC,MACvH,OAAO,mBAAmB,0BACxB,WACA,SAAS,IAAI,GAAG;AACvB,SAAO,EAAE,CAAC,kBAAkB,GAAG,MAAM,CAAC,mBAAmB,GAAG,MAAM,MAAA;AACpE;AAEO,SAAS,uBACd,OACQ;AACR,SAAO,GAAG,MAAM,kBAAkB,CAAC,IAAI,MAAM,mBAAmB,CAAC;AACnE;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/db-sqlite-persistence-core",
-  "version": "0.4.4",
+  "version": "0.4.7",
   "description": "SQLite persisted collection core for TanStack DB",
   "author": "TanStack Team",
   "license": "MIT",
@@ -50,13 +50,14 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@tanstack/db": "0.12.0"
+    "@tanstack/db": "0.12.3"
   },
   "peerDependencies": {
     "typescript": ">=4.7"
   },
   "devDependencies": {
-    "@vitest/coverage-istanbul": "^3.2.4"
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "temporal-polyfill": "^0.3.0"
   },
   "scripts": {
     "build": "vite build",

package/src/persisted.ts

@@ -24,10 +24,11 @@ import {
   PersistedCollectionDurabilityError,
   toPersistedCollectionDurabilityError,
 } from './errors'
-import { serializeSQLiteBigInt } from './sqlite-value'
+import { serializeSQLiteBigInt, serializeSQLiteTemporal } from './sqlite-value'
 import {
   toProcessLocalLoadSubsetOptions,
   toTransportedLoadSubsetOptions,
+  validateRemoteSubsetOptions,
 } from './remote-subset-wire'
 import {
   reportRemoteSubsetOwnerError,
@@ -543,6 +544,12 @@ export interface PersistedCollectionCoordinator {
     collectionId: string,
     mutations: Array<PersistedMutationEnvelope>,
   ) => Promise<ApplyLocalMutationsResponse>
+  /**
+   * Applies a committed transaction through the supplied adapter when present.
+   * Wrappers must forward this leader-local loan: scheduling it again can wait
+   * on the hydration that is awaiting this call. Never serialize or retain the
+   * loan after the call; ordinary work uses the registered collection adapter.
+   */
   requestApplyCommittedTx: (
     collectionId: string,
     tx: PersistedTx,
@@ -887,8 +894,9 @@ export class SingleProcessCoordinator implements PersistedCollectionCoordinator
   public async requestApplyCommittedTx(
     collectionId: string,
     tx: PersistedTx,
+    scopedAdapter?: HydrationPersistenceAdapter,
   ): Promise<ApplyCommittedTxResponse> {
-    const adapter = this.collectionAdapters.get(collectionId)
+    const adapter = scopedAdapter ?? this.collectionAdapters.get(collectionId)
     if (!adapter) {
       throw new InvalidPersistedCollectionConfigError(
         `SingleProcessCoordinator has no persistence adapter configured for collection "${collectionId}"`,
@@ -1152,6 +1160,9 @@ function toStableSerializable(value: unknown): unknown {
       return undefined
   }
 
+  const temporal = serializeSQLiteTemporal(value)
+  if (temporal) return temporal
+
   if (value instanceof Date) {
     return value.toISOString()
   }
@@ -1730,7 +1741,6 @@ class PersistedCollectionRuntime<
     await this.hydrateSubsetUnsafe(
       baseline,
       {
-        requestRemoteEnsure: false,
         lifecycleGeneration,
         bindKeySetEvidence: true,
       },
@@ -1866,6 +1876,8 @@ class PersistedCollectionRuntime<
     const truncateGeneration = this.sourceTruncateGeneration
     const routeRemoteDemandDuringHydration =
       this.canRouteRemoteDemandThroughCoordinator()
+    // Wire admission failures are permanent input errors, not transport retries.
+    if (routeRemoteDemandDuringHydration) validateRemoteSubsetOptions(options)
     this.activeSubsets.set(subsetKey, options)
     const appliedCursor = this.appliedReceiptSequence
     try {
@@ -1875,9 +1887,6 @@ class PersistedCollectionRuntime<
             this.hydrateSubsetUnsafe(
               options,
               {
-                requestRemoteEnsure:
-                  this.mode === `sync-present` &&
-                  !routeRemoteDemandDuringHydration,
                 lifecycleGeneration,
                 requestLocalLoadFailure: true,
                 rejectBufferedReplayFailure: true,
@@ -1896,6 +1905,14 @@ class PersistedCollectionRuntime<
       })
       if (lifecycleGeneration !== this.lifecycleGeneration) return
       await this.waitForAppliedReceiptsAfter(appliedCursor)
+      // Leadership can change while hydration waits. Validate newly remote
+      // demand inside the admission cleanup boundary, before retry can own it.
+      if (
+        !routeRemoteDemandDuringHydration &&
+        this.canRouteRemoteDemandThroughCoordinator()
+      ) {
+        validateRemoteSubsetOptions(options)
+      }
     } catch (error) {
       if (this.activeSubsets.get(subsetKey) === options) {
         this.activeSubsets.delete(subsetKey)
@@ -2056,7 +2073,6 @@ class PersistedCollectionRuntime<
         this.hydrateSubsetUnsafe(
           options,
           {
-            requestRemoteEnsure: false,
             lifecycleGeneration,
             rejectBufferedReplayFailure: true,
           },
@@ -2329,7 +2345,6 @@ class PersistedCollectionRuntime<
   private async hydrateSubsetUnsafe(
     options: LoadSubsetOptions,
     config: {
-      requestRemoteEnsure: boolean
       lifecycleGeneration: number
       bindKeySetEvidence?: boolean
       requestLocalLoadFailure?: boolean
@@ -2390,10 +2405,6 @@ class PersistedCollectionRuntime<
       if (config.lifecycleGeneration !== this.lifecycleGeneration) return
       replayFailure = await this.flushQueuedHydrationTransactionsUnsafe(adapter)
       if (config.lifecycleGeneration !== this.lifecycleGeneration) return
-
-      if (config.requestRemoteEnsure && !replayFailure) {
-        this.queueRemoteSubsetEnsure(options)
-      }
     } catch (error) {
       if (config.requestLocalLoadFailure && !rowsLoaded) {
         // Keep admitting source work to the hydration queue while recovery
@@ -3262,6 +3273,9 @@ class PersistedCollectionRuntime<
     const subsetKey = this.getSubsetKey(options)
     if (this.activeSubsets.get(subsetKey) !== options) return
 
+    // A previously local acquisition can become remote after an ownership
+    // change. Recovery must reject permanent wire errors before retry owns it.
+    validateRemoteSubsetOptions(options)
     this.pendingRemoteSubsetEnsures.set(subsetKey, options)
     void this.flushPendingRemoteSubsetEnsures()
   }
@@ -3808,9 +3822,8 @@ class PersistedCollectionRuntime<
     indexMetadata: CollectionIndexMetadata,
     adapter: HydrationPersistenceAdapter,
   ): Promise<boolean> {
-    const spec = this.buildPersistedIndexSpec(indexMetadata)
-
     try {
+      const spec = this.buildPersistedIndexSpec(indexMetadata)
       await adapter.ensureIndex(
         this.collectionId,
         indexMetadata.signature,
@@ -3827,9 +3840,8 @@ class PersistedCollectionRuntime<
     indexMetadata: CollectionIndexMetadata,
     completedLocally: boolean,
   ): Promise<void> {
-    const spec = this.buildPersistedIndexSpec(indexMetadata)
-
     try {
+      const spec = this.buildPersistedIndexSpec(indexMetadata)
       await this.persistence.coordinator.requestEnsurePersistedIndex(
         this.collectionId,
         indexMetadata.signature,
@@ -4590,6 +4602,9 @@ function createWrappedSyncConfig<
             return visibleAfterDurable(openTransaction, applied)
           }
 
+          // Admission is complete. Only queued hydration replay remains tied
+          // to its sequence; retain hydrationContext for row metadata ownership.
+          openTransaction.hydrationSequence = undefined
           let applied: Promise<void>
           try {
             applied = runtime.applyHydrationBufferedTransaction(transaction)