@absolutejs/sync 1.18.1 → 1.19.0

package/dist/engine/syncEngine.d.ts

@@ -266,6 +266,36 @@ export type SyncEngine = {
      * Added in 1.13.0.
      */
     metrics: () => EngineMetrics;
+    /**
+     * Capture the engine's change log + version as a serializable
+     * {@link ChangeLogSnapshot} the host can persist (disk, S3, the cluster
+     * bus) and restore on the next boot via
+     * {@link SyncEngineOptions.initialChangeLog} or
+     * {@link SyncEngine.importChangeLog}. The receiving engine MUST share this
+     * engine's `instanceId` — otherwise the resume contract silently breaks.
+     *
+     * Cheap: the snapshot's `entries` is a shallow copy of the bounded log
+     * (capped by `changeLogSize` / `changeLogRetainMs`). Call on a timer or on
+     * graceful shutdown — both are fine; the snapshot is monotonic in commit
+     * order, so a partial roll-forward (apply entries newer than the snapshot
+     * from another source) is safe.
+     *
+     * Added in 1.19.0.
+     */
+    exportChangeLog: () => ChangeLogSnapshot;
+    /**
+     * Adopt a {@link ChangeLogSnapshot} into a running engine that has not yet
+     * committed any local changes (its `version` is 0). The snapshot's
+     * `instanceId` MUST match this engine's `instanceId`. Throws otherwise.
+     *
+     * Convenience for hosts that want to set up the engine, register surfaces,
+     * AND THEN restore. Equivalent to passing the snapshot via
+     * `createSyncEngine({ initialChangeLog })` if you have it at construction
+     * time. Returns the number of entries imported.
+     *
+     * Added in 1.19.0.
+     */
+    importChangeLog: (snapshot: ChangeLogSnapshot) => number;
     /**
      * Subscribe to the live engine activity stream (changes, mutation outcomes,
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.
@@ -384,6 +414,35 @@ export declare class CdcConsumerSlowError extends Error {
     readonly lastDeliveredVersion: number;
     constructor(maxBuffer: number, lastDeliveredVersion: number);
 }
+/**
+ * Serializable snapshot of an engine's change log + monotonic version, returned
+ * by {@link SyncEngine.exportChangeLog} and consumed by
+ * {@link SyncEngineOptions.initialChangeLog} or
+ * {@link SyncEngine.importChangeLog}.
+ *
+ * The PaaS host persists this on shard rotation (every N seconds or on graceful
+ * shutdown) and hands it back to the replacement engine so resume cursors
+ * referencing this `instanceId` keep working past the restart. Bounded by the
+ * receiving engine's `changeLogSize` + `changeLogRetainMs` policies — entries
+ * that exceed either cap on import are trimmed exactly as if they had been
+ * logged live.
+ *
+ * Added in 1.19.0.
+ */
+export type ChangeLogSnapshot = {
+    /** The exporting engine's `instanceId`. Receiver MUST match. */
+    instanceId: string;
+    /** The exporting engine's monotonic version at snapshot time. */
+    version: number;
+    /** Every retained log entry, in commit order (oldest first). */
+    entries: ReadonlyArray<LoggedChange>;
+    /**
+     * Optional version-stamp the host may use to compare snapshots without
+     * deserializing the entries (e.g. for incremental persistence). Set to
+     * `Date.now()` at export time. Receivers ignore this field.
+     */
+    exportedAt?: number;
+};
 export type SyncEngineOptions = {
     /**
      * Stable identifier for this engine instance. Defaults to a per-process
@@ -482,6 +541,22 @@ export type SyncEngineOptions = {
      * @see {@link BridgeFetchConfig}
      */
     bridgeFetch?: BridgeFetchConfig;
+    /**
+     * Seed the engine's change log on boot from a prior snapshot — produced by
+     * {@link SyncEngine.exportChangeLog} on the previous instance, persisted by
+     * the host across a shard reboot, then handed back here. Cursors that
+     * referenced this engine's `instanceId` stay resumable past the restart
+     * (provided their last-seen point still lives in the retained log).
+     *
+     * The snapshot's `instanceId` MUST match `options.instanceId` (otherwise
+     * `createSyncEngine` throws — a wrong-id restore would silently break the
+     * resume contract). Snapshot `version` becomes this engine's local
+     * monotonic version; entries are inserted in version order. Subscribers,
+     * permissions, schemas, schedules, packs, mutations, and the reactive
+     * cache are NOT in the snapshot — re-register them as normal after
+     * `createSyncEngine` returns. Added in 1.19.0.
+     */
+    initialChangeLog?: ChangeLogSnapshot;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/dist/index.js

@@ -1309,6 +1309,31 @@ var createSyncEngine = (options = {}) => {
   const runInTransaction = options.transaction;
   const instanceId = options.instanceId ?? globalThis.crypto?.randomUUID?.() ?? `i${Math.random()}`;
   let clusterBus;
+  const importChangeLog = (snapshot) => {
+    if (version !== 0) {
+      throw new Error(`[sync] importChangeLog: engine already has version ${version}; ` + `restore must happen before any local writes commit.`);
+    }
+    if (snapshot.instanceId !== instanceId) {
+      throw new Error(`[sync] importChangeLog: snapshot instanceId "${snapshot.instanceId}" ` + `does not match this engine's instanceId "${instanceId}". ` + `Pass options.instanceId = "${snapshot.instanceId}" to createSyncEngine.`);
+    }
+    version = snapshot.version;
+    for (const entry of snapshot.entries) {
+      changeLog.push(entry);
+    }
+    while (changeLog.length > changeLogSize) {
+      changeLog.shift();
+    }
+    if (changeLogRetainMs !== null && changeLogRetainMs > 0) {
+      const cutoff = Date.now() - changeLogRetainMs;
+      while (changeLog.length > 0 && changeLog[0].at < cutoff) {
+        changeLog.shift();
+      }
+    }
+    return snapshot.entries.length;
+  };
+  if (options.initialChangeLog !== undefined) {
+    importChangeLog(options.initialChangeLog);
+  }
   const broadcast = (changes, originVersion) => {
     if (clusterBus !== undefined && changes.length > 0) {
       clusterBus.publish({ changes, origin: instanceId, originVersion });
@@ -1832,13 +1857,20 @@ var createSyncEngine = (options = {}) => {
         oldestPerOrigin.set(entry.origin, entry.originVersion);
       }
     }
+    const oldestLogVersion = changeLog[0]?.version;
     for (const [origin, lastSeen] of Object.entries(sinceVec)) {
       if (origin === instanceId) {
         if (lastSeen >= version)
           continue;
         const oldestLocal = oldestPerOrigin.get(instanceId);
-        if (oldestLocal === undefined || oldestLocal > lastSeen + 1)
+        if (oldestLocal !== undefined) {
+          if (oldestLocal > lastSeen + 1)
+            return false;
+          continue;
+        }
+        if (oldestLogVersion !== undefined && oldestLogVersion > lastSeen + 1) {
           return false;
+        }
       } else {
         const oldestPeer = oldestPerOrigin.get(origin);
         if (oldestPeer === undefined) {
@@ -2571,6 +2603,13 @@ var createSyncEngine = (options = {}) => {
         }))
       };
     },
+    exportChangeLog: () => ({
+      entries: changeLog.slice(),
+      exportedAt: Date.now(),
+      instanceId,
+      version
+    }),
+    importChangeLog,
     metrics: () => {
       const now = Date.now();
       const byCollection = {};
@@ -2986,5 +3025,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=8942CF1B0DE51E1664756E2164756E21
+//# debugId=EB8C381967D0311A64756E2164756E21
 //# sourceMappingURL=index.js.map