@pylonsync/sync 0.3.316 → 0.3.318

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { type RoomError, type RoomMember, type RoomSubscriber } from "./room-sub
 import { SessionResolver } from "./session-resolver";
 export { RoomSubscriptions, type RoomError, type RoomErrorCode, type RoomMember, type RoomMessage, type RoomMessageSubscriber, type RoomSubscriber, } from "./room-subscriptions";
 export { IndexedDBPersistence, persistChange } from "./persistence";
+export type { ReplicaPersistence } from "./persistence";
 export { buildRequest, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
 export type { PylonRequestInit, TransportConfig } from "./transport";
 export { LocalStore } from "./local-store";
@@ -26,6 +27,13 @@ export interface SyncEngineConfig {
     token?: string;
     /** Enable IndexedDB persistence. Data survives page refresh. Default: true in browser. */
     persist?: boolean;
+    /**
+     * Replica persistence backend. Default: IndexedDB where available
+     * (browsers). Non-browser hosts (React Native, Tauri) inject an adapter
+     * here — without one their replica is memory-only and a cold offline
+     * launch shows an empty store. `persist: false` still disables entirely.
+     */
+    persistence?: import("./persistence").ReplicaPersistence;
     /** App name for IndexedDB database naming. Default: "default". */
     appName?: string;
     /**

package/dist/persistence.d.ts

@@ -1,9 +1,31 @@
 import type { Row, ChangeEvent, SyncCursor, MutationQueuePersistence, PendingMutation } from "./index";
+/**
+ * The engine's durable-replica backend. IndexedDBPersistence is the browser
+ * implementation; non-browser hosts (React Native, Tauri) implement this
+ * and pass it via `SyncEngineConfig.persistence` — the exact call surface
+ * the engine + `persistChange` use, nothing more.
+ */
+export interface ReplicaPersistence {
+    open(): Promise<void>;
+    /** Rows + cursor read as ONE consistent snapshot (see warm-load notes). */
+    loadSnapshot(): Promise<{
+        entities: Record<string, Row[]>;
+        cursor: SyncCursor | null;
+        hadCache: boolean;
+    }>;
+    /** `undefined` = never recorded (fresh install); `null` = anonymous. */
+    loadIdentity(): Promise<string | null | undefined>;
+    saveIdentity(userId: string | null): Promise<boolean>;
+    saveCursor(cursor: SyncCursor): Promise<boolean>;
+    saveRow(entity: string, id: string, data: Row): Promise<boolean>;
+    deleteRow(entity: string, id: string): Promise<boolean>;
+    clear(): Promise<boolean>;
+}
 /**
  * IndexedDB-backed persistence for the sync store.
  * Saves entity rows and sync cursor so data survives page refresh.
  */
-export declare class IndexedDBPersistence {
+export declare class IndexedDBPersistence implements ReplicaPersistence {
     private db;
     private dbName;
     /** Shared connection. Exposed so sibling persistence classes (e.g. the
@@ -103,7 +125,7 @@ export declare class IndexedDBPersistence {
  * can hold the persisted cursor back rather than skip the row on restart).
  * A change with no `data` is a no-op and counts as durable.
  */
-export declare function persistChange(persistence: IndexedDBPersistence, change: ChangeEvent): Promise<boolean>;
+export declare function persistChange(persistence: ReplicaPersistence, change: ChangeEvent): Promise<boolean>;
 /**
  * IndexedDB-backed implementation of `MutationQueuePersistence`. Wires the
  * `MutationQueue` into the same database as the entity mirror so everything

package/dist/session-resolver.d.ts

@@ -28,6 +28,7 @@ export interface TokenTransition {
 }
 export declare class SessionResolver {
     private _resolved;
+    private _observed;
     /** `undefined` until the first observation — distinguishes "we've
      *  never seen a token" from "the token is null." Same for tenant. */
     private lastSeenToken;
@@ -57,6 +58,10 @@ export declare class SessionResolver {
      *  Production callers should use `inspectSession` + `commitObservation`
      *  to control the timing of state mutation. */
     observeSession(next: ResolvedSession): SessionTransition;
+    /** Has /api/auth/me actually resolved THIS run? False on an offline
+     *  start — callers that would destroy state on an identity mismatch
+     *  (replica wipes) must not act on the EMPTY placeholder session. */
+    hasObserved(): boolean;
     /** Feed in the current bearer token. Returns whether it flipped
      *  since the previous observation. The engine uses this in pull()
      *  to decide whether to reset before reading the cursor. */

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.316",
+  "version": "0.3.318",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/custom-persistence.test.ts

@@ -0,0 +1,144 @@
+// Pluggable replica persistence (SyncEngineConfig.persistence).
+//
+// Non-browser hosts (React Native, Tauri) have no IndexedDB — before this
+// config existed their replica was memory-only and a cold offline launch
+// rendered an empty store. These tests drive the engine with a MEMORY
+// adapter and prove:
+//
+//   1. A cached replica hydrates the store on start() with the network
+//      DOWN — the offline-gym cold start.
+//   2. Applied changes flow through the adapter (saveRow), so the next
+//      cold start has them.
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import {
+  SyncEngine,
+  type ReplicaPersistence,
+  type Row,
+  type SyncCursor,
+} from "./index";
+
+class MemoryPersistence implements ReplicaPersistence {
+  entities = new Map<string, Map<string, Row>>();
+  cursor: SyncCursor | null = null;
+  identity: string | null | undefined = undefined;
+  savedRows: Array<[string, string]> = [];
+
+  async open(): Promise<void> {}
+  async loadSnapshot() {
+    const entities: Record<string, Row[]> = {};
+    for (const [e, rows] of this.entities) entities[e] = [...rows.values()];
+    return {
+      entities,
+      cursor: this.cursor,
+      hadCache: this.entities.size > 0 || this.cursor != null,
+    };
+  }
+  async loadIdentity() {
+    return this.identity;
+  }
+  async saveIdentity(userId: string | null) {
+    this.identity = userId;
+    return true;
+  }
+  async saveCursor(cursor: SyncCursor) {
+    this.cursor = cursor;
+    return true;
+  }
+  async saveRow(entity: string, id: string, data: Row) {
+    let m = this.entities.get(entity);
+    if (!m) {
+      m = new Map();
+      this.entities.set(entity, m);
+    }
+    m.set(id, data);
+    this.savedRows.push([entity, id]);
+    return true;
+  }
+  async deleteRow(entity: string, id: string) {
+    this.entities.get(entity)?.delete(id);
+    return true;
+  }
+  async clear() {
+    this.entities.clear();
+    this.cursor = null;
+    return true;
+  }
+}
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+function offlineFetch(): typeof fetch {
+  return (() => Promise.reject(new TypeError("network down"))) as typeof fetch;
+}
+
+function makeEngine(persistence: ReplicaPersistence): SyncEngine {
+  return new SyncEngine({
+    baseUrl: "http://sync-test.invalid",
+    transport: "poll",
+    persistence,
+    appName: "custom-persistence-test",
+  });
+}
+
+let engine: SyncEngine | null = null;
+beforeEach(() => {
+  engine = null;
+});
+afterEach(async () => {
+  await engine?.stop();
+});
+
+test("cold OFFLINE start hydrates the store from a custom adapter", async () => {
+  const mem = new MemoryPersistence();
+  mem.identity = "user-1";
+  mem.cursor = { last_seq: 42 };
+  mem.entities.set(
+    "Workout",
+    new Map([
+      ["w1", { id: "w1", title: "Cached Leg Day", ownerId: "user-1" }],
+      ["w2", { id: "w2", title: "Cached Push Day", ownerId: "user-1" }],
+    ]),
+  );
+
+  globalThis.fetch = offlineFetch();
+  engine = makeEngine(mem);
+  await engine.start();
+
+  const rows = engine.store.list("Workout");
+  expect(rows.length).toBe(2);
+  expect(rows.map((r) => r.title).sort()).toEqual([
+    "Cached Leg Day",
+    "Cached Push Day",
+  ]);
+});
+
+test("applied changes persist through the adapter", async () => {
+  const mem = new MemoryPersistence();
+  globalThis.fetch = offlineFetch();
+  engine = makeEngine(mem);
+  await engine.start();
+
+  await engine.store.applyChangesAsync([
+    {
+      kind: "insert",
+      entity: "Workout",
+      row_id: "w9",
+      seq: 1,
+      data: { id: "w9", title: "New Session" },
+      timestamp: "",
+    },
+  ]);
+  // Adapter writes settle on the applyChanges await (the engine passes
+  // each change through persistChange → saveRow).
+  expect(mem.savedRows.some(([e, id]) => e === "Workout" && id === "w9")).toBe(true);
+
+  // ...and the NEXT engine (fresh memory) sees it on a cold offline start.
+  await engine.stop();
+  engine = makeEngine(mem);
+  await engine.start();
+  expect(engine.store.list("Workout").some((r) => r.id === "w9")).toBe(true);
+});

package/src/index.ts

@@ -43,6 +43,7 @@ export {
   type RoomSubscriber,
 } from "./room-subscriptions";
 export { IndexedDBPersistence, persistChange } from "./persistence";
+export type { ReplicaPersistence } from "./persistence";
 export {
   buildRequest,
   pylonFetch,
@@ -117,6 +118,13 @@ export interface SyncEngineConfig {
   token?: string;
   /** Enable IndexedDB persistence. Data survives page refresh. Default: true in browser. */
   persist?: boolean;
+  /**
+   * Replica persistence backend. Default: IndexedDB where available
+   * (browsers). Non-browser hosts (React Native, Tauri) inject an adapter
+   * here — without one their replica is memory-only and a cold offline
+   * launch shows an empty store. `persist: false` still disables entirely.
+   */
+  persistence?: import("./persistence").ReplicaPersistence;
   /** App name for IndexedDB database naming. Default: "default". */
   appName?: string;
   /**
@@ -198,7 +206,7 @@ export class SyncEngine {
    *  at all and SSR-only consumers never reach start(). */
   private transport: Transport | null = null;
   private _connectionStatus: SyncConnectionStatus = "offline";
-  private persistence: import("./persistence").IndexedDBPersistence | null = null;
+  private persistence: import("./persistence").ReplicaPersistence | null = null;
 
   /**
    * Flips true once `start()` has either:
@@ -629,11 +637,17 @@ export class SyncEngine {
     this.armInitialSyncFallback();
 
     // Load persisted data if available.
-    const shouldPersist = this.config.persist !== false && typeof indexedDB !== "undefined";
+    const shouldPersist =
+      this.config.persist !== false &&
+      (this.config.persistence != null || typeof indexedDB !== "undefined");
     if (shouldPersist) {
       try {
-        const { IndexedDBPersistence } = await import("./persistence");
-        this.persistence = new IndexedDBPersistence(this.config.appName);
+        if (this.config.persistence) {
+          this.persistence = this.config.persistence;
+        } else {
+          const { IndexedDBPersistence } = await import("./persistence");
+          this.persistence = new IndexedDBPersistence(this.config.appName);
+        }
         await this.persistence.open();
 
         // Warm-load entities + cursor in ONE readonly transaction so
@@ -727,10 +741,20 @@ export class SyncEngine {
         // would let pull+reconcile sweep the optimistic ghosts before
         // push() ever fires.
         try {
-          const { IndexedDBMutationPersistence } = await import("./persistence");
-          const mqPersistence = new IndexedDBMutationPersistence(persistence);
-          this.mutations.attachPersistence(mqPersistence);
-          await this.mutations.hydrate();
+          const { IndexedDBMutationPersistence, IndexedDBPersistence } = await import(
+            "./persistence"
+          );
+          // The durable mutation queue rides the IDB connection; a custom
+          // ReplicaPersistence (RN/Tauri) doesn't carry one, so the queue
+          // stays in-memory there — pending offline writes survive within
+          // the session but not across a force-kill. Durable queues for
+          // custom adapters are a follow-up (MutationQueuePersistence is
+          // already an interface).
+          if (persistence instanceof IndexedDBPersistence) {
+            const mqPersistence = new IndexedDBMutationPersistence(persistence);
+            this.mutations.attachPersistence(mqPersistence);
+            await this.mutations.hydrate();
+          }
           // The hydrated offline writes are drained in the leader path
           // below (after `initMultiTab` settles), NOT here. We're still
           // pre-election at this point, so `isMultiTabLeader` is false
@@ -1447,6 +1471,13 @@ export class SyncEngine {
     if (!this._hadCachedReplica) return;
     const prev = this._replicaIdentity;
     if (prev === undefined) return;
+    // OFFLINE start: /api/auth/me never resolved, so the session is the
+    // EMPTY placeholder (userId null) — that's "unknown", not "anonymous".
+    // Wiping here destroyed the cached replica on every airplane-mode
+    // reload (the offline cold start persistence exists FOR). Keep the
+    // cache; if the session later resolves as a different identity, the
+    // observeSession/observeToken verdicts reset the replica then.
+    if (!this.session.hasObserved()) return;
     const now = this.session.resolved().userId;
     if (prev === now) return;
     // Identity flipped across the reload. Drop the prior identity's rows.

package/src/persistence.ts

@@ -6,6 +6,33 @@ import type {
   PendingMutation,
 } from "./index";
 
+// ---------------------------------------------------------------------------
+// Replica persistence contract
+// ---------------------------------------------------------------------------
+
+/**
+ * The engine's durable-replica backend. IndexedDBPersistence is the browser
+ * implementation; non-browser hosts (React Native, Tauri) implement this
+ * and pass it via `SyncEngineConfig.persistence` — the exact call surface
+ * the engine + `persistChange` use, nothing more.
+ */
+export interface ReplicaPersistence {
+  open(): Promise<void>;
+  /** Rows + cursor read as ONE consistent snapshot (see warm-load notes). */
+  loadSnapshot(): Promise<{
+    entities: Record<string, Row[]>;
+    cursor: SyncCursor | null;
+    hadCache: boolean;
+  }>;
+  /** `undefined` = never recorded (fresh install); `null` = anonymous. */
+  loadIdentity(): Promise<string | null | undefined>;
+  saveIdentity(userId: string | null): Promise<boolean>;
+  saveCursor(cursor: SyncCursor): Promise<boolean>;
+  saveRow(entity: string, id: string, data: Row): Promise<boolean>;
+  deleteRow(entity: string, id: string): Promise<boolean>;
+  clear(): Promise<boolean>;
+}
+
 // ---------------------------------------------------------------------------
 // IndexedDB persistence layer
 // ---------------------------------------------------------------------------
@@ -23,7 +50,7 @@ const MUTATIONS_STORE = "pendingMutations";
  * IndexedDB-backed persistence for the sync store.
  * Saves entity rows and sync cursor so data survives page refresh.
  */
-export class IndexedDBPersistence {
+export class IndexedDBPersistence implements ReplicaPersistence {
   private db: IDBDatabase | null = null;
   private dbName: string;
 
@@ -330,7 +357,7 @@ export class IndexedDBPersistence {
  * A change with no `data` is a no-op and counts as durable.
  */
 export async function persistChange(
-  persistence: IndexedDBPersistence,
+  persistence: ReplicaPersistence,
   change: ChangeEvent
 ): Promise<boolean> {
   switch (change.kind) {

package/src/session-resolver.ts

@@ -50,6 +50,7 @@ const EMPTY_SESSION: ResolvedSession = {
 
 export class SessionResolver {
   private _resolved: ResolvedSession = EMPTY_SESSION;
+  private _observed = false;
   /** `undefined` until the first observation — distinguishes "we've
    *  never seen a token" from "the token is null." Same for tenant. */
   private lastSeenToken: string | null | undefined = undefined;
@@ -110,9 +111,17 @@ export class SessionResolver {
   observeSession(next: ResolvedSession): SessionTransition {
     const verdict = this.inspectSession(next);
     this.commitObservation(next);
+    this._observed = true;
     return verdict;
   }
 
+  /** Has /api/auth/me actually resolved THIS run? False on an offline
+   *  start — callers that would destroy state on an identity mismatch
+   *  (replica wipes) must not act on the EMPTY placeholder session. */
+  hasObserved(): boolean {
+    return this._observed;
+  }
+
   /** Feed in the current bearer token. Returns whether it flipped
    *  since the previous observation. The engine uses this in pull()
    *  to decide whether to reset before reading the cursor. */