@net-mesh/sdk 0.19.0

package/dist/cortex.js

@@ -0,0 +1,584 @@
+"use strict";
+/**
+ * CortEX + NetDb — typed event-sourced state with reactive watches.
+ *
+ * Wraps the native `@net-mesh/core` CortEX bindings with ergonomic
+ * TypeScript APIs: `AsyncIterable`-shaped watches (so `for await`
+ * works naturally), typed errors via `CortexError` / `NetDbError`
+ * pattern matching, and the `snapshotAndWatch` primitive whose race
+ * fix landed on v2 (see `docs/STORAGE_AND_CORTEX.md`).
+ *
+ * @example
+ * ```typescript
+ * import { NetDb, TaskStatus, CortexError } from '@net-mesh/sdk';
+ *
+ * const db = await NetDb.open({ originHash: 0xABCDEF01, withTasks: true });
+ * const tasks = db.tasks!;
+ *
+ * try {
+ *   tasks.create(1n, 'write docs', 100n);
+ *   await tasks.waitForSeq(seq);
+ * } catch (e) {
+ *   if (e instanceof CortexError) { /* handle adapter-level error *\/ }
+ *   else { throw e; }
+ * }
+ *
+ * // "Paint what's here now, then react to changes":
+ * const { snapshot, updates } = await tasks.snapshotAndWatch({
+ *   status: TaskStatus.Pending,
+ * });
+ * render(snapshot);
+ * for await (const next of updates) render(next);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetDb = exports.MemoriesAdapter = exports.TasksAdapter = exports.RedexFile = exports.Redex = exports.RedexError = exports.NetDbError = exports.CortexError = void 0;
+const core_1 = require("@net-mesh/core");
+// Typed error classes shipped by `@net-mesh/core/errors`. Re-exported here
+// so SDK consumers can `import { CortexError } from '@net-mesh/sdk'`
+// without a second package path. `classifyError` is what the wrappers
+// below use internally.
+var errors_1 = require("@net-mesh/core/errors");
+Object.defineProperty(exports, "CortexError", { enumerable: true, get: function () { return errors_1.CortexError; } });
+Object.defineProperty(exports, "NetDbError", { enumerable: true, get: function () { return errors_1.NetDbError; } });
+const errors_2 = require("@net-mesh/core/errors");
+/**
+ * Raised on `redex:` prefixed failures: append / tail / read / sync /
+ * close, invalid channel names, mutually-exclusive config options.
+ * Extends `Error`; catch with `instanceof RedexError`.
+ */
+class RedexError extends Error {
+    constructor(detail) {
+        super(detail ?? 'redex error');
+        this.name = 'RedexError';
+        Object.setPrototypeOf(this, RedexError.prototype);
+    }
+}
+exports.RedexError = RedexError;
+/** Classify a napi-thrown error. Mirrors `@net-mesh/core/errors` for the
+ *  `redex:` prefix which that package does not yet recognize. */
+function classifyWithRedex(e) {
+    const classified = (0, errors_2.classifyError)(e);
+    if (classified !== e)
+        return classified; // cortex: / netdb: already handled
+    const msg = e?.message ?? '';
+    if (msg.startsWith('redex:'))
+        return new RedexError(msg);
+    return e;
+}
+/**
+ * Local RedEX manager. Holds the set of open files on this process.
+ * Cheap to share; adapters borrow it by reference.
+ */
+class Redex {
+    /** @internal */
+    napi;
+    constructor(opts) {
+        this.napi = new core_1.Redex(opts?.persistentDir);
+    }
+    /**
+     * Open (or get) a raw RedEX file for domain-agnostic persistent
+     * logging. Returns the same handle across repeat calls with the
+     * same `name`; `config` is honored only on first open.
+     *
+     * Use this when you want an append-only event log without the
+     * CortEX fold / typed-adapter layer. Appends, tailing, and range
+     * reads work directly over the file.
+     *
+     * With `config.persistent = true`, this manager must have been
+     * constructed with a `persistentDir`.
+     */
+    openFile(name, config) {
+        try {
+            const napiCfg = toNapiFileConfig(config);
+            return new RedexFile(this.napi.openFile(name, napiCfg ?? null));
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+}
+exports.Redex = Redex;
+function toNapiFileConfig(c) {
+    if (!c)
+        return undefined;
+    return {
+        persistent: c.persistent,
+        fsyncEveryN: c.fsyncEveryN,
+        fsyncIntervalMs: c.fsyncIntervalMs,
+        retentionMaxEvents: c.retentionMaxEvents,
+        retentionMaxBytes: c.retentionMaxBytes,
+        retentionMaxAgeMs: c.retentionMaxAgeMs,
+    };
+}
+function toRedexEvent(raw) {
+    return {
+        seq: raw.seq,
+        payload: raw.payload,
+        checksum: raw.checksum,
+        isInline: raw.isInline,
+    };
+}
+/** Raw RedEX file handle. Append, tail, range-read without the
+ *  CortEX adapter layer. */
+class RedexFile {
+    /** @internal */
+    napi;
+    constructor(inner) {
+        this.napi = inner;
+    }
+    /** Append one payload. Returns the assigned sequence number. */
+    append(payload) {
+        try {
+            return this.napi.append(payload);
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+    /** Append a batch atomically. Returns the seq of the first event
+     *  (subsequent events are `first + 0, first + 1, ...`), or `null`
+     *  for an empty batch (no seq is allocated when there's nothing to
+     *  append). */
+    appendBatch(payloads) {
+        try {
+            return this.napi.appendBatch(payloads);
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+    /** Read the half-open range `[start, end)` from the in-memory
+     *  index. Only retained entries are returned. */
+    readRange(start, end) {
+        try {
+            return this.napi.readRange(start, end).map(toRedexEvent);
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+    /** Number of retained events (post-retention eviction). Returned
+     *  as `bigint` because event counts can exceed `Number.MAX_SAFE_INTEGER`
+     *  (~9 P) in theory — though in practice they'll fit in a `number`,
+     *  the lossless type is the safe surface. */
+    len() {
+        return this.napi.len();
+    }
+    /** Open a live tail. Yields every event with `seq >= fromSeq`
+     *  (default `0n`) — atomically backfills the retained range and
+     *  then streams appends. Breaking out of `for await` releases the
+     *  native iterator via `return()`. */
+    async tail(fromSeq) {
+        try {
+            const iter = await this.napi.tail(fromSeq ?? null);
+            const raw = {
+                // The napi tail emits `redex:` errors for tail-time failures
+                // (file closed mid-stream, decode failures on reopen, etc.).
+                // Without classifying here, those surface as bare `Error`s
+                // — callers doing `instanceof RedexError` miss them.
+                async next() {
+                    try {
+                        const v = await iter.next();
+                        return v === null ? null : toRedexEvent(v);
+                    }
+                    catch (e) {
+                        throw classifyWithRedex(e);
+                    }
+                },
+                close: () => iter.close(),
+            };
+            return wrapWatchIter(raw);
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+    /** Explicit fsync. Always fsyncs regardless of policy; no-op on
+     *  heap-only files. */
+    sync() {
+        try {
+            this.napi.sync();
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+    /** Close the file. Outstanding tail iterators end cleanly on
+     *  their next emission. */
+    close() {
+        try {
+            this.napi.close();
+        }
+        catch (e) {
+            throw classifyWithRedex(e);
+        }
+    }
+}
+exports.RedexFile = RedexFile;
+/**
+ * Turn a pull-based NAPI iterator into an `AsyncIterable` that plays
+ * nicely with `for await (...)`. The `return()` hook (fired by `break`
+ * / `throw` inside the loop) calls `close()` so native resources are
+ * released deterministically — dropping the loop is enough, no manual
+ * cleanup needed.
+ */
+function wrapWatchIter(raw) {
+    return {
+        [Symbol.asyncIterator]() {
+            let done = false;
+            const finish = () => ({ value: undefined, done: true });
+            return {
+                async next() {
+                    if (done)
+                        return finish();
+                    const v = await raw.next();
+                    if (v === null) {
+                        done = true;
+                        return finish();
+                    }
+                    return { value: v, done: false };
+                },
+                async return() {
+                    if (!done) {
+                        done = true;
+                        raw.close();
+                    }
+                    return finish();
+                },
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Tasks adapter
+// ---------------------------------------------------------------------------
+/**
+ * Typed tasks adapter. CRUD plus `listTasks` / `watch` /
+ * `snapshotAndWatch` for reactive consumers.
+ */
+class TasksAdapter {
+    /** @internal */
+    napi;
+    constructor(inner) {
+        this.napi = inner;
+    }
+    /**
+     * Open a standalone tasks adapter against a `Redex`. For bundled
+     * tasks + memories access, prefer {@link NetDb.open}.
+     */
+    static async open(redex, originHash, opts) {
+        try {
+            const inner = await core_1.TasksAdapter.open(redex.napi, originHash, opts?.persistent ?? null);
+            return new TasksAdapter(inner);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Restore from a snapshot captured via {@link TasksAdapter.snapshot}. */
+    static async openFromSnapshot(redex, originHash, snapshot, opts) {
+        try {
+            const inner = await core_1.TasksAdapter.openFromSnapshot(redex.napi, originHash, snapshot.stateBytes, snapshot.lastSeq ?? null, opts?.persistent ?? null);
+            return new TasksAdapter(inner);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    create(id, title, nowNs) {
+        try {
+            return this.napi.create(id, title, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    rename(id, newTitle, nowNs) {
+        try {
+            return this.napi.rename(id, newTitle, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    complete(id, nowNs) {
+        try {
+            return this.napi.complete(id, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    delete(id) {
+        try {
+            return this.napi.delete(id);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Total count in the materialized state (ignores any filter). */
+    count() {
+        try {
+            return this.napi.count();
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Wait for the fold task to have applied every event up through `seq`. */
+    async waitForSeq(seq) {
+        try {
+            return await this.napi.waitForSeq(seq);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Snapshot query over the materialized state. */
+    listTasks(filter) {
+        try {
+            return this.napi.listTasks(filter ?? null);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Capture a serialized state snapshot for {@link TasksAdapter.openFromSnapshot}. */
+    snapshot() {
+        try {
+            return this.napi.snapshot();
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /**
+     * Reactive watch. Yields the current filter result first, then once
+     * per fold tick where the result differs from the previous emission.
+     * Breaking out of `for await` calls `close()` automatically.
+     */
+    async watch(filter) {
+        try {
+            const iter = await this.napi.watchTasks(filter ?? null);
+            return wrapWatchIter(iter);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /**
+     * Atomic "paint what's here now, then react to changes." Returns the
+     * snapshot and an `AsyncIterable` of subsequent filter results.
+     *
+     * Prefer this to calling `listTasks` + `watch` separately — they
+     * race each other, and a mutation landing between the two reads
+     * would be silently lost.
+     */
+    async snapshotAndWatch(filter) {
+        try {
+            const combined = await this.napi.snapshotAndWatchTasks(filter ?? null);
+            const iter = {
+                next: () => combined.next(),
+                close: () => combined.close(),
+            };
+            return {
+                snapshot: combined.snapshot,
+                updates: wrapWatchIter(iter),
+            };
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+}
+exports.TasksAdapter = TasksAdapter;
+// ---------------------------------------------------------------------------
+// Memories adapter
+// ---------------------------------------------------------------------------
+/**
+ * Typed memories adapter. CRUD plus `listMemories` / `watch` /
+ * `snapshotAndWatch`.
+ */
+class MemoriesAdapter {
+    /** @internal */
+    napi;
+    constructor(inner) {
+        this.napi = inner;
+    }
+    static async open(redex, originHash, opts) {
+        try {
+            const inner = await core_1.MemoriesAdapter.open(redex.napi, originHash, opts?.persistent ?? null);
+            return new MemoriesAdapter(inner);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    static async openFromSnapshot(redex, originHash, snapshot, opts) {
+        try {
+            const inner = await core_1.MemoriesAdapter.openFromSnapshot(redex.napi, originHash, snapshot.stateBytes, snapshot.lastSeq ?? null, opts?.persistent ?? null);
+            return new MemoriesAdapter(inner);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    store(id, content, tags, source, nowNs) {
+        try {
+            return this.napi.store(id, content, tags, source, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    retag(id, tags, nowNs) {
+        try {
+            return this.napi.retag(id, tags, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    pin(id, nowNs) {
+        try {
+            return this.napi.pin(id, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    unpin(id, nowNs) {
+        try {
+            return this.napi.unpin(id, nowNs);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    delete(id) {
+        try {
+            return this.napi.delete(id);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    count() {
+        try {
+            return this.napi.count();
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    async waitForSeq(seq) {
+        try {
+            return await this.napi.waitForSeq(seq);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    listMemories(filter) {
+        try {
+            return this.napi.listMemories(filter ?? null);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    snapshot() {
+        try {
+            return this.napi.snapshot();
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    async watch(filter) {
+        try {
+            const iter = await this.napi.watchMemories(filter ?? null);
+            return wrapWatchIter(iter);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Atomic snapshot + delta stream. See {@link TasksAdapter.snapshotAndWatch}. */
+    async snapshotAndWatch(filter) {
+        try {
+            const combined = await this.napi.snapshotAndWatchMemories(filter ?? null);
+            const iter = {
+                next: () => combined.next(),
+                close: () => combined.close(),
+            };
+            return {
+                snapshot: combined.snapshot,
+                updates: wrapWatchIter(iter),
+            };
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+}
+exports.MemoriesAdapter = MemoriesAdapter;
+// ---------------------------------------------------------------------------
+// NetDb facade
+// ---------------------------------------------------------------------------
+/**
+ * Unified NetDB handle. Bundles `TasksAdapter` + `MemoriesAdapter`
+ * under one object. Open with both models for the common case, or
+ * with only one if the other isn't needed.
+ */
+class NetDb {
+    /** @internal */
+    napi;
+    constructor(inner) {
+        this.napi = inner;
+    }
+    static async open(config) {
+        try {
+            const inner = await core_1.NetDb.open(config);
+            return new NetDb(inner);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    static async openFromSnapshot(config, bundle) {
+        try {
+            const inner = await core_1.NetDb.openFromSnapshot(config, bundle);
+            return new NetDb(inner);
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** The tasks adapter, or `null` if `withTasks` wasn't set at open. */
+    get tasks() {
+        const t = this.napi.tasks;
+        return t ? new TasksAdapter(t) : null;
+    }
+    /** The memories adapter, or `null` if `withMemories` wasn't set. */
+    get memories() {
+        const m = this.napi.memories;
+        return m ? new MemoriesAdapter(m) : null;
+    }
+    /** Snapshot every enabled model into one bundle. */
+    snapshot() {
+        try {
+            return this.napi.snapshot();
+        }
+        catch (e) {
+            throw (0, errors_2.classifyError)(e);
+        }
+    }
+    /** Close every enabled adapter. Idempotent. */
+    close() {
+        this.napi.close();
+    }
+}
+exports.NetDb = NetDb;