@absolutejs/sync 1.21.0 → 1.22.0

package/dist/engine/syncEngine.d.ts

@@ -297,6 +297,33 @@ export type SyncEngine = {
      * Added in 1.19.0.
      */
     importChangeLog: (snapshot: ChangeLogSnapshot) => number;
+    /**
+     * Reconstruct the state of registered tables as of a target
+     * timestamp by walking the change log forward and folding each op
+     * into a per-table view. Useful for forensic incident response
+     * ("what did the tenant see at 14:32?") and the "I deleted prod
+     * — restore us to 2h ago" recovery story.
+     *
+     * The reconstruction is exact when the log spans `targetAt` (i.e.
+     * the log's oldest entry is at version 1). When the log has been
+     * trimmed (`changeLogSize` / `changeLogRetainMs` evicted older
+     * entries) AND `targetAt` falls in the gap, the result is
+     * best-effort: state walked forward from the OLDEST retained
+     * entry, with `truncated: true` so the caller knows.
+     *
+     * Added in 1.22.0.
+     *
+     * @example
+     * ```ts
+     * const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
+     * const result = await engine.replayTo({ at: twoHoursAgo, tables: ['orders'] });
+     * if (result.truncated) {
+     *   console.warn('Replay truncated — log retention window too short.');
+     * }
+     * console.log(result.rows.orders); // orders as of two hours ago
+     * ```
+     */
+    replayTo: (options: ReplayOptions) => Promise<ReplayResult>;
     /**
      * Subscribe to the live engine activity stream (changes, mutation outcomes,
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.
@@ -467,6 +494,48 @@ export type ChangeLogSnapshot = {
      */
     exportedAt?: number;
 };
+/**
+ * Options for {@link SyncEngine.replayTo}. Added in 1.22.0.
+ */
+export type ReplayOptions = {
+    /**
+     * Target timestamp (`Date.now()`-shaped). The engine walks the
+     * change log forward, applying entries with `at <= targetAt`. The
+     * result is the state as-of `targetAt` (or as close as the log
+     * permits — see `truncated`).
+     */
+    at: number;
+    /**
+     * Optional table filter. When set, only entries whose `table` is
+     * in this list are folded into the result; entries for other
+     * tables are skipped. Useful for "show me what `tasks` looked
+     * like at T" without paying to reconstruct every table.
+     */
+    tables?: ReadonlyArray<string>;
+};
+/**
+ * Returned by {@link SyncEngine.replayTo}. Added in 1.22.0.
+ *
+ * - `rows` — per-table arrays of rows that existed as of `asOfAt`.
+ *   Keys are table names; values are the row objects (in last-write
+ *   order — last write wins for duplicate-keyed inserts).
+ * - `asOfVersion` / `asOfAt` — the version + wall-clock of the LAST
+ *   entry folded into the result. May be earlier than `targetAt` if
+ *   no entries existed between the last-included entry and the
+ *   target.
+ * - `truncated` — `true` when the log has been trimmed past the
+ *   target window (`changeLog[0].version > 1 && changeLog[0].at >
+ *   targetAt`). In this case, `rows` represents the state walked
+ *   forward from the OLDEST retained entry — NOT the actual state
+ *   at `targetAt`. The caller should treat the result as
+ *   "best-effort given retention window" and warn the operator.
+ */
+export type ReplayResult = {
+    asOfVersion: number;
+    asOfAt: number;
+    rows: Record<string, ReadonlyArray<unknown>>;
+    truncated: boolean;
+};
 export type SyncEngineOptions = {
     /**
      * Stable identifier for this engine instance. Defaults to a per-process

package/dist/index.js

@@ -2801,6 +2801,43 @@ var createSyncEngine = (options = {}) => {
       version
     }),
     importChangeLog,
+    replayTo: async ({ at, tables }) => {
+      const filterTables = tables !== undefined ? new Set(tables) : undefined;
+      const state = new Map;
+      let asOfVersion = 0;
+      let asOfAt = 0;
+      const oldest = changeLog[0];
+      const truncated = oldest !== undefined && oldest.version > 1 && oldest.at > at;
+      for (const entry of changeLog) {
+        if (entry.at > at)
+          break;
+        if (filterTables !== undefined && !filterTables.has(entry.table)) {
+          continue;
+        }
+        let tableState = state.get(entry.table);
+        if (tableState === undefined) {
+          tableState = new Map;
+          state.set(entry.table, tableState);
+        }
+        const reader = readers.get(entry.table);
+        const key = reader?.key?.(entry.change.row) ?? entry.change.row?.id;
+        if (key === undefined) {
+          continue;
+        }
+        if (entry.change.op === "delete") {
+          tableState.delete(key);
+        } else {
+          tableState.set(key, entry.change.row);
+        }
+        asOfVersion = entry.version;
+        asOfAt = entry.at;
+      }
+      const rows = {};
+      for (const [table, map] of state) {
+        rows[table] = [...map.values()];
+      }
+      return { asOfAt, asOfVersion, rows, truncated };
+    },
     metrics: () => {
       const now = Date.now();
       const byCollection = {};
@@ -3218,5 +3255,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=06ECBF0C02EA0B8464756E2164756E21
+//# debugId=6DBA546C7A7B1DC564756E2164756E21
 //# sourceMappingURL=index.js.map