@rotorsoft/act 2.1.1 → 2.1.2

package/dist/@types/types/restore.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @module act/types/restore
+ * Types for restore and transfer: the scan options and result, the source
+ * an `IAct.restore` reads and the sink it writes.
+ */
+import type { Committed, Query, Schemas } from "./action.js";
+import type { Disposable } from "./ports.js";
+/**
+ * Options for the orchestrator's restore scan loop, consumed by
+ * {@link IAct.restore} (and threaded through to the internal `scan`).
+ * Adapters never see these — they're entirely interpreted on the
+ * orchestrator side.
+ *
+ * Compaction flags ({@link drop_snapshots}, {@link drop_closed_streams})
+ * and the migration overlay ({@link event_migrations},
+ * {@link stream_rename}) all apply per event before the sink writes
+ * anything. Any throw aborts the whole scan — atomic rollback in the
+ * sink means a failing transform leaves the target byte-for-byte
+ * unchanged.
+ */
+export type ScanOptions = {
+    /**
+     * Skip events with `name === SNAP_EVENT`. The next snap policy
+     * regenerates snapshots against current code; useful for backups
+     * that should compact stale snapshot bytes. Counted in
+     * {@link ScanResult.dropped}`.snapshots`.
+     *
+     * Single-pass: no source-shape implications. Default `false`.
+     */
+    readonly drop_snapshots?: boolean;
+    /**
+     * Optional progress callback. The scan loop fires it once per event
+     * during iteration. Three fields:
+     *
+     *   - `processed` — running 1-based count of events processed.
+     *   - `id` — current event's id.
+     *   - `max_id` — highest id in the source, probed once at scan start
+     *     via `source.query(noop, { backward: true, limit: 1 })`. O(1) on
+     *     indexed stores. Left `undefined` when the probe can't determine
+     *     it (e.g. `CsvFile`-style sources that ignore the filter and
+     *     stream more than one event from the probe call).
+     *
+     * UIs render either `processed / ?` (event count) or `id / max_id`
+     * (position through the id space) depending on need.
+     *
+     * Synchronous handler — the scan loop calls it directly.
+     * **Throttling / batching is the caller's responsibility**: for a
+     * million-event restore, debounce in the handler rather than
+     * expecting the loop to coalesce calls. Keeping it unthrottled
+     * means callers that want every-event reporting get it without a
+     * config knob.
+     */
+    readonly on_progress?: (p: {
+        processed: number;
+        id: number;
+        max_id?: number;
+    }) => void;
+    /**
+     * Per-batch row count for the scan pagination loop. Each
+     * call to `source.query` requests `limit: batch_size` and `after:
+     * <last id seen>`. Default `500`. Lower values trade round trips for
+     * memory; higher values approach the cost of an unbounded query.
+     */
+    readonly batch_size?: number;
+    /**
+     * When `true`, {@link IAct.restore} runs the scan loop without
+     * touching the store — events are validated and counted but no
+     * transaction is opened and no rows are written. Returned `kept` /
+     * `dropped` reflect what a subsequent destructive restore against
+     * the same source would land; a throw means the source has a
+     * blocker (the running index pinpoints it).
+     *
+     * No `Store.restore` capability is required for a dry-run — the
+     * adapter is never called. Default `false`.
+     */
+    readonly dry_run?: boolean;
+    /**
+     * Compact streams that have been closed (tombstoned) via
+     * {@link IAct.close}. The scan walks the source once
+     * upfront to collect streams with a `__tombstone__` event, then
+     * the main loop drops every **pre-close event** whose stream is in
+     * that set. The tombstone itself is **kept** — it's the gate that
+     * makes {@link IAct.do} throw `StreamClosedError` in the rebuilt
+     * store, so dropping it would silently reopen the stream.
+     *
+     * Useful for compaction during transfer: the new (migrated) store
+     * keeps the close gate but drops the historical detail.
+     *
+     * Counted in {@link ScanResult.dropped}`.closed_streams` (pre-close
+     * events only; the tombstone is counted in `kept`).
+     *
+     * Default `false`.
+     */
+    readonly drop_closed_streams?: boolean;
+    /**
+     * Per-event migrations applied during scan. Keys are
+     * source event names; values describe how to rewrite the event into
+     * its current-version form before the sink writes it.
+     *
+     * Transfer-time only — never registered at app build time and never
+     * auto-applied to a live store. Operators configure migrations
+     * explicitly per-call (typically through the inspector's transfer
+     * dialog when moving from an old store to a new one).
+     *
+     * Each row that matches a key:
+     *   1. parses `event.data` against `from_schema` (validates source);
+     *   2. runs `migrate(parsed)` to transform the payload;
+     *   3. parses the result against `to_schema` (validates target);
+     *   4. is rewritten with `name = to` and `data = migrated`.
+     *
+     * Any throw aborts the whole scan — atomic transaction rollback in
+     * the sink means a failing migration leaves the target byte-for-byte
+     * unchanged.
+     */
+    readonly event_migrations?: Record<string, EventMigration<any, any>>;
+    /**
+     * Per-stream rename applied during scan. The returned string
+     * replaces `event.stream` and the streams named in its causation. Useful for
+     * tenant relocation (`s => s.replace(/^old-tenant-/, "new-tenant-")`)
+     * or prefix cleanup.
+     *
+     * Applied AFTER {@link event_migrations} so the migration sees the
+     * original stream name (in case the migration's `migrate` function
+     * inspects it).
+     */
+    readonly stream_rename?: (stream: string) => string;
+};
+/**
+ * Per-event migration definition for {@link ScanOptions.event_migrations}.
+ * Carries both the rename target and the schema-guarded transform that
+ * rewrites the event's `data` payload.
+ */
+export type EventMigration<TOld, TNew> = {
+    /** Target event name (the current version). */
+    readonly to: string;
+    /** Schema of the source event's `data`. Throws on mismatch. */
+    readonly from_schema: {
+        parse: (data: unknown) => TOld;
+    };
+    /** Schema of the migrated event's `data`. Throws on mismatch. */
+    readonly to_schema: {
+        parse: (data: unknown) => TNew;
+    };
+    /** Pure data transformer. */
+    readonly migrate: (data: TOld) => TNew;
+};
+/**
+ * Result of {@link IAct.restore}.
+ *
+ * `kept` and `duration_ms` are always populated. `dropped` carries
+ * per-category counters when {@link ScanOptions.drop_snapshots} (or
+ * future compaction flags) trigger drops; otherwise zeros. Live
+ * restore is atomic — any error throws and rolls back, so there's no
+ * per-event error reporting on the result.
+ */
+export type ScanResult = {
+    /** Number of events written to the rebuilt store. */
+    readonly kept: number;
+    /** Wall-clock duration of the call, in milliseconds. */
+    readonly duration_ms: number;
+    /** Per-category drop counters. */
+    readonly dropped: {
+        readonly closed_streams: number;
+        readonly snapshots: number;
+    };
+    /** Events rewritten by {@link ScanOptions.event_migrations}. */
+    readonly migrated: number;
+};
+/**
+ * Construct a {@link CsvFile} from either a filesystem path (for
+ * reading and/or writing through the OS) or an in-memory blob (a
+ * pre-loaded CSV string, used by the inspector when a CSV arrives
+ * over the wire via tRPC).
+ *
+ * Both modes share the same on-disk format, so the same blob shape
+ * can be round-tripped through the transfer pipeline.
+ */
+export type CsvFileOptions = {
+    path: string;
+} | {
+    blob: string;
+};
+/**
+ * Read end of the transfer pipeline. Anything
+ * that exposes a `Store.query`-shaped reader plus `dispose` can be
+ * used as a source for {@link IAct.restore}.
+ *
+ * `Store` extends this interface; the framework's `CsvFile` utility
+ * implements it on top of file I/O so a CSV can be a transfer
+ * source. The pipeline never sees a discriminator — both ends speak
+ * the same shape.
+ */
+export interface EventSource extends Disposable {
+    /**
+     * Read events into a per-event callback. Adapters MUST `await
+     * Promise.resolve(callback(event))` per event — sync callbacks
+     * resolve immediately (zero overhead), async callbacks throttle
+     * the read loop. This is the seam that lets `iterate()` apply
+     * backpressure without changing the callback's declared return
+     * type. Callback returns `void`, which TypeScript treats as
+     * "return value ignored" — existing call sites passing
+     * `e => arr.push(e)` (which returns `number`) keep working.
+     */
+    query<E extends Schemas>(callback: (event: Committed<E, keyof E>) => void, query?: Query): Promise<number>;
+}
+/**
+ * Write end of the transfer pipeline. Anything
+ * that can host the destructive driver-pattern `restore` HOF (atomic
+ * wipe + per-event commit) is an `EventSink` — `Store` adapters
+ * that ship the optional `restore` method, plus the framework's
+ * `CsvFile` utility for "write to a file" targets.
+ *
+ * `restore` is required here (vs. optional on `Store`) because the
+ * sink slot in {@link IAct.restore} demands a writer; non-restorable
+ * stores satisfy {@link EventSource} only.
+ */
+export interface EventSink extends Disposable {
+    restore(driver: (callback: (event: Committed<Schemas, keyof Schemas>) => Promise<number>) => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=restore.d.ts.map

package/dist/@types/types/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../../src/types/restore.ts"],"names":[],"mappings":"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"}

package/dist/adapter.cjs

@@ -6,8 +6,8 @@
 
 
 
-var _chunkPZQXTGWFcjs = require('./chunk-PZQXTGWF.cjs');
-require('./chunk-7VYSJIXD.cjs');
+var _chunkD7LQNOEVcjs = require('./chunk-D7LQNOEV.cjs');
+require('./chunk-QFYPSI6P.cjs');
 
 
 
@@ -16,5 +16,5 @@ require('./chunk-7VYSJIXD.cjs');
 
 
 
-exports.checkAppends = _chunkPZQXTGWFcjs.checkAppends; exports.checkVersion = _chunkPZQXTGWFcjs.checkVersion; exports.concurrencyError = _chunkPZQXTGWFcjs.concurrencyError; exports.fairSlots = _chunkPZQXTGWFcjs.fairSlots; exports.isStreamName = _chunkPZQXTGWFcjs.isStreamName; exports.parseNotification = _chunkPZQXTGWFcjs.parseNotification; exports.seedEvent = _chunkPZQXTGWFcjs.seedEvent;
+exports.checkAppends = _chunkD7LQNOEVcjs.checkAppends; exports.checkVersion = _chunkD7LQNOEVcjs.checkVersion; exports.concurrencyError = _chunkD7LQNOEVcjs.concurrencyError; exports.fairSlots = _chunkD7LQNOEVcjs.fairSlots; exports.isStreamName = _chunkD7LQNOEVcjs.isStreamName; exports.parseNotification = _chunkD7LQNOEVcjs.parseNotification; exports.seedEvent = _chunkD7LQNOEVcjs.seedEvent;
 //# sourceMappingURL=adapter.cjs.map

package/dist/adapter.js

@@ -6,8 +6,8 @@ import {
   isStreamName,
   parseNotification,
   seedEvent
-} from "./chunk-UXDNSZAD.js";
-import "./chunk-W3PHEA5Q.js";
+} from "./chunk-TUALNYW2.js";
+import "./chunk-C35J3SNT.js";
 export {
   checkAppends,
   checkVersion,

package/dist/{chunk-QPVUARKL.js → chunk-ADMH76IO.js}

@@ -3,7 +3,7 @@ import {
   checkVersion,
   fairSlots,
   seedEvent
-} from "./chunk-UXDNSZAD.js";
+} from "./chunk-TUALNYW2.js";
 import {
   DEFAULT_LANE,
   DEFAULT_QUERY_STREAMS_LIMIT,
@@ -11,7 +11,7 @@ import {
   LogLevels,
   SNAP_EVENT,
   ValidationError
-} from "./chunk-W3PHEA5Q.js";
+} from "./chunk-C35J3SNT.js";
 
 // src/adapters/console-logger.ts
 var LEVEL_VALUES = {
@@ -1201,4 +1201,4 @@ export {
   disposeAndExit,
   dispose
 };
-//# sourceMappingURL=chunk-QPVUARKL.js.map
+//# sourceMappingURL=chunk-ADMH76IO.js.map