@laminardb/node 0.30.0-alpha.2 → 0.30.0-alpha.3

package/dist/arrow.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `apache-arrow` interop helpers (plan 00 D6).
+ *
+ * `apache-arrow` is an optional peer dependency: these helpers load it
+ * lazily and throw a clear `LaminarError` when it is absent. The IPC
+ * `Buffer` API on results/batches always works without it.
+ */
+import type { ArrowBatch, QueryResult } from './index.js';
+/**
+ * Rehydrate a whole result (or a single batch) as an `apache-arrow` `Table`
+ * via `tableFromIPC`. Requires the optional `apache-arrow` dependency.
+ */
+export declare function tableFrom(source: QueryResult | ArrowBatch): unknown;

package/dist/arrow.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * `apache-arrow` interop helpers (plan 00 D6).
+ *
+ * `apache-arrow` is an optional peer dependency: these helpers load it
+ * lazily and throw a clear `LaminarError` when it is absent. The IPC
+ * `Buffer` API on results/batches always works without it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tableFrom = tableFrom;
+const errors_js_1 = require("./errors.js");
+let arrowModule;
+function arrow() {
+    if (arrowModule === undefined) {
+        try {
+            // WHY require: optional peer — load lazily so absence only fails here
+            arrowModule = require('apache-arrow');
+        }
+        catch {
+            throw new errors_js_1.LaminarInternalError('apache-arrow is not installed; add it as a dependency to use tableFrom(), or use the toIPC()/toArray() APIs', 900);
+        }
+    }
+    return arrowModule;
+}
+/**
+ * Rehydrate a whole result (or a single batch) as an `apache-arrow` `Table`
+ * via `tableFromIPC`. Requires the optional `apache-arrow` dependency.
+ */
+function tableFrom(source) {
+    return arrow().tableFromIPC(source.toIPC());
+}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The typed error hierarchy (plan 00 D2/D8).
+ *
+ * The native seam throws plain `Error`s whose message starts with
+ * `[LAMINAR_<code>]` (napi-rs 3.12 cannot carry custom codes across promise
+ * rejections — see docs/plans/01 spike results). The public API re-throws
+ * them as `LaminarError` subclasses with a real `code` property and the
+ * prefix stripped from `message`.
+ */
+/** Base class: engine or binding failure with a numeric core error code. */
+export declare class LaminarError extends Error {
+    /** Numeric code from the core taxonomy (e.g. `400`). */
+    readonly code: number;
+    /** Class name (e.g. `LaminarQueryError`). */
+    readonly codeName: string;
+    constructor(message: string, code: number, options?: {
+        cause?: unknown;
+    });
+}
+/** 100–199: connection lifecycle failures. */
+export declare class LaminarConnectionError extends LaminarError {
+}
+/** 200–299: schema and catalog failures. */
+export declare class LaminarSchemaError extends LaminarError {
+}
+/** 300–399: ingestion failures. */
+export declare class LaminarIngestionError extends LaminarError {
+}
+/** 400–499: query failures. */
+export declare class LaminarQueryError extends LaminarError {
+}
+/** 500–599: subscription failures. */
+export declare class LaminarSubscriptionError extends LaminarError {
+}
+/** 900–999: internal engine or binding failures. */
+export declare class LaminarInternalError extends LaminarError {
+}
+/**
+ * Convert a thrown native error into the typed hierarchy. Coded errors get
+ * the matching subclass with the prefix stripped; napi argument-coercion
+ * failures (below the engine layer) and anything unrecognized wrap into
+ * `LaminarInternalError` with code `900`, preserving the original as
+ * `cause`.
+ */
+export declare function toLaminarError(error: unknown): LaminarError;
+/** Run `thunk`, re-throwing any failure through {@link toLaminarError}. */
+export declare function wrapSync<T>(thunk: () => T): T;
+/**
+ * Call `work` and await its result, re-throwing both synchronous throws (napi
+ * argument coercion happens before the promise exists) and rejections through
+ * {@link toLaminarError}.
+ */
+export declare function wrapAsync<T>(work: () => PromiseLike<T>): Promise<T>;

