@zvndev/powdb-client 0.8.1 → 0.10.0

package/dist/cjs/script.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Statement-aware PowQL script splitting.
+ *
+ * Mirrors the server-side splitter (`powdb_query::lexer::split_statements`)
+ * exactly, so a script file behaves the same whether it is fed to the CLI's
+ * `--exec` / `.powql` path or to {@link Client.execScript} over the wire:
+ *
+ *   - `;` splits statements only at the top level.
+ *   - `;` inside a `"..."` string literal never splits. A backslash inside a
+ *     string consumes the next character unconditionally (mirroring the
+ *     PowQL lexer), so `\"` and `\;` stay inside the string.
+ *   - `#` starts a comment that runs to end-of-line; a `;` inside a comment
+ *     never splits.
+ *   - Segments are trimmed; empty segments (leading/doubled/trailing `;`,
+ *     blank lines) are dropped.
+ *   - Never errors: an unterminated string simply makes the rest of the
+ *     input the final segment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitStatements = splitStatements;
+/**
+ * Split a PowQL script into individual statements.
+ *
+ * String-literal- and `#`-comment-aware `;` splitting with the exact
+ * semantics of the CLI/server splitter (see module docs above).
+ */
+function splitStatements(input) {
+    const out = [];
+    let start = 0;
+    let state = "normal";
+    for (let i = 0; i < input.length; i++) {
+        const c = input[i];
+        switch (state) {
+            case "normal":
+                if (c === ";") {
+                    const seg = input.slice(start, i).trim();
+                    if (seg.length > 0)
+                        out.push(seg);
+                    start = i + 1;
+                }
+                else if (c === '"') {
+                    state = "in-string";
+                }
+                else if (c === "#") {
+                    state = "in-comment";
+                }
+                break;
+            case "in-string":
+                // Mirror the lexer: a backslash consumes the next char
+                // unconditionally, so `\"` and `\;` stay inside the string.
+                if (c === "\\") {
+                    i++;
+                }
+                else if (c === '"') {
+                    state = "normal";
+                }
+                break;
+            case "in-comment":
+                if (c === "\n")
+                    state = "normal";
+                break;
+        }
+    }
+    const seg = input.slice(start).trim();
+    if (seg.length > 0)
+        out.push(seg);
+    return out;
+}

package/dist/cjs/typed.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Optional row-level type coercion for `queryTyped`.
+ *
+ * The server's wire format serialises every value to a string (see
+ * `crates/server/src/handler.rs::value_to_display`):
+ *   Int      → decimal digits, e.g. "42" or "-7"
+ *   Float    → Rust `{}` format, e.g. "3.14"
+ *   Bool     → "true" / "false"
+ *   Str      → raw UTF-8 (may contain anything)
+ *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
+ *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Bytes    → "<N bytes>" (LOSSY — see note below)
+ *
+ * `queryTyped` takes a user-supplied schema and coerces each column string
+ * into the corresponding JS value. Rationale for requiring the caller to
+ * supply the schema (rather than introspecting): PowDB has no `describe`
+ * statement yet, and going via `select` off a system catalog is one extra
+ * round trip per typed query. When schema introspection lands, a helper
+ * that builds the schema object can be added without changing this API.
+ *
+ * Bytes caveat: the current wire format is lossy for byte columns (renders
+ * `<N bytes>`). Until the wire protocol grows a binary column type, this
+ * module throws on `bytes` columns rather than guessing — use `str` in the
+ * schema if you just want the `<N bytes>` placeholder.
+ */
+/**
+ * Supported column types. Mirrors the server's `DataType` enum minus the
+ * `Bytes` variant, which is intentionally unsupported here.
+ */
+export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid";
+/** Map of column name → declared type. Columns not in the map pass through as strings. */
+export type TypedSchema = Record<string, ColumnType>;
+/** Coerced value type. `int` may return `bigint` if the value exceeds Number.MAX_SAFE_INTEGER. */
+export type Coerced = number | bigint | boolean | string | Date | null;
+/** A row of coerced values keyed by column name. */
+export type TypedRow = Record<string, Coerced>;
+/**
+ * Coerce a single string value to the JS type declared in `schema`. `null`
+ * is returned for the conventional null sentinel — see note at call site.
+ * Unknown column types fall through as strings.
+ */
+export declare function coerceValue(column: string, raw: string, type: ColumnType | undefined): Coerced;
+/**
+ * Coerce a single result row (a string tuple) into a typed object keyed by
+ * column name.
+ */
+export declare function coerceRow(columns: string[], values: string[], schema: TypedSchema): TypedRow;
+/** Coerce every row in a rows-result into typed objects. */
+export declare function coerceRows(columns: string[], rows: string[][], schema: TypedSchema): TypedRow[];

