@laminardb/node 0.30.0-alpha.1

package/dist/index.js

@@ -0,0 +1,420 @@
+"use strict";
+/**
+ * Public API of `@laminardb/node` (plan 00 D8).
+ *
+ * This module is the documented surface; the generated napi binding
+ * (`index.js` at the package root) is an internal seam. Everything here
+ * wraps the native calls so failures surface as the typed
+ * {@link LaminarError} hierarchy.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LaminarDB = void 0;
+exports.QueryStream = void 0;
+exports.PushSubscription = void 0;
+exports.Subscription = void 0;
+exports.Connection = void 0;
+exports.Writer = void 0;
+exports.tableFrom = void 0;
+exports.toLaminarError = void 0;
+exports.LaminarInternalError = void 0;
+exports.LaminarSubscriptionError = void 0;
+exports.LaminarQueryError = void 0;
+exports.LaminarIngestionError = void 0;
+exports.LaminarSchemaError = void 0;
+exports.LaminarConnectionError = void 0;
+exports.LaminarError = void 0;
+const errors_js_1 = require("./errors.js");
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "LaminarError", { enumerable: true, get: function () { return errors_js_2.LaminarError; } });
+Object.defineProperty(exports, "LaminarConnectionError", { enumerable: true, get: function () { return errors_js_2.LaminarConnectionError; } });
+Object.defineProperty(exports, "LaminarSchemaError", { enumerable: true, get: function () { return errors_js_2.LaminarSchemaError; } });
+Object.defineProperty(exports, "LaminarIngestionError", { enumerable: true, get: function () { return errors_js_2.LaminarIngestionError; } });
+Object.defineProperty(exports, "LaminarQueryError", { enumerable: true, get: function () { return errors_js_2.LaminarQueryError; } });
+Object.defineProperty(exports, "LaminarSubscriptionError", { enumerable: true, get: function () { return errors_js_2.LaminarSubscriptionError; } });
+Object.defineProperty(exports, "LaminarInternalError", { enumerable: true, get: function () { return errors_js_2.LaminarInternalError; } });
+Object.defineProperty(exports, "toLaminarError", { enumerable: true, get: function () { return errors_js_2.toLaminarError; } });
+var arrow_js_1 = require("./arrow.js");
+Object.defineProperty(exports, "tableFrom", { enumerable: true, get: function () { return arrow_js_1.tableFrom; } });
+const native = require('../index.js') ?? undefined;
+/** Streaming writer for one source; single-owner. */
+class Writer {
+    #native;
+    /** @internal */
+    constructor(native) {
+        this.#native = native;
+    }
+    name() {
+        return this.#native.name();
+    }
+    schema() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.schema());
+    }
+    /** Push one batch built from row objects; returns rows written. `Date`
+     * values are converted to epoch milliseconds automatically. */
+    writeRows(rows) {
+        return (0, errors_js_1.wrapSync)(() => this.#native.writeRows(normalizeRows(rows)));
+    }
+    /** Push every batch from an Arrow IPC stream `Buffer`. */
+    writeArrow(bytes) {
+        return (0, errors_js_1.wrapSync)(() => this.#native.writeArrow(bytes));
+    }
+    /** Advance the event-time watermark (milliseconds since epoch). */
+    watermark(timestamp) {
+        this.#native.watermark(timestamp);
+    }
+    currentWatermark() {
+        return this.#native.currentWatermark();
+    }
+    /** Rows buffered in the source, not yet consumed by the pipeline. */
+    pending() {
+        return this.#native.pending();
+    }
+    capacity() {
+        return this.#native.capacity();
+    }
+    /** True when the source buffer is more than 80% full — slow down. */
+    isBackpressured() {
+        return this.#native.isBackpressured();
+    }
+    /** Idempotent; writes after close throw `LaminarIngestionError` (301). */
+    close() {
+        this.#native.close();
+    }
+}
+exports.Writer = Writer;
+/** Convert `Date` instances to epoch milliseconds (the native seam's
+ * temporal convention) inside row objects; other values pass through. */
+function normalizeRows(rows) {
+    let changed = false;
+    const normalized = rows.map((row) => {
+        let rowChanged = false;
+        const copy = {};
+        for (const [key, value] of Object.entries(row)) {
+            if (value instanceof Date) {
+                copy[key] = value.getTime();
+                rowChanged = true;
+            }
+            else {
+                copy[key] = value;
+            }
+        }
+        if (rowChanged)
+            changed = true;
+        return rowChanged ? copy : row;
+    });
+    return changed ? normalized : rows;
+}
+/**
+ * An open LaminarDB connection. Safe to share across async contexts;
+ * `close()` is idempotent, and use after close throws
+ * `LaminarConnectionError` (101) rather than crashing.
+ *
+ * DDL that changes topology (`CREATE SOURCE`/`STREAM`/`SINK`) must run
+ * before `start()`; the engine rejects topology changes on a running
+ * pipeline.
+ */
+class Connection {
+    #native;
+    /** @internal */
+    constructor(native) {
+        this.#native = native;
+    }
+    /**
+     * Execute one SQL statement. `SELECT` returns `kind: 'query'` with the
+     * fully collected `result`; SHOW/DESCRIBE return `kind: 'metadata'`.
+     */
+    execute(sql) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.execute(sql)).then(mapOutcome);
+    }
+    /** Execute a query and return its collected result; non-query SQL throws
+     * `LaminarQueryError` (400). */
+    query(sql) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.query(sql)).then(wrapResult);
+    }
+    /** Ingest row objects into a source; returns rows pushed. `Date` values
+     * are converted to epoch milliseconds automatically. */
+    insert(source, rows) {
+        return (0, errors_js_1.wrapSync)(() => this.#native.insert(source, normalizeRows(rows)));
+    }
+    /** Ingest an Arrow IPC stream `Buffer` into a source; returns rows pushed. */
+    insertArrow(source, bytes) {
+        return (0, errors_js_1.wrapSync)(() => this.#native.insertArrow(source, bytes));
+    }
+    /** Open a streaming writer for a source (throws 200 if unknown). */
+    writer(source) {
+        return (0, errors_js_1.wrapSync)(() => new Writer(this.#native.writer(source)));
+    }
+    /** Start the streaming pipeline (idempotent). */
+    start() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.start());
+    }
+    /**
+     * Trigger a manual checkpoint. Requires checkpointing in the open config
+     * and at least one stream or sink in the topology (the core wires the
+     * coordinator only for real pipelines).
+     */
+    checkpoint() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.checkpoint());
+    }
+    isCheckpointEnabled() {
+        return this.#native.isCheckpointEnabled();
+    }
+    listSources() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.listSources());
+    }
+    listStreams() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.listStreams());
+    }
+    listSinks() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.listSinks());
+    }
+    sourceInfos() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.sourceInfos());
+    }
+    /** Schema of a source; unknown names throw `LaminarSchemaError` (200). */
+    schema(name) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.schema(name));
+    }
+    /** Subscribe to a stream or materialized view (pull style). The returned
+     * subscription is async-iterable; terminal failures throw
+     * `LaminarSubscriptionError` (502 lag / 500 otherwise) and end iteration. */
+    subscribe(name, options) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.subscribe(name, options?.filter ?? null, options?.fromEpoch ?? null)).then((subscription) => new Subscription(subscription));
+    }
+    /** Subscribe push style: `onData` per frame (awaited per delivery —
+     * backpressure, not queueing). Errors and open failures surface via
+     * `onError`, always followed by `onClose`. */
+    subscribeWith(name, handlers, options) {
+        // WHY the wrapper: native delivery awaits the returned promise, so sync
+        // handlers must still produce one; this is the settlement-aware
+        // backpressure contract (plan 03).
+        const userHandler = handlers.onData;
+        const promiseReturning = (frame) => {
+            const settled = userHandler(frame);
+            return settled instanceof Promise ? settled : Promise.resolve();
+        };
+        const native = (0, errors_js_1.wrapSync)(() => this.#native.subscribeWith(name, options?.filter ?? null, options?.fromEpoch ?? null, promiseReturning, handlers.onError ?? (() => { }), handlers.onClose ?? (() => { })));
+        return new PushSubscription(native);
+    }
+    /** Execute a query and stream its batches on demand; non-query SQL throws
+     * `LaminarQueryError` (400). The stream is async-iterable. */
+    streamQuery(sql) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.streamQuery(sql)).then((stream) => new QueryStream(stream));
+    }
+    /** Cancel a query by the id reported by `streamQuery().queryId`. */
+    cancelQuery(queryId) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.cancelQuery(queryId));
+    }
+    /** Aggregate pipeline counters. */
+    metrics() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.metrics());
+    }
+    /** Counters for one source; unknown names throw (200). */
+    sourceMetrics(name) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.sourceMetrics(name));
+    }
+    /** Counters for every source. */
+    allSourceMetrics() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.allSourceMetrics());
+    }
+    /** Counters for one stream; unknown names throw (200). */
+    streamMetrics(name) {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.streamMetrics(name));
+    }
+    /** Counters for every stream. */
+    allStreamMetrics() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.allStreamMetrics());
+    }
+    /** Engine lifecycle state name (e.g. `Running`). */
+    pipelineState() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.pipelineState());
+    }
+    /** Minimum event-time watermark across sources (epoch milliseconds). */
+    pipelineWatermark() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.pipelineWatermark());
+    }
+    /** Total events the pipeline has processed. */
+    totalEventsProcessed() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.totalEventsProcessed());
+    }
+    isClosed() {
+        return this.#native.isClosed();
+    }
+    /** Graceful shutdown; idempotent and safe under concurrent calls. */
+    close() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.close());
+    }
+}
+exports.Connection = Connection;
+/** A pull-based framed subscription; async-iterable:
+ * `for await (const frame of conn.subscribe('rollup'))`. */
+class Subscription {
+    #native;
+    /** @internal */
+    constructor(native) {
+        this.#native = native;
+    }
+    schema() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.schema());
+    }
+    /** Next frame, or `null` at end-of-stream / after `cancel()`. */
+    nextFrame() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.nextFrame());
+    }
+    isActive() {
+        return this.#native.isActive();
+    }
+    /** Idempotent; a pending `nextFrame` resolves `null`. */
+    cancel() {
+        this.#native.cancel();
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const frame = await this.nextFrame();
+                return frame === null
+                    ? { value: undefined, done: true }
+                    : { value: frame, done: false };
+            },
+            return: async () => {
+                this.cancel();
+                return { value: undefined, done: true };
+            },
+        };
+    }
+}
+exports.Subscription = Subscription;
+/** A push-based subscription handle; `close()` stops delivery and resolves
+ * after the reader has stopped (no callbacks fire afterwards). */
+class PushSubscription {
+    #native;
+    /** @internal */
+    constructor(native) {
+        this.#native = native;
+    }
+    isActive() {
+        return this.#native.isActive();
+    }
+    /** Stop delivery and wait for the reader. Idempotent. */
+    close() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.close());
+    }
+}
+exports.PushSubscription = PushSubscription;
+/** A streaming query result; async-iterable over `ArrowBatch`es:
+ * `for await (const batch of conn.streamQuery(sql))`. */
+class QueryStream {
+    #native;
+    /** @internal */
+    constructor(native) {
+        this.#native = native;
+    }
+    schema() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.schema());
+    }
+    /** Query id, usable with `Connection.cancelQuery`. */
+    queryId() {
+        return this.#native.queryId();
+    }
+    /** Next batch, or `null` at end-of-stream / after `cancel()`. */
+    nextBatch() {
+        return (0, errors_js_1.wrapAsync)(() => this.#native.nextBatch());
+    }
+    /** Idempotent; a pending `nextBatch` resolves `null`. */
+    cancel() {
+        this.#native.cancel();
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const batch = await this.nextBatch();
+                return batch === null
+                    ? { value: undefined, done: true }
+                    : { value: batch, done: false };
+            },
+            return: async () => {
+                this.cancel();
+                return { value: undefined, done: true };
+            },
+        };
+    }
+}
+exports.QueryStream = QueryStream;
+/** Entry point. */
+class LaminarDB {
+    constructor() {
+        throw new Error('LaminarDB is a static entry point; use LaminarDB.open()');
+    }
+    /**
+     * Open an embedded database. `open()` and `open(':memory:')` are
+     * in-memory; `open(path)` sets the storage directory (local-durable
+     * embedded mode when `checkpoint` is configured); `config.storageDir`
+     * wins over the positional path.
+     */
+    static open(path, config) {
+        return (0, errors_js_1.wrapAsync)(() => native.open(path, config)).then((connection) => new Connection(connection));
+    }
+    /** Binding and pinned-core version, e.g. `0.30.0-alpha.1 (core v0.30.0)`. */
+    static version() {
+        return native.version();
+    }
+}
+exports.LaminarDB = LaminarDB;
+class QueryResultImpl {
+    #native;
+    constructor(native) {
+        this.#native = native;
+    }
+    schema() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.schema());
+    }
+    numRows() {
+        return this.#native.numRows();
+    }
+    numBatches() {
+        return this.#native.numBatches();
+    }
+    batch(index) {
+        return (0, errors_js_1.wrapSync)(() => new ArrowBatchImpl(this.#native.batch(index)));
+    }
+    toIPC() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.toIPC());
+    }
+    toArray() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.toArray());
+    }
+}
+class ArrowBatchImpl {
+    #native;
+    constructor(native) {
+        this.#native = native;
+    }
+    numRows() {
+        return this.#native.numRows();
+    }
+    numColumns() {
+        return this.#native.numColumns();
+    }
+    schema() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.schema());
+    }
+    toIPC() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.toIPC());
+    }
+    toArray() {
+        return (0, errors_js_1.wrapSync)(() => this.#native.toArray());
+    }
+}
+function wrapResult(native) {
+    return new QueryResultImpl(native);
+}
+function mapOutcome(native) {
+    return {
+        kind: native.kind,
+        statementType: native.statementType,
+        objectName: native.objectName,
+        rowsAffected: native.rowsAffected,
+        queryId: native.queryId,
+        result: native.result === undefined ? undefined : wrapResult(native.result),
+    };
+}