@zvndev/powdb-client 0.9.0 → 0.11.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,393 @@
+/**
+ * PowDB TypeScript client.
+ *
+ * Thin async wrapper around a TCP (or TLS) socket speaking the PowDB wire
+ * protocol.
+ *
+ *     const client = await Client.connect({
+ *       host: "127.0.0.1",
+ *       port: 5433,
+ *       dbName: "default",
+ *       password: process.env.POWDB_PASSWORD,
+ *     });
+ *
+ *     const result = await client.query("User filter .age > 27 { .name, .age }");
+ *     await client.close();
+ */
+import * as tls from "node:tls";
+import { EventEmitter } from "node:events";
+import { type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus } from "./protocol.js";
+import { type TypedRow, type TypedSchema } from "./typed.js";
+/** Client library version. Compared to the server's reported version. */
+export declare const CLIENT_VERSION = "0.11.0";
+export type QueryResult = {
+    kind: "rows";
+    columns: string[];
+    rows: string[][];
+} | {
+    kind: "scalar";
+    value: string;
+} | {
+    kind: "ok";
+    affected: bigint;
+} | {
+    kind: "message";
+    message: string;
+};
+/**
+ * A value bound to a positional `$N` placeholder in {@link Client.query}.
+ *
+ * The server binds these at the token level — a string is substituted as a
+ * literal token, never interpolated — so injection-shaped input is inert.
+ * Numbers bind as ints when integral and floats otherwise; `bigint` always
+ * binds as an int; `null` binds PowQL `null`.
+ */
+export type QueryParam = string | number | bigint | boolean | null;
+/** Options for {@link Client.execScript} / {@link Pool.execScript}. */
+export interface ExecScriptOptions {
+    /**
+     * When `true`, keep dispatching statements after one fails and return a
+     * per-statement outcome array instead of throwing. Defaults to `false`
+     * (fail-fast: stop dispatching and reject with a {@link PowDBScriptError}
+     * carrying the failing statement's index and the results so far).
+     */
+    continueOnError?: boolean;
+    /**
+     * When `true`, run the whole script atomically: `execScript` opens a
+     * transaction before dispatching and sends `commit` only after EVERY
+     * statement's reply has arrived successfully — on any failure it sends
+     * `rollback` instead, so no statement's effect survives. This is the only
+     * all-or-nothing mode: embedding your own `begin`/`commit` in a pipelined
+     * script is NOT safe (a trailing `commit` is already on the wire when an
+     * earlier error reply arrives, so partial work would commit), and a
+     * transactional script containing its own transaction-control statements
+     * is rejected up front. Mutually exclusive with `continueOnError`.
+     */
+    transactional?: boolean;
+    /** Abort the remaining statements (see {@link Client.query}). */
+    signal?: AbortSignal;
+}
+/**
+ * Per-statement outcome from `execScript(script, { continueOnError: true })`.
+ * Array order matches statement order in the script.
+ */
+export type ScriptStatementOutcome = {
+    statement: string;
+    ok: true;
+    result: QueryResult;
+} | {
+    statement: string;
+    ok: false;
+    error: Error;
+};
+/** Unsigned 64-bit sync protocol value. Numbers must be safe non-negative integers. */
+export type SyncU64 = bigint | number;
+/**
+ * Database identity carried by the sync protocol. Strings are the 32-hex-char
+ * form stored in `.powdb-sync/identity.json`; byte arrays must be exactly 16B.
+ */
+export type SyncDatabaseId = string | Uint8Array;
+export interface SyncPullRequest {
+    replicaId: string;
+    sinceLsn: SyncU64;
+    maxUnits: number;
+    maxBytes: SyncU64;
+    databaseId: SyncDatabaseId;
+    primaryGeneration: SyncU64;
+    walFormatVersion: number;
+    catalogVersion: number;
+    segmentFormatVersion: number;
+}
+export interface SyncAckRequest {
+    replicaId: string;
+    appliedLsn: SyncU64;
+    remoteLsn: SyncU64;
+}
+export interface SyncPullResult {
+    status: WireSyncStatus;
+    units: WireRetainedUnit[];
+    hasMore: boolean;
+}
+export interface SyncAckResult {
+    previousAppliedLsn: bigint;
+    appliedLsn: bigint;
+    remoteLsn: bigint;
+    advanced: boolean;
+    status: WireSyncStatus;
+}
+export interface ClientOptions {
+    /** TCP host. Required unless `path` (a Unix domain socket) is given. */
+    host?: string;
+    /** TCP port. Required unless `path` (a Unix domain socket) is given. */
+    port?: number;
+    /**
+     * Path to a Unix domain socket. When set, the client connects over the
+     * socket instead of TCP (same-host, ~2× lower round-trip latency) and
+     * `host`/`port`/`tls` are ignored. Requires a server started with
+     * `--socket <path>`.
+     */
+    path?: string;
+    dbName?: string;
+    password?: string | null;
+    /**
+     * User name for multi-user authentication. Servers ≥0.4.5 with named users
+     * defined require a `(user, password)` pair; role enforcement (readonly vs
+     * readwrite) requires server ≥0.4.6. Omit for legacy shared-password or
+     * no-auth servers — the Connect frame is then byte-identical to 0.3.x.
+     */
+    user?: string;
+    /** Connection timeout in ms. Defaults to 5000. */
+    connectTimeoutMs?: number;
+    /**
+     * Enable TLS. When `true`, connect over TLS with system defaults
+     * (servername is taken from `host`). When an object, passed through to
+     * `tls.connect(port, host, options)`. Defaults to plain TCP.
+     */
+    tls?: boolean | tls.ConnectionOptions;
+    /**
+     * Pipelined ("eager") connect. When `true`, {@link Client.connect}
+     * resolves as soon as the socket is open and the Connect frame has been
+     * written — it does NOT wait for the server's ConnectOk. Queries issued
+     * immediately are queued and written right behind the Connect frame (the
+     * server reads frames sequentially, so this is valid on the wire), saving
+     * a full round trip on every fresh connection.
+     *
+     * If the handshake then fails (bad password, protocol mismatch), every
+     * queued query rejects with the handshake error and the client closes.
+     * `serverVersion` is `""` until the ConnectOk arrives; await
+     * {@link Client.ready} if you need the handshake settled. Defaults to
+     * `false` (connect blocks until ConnectOk, exactly as before).
+     */
+    eager?: boolean;
+}
+/**
+ * Event map for {@link Client}. Typed so `client.on("query", ...)` gets
+ * inference for the payload.
+ *
+ *   - `"query"`: one emission per completed (or failed) query attempt,
+ *     whether via `query` or `queryTyped`. `durationMs` is the client-side
+ *     round-trip including abort handling. `ok=false` means the server
+ *     returned an Error frame or the client rejected locally.
+ *   - `"close"`: the underlying socket has been fully torn down. Emitted
+ *     once per client.
+ */
+export interface ClientEvents {
+    query: [
+        {
+            query: string;
+            durationMs: number;
+            ok: boolean;
+            kind?: "rows" | "scalar" | "ok" | "message";
+            error?: Error;
+        }
+    ];
+    sync: [
+        {
+            operation: "status" | "pull" | "ack";
+            replicaId: string;
+            durationMs: number;
+            ok: boolean;
+            status?: WireSyncStatus;
+            stale?: boolean;
+            repairAction?: SyncRepairAction;
+            units?: number;
+            advanced?: boolean;
+            error?: Error;
+        }
+    ];
+    close: [{
+        error: Error | null;
+    }];
+}
+export declare class Client extends EventEmitter<ClientEvents> {
+    private readonly socket;
+    /** FIFO of raw chunks; concatenated lazily when we try to decode. */
+    private readonly chunks;
+    /** Cached length of everything currently in `chunks`. */
+    private totalLen;
+    private readonly pending;
+    private closed;
+    private closeError;
+    /** Settled once the Connect→ConnectOk handshake completes (or fails). */
+    private handshake;
+    /** True once ConnectOk has been received. */
+    private handshakeComplete;
+    private _serverVersion;
+    /**
+     * Server version from the ConnectOk frame. For a client opened with
+     * `eager: true` this is `""` until the handshake reply arrives (await
+     * {@link ready} to guarantee it is populated).
+     */
+    get serverVersion(): string;
+    private constructor();
+    /**
+     * Open a connection, send Connect, and wait for ConnectOk.
+     *
+     * With `eager: true`, resolve as soon as the Connect frame is written
+     * instead — queries may be issued immediately and are pipelined behind
+     * the handshake (see {@link ClientOptions.eager} and {@link ready}).
+     */
+    static connect(opts: ClientOptions): Promise<Client>;
+    /**
+     * Resolves once the Connect→ConnectOk handshake has completed; rejects
+     * with the handshake error if it failed. For non-eager clients this has
+     * already settled by the time {@link connect} returns. Eager callers can
+     * await it to learn the handshake outcome without issuing a query.
+     */
+    ready(): Promise<void>;
+    /**
+     * Write the Connect frame and register the handshake as the first entry
+     * in the pending queue. The reply-matching machinery is strictly FIFO, so
+     * the ConnectOk (or Error) frame is matched to the handshake before any
+     * pipelined query sees a reply. On failure, every queued query is
+     * rejected with the handshake error and the socket is torn down.
+     */
+    private startHandshake;
+    /**
+     * Run a PowQL statement and return the typed result.
+     *
+     * When `opts.signal` is provided and fires, the returned promise rejects
+     * with the signal's `reason` (or an `AbortError`). The socket is NOT
+     * destroyed — the server will still eventually send its reply, which we
+     * silently discard so other in-flight queries keep working.
+     */
+    query(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<QueryResult>;
+    /**
+     * Run a SQL statement through the server-side SQL frontend. The plain
+     * {@link query} method remains PowQL for wire compatibility.
+     */
+    querySql(query: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<QueryResult>;
+    /**
+     * Fetch primary-side sync status for one embedded replica cursor.
+     *
+     * This speaks the private authenticated sync frame added for the embedded
+     * replica product. Servers without sync support return a protocol/query
+     * error; unauthenticated or readonly users are rejected server-side.
+     */
+    syncStatus(replicaId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<WireSyncStatus>;
+    /**
+     * Pull a bounded retained-unit chunk after this replica's primary-side cursor.
+     *
+     * The caller supplies the database identity and format versions from the
+     * sync bootstrap metadata. The server rejects mismatches and non-applyable
+     * transaction cuts instead of returning ambiguous history.
+     */
+    syncPull(request: SyncPullRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SyncPullResult>;
+    /** Acknowledge that the replica applied retained history through `appliedLsn`. */
+    syncAck(request: SyncAckRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SyncAckResult>;
+    /**
+     * Like {@link query}, but coerces string result columns to typed JS values
+     * using the caller-supplied schema. See `./typed.ts` for the coercion
+     * rules and supported column types.
+     *
+     * Returns a `TypedRow[]` — an array of objects keyed by column name.
+     * Throws `PowDBError(code="query_failed")` if the query is not a
+     * rows-returning query.
+     */
+    queryTyped(query: string, schema: TypedSchema, opts?: {
+        signal?: AbortSignal;
+    }): Promise<TypedRow[]>;
+    /**
+     * Execute a multi-statement PowQL script on this connection, pipelined.
+     *
+     * The script is split with the same statement-aware semantics as the CLI
+     * (see {@link splitStatements}: `;` inside string literals and `#`
+     * comments never splits; empty statements are dropped). All statements
+     * are then written down the single connection back-to-back WITHOUT
+     * waiting for each reply — the server reads frames sequentially, so an
+     * N-statement script costs one round trip instead of N. Results are
+     * collected in statement order.
+     *
+     * Error handling:
+     *   - Default (fail-fast): resolve with `QueryResult[]` (one entry per
+     *     statement). On the first failed statement, stop dispatching further
+     *     statements and reject with a {@link PowDBScriptError} carrying the
+     *     failing `statementIndex`, the `statement` text, and the successful
+     *     `results` so far. NOTE: because dispatch is pipelined, statements
+     *     already written when the error reply arrives (typically the whole
+     *     script) still execute server-side. If you need all-or-nothing
+     *     behavior use `transactional: true` — do NOT embed `begin`/`commit`
+     *     in the script yourself: the trailing `commit` is already on the
+     *     wire when an error reply arrives, so it commits the partial work.
+     *   - `transactional: true`: `execScript` opens the transaction itself,
+     *     waits for every statement's reply, and only then sends `commit`
+     *     (or `rollback` if any statement failed), so no statement's effect
+     *     survives a failure. On failure the {@link PowDBScriptError}'s
+     *     `results` are the replies received before rollback — their effects
+     *     are NOT persisted.
+     *   - `continueOnError: true`: dispatch every statement regardless of
+     *     failures and resolve with a dense {@link ScriptStatementOutcome}
+     *     array recording each statement's result or error.
+     *
+     * Each statement emits the usual `"query"` event.
+     */
+    execScript(script: string, opts?: {
+        continueOnError?: false;
+        transactional?: boolean;
+        signal?: AbortSignal;
+    }): Promise<QueryResult[]>;
+    execScript(script: string, opts: {
+        continueOnError: true;
+        signal?: AbortSignal;
+    }): Promise<ScriptStatementOutcome[]>;
+    /**
+     * Poll a query on an interval and invoke `onRows` for every successful
+     * run. Returns an unsubscribe function. Does NOT deduplicate results —
+     * `onRows` fires every interval, even if the rows are unchanged.
+     *
+     * Pragmatic first-cut live-data. If a query takes longer than
+     * `intervalMs`, the next tick waits for the in-flight one to finish
+     * (no pile-up). Errors fire `onError` (if provided) without stopping
+     * the watcher unless `stopOnError: true`.
+     */
+    watch(query: string, opts: {
+        intervalMs: number;
+        onRows: (rows: QueryResult) => void;
+        onError?: (err: Error) => void;
+        stopOnError?: boolean;
+    }): {
+        stop: () => void;
+    };
+    /**
+     * Send Disconnect and tear down the socket. Waits for the remote FIN-ack
+     * (`socket.end` callback) but falls back to `destroy()` after a bounded
+     * timeout so an unresponsive peer cannot make `close()` hang forever.
+     */
+    close(): Promise<void>;
+    private send;
+    /**
+     * Resolve once the socket's write buffer has drained. Also resolves if
+     * the client closes while waiting, so a dead peer cannot hang a
+     * backpressured `execScript` dispatch loop forever.
+     */
+    private drained;
+    private onData;
+    /** Collapse the chunk queue into a single Buffer. */
+    private coalesce;
+    /** Drop the first `n` bytes off the chunk queue. */
+    private consume;
+    private onClose;
+}
+export { encode, tryDecode } from "./protocol.js";
+export type { Message, SyncRepairAction, WireParam, WireRetainedUnit, WireSyncStatus, } from "./protocol.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
+export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
+export { Pool } from "./pool.js";
+export type { PoolOptions } from "./pool.js";
+export { splitStatements } from "./script.js";
+export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
+export type { PowDBErrorCode } from "./errors.js";
+export { coerceValue, coerceRow, coerceRows, } from "./typed.js";
+export type { ColumnType, TypedSchema, TypedRow, Coerced, } from "./typed.js";