package/dist/cjs/typed.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Optional row-level type coercion for `queryTyped`.
+ *
+ * The server's wire format serialises every value to a string (see
+ * `crates/server/src/handler.rs::value_to_display`):
+ *   Int      → decimal digits, e.g. "42" or "-7"
+ *   Float    → Rust `{}` format, e.g. "3.14"
+ *   Bool     → "true" / "false"
+ *   Str      → raw UTF-8 (may contain anything)
+ *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
+ *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Bytes    → "<N bytes>" (LOSSY — see note below)
+ *
+ * `queryTyped` takes a user-supplied schema and coerces each column string
+ * into the corresponding JS value. Rationale for requiring the caller to
+ * supply the schema (rather than introspecting): PowDB has no `describe`
+ * statement yet, and going via `select` off a system catalog is one extra
+ * round trip per typed query. When schema introspection lands, a helper
+ * that builds the schema object can be added without changing this API.
+ *
+ * Bytes caveat: the current wire format is lossy for byte columns (renders
+ * `<N bytes>`). Until the wire protocol grows a binary column type, this
+ * module throws on `bytes` columns rather than guessing — use `str` in the
+ * schema if you just want the `<N bytes>` placeholder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceValue = coerceValue;
+exports.coerceRow = coerceRow;
+exports.coerceRows = coerceRows;
+const errors_js_1 = require("./errors.js");
+/**
+ * Coerce a single string value to the JS type declared in `schema`. `null`
+ * is returned for the conventional null sentinel — see note at call site.
+ * Unknown column types fall through as strings.
+ */
+function coerceValue(column, raw, type) {
+    // The server's wire format distinguishes NULL from empty string by the
+    // literal "null" bareword in scalar displays. For typed columns we treat
+    // the single token "null" as NULL; empty string remains empty string for
+    // `str` columns (can be an intentional empty value).
+    if (type !== "str" && raw === "null")
+        return null;
+    switch (type) {
+        case undefined:
+        case "str":
+            return raw;
+        case "int": {
+            if (!/^-?\d+$/.test(raw)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared int but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            // Promote to BigInt when the value doesn't round-trip through Number.
+            const n = Number(raw);
+            if (Number.isSafeInteger(n))
+                return n;
+            return BigInt(raw);
+        }
+        case "float": {
+            const n = Number(raw);
+            if (!Number.isFinite(n)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared float but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            return n;
+        }
+        case "bool":
+            if (raw === "true")
+                return true;
+            if (raw === "false")
+                return false;
+            throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared bool but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+        case "datetime": {
+            if (!/^-?\d+$/.test(raw)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared datetime but got ${JSON.stringify(raw)} (expected microseconds since epoch)`, "type_coercion_failed");
+            }
+            // Server sends microseconds since epoch. JS Date uses milliseconds.
+            // BigInt division avoids float precision loss for far-future dates.
+            const micros = BigInt(raw);
+            const millis = Number(micros / 1000n);
+            return new Date(millis);
+        }
+        case "uuid": {
+            // Canonical 8-4-4-4-12 hex, lowercase (per server format).
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(raw)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared uuid but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            return raw;
+        }
+    }
+}
+/**
+ * Coerce a single result row (a string tuple) into a typed object keyed by
+ * column name.
+ */
+function coerceRow(columns, values, schema) {
+    const out = {};
+    for (let i = 0; i < columns.length; i++) {
+        const col = columns[i];
+        out[col] = coerceValue(col, values[i] ?? "null", schema[col]);
+    }
+    return out;
+}
+/** Coerce every row in a rows-result into typed objects. */
+function coerceRows(columns, rows, schema) {
+    return rows.map((r) => coerceRow(columns, r, schema));
+}

package/dist/errors.d.ts

@@ -6,6 +6,7 @@
  * is intentionally small — new codes are added only when a caller has a
  * legitimate reason to handle them differently.
  */
+import type { QueryResult } from "./index.js";
 export type PowDBErrorCode = 
 /** TCP/TLS connect, DNS, connect timeout. Transient — safe to retry. */
 "connect_failed"
@@ -41,3 +42,29 @@ export declare class PowDBError extends Error {
  * to branch on `.code` but TypeScript sees `unknown`.
  */
 export declare function isPowDBError(err: unknown): err is PowDBError;
+/**
+ * Failure of one statement inside `client.execScript(...)` (fail-fast mode).
+ *
+ * `code` mirrors the failing statement's error code (`"query_failed"` for a
+ * server Error frame, `"aborted"` for a fired AbortSignal, ...), so the usual
+ * `.code` branching keeps working; `cause` carries the underlying error.
+ * `statementIndex`/`statement` identify the failing statement within the
+ * split script, and `results` holds the successful results of every
+ * statement before it, in order.
+ */
+export declare class PowDBScriptError extends PowDBError {
+    /** Zero-based index of the failing statement within the split script. */
+    readonly statementIndex: number;
+    /** Text of the failing statement (as split, trimmed). */
+    readonly statement: string;
+    /** Results of the statements before the failing one, in order. */
+    readonly results: QueryResult[];
+    constructor(message: string, code: PowDBErrorCode, details: {
+        statementIndex: number;
+        statement: string;
+        results: QueryResult[];
+        cause?: unknown;
+    });
+}
+/** Narrow `unknown` to a PowDBScriptError. */
+export declare function isPowDBScriptError(err: unknown): err is PowDBScriptError;

package/dist/errors.js

@@ -29,3 +29,33 @@ export class PowDBError extends Error {
 export function isPowDBError(err) {
     return err instanceof PowDBError;
 }
+/**
+ * Failure of one statement inside `client.execScript(...)` (fail-fast mode).
+ *
+ * `code` mirrors the failing statement's error code (`"query_failed"` for a
+ * server Error frame, `"aborted"` for a fired AbortSignal, ...), so the usual
+ * `.code` branching keeps working; `cause` carries the underlying error.
+ * `statementIndex`/`statement` identify the failing statement within the
+ * split script, and `results` holds the successful results of every
+ * statement before it, in order.
+ */
+export class PowDBScriptError extends PowDBError {
+    /** Zero-based index of the failing statement within the split script. */
+    statementIndex;
+    /** Text of the failing statement (as split, trimmed). */
+    statement;
+    /** Results of the statements before the failing one, in order. */
+    results;
+    constructor(message, code, details) {
+        super(message, code, { cause: details.cause });
+        this.name = "PowDBScriptError";
+        this.statementIndex = details.statementIndex;
+        this.statement = details.statement;
+        this.results = details.results;
+        Object.setPrototypeOf(this, PowDBScriptError.prototype);
+    }
+}
+/** Narrow `unknown` to a PowDBScriptError. */
+export function isPowDBScriptError(err) {
+    return err instanceof PowDBScriptError;
+}

package/dist/index.d.ts

@@ -19,7 +19,7 @@ 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.8.1";
+export declare const CLIENT_VERSION = "0.10.0";
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -43,6 +43,43 @@ export type QueryResult = {
  * 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;
 /**
@@ -107,6 +144,21 @@ export interface ClientOptions {
      * `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
@@ -156,10 +208,41 @@ export declare class Client extends EventEmitter<ClientEvents> {
     private readonly pending;
     private closed;
     private closeError;
-    readonly serverVersion: string;
+    /** 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, wait for ConnectOk. */
+    /**
+     * 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.
      *
@@ -216,6 +299,49 @@ export declare class Client extends EventEmitter<ClientEvents> {
     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 —
@@ -241,6 +367,12 @@ export declare class Client extends EventEmitter<ClientEvents> {
      */
     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;
@@ -254,7 +386,8 @@ export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MA
 export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";
-export { PowDBError, isPowDBError } from "./errors.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";