@rotorsoft/act 1.1.0 → 1.2.0

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-TN4XS7WE.js";
+} from "./chunk-J6NDEEXC.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -899,6 +899,60 @@ async function tombstone(stream, expectedVersion, correlation) {
     throw error;
   }
 }
+function isValid(event) {
+  if (event.version < 0) return false;
+  if (!(event.created instanceof Date) || Number.isNaN(event.created.getTime()))
+    return false;
+  return true;
+}
+async function scan(source, opts = {}, callback) {
+  const { drop_snapshots = false, on_progress } = opts;
+  const idMap = /* @__PURE__ */ new Map();
+  let kept = 0;
+  let droppedSnapshots = 0;
+  let processed = 0;
+  for await (const event of source) {
+    processed++;
+    if (!isValid(event)) throw new Error(`Invalid event at index ${processed}`);
+    if (on_progress) on_progress({ processed });
+    if (drop_snapshots && event.name === SNAP_EVENT) {
+      droppedSnapshots++;
+      continue;
+    }
+    if (!callback) {
+      kept++;
+      continue;
+    }
+    let remapped = event;
+    const causedBy = event.meta.causation.event?.id;
+    if (causedBy !== void 0) {
+      const newCausedBy = idMap.get(causedBy);
+      if (newCausedBy !== void 0 && newCausedBy !== causedBy) {
+        remapped = {
+          ...event,
+          meta: {
+            ...event.meta,
+            causation: {
+              ...event.meta.causation,
+              event: { ...event.meta.causation.event, id: newCausedBy }
+            }
+          }
+        };
+      }
+    }
+    const newId = await callback(remapped);
+    idMap.set(event.id, newId);
+    kept++;
+  }
+  return {
+    kept,
+    dropped: {
+      closed_streams: 0,
+      snapshots: droppedSnapshots,
+      empty_streams: 0
+    }
+  };
+}
 async function load(me, stream, callback, asOf) {
   const timeTravel = !!asOf && Object.values(asOf).some((v) => v !== void 0);
   const cached = timeTravel ? void 0 : await cache().get(stream);
@@ -2533,6 +2587,67 @@ var Act = class {
       return count;
     });
   }
+  /**
+   * Atomically wipe the store and rebuild it from an async stream of
+   * committed events. The framework owns iteration, validation,
+   * `drop_snapshots` filtering, `on_progress`, and the per-call
+   * `old → new` causation remap; the adapter's {@link Store.restore}
+   * driver supplies the transaction lifecycle and per-event insert.
+   *
+   * Throws if the adapter has no restore capability. Throws on the
+   * first invalid event (negative version, malformed `created`) with
+   * the running index in the message; atomic transaction rollback in
+   * the adapter means a failing restore leaves the store byte-for-byte
+   * unchanged.
+   *
+   * @param source - Async stream of events in target order. Streamed
+   *   rather than buffered so multi-million-event backups don't OOM.
+   *   Each event's original `id` is used as a causation lookup key but
+   *   never written through — adapters renumber densely.
+   * @param opts - {@link ScanOptions}. `drop_snapshots` skips
+   *   `__snapshot__` events (counted in the result); `on_progress`
+   *   fires once per event.
+   * @returns {@link ScanResult} with `kept`, `duration_ms`, and
+   *   `dropped` per-category counters.
+   *
+   * @example Round-trip a CSV backup
+   * ```typescript
+   * async function* parseCsv(blob: string) {
+   *   for (const line of blob.split("\n").slice(1)) {
+   *     const [id, name, data, stream, version, created, meta] = parse(line);
+   *     yield {
+   *       id: +id, name, data: JSON.parse(data), stream,
+   *       version: +version, created: new Date(created),
+   *       meta: JSON.parse(meta),
+   *     };
+   *   }
+   * }
+   * const result = await app.restore(parseCsv(csvBlob), {});
+   * console.log(`Restored ${result.kept} events in ${result.duration_ms}ms`);
+   * await cache().clear();   // operator's responsibility
+   * ```
+   *
+   * @see {@link Store.restore} for the underlying driver-pattern primitive.
+   */
+  async restore(source, opts = {}) {
+    return this._scoped(async () => {
+      const started = Date.now();
+      if (opts.dry_run) {
+        const partial = await scan(source, opts);
+        return { ...partial, duration_ms: Date.now() - started };
+      }
+      const s = store();
+      if (!s.restore) throw new Error("adapter has no restore capability");
+      let kept = 0;
+      let dropped = { closed_streams: 0, snapshots: 0, empty_streams: 0 };
+      await s.restore(async (callback) => {
+        const partial = await scan(source, opts, callback);
+        kept = partial.kept;
+        dropped = partial.dropped;
+      });
+      return { kept, dropped, duration_ms: Date.now() - started };
+    });
+  }
   /**
    * Return every currently-blocked stream position. Convenience wrapper
    * around `store().query_streams(cb, { blocked: true })` for the common