@rotorsoft/act 1.1.0 → 1.3.0

package/dist/index.cjs

@@ -36,6 +36,7 @@ __export(index_exports, {
   CommittedMetaSchema: () => CommittedMetaSchema,
   ConcurrencyError: () => ConcurrencyError,
   ConsoleLogger: () => ConsoleLogger,
+  CsvFile: () => CsvFile,
   DEFAULT_LANE: () => DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS: () => DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS: () => DEFAULT_SETTLE_DEBOUNCE_MS,
@@ -717,7 +718,7 @@ var InMemoryStore = class {
           continue;
         if (query.after && e.id <= query.after) break;
         if (query.created_after && e.created <= query.created_after) break;
-        callback(e);
+        await Promise.resolve(callback(e));
         count++;
         if (query?.limit && count >= query.limit) break;
       }
@@ -729,7 +730,7 @@ var InMemoryStore = class {
         if (query?.created_after && e.created <= query.created_after) continue;
         if (query?.before && e.id >= query.before) break;
         if (query?.created_before && e.created >= query.created_before) break;
-        callback(e);
+        await Promise.resolve(callback(e));
         count++;
         if (query?.limit && count >= query.limit) break;
       }
@@ -1154,23 +1155,19 @@ var InMemoryStore = class {
     return result;
   }
   /**
-   * Atomically rebuild the store from a stream of {@link RestoreRow}.
+   * Atomically wipe-and-rebuild the store under an in-process snapshot.
    *
-   * Captures every index state up front, clears it, then iterates the
-   * source. Any throw mid-iteration restores the snapshot, leaving
-   * the store byte-for-byte unchanged from the operator's
-   * perspective.
+   * Captures every index state up front, clears it, then hands the
+   * orchestrator a per-event insert `callback` via the driver. Any
+   * throw inside the driver restores the snapshot, leaving the store
+   * byte-for-byte unchanged from the operator's perspective.
    *
-   * `id`s are reassigned `0..N-1` as rows arrive (matching the
+   * `id`s are reassigned `0..N-1` as events arrive (matching the
    * adapter's commit-id convention — InMemory uses `_events.length`).
-   * `created` is preserved verbatim from the source. Causation
-   * references in `meta.causation.event.id` are remapped via the
-   * `old → new` table that's built as rows land — references to ids
-   * not in the source pass through unchanged.
+   * `created` is preserved verbatim from the source.
    */
-  async restore(source, _opts = {}) {
+  async restore(driver) {
     await sleep();
-    const started = Date.now();
     const prevEvents = this._events;
     const prevStreams = this._streams;
     const prevStreamVersions = this._streamVersions;
@@ -1181,50 +1178,18 @@ var InMemoryStore = class {
     this._streamVersions = /* @__PURE__ */ new Map();
     this._maxEventIdByStream = /* @__PURE__ */ new Map();
     this._maxNonSnapEventId = -1;
-    const idMap = /* @__PURE__ */ new Map();
     try {
-      let kept = 0;
-      for await (const row of source) {
+      await driver(async (event) => {
         const id = this._events.length;
-        const created = row.created instanceof Date ? row.created : new Date(row.created);
-        let meta = row.meta;
-        const causedBy = meta.causation.event?.id;
-        if (causedBy !== void 0) {
-          const remapped = idMap.get(causedBy);
-          if (remapped !== void 0 && remapped !== causedBy) {
-            meta = {
-              ...meta,
-              causation: {
-                ...meta.causation,
-                event: { ...meta.causation.event, id: remapped }
-              }
-            };
-          }
-        }
-        const committed = {
-          id,
-          stream: row.stream,
-          version: row.version,
-          created,
-          name: row.name,
-          data: row.data,
-          meta
-        };
+        const committed = { ...event, id };
         this._events.push(committed);
-        idMap.set(row.id, id);
-        this._streamVersions.set(row.stream, row.version);
-        if (row.name !== SNAP_EVENT) {
-          this._maxEventIdByStream.set(row.stream, id);
+        this._streamVersions.set(event.stream, event.version);
+        if (event.name !== SNAP_EVENT) {
+          this._maxEventIdByStream.set(event.stream, id);
           this._maxNonSnapEventId = id;
         }
-        kept++;
-      }
-      return {
-        kept,
-        duration_ms: Date.now() - started,
-        dropped: { closed_streams: 0, snapshots: 0, empty_streams: 0 },
-        dry_run: false
-      };
+        return id;
+      });
     } catch (err) {
       this._events = prevEvents;
       this._streams = prevStreams;
@@ -2124,6 +2089,51 @@ var subscribe = (streams) => store2().subscribe(streams);
 
 // src/internal/event-sourcing.ts
 var import_act_patch = require("@rotorsoft/act-patch");
+async function* iterate(source, filter) {
+  const state2 = {
+    slot: null,
+    onProduce: null,
+    onConsume: null,
+    done: false,
+    error: void 0
+  };
+  const wakeProduce = () => {
+    const fn = state2.onProduce;
+    state2.onProduce = null;
+    if (fn) fn();
+  };
+  void source.query((event) => {
+    state2.slot = event;
+    wakeProduce();
+    return new Promise((resolve) => {
+      state2.onConsume = () => resolve();
+    });
+  }, filter).then(
+    () => {
+      state2.done = true;
+      wakeProduce();
+    },
+    (err) => {
+      state2.error = err;
+      state2.done = true;
+      wakeProduce();
+    }
+  );
+  while (true) {
+    if (state2.slot === null && !state2.done)
+      await new Promise((resolve) => {
+        state2.onProduce = resolve;
+      });
+    if (state2.error) throw state2.error;
+    if (state2.slot === null) return;
+    const event = state2.slot;
+    state2.slot = null;
+    const fn = state2.onConsume;
+    state2.onConsume = null;
+    fn();
+    yield event;
+  }
+}
 async function snap(snapshot) {
   try {
     const { id, stream, name, meta, version } = snapshot.event;
@@ -2155,6 +2165,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 iterate(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 cache2().get(stream);
@@ -3789,6 +3853,70 @@ 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 = {}, sink) {
+    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 target = sink ?? (() => {
+        const s = store2();
+        if (!s.restore) throw new Error("adapter has no restore capability");
+        return s;
+      })();
+      let kept = 0;
+      let dropped = { closed_streams: 0, snapshots: 0, empty_streams: 0 };
+      await target.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
@@ -4354,6 +4482,167 @@ function action_builder(state2) {
   };
   return builder;
 }
+
+// src/csv.ts
+var import_node_fs = require("fs");
+var import_node_readline = require("readline");
+var CSV_COLUMNS = [
+  "id",
+  "name",
+  "data",
+  "stream",
+  "version",
+  "created",
+  "meta"
+];
+var CsvFile = class {
+  path;
+  blob;
+  constructor(options) {
+    if ("path" in options) {
+      this.path = options.path;
+      this.blob = null;
+    } else {
+      this.path = null;
+      this.blob = options.blob;
+    }
+  }
+  async query(callback, _filter) {
+    const lines = this.blob !== null ? linesFromBlob(this.blob) : linesFromFile(this.path);
+    let count = 0;
+    let header = null;
+    for await (const line of lines) {
+      if (!line.trim()) continue;
+      const fields = parseCsvLine(line);
+      if (!header) {
+        header = fields;
+        const expected = CSV_COLUMNS.join(",");
+        if (header.join(",") !== expected)
+          throw new Error(`Invalid CSV header. Expected: ${expected}`);
+        continue;
+      }
+      if (fields.length !== CSV_COLUMNS.length)
+        throw new Error(
+          `Row ${count + 1}: expected ${CSV_COLUMNS.length} fields, got ${fields.length}`
+        );
+      const event = {
+        id: Number.parseInt(fields[0], 10),
+        name: fields[1],
+        data: JSON.parse(fields[2]),
+        stream: fields[3],
+        version: Number.parseInt(fields[4], 10),
+        created: new Date(fields[5]),
+        meta: JSON.parse(fields[6])
+      };
+      await Promise.resolve(callback(event));
+      count++;
+    }
+    if (header === null)
+      throw new Error("CSV must have a header and at least one row");
+    return count;
+  }
+  async restore(driver) {
+    if (this.path === null)
+      throw new Error(
+        "CsvFile in blob mode is read-only \u2014 provide `path` to write"
+      );
+    const writer = (0, import_node_fs.createWriteStream)(this.path, {
+      flags: "w",
+      encoding: "utf8"
+    });
+    let nextId = 1;
+    try {
+      await writeLine(writer, CSV_COLUMNS.join(","));
+      await driver(async (event) => {
+        const id = nextId++;
+        const row = [
+          String(id),
+          csvEscape(event.name),
+          csvEscape(JSON.stringify(event.data)),
+          csvEscape(event.stream),
+          String(event.version),
+          event.created.toISOString(),
+          csvEscape(JSON.stringify(event.meta))
+        ].join(",");
+        await writeLine(writer, row);
+        return id;
+      });
+    } finally {
+      await new Promise((resolve) => writer.end(resolve));
+    }
+  }
+  async dispose() {
+  }
+};
+async function* linesFromFile(path) {
+  const stream = (0, import_node_fs.createReadStream)(path, { encoding: "utf8" });
+  const rl = (0, import_node_readline.createInterface)({
+    input: stream,
+    crlfDelay: Number.POSITIVE_INFINITY
+  });
+  try {
+    for await (const line of rl) yield line;
+  } finally {
+    rl.close();
+    stream.close();
+  }
+}
+async function* linesFromBlob(blob) {
+  let start = 0;
+  while (start < blob.length) {
+    const nl = blob.indexOf("\n", start);
+    const end = nl === -1 ? blob.length : nl;
+    yield blob.slice(start, end);
+    start = nl === -1 ? blob.length : nl + 1;
+    await Promise.resolve();
+  }
+}
+function parseCsvLine(line) {
+  const fields = [];
+  let i = 0;
+  while (i < line.length) {
+    if (line[i] === '"') {
+      let value = "";
+      i++;
+      while (i < line.length) {
+        if (line[i] === '"' && line[i + 1] === '"') {
+          value += '"';
+          i += 2;
+        } else if (line[i] === '"') {
+          i++;
+          break;
+        } else {
+          value += line[i++];
+        }
+      }
+      fields.push(value);
+      if (line[i] === ",") i++;
+    } else {
+      const next = line.indexOf(",", i);
+      if (next === -1) {
+        fields.push(line.slice(i));
+        i = line.length;
+      } else {
+        fields.push(line.slice(i, next));
+        i = next + 1;
+      }
+    }
+  }
+  return fields;
+}
+function csvEscape(value) {
+  if (/[",\n\r]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+  return value;
+}
+function writeLine(writer, line) {
+  return new Promise((resolve, reject) => {
+    writer.write(`${line}
+`, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Act,
@@ -4362,6 +4651,7 @@ function action_builder(state2) {
   CommittedMetaSchema,
   ConcurrencyError,
   ConsoleLogger,
+  CsvFile,
   DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS,