@rotorsoft/act 1.1.0 → 1.3.0

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   sleep,
   store,
   validate
-} from "./chunk-TN4XS7WE.js";
+} from "./chunk-XKCTGUW2.js";
 import {
   ActorSchema,
   CausationEventSchema,
@@ -868,6 +868,51 @@ var subscribe = (streams) => store().subscribe(streams);
 
 // src/internal/event-sourcing.ts
 import { patch } from "@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;
@@ -899,6 +944,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 cache().get(stream);
@@ -2533,6 +2632,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 = store();
+        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
@@ -3098,6 +3261,167 @@ function action_builder(state2) {
   };
   return builder;
 }
+
+// src/csv.ts
+import { createReadStream, createWriteStream } from "fs";
+import { createInterface } from "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 = 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 = createReadStream(path, { encoding: "utf8" });
+  const rl = 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();
+    });
+  });
+}
 export {
   Act,
   ActorSchema,
@@ -3105,6 +3429,7 @@ export {
   CommittedMetaSchema,
   ConcurrencyError,
   ConsoleLogger,
+  CsvFile,
   DEFAULT_LANE,
   DEFAULT_MAX_SUBSCRIBED_STREAMS,
   DEFAULT_SETTLE_DEBOUNCE_MS,