@loradb/lora-node 0.15.0 → 0.17.0

package/dist/index.js

@@ -31,6 +31,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
 exports.createDatabase = createDatabase;
 exports.openWalDatabase = openWalDatabase;
 const node_buffer_1 = require("node:buffer");
@@ -46,10 +47,20 @@ __exportStar(require("./types.js"), exports);
 class NativeRowStream {
     #inner;
     #streamId;
+    #signal;
+    #release;
     #closed = false;
-    constructor(inner, streamId) {
+    constructor(inner, streamId, signal, release) {
         this.#inner = inner;
         this.#streamId = streamId;
+        this.#signal = signal;
+        this.#release = release;
+    }
+    #finish() {
+        this.#closed = true;
+        const release = this.#release;
+        this.#release = undefined;
+        release?.();
     }
     [Symbol.asyncIterator]() {
         return this;
@@ -69,13 +80,15 @@ class NativeRowStream {
         try {
             const row = this.#inner.streamNext(this.#streamId);
             if (row === null) {
-                this.#closed = true;
+                this.#finish();
                 return { done: true, value: undefined };
             }
             return { done: false, value: row };
         }
         catch (err) {
-            this.#closed = true;
+            this.#finish();
+            if (this.#signal?.aborted)
+                throw this.#signal.reason;
             throw (0, types_js_1.wrapError)(err);
         }
     }
@@ -96,7 +109,7 @@ class NativeRowStream {
     close() {
         if (this.#closed)
             return;
-        this.#closed = true;
+        this.#finish();
         try {
             this.#inner.streamClose(this.#streamId);
         }
@@ -105,6 +118,189 @@ class NativeRowStream {
         }
     }
 }
+const CHANGES_POLL_MAX = 256;
+class NativeChangeFeed {
+    #inner;
+    #signal;
+    #onDone;
+    #opened;
+    ready;
+    #id;
+    #buffer = [];
+    #done = false;
+    #error = undefined;
+    #lastLsn;
+    #wakeSeq = 0;
+    #wake;
+    #queue = Promise.resolve();
+    #onAbort;
+    constructor(inner, options, onDone) {
+        this.#inner = inner;
+        this.#signal = options?.signal;
+        this.#onDone = onDone;
+        const fromLsn = normalizeLsn(options?.fromLsn);
+        this.#lastLsn = fromLsn ?? undefined;
+        const bufferSize = normalizeBufferSize(options?.bufferSize);
+        if (this.#signal?.aborted) {
+            this.#done = true;
+            this.#error = this.#signal.reason;
+            this.#opened = Promise.reject(this.#signal.reason);
+        }
+        else {
+            // Subscribes synchronously when capture is already on, so writes
+            // issued after `changes()` returns are never missed.
+            let opening;
+            try {
+                opening = inner.openChanges(fromLsn, bufferSize, () => this.#onWake());
+            }
+            catch (err) {
+                opening = Promise.reject(err);
+            }
+            this.#opened = opening.then((id) => {
+                this.#id = id;
+                if (this.#done)
+                    this.#closeNative();
+                return id;
+            });
+            if (this.#signal) {
+                const signal = this.#signal;
+                this.#onAbort = () => {
+                    this.#buffer = [];
+                    this.#end(signal.reason);
+                };
+                signal.addEventListener("abort", this.#onAbort, { once: true });
+            }
+        }
+        this.ready = this.#opened.then(() => undefined, (err) => {
+            throw (0, types_js_1.wrapError)(err);
+        });
+        // `ready` is optional to await; its rejection also reaches `next()`.
+        this.ready.catch(() => undefined);
+    }
+    get lastLsn() {
+        return this.#lastLsn;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        // Serialize concurrent `next()` calls so batches stay in order.
+        const result = this.#queue.then(() => this.#next());
+        this.#queue = result.catch(() => undefined);
+        return result;
+    }
+    async return() {
+        this.close();
+        return { done: true, value: undefined };
+    }
+    close() {
+        this.#buffer = [];
+        this.#end(undefined);
+    }
+    /** Called by `dispose()`: the native side already dropped the feed. */
+    disposed() {
+        this.#id = undefined;
+        this.#end(undefined);
+    }
+    async #next() {
+        for (;;) {
+            const buffered = this.#buffer.shift();
+            if (buffered) {
+                this.#lastLsn = buffered.lsn;
+                return { done: false, value: buffered };
+            }
+            if (this.#done) {
+                const err = this.#error;
+                this.#error = undefined;
+                if (err !== undefined)
+                    throw err;
+                return { done: true, value: undefined };
+            }
+            let id;
+            try {
+                id = await this.#opened;
+            }
+            catch (err) {
+                this.#end((0, types_js_1.wrapError)(err));
+                continue;
+            }
+            if (this.#done)
+                continue;
+            const seq = this.#wakeSeq;
+            let polled;
+            try {
+                polled = await this.#inner.changesPoll(id, CHANGES_POLL_MAX);
+            }
+            catch (err) {
+                this.#end(this.#done ? undefined : (0, types_js_1.wrapError)(err));
+                continue;
+            }
+            this.#buffer.push(...polled.batches);
+            if (polled.closed) {
+                this.#end(undefined);
+                continue;
+            }
+            if (polled.batches.length === 0 && seq === this.#wakeSeq && !this.#done) {
+                await new Promise((resolve) => {
+                    this.#wake = resolve;
+                });
+            }
+        }
+    }
+    #onWake() {
+        this.#wakeSeq += 1;
+        const wake = this.#wake;
+        this.#wake = undefined;
+        wake?.();
+    }
+    #end(error) {
+        if (this.#done) {
+            if (error !== undefined && this.#error === undefined)
+                this.#error = error;
+            return;
+        }
+        this.#done = true;
+        this.#error = error;
+        if (this.#onAbort && this.#signal) {
+            this.#signal.removeEventListener("abort", this.#onAbort);
+            this.#onAbort = undefined;
+        }
+        this.#closeNative();
+        this.#onDone(this);
+        this.#onWake();
+    }
+    #closeNative() {
+        const id = this.#id;
+        if (id === undefined)
+            return;
+        this.#id = undefined;
+        try {
+            this.#inner.changesClose(id);
+        }
+        catch {
+            // Already gone (database disposed).
+        }
+    }
+}
+function normalizeLsn(lsn) {
+    if (lsn === undefined)
+        return null;
+    const value = typeof lsn === "bigint" ? Number(lsn) : lsn;
+    if (!Number.isSafeInteger(value) ||
+        value < 0 ||
+        (typeof lsn === "bigint" && BigInt(value) !== lsn)) {
+        throw new types_js_1.LoraError(`\`fromLsn\` must be a non-negative safe integer, got ${String(lsn)}`, "LORA_INVALID_PARAMS");
+    }
+    return value;
+}
+function normalizeBufferSize(size) {
+    if (size === undefined)
+        return null;
+    if (!Number.isInteger(size) || size < 1 || size > 0xffff_ffff) {
+        throw new types_js_1.LoraError(`\`bufferSize\` must be a positive integer, got ${String(size)}`, "LORA_INVALID_PARAMS");
+    }
+    return size;
+}
 function isFetchUrl(url) {
     return (url.protocol === "http:" ||
         url.protocol === "https:" ||
@@ -253,6 +449,7 @@ function normalizeSnapshotLoadOptions(options) {
  */
 class DatabaseImpl {
     #inner;
+    #feeds = new Set();
     constructor(inner) {
         this.#inner = inner;
     }
@@ -262,15 +459,25 @@ class DatabaseImpl {
      * with a narrowed `code` from the `LoraErrorCode` union (e.g.
      * `LORA_PARSE`, `LORA_INVALID_PARAMS`, `LORA_INTERNAL`).
      */
-    async execute(query, params) {
+    async execute(query, params, options) {
         try {
-            const buf = await this.#inner.execute(query, params ?? null);
+            const encoded = encodeParams(params);
+            const buf = await this.#limited(options, (timeoutMs, token) => this.#inner.execute(query, encoded, timeoutMs, token));
             return (0, decode_js_1.decodeResult)(buf);
         }
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
         }
     }
+    /**
+     * Run `start` under `options`. Without a signal the timeout goes to the
+     * native call directly. With one, a native cancellation token carries
+     * the timeout, `abort` cancels the query server-side, and a cancelled
+     * call rejects with the signal's reason.
+     */
+    #limited(options, start) {
+        return runLimited(this.#inner, options, start);
+    }
     /**
      * Compile a query and return its execution plan without running it.
      *
@@ -281,7 +488,7 @@ class DatabaseImpl {
      */
     async explain(query, params) {
         try {
-            return (await this.#inner.explain(query, params ?? null));
+            return (await this.#inner.explain(query, encodeParams(params)));
         }
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
@@ -298,7 +505,7 @@ class DatabaseImpl {
      */
     async profile(query, params) {
         try {
-            return (await this.#inner.profile(query, params ?? null));
+            return (await this.#inner.profile(query, encodeParams(params)));
         }
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
@@ -311,18 +518,39 @@ class DatabaseImpl {
      * Rows are materialized by the native `execute()` promise today, then
      * yielded one at a time to JS consumers.
      */
-    stream(query, params) {
+    stream(query, params, options) {
         try {
-            const streamId = this.#inner.openStream(query, params ?? null);
-            return new NativeRowStream(this.#inner, streamId);
+            const encoded = encodeParams(params);
+            const timeoutMs = normalizeTimeout(options?.timeoutMs);
+            const signal = options?.signal;
+            if (signal == null) {
+                const streamId = this.#inner.openStream(query, encoded, timeoutMs, null);
+                return new NativeRowStream(this.#inner, streamId);
+            }
+            signal.throwIfAborted();
+            const token = this.#inner.createCancelToken(timeoutMs);
+            const onAbort = () => this.#inner.cancelQuery(token);
+            signal.addEventListener("abort", onAbort, { once: true });
+            const release = () => {
+                signal.removeEventListener("abort", onAbort);
+                this.#inner.releaseCancelToken(token);
+            };
+            try {
+                const streamId = this.#inner.openStream(query, encoded, null, token);
+                return new NativeRowStream(this.#inner, streamId, signal, release);
+            }
+            catch (err) {
+                release();
+                throw err;
+            }
         }
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
         }
     }
     /** Alias for `stream()`, useful when naming the row-level API explicitly. */
-    rows(query, params) {
-        return this.stream(query, params);
+    rows(query, params, options) {
+        return this.stream(query, params, options);
     }
     /**
      * Execute a statement batch inside one native transaction.
@@ -331,9 +559,32 @@ class DatabaseImpl {
      * native transaction is dropped before commit and all prior writes in the
      * batch are rolled back.
      */
-    async transaction(statements, mode = "read_write") {
+    /**
+     * Begin an interactive transaction: run statements, decide in JS, then
+     * `commit()` or `rollback()`.
+     *
+     * A `read_write` transaction holds the database's writer lock from
+     * `begin()` until it finishes, so no other write can interleave with it
+     * (other writers wait). Reads outside the transaction keep seeing the
+     * last committed state. A statement that fails rolls the transaction
+     * back. An unfinished transaction rolls back when the handle is disposed
+     * (`await using tx = await db.begin()`), when the database is disposed,
+     * or when the process exits. Keep transactions short: while one is open,
+     * writers queue behind it.
+     */
+    async begin(mode = "read_write") {
         try {
-            const buffers = await this.#inner.transaction(statements, mode);
+            const id = await this.#inner.beginTransaction(mode);
+            return new Transaction(this.#inner, id);
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    async transaction(statements, mode = "read_write", options) {
+        try {
+            const encoded = statements.map((st) => st.params == null ? st : { ...st, params: encodeParams(st.params) });
+            const buffers = await this.#limited(options, (timeoutMs, token) => this.#inner.transaction(encoded, mode, timeoutMs, token));
             return buffers.map((buf) => (0, decode_js_1.decodeResult)(buf));
         }
         catch (err) {
@@ -396,6 +647,34 @@ class DatabaseImpl {
         catch (err) {
             throw (0, types_js_1.wrapError)(err);
         }
+        finally {
+            for (const feed of [...this.#feeds])
+                feed.disposed();
+            this.#feeds.clear();
+        }
+    }
+    /**
+     * Subscribe to committed changes: one `LoraChangeBatch` per committed
+     * write (auto-commit query, transaction, streamed write, `clear()`,
+     * snapshot restore), in commit order. Rolled-back work never appears.
+     *
+     * ```ts
+     * for await (const batch of db.changes({ fromLsn: saved })) {
+     *   for (const change of batch.changes) handle(change);
+     *   saved = batch.lsn;
+     * }
+     * ```
+     *
+     * Writers never wait for the feed. A consumer that falls more than
+     * `bufferSize` batches behind gets `LORA_CHANGES_LAGGED` after the
+     * buffered batches and should resume with `fromLsn: feed.lastLsn`.
+     * `dispose()` ends every feed. An open feed does not keep the process
+     * alive on its own.
+     */
+    changes(options) {
+        const feed = new NativeChangeFeed(this.#inner, options, (done) => this.#feeds.delete(done));
+        this.#feeds.add(feed);
+        return feed;
     }
     /**
      * Save the graph as a snapshot.
@@ -460,6 +739,127 @@ class DatabaseImpl {
         }
     }
 }
+/**
+ * An open interactive transaction from `Database.begin()`.
+ */
+class Transaction {
+    #inner;
+    #id;
+    #open = true;
+    /** @internal */
+    constructor(inner, id) {
+        this.#inner = inner;
+        this.#id = id;
+    }
+    /** Whether the transaction can still run statements. */
+    get isOpen() {
+        return this.#open;
+    }
+    /**
+     * Run one statement inside the transaction. It sees the transaction's
+     * own uncommitted writes. If it fails, the transaction is rolled back.
+     */
+    async execute(query, params, options) {
+        this.#assertOpen();
+        try {
+            const encoded = encodeParams(params);
+            const buf = await runLimited(this.#inner, options, (timeoutMs, token) => this.#inner.txExecute(this.#id, query, encoded, timeoutMs, token));
+            return (0, decode_js_1.decodeResult)(buf);
+        }
+        catch (err) {
+            this.#open = false;
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    /**
+     * Run several statements inside the transaction in one native call and
+     * return their results in order. Each statement sees the writes of the
+     * ones before it. This saves the per-call round trip of calling
+     * `execute()` once per statement.
+     *
+     * The batch stops at the first failing statement: the transaction is
+     * rolled back (as with a failed `execute()`) and the promise rejects
+     * with that statement's error, whose message ends with
+     * `(statement i of n)`. `options.timeoutMs` and `options.signal` bound
+     * the whole batch.
+     */
+    async executeMany(statements, options) {
+        this.#assertOpen();
+        let encoded;
+        try {
+            encoded = statements.map((st) => st.params == null ? st : { ...st, params: encodeParams(st.params) });
+        }
+        catch (err) {
+            // Invalid params: nothing ran, the transaction stays open.
+            throw (0, types_js_1.wrapError)(err);
+        }
+        try {
+            const buffers = await runLimited(this.#inner, options, (timeoutMs, token) => this.#inner.txExecuteMany(this.#id, encoded, timeoutMs, token));
+            return buffers.map((buf) => (0, decode_js_1.decodeResult)(buf));
+        }
+        catch (err) {
+            this.#open = false;
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    /** Commit every write made in the transaction and release the writer lock. */
+    async commit() {
+        await this.#finish(true);
+    }
+    /** Discard every write made in the transaction and release the writer lock. */
+    async rollback() {
+        await this.#finish(false);
+    }
+    /** Roll back if still open. Lets `await using tx = await db.begin()` clean up. */
+    async [Symbol.asyncDispose]() {
+        if (this.#open)
+            await this.rollback();
+    }
+    async #finish(commit) {
+        this.#assertOpen();
+        this.#open = false;
+        try {
+            await this.#inner.txFinish(this.#id, commit);
+        }
+        catch (err) {
+            throw (0, types_js_1.wrapError)(err);
+        }
+    }
+    #assertOpen() {
+        if (!this.#open) {
+            throw new types_js_1.LoraError("transaction is no longer open (already committed, rolled back, or failed)", "LORA_TRANSACTION");
+        }
+    }
+}
+exports.Transaction = Transaction;
+/**
+ * Run `start` under `options`. Without a signal the timeout goes to the
+ * native call directly. With one, a native cancellation token carries the
+ * timeout, `abort` cancels the query server-side, and a cancelled call
+ * rejects with the signal's reason.
+ */
+async function runLimited(inner, options, start) {
+    const timeoutMs = normalizeTimeout(options?.timeoutMs);
+    const signal = options?.signal;
+    if (signal == null)
+        return start(timeoutMs, null);
+    signal.throwIfAborted();
+    const token = inner.createCancelToken(timeoutMs);
+    const onAbort = () => inner.cancelQuery(token);
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        return await start(null, token);
+    }
+    catch (err) {
+        if (signal.aborted)
+            throw signal.reason;
+        throw err;
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        inner.releaseCancelToken(token);
+    }
+}
 /**
  * Create and initialize a new LoraDB instance.
  *
@@ -522,8 +922,8 @@ async function createDatabase(databaseName, options = {}) {
         const syncMode = options.syncMode ?? null;
         const groupSyncIntervalMs = options.groupSyncIntervalMs ?? null;
         return new DatabaseImpl(databaseName == null
-            ? new NativeDatabase()
-            : new NativeDatabase(databaseName, options.databaseDir ?? null, syncMode, groupSyncIntervalMs, null, null, null, null, null));
+            ? new NativeDatabase(null, null, null, null, null, null, null, null, null, options.queryTimeoutMs ?? null)
+            : new NativeDatabase(databaseName, options.databaseDir ?? null, syncMode, groupSyncIntervalMs, null, null, null, null, null, options.queryTimeoutMs ?? null));
     }
     catch (err) {
         throw (0, types_js_1.wrapError)(err);
@@ -550,4 +950,73 @@ async function openWalDatabase(options) {
         throw (0, types_js_1.wrapError)(err);
     }
 }
+/**
+ * Prepare params for the native boundary. Params cross as JSON-shaped
+ * values, which cannot carry a `bigint`, so every bigint is rewritten to
+ * `{ kind: "integer", value: "<decimal>" }` and decoded exactly on the
+ * Rust side. Returns the input unchanged (no copy) when it holds no
+ * bigint, which is the common case.
+ */
+function encodeParams(params) {
+    if (params == null)
+        return null;
+    return needsEncoding(params) ? encodeBigInts(params) : params;
+}
+/**
+ * An integer-valued `number` past 2^53 has usually already been rounded
+ * by JavaScript (an id or timestamp parsed from JSON, say). Storing it
+ * would make that corruption permanent, so refuse it and point at bigint.
+ * Magnitudes of 2^63 and up cannot be 64-bit integers and stay floats.
+ */
+function checkNumber(value) {
+    if (Number.isInteger(value) &&
+        !Number.isSafeInteger(value) &&
+        Math.abs(value) < 2 ** 63) {
+        throw new types_js_1.LoraError(`integer ${value} is outside the JavaScript safe-integer range and may already be rounded; pass it as a bigint`, "LORA_INVALID_PARAMS");
+    }
+}
+function needsEncoding(value) {
+    if (typeof value === "bigint")
+        return true;
+    if (typeof value === "number") {
+        checkNumber(value);
+        return false;
+    }
+    if (value === null || typeof value !== "object")
+        return false;
+    if (ArrayBuffer.isView(value))
+        return false;
+    if (Array.isArray(value)) {
+        let found = false;
+        for (const item of value)
+            found = needsEncoding(item) || found;
+        return found;
+    }
+    let found = false;
+    for (const key in value) {
+        found = needsEncoding(value[key]) || found;
+    }
+    return found;
+}
+function encodeBigInts(value) {
+    if (typeof value === "bigint")
+        return { kind: "integer", value: value.toString() };
+    if (value === null || typeof value !== "object" || ArrayBuffer.isView(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map(encodeBigInts);
+    const out = {};
+    for (const key in value)
+        out[key] = encodeBigInts(value[key]);
+    return out;
+}
+function normalizeTimeout(timeoutMs) {
+    if (timeoutMs === undefined)
+        return null;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new types_js_1.LoraError(`timeoutMs must be a non-negative finite number, got ${timeoutMs}`, "LORA_INVALID_PARAMS");
+    }
+    // The native side takes whole milliseconds as u32; 0 disables.
+    return Math.min(Math.ceil(timeoutMs), 0xffff_ffff);
+}
 //# sourceMappingURL=index.js.map