@laminardb/node 0.30.0-alpha.1

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