package/dist/errors.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * The typed error hierarchy (plan 00 D2/D8).
+ *
+ * The native seam throws plain `Error`s whose message starts with
+ * `[LAMINAR_<code>]` (napi-rs 3.12 cannot carry custom codes across promise
+ * rejections — see docs/plans/01 spike results). The public API re-throws
+ * them as `LaminarError` subclasses with a real `code` property and the
+ * prefix stripped from `message`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+exports.toLaminarError = toLaminarError;
+exports.wrapSync = wrapSync;
+exports.wrapAsync = wrapAsync;
+const CODE_PREFIX = /^\[LAMINAR_(\d+)\]\s?/;
+/** Base class: engine or binding failure with a numeric core error code. */
+class LaminarError extends Error {
+    /** Numeric code from the core taxonomy (e.g. `400`). */
+    code;
+    /** Class name (e.g. `LaminarQueryError`). */
+    codeName;
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.code = code;
+        this.codeName = new.target.name;
+    }
+}
+exports.LaminarError = LaminarError;
+/** 100–199: connection lifecycle failures. */
+class LaminarConnectionError extends LaminarError {
+}
+exports.LaminarConnectionError = LaminarConnectionError;
+/** 200–299: schema and catalog failures. */
+class LaminarSchemaError extends LaminarError {
+}
+exports.LaminarSchemaError = LaminarSchemaError;
+/** 300–399: ingestion failures. */
+class LaminarIngestionError extends LaminarError {
+}
+exports.LaminarIngestionError = LaminarIngestionError;
+/** 400–499: query failures. */
+class LaminarQueryError extends LaminarError {
+}
+exports.LaminarQueryError = LaminarQueryError;
+/** 500–599: subscription failures. */
+class LaminarSubscriptionError extends LaminarError {
+}
+exports.LaminarSubscriptionError = LaminarSubscriptionError;
+/** 900–999: internal engine or binding failures. */
+class LaminarInternalError extends LaminarError {
+}
+exports.LaminarInternalError = LaminarInternalError;
+function classFor(code) {
+    if (code >= 100 && code <= 199)
+        return LaminarConnectionError;
+    if (code >= 200 && code <= 299)
+        return LaminarSchemaError;
+    if (code >= 300 && code <= 399)
+        return LaminarIngestionError;
+    if (code >= 400 && code <= 499)
+        return LaminarQueryError;
+    if (code >= 500 && code <= 599)
+        return LaminarSubscriptionError;
+    return LaminarInternalError;
+}
+/**
+ * Convert a thrown native error into the typed hierarchy. Coded errors get
+ * the matching subclass with the prefix stripped; napi argument-coercion
+ * failures (below the engine layer) and anything unrecognized wrap into
+ * `LaminarInternalError` with code `900`, preserving the original as
+ * `cause`.
+ */
+function toLaminarError(error) {
+    if (error instanceof LaminarError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    const match = CODE_PREFIX.exec(message);
+    if (match) {
+        const code = Number.parseInt(match[1], 10);
+        const Class = classFor(code);
+        return new Class(message.slice(match[0].length), code, { cause: error });
+    }
+    return new LaminarInternalError(message, 900, { cause: error });
+}
+/** Run `thunk`, re-throwing any failure through {@link toLaminarError}. */
+function wrapSync(thunk) {
+    try {
+        return thunk();
+    }
+    catch (error) {
+        throw toLaminarError(error);
+    }
+}
+/**
+ * Call `work` and await its result, re-throwing both synchronous throws (napi
+ * argument coercion happens before the promise exists) and rejections through
+ * {@link toLaminarError}.
+ */
+async function wrapAsync(work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        throw toLaminarError(error);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+/**
+ * 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.
+ */
+export { LaminarError, LaminarConnectionError, LaminarSchemaError, LaminarIngestionError, LaminarQueryError, LaminarSubscriptionError, LaminarInternalError, toLaminarError, } from './errors.js';
+export { tableFrom } from './arrow.js';
+/** One column of a result schema; `dataType` is informational. */
+export interface FieldInfo {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+}
+/** Checkpointing options; an empty object enables manual checkpoints only. */
+export interface CheckpointConfig {
+    /** Interval in milliseconds; omitted = manual `checkpoint()` only. */
+    intervalMs?: number;
+    /** One attempt deadline in milliseconds; omitted = core default (120 s). */
+    timeoutMs?: number;
+    /** Checkpoint directory; omitted = storage directory, then `./data`. */
+    dataDir?: string;
+    maxNodeDataBytes?: number;
+}
+/** Connection options for {@link LaminarDB.open}. */
+export interface OpenConfig {
+    /** Local durability directory; wins over the positional path argument. */
+    storageDir?: string;
+    checkpoint?: CheckpointConfig;
+    /** Default source buffer size in rows. */
+    bufferSize?: number;
+    /** Emit windowed aggregates incrementally before window close. */
+    incrementalEmit?: boolean;
+    /** Object-store URL for cloud checkpoints (e.g. `s3://bucket/prefix`). */
+    objectStoreUrl?: string;
+    objectStoreOptions?: Record<string, string>;
+}
+/** Row object: column name to value. `null` marks null slots. */
+export type Row = Record<string, unknown>;
+/** A fully collected query result. Obtain via `Connection.query()` or
+ * `ExecuteOutcome.result`. */
+export interface QueryResult {
+    /** Schema fields in declaration order. */
+    schema(): FieldInfo[];
+    numRows(): number;
+    numBatches(): number;
+    /** Batch `index` (0-based); throws `LaminarQueryError` (400) if out of range. */
+    batch(index: number): ArrowBatch;
+    /** The whole result as one Arrow IPC stream `Buffer`. */
+    toIPC(): Buffer;
+    /** All rows as objects; see the conversion notes in the README. */
+    toArray(): Row[];
+}
+/** One Arrow RecordBatch of query output. */
+export interface ArrowBatch {
+    numRows(): number;
+    numColumns(): number;
+    schema(): FieldInfo[];
+    toIPC(): Buffer;
+    toArray(): Row[];
+}
+/** One executed statement's outcome; `kind` discriminates the payload. */
+export interface ExecuteOutcome {
+    readonly kind: 'ddl' | 'rows-affected' | 'query' | 'metadata';
+    readonly statementType?: string;
+    readonly objectName?: string;
+    readonly rowsAffected?: number;
+    readonly queryId?: number;
+    /** The collected result for `query`/`metadata` kinds; `undefined` otherwise. */
+    readonly result?: QueryResult;
+}
+/** One frame from a subscription: `data` carries a batch, `barrier` marks
+ * checkpoint progress. */
+export interface SubscriptionFrame {
+    readonly kind: 'data' | 'barrier';
+    readonly batch?: ArrowBatch;
+    /** Portal-local sequence (neither durable nor cluster-global). */
+    readonly sequence: number;
+    readonly epoch?: number;
+    readonly checkpointId?: number;
+    readonly throughSequence?: number;
+}
+/** Options for the subscription styles. */
+export interface SubscribeOptions {
+    /** Optional SQL row filter applied server-side. */
+    filter?: string;
+    /** Replay entries after this committed checkpoint epoch (rejects when
+     * unretained). */
+    fromEpoch?: number;
+}
+/** Push-style handlers for `subscribeWith`. */
+export interface PushHandlers {
+    /** May be sync or async: the facade normalizes every delivery to an
+     * awaited promise, so slow handlers backpressure the stream. Rejections
+     * surface once via `onError` and stop delivery. */
+    onData: (frame: SubscriptionFrame) => void | Promise<void>;
+    onError?: (error: {
+        code: number;
+        message: string;
+    }) => void;
+    onClose?: () => void;
+}
+/** Aggregate pipeline counters. */
+export interface PipelineMetricsInfo {
+    totalEventsIngested: number;
+    totalEventsEmitted: number;
+    totalEventsDropped: number;
+    totalCycles: number;
+    totalBatches: number;
+    uptimeMs: number;
+    state: string;
+    sourceCount: number;
+    streamCount: number;
+    sinkCount: number;
+    pipelineWatermark: number;
+    mvUpdates: number;
+    mvBytesStored: number;
+}
+/** Counters for one source. */
+export interface SourceMetricsInfo {
+    name: string;
+    totalEvents: number;
+    pending: number;
+    capacity: number;
+    isBackpressured: boolean;
+    watermark: number;
+    utilization: number;
+}
+/** Counters for one stream. */
+export interface StreamMetricsInfo {
+    name: string;
+    totalEvents: number;
+    sql?: string;
+}
+/** One manual checkpoint's outcome. */
+export interface CheckpointOutcome {
+    readonly success: boolean;
+    readonly checkpointId: number;
+    readonly epoch: number;
+    readonly durationMs: number;
+    readonly error?: string;
+}
+/** One registered source. */
+export interface SourceInfo {
+    name: string;
+    schema: FieldInfo[];
+    watermarkColumn?: string;
+}
+interface NativeFieldInfo {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+}
+interface NativeArrowBatch {
+    numRows(): number;
+    numColumns(): number;
+    schema(): NativeFieldInfo[];
+    toIPC(): Buffer;
+    toArray(): Record<string, unknown>[];
+}
+interface NativeQueryResult {
+    schema(): NativeFieldInfo[];
+    numRows(): number;
+    numBatches(): number;
+    batch(index: number): NativeArrowBatch;
+    toIPC(): Buffer;
+    toArray(): Record<string, unknown>[];
+}
+interface NativeExecuteOutcome {
+    readonly kind: string;
+    readonly statementType?: string;
+    readonly objectName?: string;
+    readonly rowsAffected?: number;
+    readonly queryId?: number;
+    readonly result?: NativeQueryResult;
+}
+interface NativeSubscriptionFrame {
+    readonly kind: 'data' | 'barrier' | string;
+    readonly batch?: NativeArrowBatch;
+    readonly sequence: number;
+    readonly epoch?: number;
+    readonly checkpointId?: number;
+    readonly throughSequence?: number;
+}
+interface NativeSubscription {
+    schema(): NativeFieldInfo[];
+    nextFrame(): Promise<NativeSubscriptionFrame | null>;
+    isActive(): boolean;
+    cancel(): void;
+}
+interface NativePushSubscription {
+    isActive(): boolean;
+    close(): Promise<void>;
+}
+interface NativeQueryStream {
+    schema(): NativeFieldInfo[];
+    queryId(): number;
+    nextBatch(): Promise<NativeArrowBatch | null>;
+    cancel(): void;
+}
+interface NativeConnection {
+    subscribe(name: string, filter: string | null, fromEpoch: number | null): Promise<NativeSubscription>;
+    subscribeWith(name: string, filter: string | null, fromEpoch: number | null, onData: (frame: SubscriptionFrame) => void | Promise<void>, onError: (error: {
+        code: number;
+        message: string;
+    }) => void, onClose: () => void): NativePushSubscription;
+    streamQuery(sql: string): Promise<NativeQueryStream>;
+    cancelQuery(queryId: number): Promise<void>;
+    metrics(): Promise<Omit<PipelineMetricsInfo, never>>;
+    sourceMetrics(name: string): Promise<SourceMetricsInfo>;
+    allSourceMetrics(): Promise<SourceMetricsInfo[]>;
+    streamMetrics(name: string): Promise<StreamMetricsInfo>;
+    allStreamMetrics(): Promise<StreamMetricsInfo[]>;
+    pipelineState(): Promise<string>;
+    pipelineWatermark(): Promise<number>;
+    totalEventsProcessed(): Promise<number>;
+    execute(sql: string): Promise<NativeExecuteOutcome>;
+    query(sql: string): Promise<NativeQueryResult>;
+    insert(source: string, rows: Record<string, unknown>[]): number;
+    insertArrow(source: string, bytes: Buffer): number;
+    writer(source: string): NativeWriter;
+    start(): Promise<void>;
+    checkpoint(): Promise<{
+        success: boolean;
+        checkpointId: number;
+        epoch: number;
+        durationMs: number;
+        error?: string;
+    }>;
+    isCheckpointEnabled(): boolean;
+    listSources(): Promise<string[]>;
+    listStreams(): Promise<string[]>;
+    listSinks(): Promise<string[]>;
+    sourceInfos(): Promise<{
+        name: string;
+        schema: NativeFieldInfo[];
+        watermarkColumn?: string;
+    }[]>;
+    schema(name: string): Promise<NativeFieldInfo[]>;
+    isClosed(): boolean;
+    close(): Promise<void>;
+}
+interface NativeWriter {
+    name(): string;
+    schema(): NativeFieldInfo[];
+    writeRows(rows: Record<string, unknown>[]): number;
+    writeArrow(bytes: Buffer): number;
+    watermark(timestamp: number): void;
+    currentWatermark(): number;
+    pending(): number;
+    capacity(): number;
+    isBackpressured(): boolean;
+    close(): void;
+}
+/** Streaming writer for one source; single-owner. */
+export declare class Writer {
+    #private;
+    /** @internal */
+    constructor(native: NativeWriter);
+    name(): string;
+    schema(): FieldInfo[];
+    /** Push one batch built from row objects; returns rows written. `Date`
+     * values are converted to epoch milliseconds automatically. */
+    writeRows(rows: Row[]): number;
+    /** Push every batch from an Arrow IPC stream `Buffer`. */
+    writeArrow(bytes: Buffer): number;
+    /** Advance the event-time watermark (milliseconds since epoch). */
+    watermark(timestamp: number): void;
+    currentWatermark(): number;
+    /** Rows buffered in the source, not yet consumed by the pipeline. */
+    pending(): number;
+    capacity(): number;
+    /** True when the source buffer is more than 80% full — slow down. */
+    isBackpressured(): boolean;
+    /** Idempotent; writes after close throw `LaminarIngestionError` (301). */
+    close(): void;
+}
+/**
+ * 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.
+ */
+export declare class Connection {
+    #private;
+    /** @internal */
+    constructor(native: NativeConnection);
+    /**
+     * Execute one SQL statement. `SELECT` returns `kind: 'query'` with the
+     * fully collected `result`; SHOW/DESCRIBE return `kind: 'metadata'`.
+     */
+    execute(sql: string): Promise<ExecuteOutcome>;
+    /** Execute a query and return its collected result; non-query SQL throws
+     * `LaminarQueryError` (400). */
+    query(sql: string): Promise<QueryResult>;
+    /** Ingest row objects into a source; returns rows pushed. `Date` values
+     * are converted to epoch milliseconds automatically. */
+    insert(source: string, rows: Row[]): number;
+    /** Ingest an Arrow IPC stream `Buffer` into a source; returns rows pushed. */
+    insertArrow(source: string, bytes: Buffer): number;
+    /** Open a streaming writer for a source (throws 200 if unknown). */
+    writer(source: string): Writer;
+    /** Start the streaming pipeline (idempotent). */
+    start(): Promise<void>;
+    /**
+     * 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(): Promise<CheckpointOutcome>;
+    isCheckpointEnabled(): boolean;
+    listSources(): Promise<string[]>;
+    listStreams(): Promise<string[]>;
+    listSinks(): Promise<string[]>;
+    sourceInfos(): Promise<SourceInfo[]>;
+    /** Schema of a source; unknown names throw `LaminarSchemaError` (200). */
+    schema(name: string): Promise<FieldInfo[]>;
+    /** 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: string, options?: SubscribeOptions): Promise<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: string, handlers: PushHandlers, options?: SubscribeOptions): PushSubscription;
+    /** Execute a query and stream its batches on demand; non-query SQL throws
+     * `LaminarQueryError` (400). The stream is async-iterable. */
+    streamQuery(sql: string): Promise<QueryStream>;
+    /** Cancel a query by the id reported by `streamQuery().queryId`. */
+    cancelQuery(queryId: number): Promise<void>;
+    /** Aggregate pipeline counters. */
+    metrics(): Promise<PipelineMetricsInfo>;
+    /** Counters for one source; unknown names throw (200). */
+    sourceMetrics(name: string): Promise<SourceMetricsInfo>;
+    /** Counters for every source. */
+    allSourceMetrics(): Promise<SourceMetricsInfo[]>;
+    /** Counters for one stream; unknown names throw (200). */
+    streamMetrics(name: string): Promise<StreamMetricsInfo>;
+    /** Counters for every stream. */
+    allStreamMetrics(): Promise<StreamMetricsInfo[]>;
+    /** Engine lifecycle state name (e.g. `Running`). */
+    pipelineState(): Promise<string>;
+    /** Minimum event-time watermark across sources (epoch milliseconds). */
+    pipelineWatermark(): Promise<number>;
+    /** Total events the pipeline has processed. */
+    totalEventsProcessed(): Promise<number>;
+    isClosed(): boolean;
+    /** Graceful shutdown; idempotent and safe under concurrent calls. */
+    close(): Promise<void>;
+}
+/** A pull-based framed subscription; async-iterable:
+ * `for await (const frame of conn.subscribe('rollup'))`. */
+export declare class Subscription {
+    #private;
+    /** @internal */
+    constructor(native: NativeSubscription);
+    schema(): FieldInfo[];
+    /** Next frame, or `null` at end-of-stream / after `cancel()`. */
+    nextFrame(): Promise<SubscriptionFrame | null>;
+    isActive(): boolean;
+    /** Idempotent; a pending `nextFrame` resolves `null`. */
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SubscriptionFrame>;
+}
+/** A push-based subscription handle; `close()` stops delivery and resolves
+ * after the reader has stopped (no callbacks fire afterwards). */
+export declare class PushSubscription {
+    #private;
+    /** @internal */
+    constructor(native: NativePushSubscription);
+    isActive(): boolean;
+    /** Stop delivery and wait for the reader. Idempotent. */
+    close(): Promise<void>;
+}
+/** A streaming query result; async-iterable over `ArrowBatch`es:
+ * `for await (const batch of conn.streamQuery(sql))`. */
+export declare class QueryStream {
+    #private;
+    /** @internal */
+    constructor(native: NativeQueryStream);
+    schema(): FieldInfo[];
+    /** Query id, usable with `Connection.cancelQuery`. */
+    queryId(): number;
+    /** Next batch, or `null` at end-of-stream / after `cancel()`. */
+    nextBatch(): Promise<ArrowBatch | null>;
+    /** Idempotent; a pending `nextBatch` resolves `null`. */
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<ArrowBatch>;
+}
+/** Entry point. */
+export declare class LaminarDB {
+    private constructor();
+    /**
+     * 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?: string, config?: OpenConfig): Promise<Connection>;
+    /** Binding and pinned-core version, e.g. `0.30.0-alpha.1 (core v0.30.0)`. */
+    static version(): string;
+}

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),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laminardb/node",
-  "version": "0.30.0-alpha.2",
+  "version": "0.30.0-alpha.3",
   "description": "Embedded streaming SQL for Node.js — official LaminarDB native binding",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -76,12 +76,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@laminardb/node-linux-x64-gnu": "0.30.0-alpha.2",
-    "@laminardb/node-linux-x64-musl": "0.30.0-alpha.2",
-    "@laminardb/node-linux-arm64-gnu": "0.30.0-alpha.2",
-    "@laminardb/node-linux-arm64-musl": "0.30.0-alpha.2",
-    "@laminardb/node-darwin-x64": "0.30.0-alpha.2",
-    "@laminardb/node-darwin-arm64": "0.30.0-alpha.2",
-    "@laminardb/node-win32-x64-msvc": "0.30.0-alpha.2"
+    "@laminardb/node-linux-x64-gnu": "0.30.0-alpha.3",
+    "@laminardb/node-linux-x64-musl": "0.30.0-alpha.3",
+    "@laminardb/node-linux-arm64-gnu": "0.30.0-alpha.3",
+    "@laminardb/node-linux-arm64-musl": "0.30.0-alpha.3",
+    "@laminardb/node-darwin-x64": "0.30.0-alpha.3",
+    "@laminardb/node-darwin-arm64": "0.30.0-alpha.3",
+    "@laminardb/node-win32-x64-msvc": "0.30.0-alpha.3"
   }
 }