@absolutejs/sync 1.21.0 → 1.23.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 = {};
@@ -3026,7 +3063,7 @@ var syncCdc = ({
 };
 // src/devtools.ts
 import { Elysia as Elysia3 } from "elysia";
-var dashboardHtml = (streamPath) => `<!doctype html>
+var dashboardHtml = (streamPath, replayPath) => `<!doctype html>
 <html lang="en"><head><meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>@absolutejs/sync devtools</title>
@@ -3049,12 +3086,37 @@ th{color:#7f849c;font-weight:600}
 .t-change{color:#94e2d5}.t-mutation{color:#cba6f7}.err{color:#f38ba8}
 .pill{padding:0 6px;border-radius:10px;background:#1c2230;flex:0 0 auto}
 .empty{color:#6c7086;padding:6px}
+.replay{grid-column:1/3}
+.replay-controls{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-bottom:8px}
+.replay-controls input{background:#0b0e14;border:1px solid #1c2230;color:#cdd6f4;border-radius:4px;padding:4px 6px;font:inherit}
+.replay-controls input[type="datetime-local"]{min-width:200px}
+.replay-controls input[type="text"]{min-width:180px}
+.replay-controls button{background:#89b4fa;border:none;color:#0b0e14;border-radius:4px;padding:5px 12px;font:inherit;font-weight:600;cursor:pointer}
+.replay-controls button:hover{background:#74c7ec}
+.replay-controls button:disabled{background:#1c2230;color:#6c7086;cursor:not-allowed}
+.replay-controls label{color:#7f849c;display:flex;align-items:center;gap:6px}
+.truncated{background:#311b1b;border:1px solid #f38ba8;color:#f38ba8;padding:6px 10px;border-radius:4px;margin-bottom:8px}
+.replay-meta{color:#a6adc8;margin-bottom:8px}
+.replay-meta b{color:#cdd6f4}
+.replay-table{margin-top:10px}
+.replay-table h3{margin:0 0 4px;color:#94e2d5;font-size:12px;font-weight:600}
+.replay-rows pre{margin:0;font-size:11px;color:#a6adc8;background:#0b0e14;border:1px solid #1c2230;border-radius:4px;padding:6px;max-height:200px;overflow:auto;white-space:pre-wrap;word-break:break-word}
 </style></head>
 <body>
 <header><b>@absolutejs/sync</b> devtools <span id="status" class="empty">connecting\u2026</span><span class="ver">v<span id="version">0</span></span></header>
 <main>
 <section><h2>Collections</h2><table><thead><tr><th>name</th><th>kind</th><th>tables</th><th class="subs">subs</th></tr></thead><tbody id="collections"></tbody></table></section>
 <section><h2>Mutations \xB7 Schedules</h2><div id="ops"></div></section>
+<section class="replay"><h2>Point-in-time replay</h2>
+<div class="replay-controls">
+  <label>at <input type="datetime-local" id="replay-at" step="1" /></label>
+  <label>tables <input type="text" id="replay-tables" placeholder="(all if blank \u2014 csv)" /></label>
+  <label>max rows per table <input type="number" id="replay-max" value="10" min="1" max="500" style="width:64px" /></label>
+  <button id="replay-go">Replay</button>
+  <button id="replay-now" type="button" title="Set datetime to right now">Now</button>
+</div>
+<div id="replay-result"><div class="empty">Pick a date+time, optionally filter tables, then click Replay to reconstruct state at that point in the log window.</div></div>
+</section>
 <section class="log"><h2>Activity</h2><div id="activity"><div class="empty">waiting for changes &amp; mutations\u2026</div></div></section>
 </main>
 <script>
@@ -3083,6 +3145,57 @@ const logActivity=(a)=>{
   box.prepend(row);
   while(box.childNodes.length>200)box.removeChild(box.lastChild);
 };
+const localToMs=(value)=>{
+  if(!value)return null;
+  const ms=new Date(value).getTime();
+  return Number.isFinite(ms)?ms:null;
+};
+const msToLocal=(ms)=>{
+  const d=new Date(ms);
+  const pad=(n)=>String(n).padStart(2,'0');
+  return d.getFullYear()+'-'+pad(d.getMonth()+1)+'-'+pad(d.getDate())+'T'+pad(d.getHours())+':'+pad(d.getMinutes())+':'+pad(d.getSeconds());
+};
+const renderReplay=(result, maxRows)=>{
+  const box=$('replay-result');
+  const tables=Object.keys(result.rows).sort();
+  const trunc=result.truncated?'<div class="truncated">\u26A0 Replay truncated \u2014 log retention window doesn\\'t cover this timestamp. Result is best-effort, walked forward from the oldest retained entry.</div>':'';
+  const meta='<div class="replay-meta">As of <b>version '+result.asOfVersion+'</b> at <b>'+(result.asOfAt?new Date(result.asOfAt).toLocaleString():'(no entries folded)')+'</b></div>';
+  if(tables.length===0){
+    box.innerHTML=trunc+meta+'<div class="empty">No rows in any table at this timestamp.</div>';
+    return;
+  }
+  const sections=tables.map((t)=>{
+    const rows=result.rows[t];
+    const total=rows.length;
+    const shown=rows.slice(0,maxRows);
+    const more=total>maxRows?'<div class="empty">\u2026 '+(total-maxRows)+' more rows omitted</div>':'';
+    return '<div class="replay-table"><h3>'+esc(t)+' <span class="empty">('+total+' row'+(total===1?'':'s')+')</span></h3><div class="replay-rows"><pre>'+esc(JSON.stringify(shown,null,2))+'</pre>'+more+'</div></div>';
+  });
+  box.innerHTML=trunc+meta+sections.join('');
+};
+const doReplay=async()=>{
+  const at=localToMs($('replay-at').value);
+  if(at===null){alert('Please pick a valid date+time');return;}
+  const tables=$('replay-tables').value.split(',').map((s)=>s.trim()).filter(Boolean);
+  const maxRows=Math.max(1,Math.min(500,parseInt($('replay-max').value)||10));
+  const btn=$('replay-go');btn.disabled=true;btn.textContent='Replaying\u2026';
+  try{
+    const params=new URLSearchParams();
+    params.set('at',String(at));
+    if(tables.length>0)params.set('tables',tables.join(','));
+    const res=await fetch('${replayPath}?'+params.toString());
+    if(!res.ok){throw new Error('HTTP '+res.status);}
+    const result=await res.json();
+    renderReplay(result,maxRows);
+  }catch(e){
+    $('replay-result').innerHTML='<div class="truncated">Replay failed: '+esc(e.message)+'</div>';
+  }finally{
+    btn.disabled=false;btn.textContent='Replay';
+  }
+};
+$('replay-go').addEventListener('click',doReplay);
+$('replay-now').addEventListener('click',()=>{$('replay-at').value=msToLocal(Date.now());});
+$('replay-at').value=msToLocal(Date.now()-60*60*1000); // default: 1 hour ago
 const src=new EventSource('${streamPath}');
 src.addEventListener('open',()=>{$('status').textContent='live';$('status').className='';});
 src.addEventListener('error',()=>{$('status').textContent='reconnecting\u2026';$('status').className='empty';});
@@ -3095,9 +3208,44 @@ var syncDevtools = ({
   snapshotMs = 2000
 }) => {
   const streamPath = `${path}/stream`;
-  return new Elysia3({ name: "@absolutejs/sync/devtools" }).get(path, () => new Response(dashboardHtml(streamPath), {
+  const replayPath = `${path}/replay`;
+  return new Elysia3({ name: "@absolutejs/sync/devtools" }).get(path, () => new Response(dashboardHtml(streamPath, replayPath), {
     headers: { "content-type": "text/html; charset=utf-8" }
-  })).get(streamPath, (context) => {
+  })).get(replayPath, async (context) => {
+    const url = new URL(context.request.url);
+    const atRaw = url.searchParams.get("at");
+    const atMs = atRaw === null ? NaN : Number(atRaw);
+    if (!Number.isFinite(atMs)) {
+      return new Response(JSON.stringify({
+        error: "invalid `at` \u2014 must be a numeric ms timestamp"
+      }), {
+        headers: {
+          "content-type": "application/json; charset=utf-8"
+        },
+        status: 400
+      });
+    }
+    const tablesRaw = url.searchParams.get("tables");
+    const tables = tablesRaw === null || tablesRaw.length === 0 ? undefined : tablesRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    try {
+      const result = await engine.replayTo(tables === undefined ? { at: atMs } : { at: atMs, tables });
+      return new Response(JSON.stringify(result), {
+        headers: {
+          "cache-control": "no-store",
+          "content-type": "application/json; charset=utf-8"
+        }
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({
+        error: error instanceof Error ? error.message : String(error)
+      }), {
+        headers: {
+          "content-type": "application/json; charset=utf-8"
+        },
+        status: 500
+      });
+    }
+  }).get(streamPath, (context) => {
     const encoder = new TextEncoder;
     const stream = new ReadableStream({
       start(controller) {
@@ -3218,5 +3366,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=06ECBF0C02EA0B8464756E2164756E21
+//# debugId=9662318FD91E917A64756E2164756E21
 //# sourceMappingURL=index.js.map