@zvndev/powdb-client 0.8.1 → 0.10.0

package/dist/index.js

@@ -18,10 +18,20 @@ import * as net from "node:net";
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
 import { encode, tryDecode, MAX_SYNC_PULL_BYTES, MAX_SYNC_PULL_UNITS, } from "./protocol.js";
-import { PowDBError } from "./errors.js";
+import { PowDBError, PowDBScriptError, isPowDBError } from "./errors.js";
+import { splitStatements } from "./script.js";
 import { coerceRows, } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export const CLIENT_VERSION = "0.8.1";
+export const CLIENT_VERSION = "0.10.0";
+/** Transaction-control statements a `transactional` script may not contain. */
+const TX_CONTROL_RE = /^(begin|commit|rollback)\b/i;
+/**
+ * Leading trivia (whitespace and `#` line comments) that may precede a
+ * statement's first real token. Must be stripped before matching
+ * {@link TX_CONTROL_RE}: the server's lexer skips comments, so
+ * `"# note\ncommit"` executes a commit — the guard has to see it too.
+ */
+const LEADING_TRIVIA_RE = /^(?:\s+|#[^\n]*)+/;
 function socketChunkToBuffer(chunk) {
     return typeof chunk === "string" ? Buffer.from(chunk) : chunk;
 }
@@ -123,91 +133,99 @@ export class Client extends EventEmitter {
     pending = [];
     closed = false;
     closeError = null;
-    serverVersion;
-    constructor(socket, serverVersion) {
+    /** Settled once the Connect→ConnectOk handshake completes (or fails). */
+    handshake = Promise.resolve();
+    /** True once ConnectOk has been received. */
+    handshakeComplete = false;
+    _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() {
+        return this._serverVersion;
+    }
+    constructor(socket) {
         super();
         this.socket = socket;
-        this.serverVersion = serverVersion;
         this.socket.on("data", (chunk) => this.onData(socketChunkToBuffer(chunk)));
         this.socket.on("error", (err) => this.onClose(err));
         this.socket.on("close", () => this.onClose(null));
     }
-    /** 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 async connect(opts) {
-        const { host, port, path, dbName = "default", password = null, user, connectTimeoutMs = 5000, tls: tlsOpt = false, } = opts;
+        const { host, port, path, dbName = "default", password = null, user, connectTimeoutMs = 5000, tls: tlsOpt = false, eager = false, } = opts;
         if (path === undefined && (host === undefined || port === undefined)) {
             throw new PowDBError("connect requires either { path } (Unix socket) or { host, port } (TCP)", "connect_failed");
         }
         const socket = await openSocket({ host, port, path }, connectTimeoutMs, tlsOpt);
-        // We need to read the initial ConnectOk before wiring up the normal
-        // pending-queue machinery, so we do a one-shot handshake here.
-        const handshake = new Promise((resolve, reject) => {
-            let scratch = Buffer.alloc(0);
-            const cleanup = () => {
-                socket.removeListener("data", onData);
-                socket.removeListener("error", onError);
-                socket.removeListener("close", onClose);
-            };
-            const onData = (chunk) => {
-                scratch = Buffer.concat([scratch, socketChunkToBuffer(chunk)]);
-                let decoded;
-                try {
-                    decoded = tryDecode(scratch);
-                }
-                catch (err) {
-                    cleanup();
-                    reject(err);
-                    return;
-                }
-                if (decoded !== null) {
-                    cleanup();
-                    // Any bytes past the handshake frame belong to later responses.
-                    // This should not happen in practice, but handle it defensively.
-                    const leftover = scratch.subarray(decoded.consumed);
-                    if (leftover.length > 0) {
-                        socket.unshift(leftover);
-                    }
-                    resolve(decoded.msg);
+        const client = new Client(socket);
+        client.startHandshake({ type: "Connect", dbName, password, username: user ?? null }, path ?? `${host}:${port}`);
+        if (!eager) {
+            await client.ready();
+        }
+        return 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() {
+        return this.handshake;
+    }
+    /**
+     * 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.
+     */
+    startHandshake(connect, versionWarnKey) {
+        this.handshake = this.send(connect).then((reply) => {
+            if (reply.type === "Error") {
+                throw new PowDBError(`connect failed: ${reply.message}`, "auth_failed");
+            }
+            if (reply.type !== "ConnectOk") {
+                throw new PowDBError(`expected ConnectOk, got ${reply.type}`, "protocol_error");
+            }
+            this.handshakeComplete = true;
+            this._serverVersion = reply.version;
+            // Advisory: warn once per host:port if the server's major differs
+            // from the client's. Do not throw or close — this is best-effort.
+            const serverMajor = majorOf(reply.version);
+            const clientMajor = majorOf(CLIENT_VERSION);
+            if (serverMajor !== clientMajor) {
+                if (!versionWarnings.has(versionWarnKey)) {
+                    versionWarnings.add(versionWarnKey);
+                    console.warn(`[powdb] server version ${reply.version} major (${serverMajor}) ` +
+                        `differs from client ${CLIENT_VERSION} major (${clientMajor}); ` +
+                        `behaviour may be inconsistent.`);
                 }
-            };
-            const onError = (err) => {
-                cleanup();
-                reject(err);
-            };
-            // Without this, a peer that FINs the connection mid-handshake (no
-            // explicit error event) would leave this promise pending forever.
-            const onClose = () => {
-                cleanup();
-                reject(new PowDBError("connection closed during handshake", "connect_failed"));
-            };
-            socket.on("data", onData);
-            socket.on("error", onError);
-            socket.on("close", onClose);
+            }
+        }, (err) => {
+            // The connection dropped before a handshake reply — surface it as a
+            // connect failure (transient, retryable) rather than a bare close.
+            if (isPowDBError(err) && err.code === "closed") {
+                throw new PowDBError("connection closed during handshake", "connect_failed", { cause: err });
+            }
+            throw err;
+        });
+        // On handshake failure, reject everything queued behind it and tear the
+        // socket down. The extra no-op catch keeps an eager caller that never
+        // awaits ready() from tripping an unhandled-rejection crash.
+        this.handshake.catch((err) => {
+            this.onClose(err);
+            this.socket.destroy();
         });
-        socket.write(encode({ type: "Connect", dbName, password, username: user ?? null }));
-        const reply = await handshake;
-        if (reply.type === "Error") {
-            socket.destroy();
-            throw new PowDBError(`connect failed: ${reply.message}`, "auth_failed");
-        }
-        if (reply.type !== "ConnectOk") {
-            socket.destroy();
-            throw new PowDBError(`expected ConnectOk, got ${reply.type}`, "protocol_error");
-        }
-        // Advisory: warn once per host:port if the server's major differs
-        // from the client's. Do not throw or close — this is best-effort.
-        const serverMajor = majorOf(reply.version);
-        const clientMajor = majorOf(CLIENT_VERSION);
-        if (serverMajor !== clientMajor) {
-            const key = path ?? `${host}:${port}`;
-            if (!versionWarnings.has(key)) {
-                versionWarnings.add(key);
-                console.warn(`[powdb] server version ${reply.version} major (${serverMajor}) ` +
-                    `differs from client ${CLIENT_VERSION} major (${clientMajor}); ` +
-                    `behaviour may be inconsistent.`);
-            }
-        }
-        return new Client(socket, reply.version);
     }
     /**
      * Run a PowQL statement and return the typed result.
@@ -471,6 +489,136 @@ export class Client extends EventEmitter {
         }
         return coerceRows(result.columns, result.rows, schema);
     }
+    async execScript(script, opts) {
+        const statements = splitStatements(script);
+        const continueOnError = opts?.continueOnError === true;
+        const transactional = opts?.transactional === true;
+        const signal = opts?.signal;
+        if (transactional && continueOnError) {
+            throw new PowDBError("execScript: `transactional` and `continueOnError` are mutually exclusive", "protocol_error");
+        }
+        if (transactional) {
+            for (let i = 0; i < statements.length; i++) {
+                if (TX_CONTROL_RE.test(statements[i].replace(LEADING_TRIVIA_RE, ""))) {
+                    throw new PowDBError(`execScript: a transactional script may not contain its own transaction control (statement ${i + 1}: ${statements[i]})`, "protocol_error");
+                }
+            }
+            // Open the transaction and WAIT for its reply before dispatching
+            // anything: if `begin` fails there must be nothing else on the wire.
+            // Deliberately no signal — an abort after `begin` is on the wire
+            // would leave the transaction open with no rollback; an
+            // already-aborted signal stops the loop below at statement 0 and
+            // takes the rollback path.
+            await this.query("begin");
+        }
+        const outcomes = new Array(statements.length);
+        const inFlight = [];
+        let firstFailureIndex = -1;
+        let firstFailureError = null;
+        let dispatched = 0;
+        for (let i = 0; i < statements.length; i++) {
+            // Stop dispatching when the script is already doomed: fail-fast saw
+            // an error, the caller aborted, or the connection is gone.
+            if (this.closed || signal?.aborted)
+                break;
+            if (!continueOnError && firstFailureIndex !== -1)
+                break;
+            const statement = statements[i];
+            const idx = i;
+            dispatched++;
+            // query() writes the frame synchronously before its first await, so
+            // this loop puts every statement on the wire without waiting for any
+            // reply; the FIFO pending queue matches replies back in order.
+            inFlight.push(this.query(statement, signal ? { signal } : undefined).then((result) => {
+                outcomes[idx] = { statement, ok: true, result };
+            }, (error) => {
+                const err = error instanceof Error ? error : new Error(String(error));
+                outcomes[idx] = { statement, ok: false, error: err };
+                // Replies are FIFO so failures normally arrive in statement
+                // order; keep the earliest defensively regardless.
+                if (firstFailureIndex === -1 || idx < firstFailureIndex) {
+                    firstFailureIndex = idx;
+                    firstFailureError = err;
+                }
+            }));
+            // Backpressure: only yield when the kernel buffer is full. These
+            // yields are also the windows in which an already-arrived error reply
+            // or abort can stop further dispatch (the checks at the loop head).
+            if (this.socket.writableNeedDrain)
+                await this.drained();
+        }
+        // Every dispatched statement has a handler attached, so this never
+        // rejects; it resolves once all in-flight replies have settled.
+        await Promise.all(inFlight);
+        if (!continueOnError) {
+            if (firstFailureIndex === -1 && dispatched < statements.length) {
+                // Dispatch stopped without any statement failing — e.g. a signal
+                // that was already aborted before the first write. Treat the first
+                // undispatched statement as the failure point.
+                firstFailureIndex = dispatched;
+                firstFailureError = signal?.aborted
+                    ? abortError(signal)
+                    : (this.closeError ?? new PowDBError("client is closed", "closed"));
+            }
+            if (firstFailureIndex !== -1) {
+                if (transactional) {
+                    // Every dispatched reply has settled, so the connection is quiet
+                    // and the transaction is still open. Best-effort rollback — the
+                    // throw below is what callers act on either way, and if the
+                    // connection died the server aborts the transaction itself.
+                    try {
+                        await this.query("rollback");
+                    }
+                    catch {
+                        /* connection may already be gone */
+                    }
+                }
+                const cause = firstFailureError;
+                const results = [];
+                for (let i = 0; i < firstFailureIndex; i++) {
+                    const o = outcomes[i];
+                    if (o !== undefined && o.ok)
+                        results.push(o.result);
+                }
+                throw new PowDBScriptError(`script failed at statement ${firstFailureIndex + 1}/${statements.length}: ${cause.message}`, isPowDBError(cause) ? cause.code : "query_failed", {
+                    statementIndex: firstFailureIndex,
+                    statement: statements[firstFailureIndex],
+                    results,
+                    cause,
+                });
+            }
+            if (transactional) {
+                // Commit only after every statement's reply settled successfully —
+                // this is the all-or-nothing guarantee. The commit reply is not
+                // part of the returned results. No signal here either: aborting a
+                // commit already on the wire buys nothing but ambiguity.
+                try {
+                    await this.query("commit");
+                }
+                catch (err) {
+                    try {
+                        await this.query("rollback");
+                    }
+                    catch {
+                        /* connection may already be gone */
+                    }
+                    throw err;
+                }
+            }
+            return outcomes.map((o) => o.result);
+        }
+        // continueOnError: synthesize outcomes for statements that were never
+        // dispatched (abort or connection loss) so the array stays dense.
+        if (dispatched < statements.length) {
+            const reason = signal?.aborted
+                ? abortError(signal)
+                : (this.closeError ?? new PowDBError("client is closed", "closed"));
+            for (let i = dispatched; i < statements.length; i++) {
+                outcomes[i] = { statement: statements[i], ok: false, error: reason };
+            }
+        }
+        return outcomes;
+    }
     /**
      * Poll a query on an interval and invoke `onRows` for every successful
      * run. Returns an unsubscribe function. Does NOT deduplicate results —
@@ -636,6 +784,26 @@ export class Client extends EventEmitter {
             });
         });
     }
+    /**
+     * 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.
+     */
+    drained() {
+        return new Promise((resolve) => {
+            if (!this.socket.writableNeedDrain || this.closed) {
+                resolve();
+                return;
+            }
+            const done = () => {
+                this.socket.removeListener("drain", done);
+                this.removeListener("close", done);
+                resolve();
+            };
+            this.socket.on("drain", done);
+            this.on("close", done);
+        });
+    }
     onData(chunk) {
         // Append to the chunk queue — O(1) — and lazily concat only when
         // we actually need contiguous bytes to decode.
@@ -739,8 +907,17 @@ export class Client extends EventEmitter {
         if (this.closed && err === null)
             return;
         this.closed = true;
-        this.closeError = err;
-        const error = err ?? new PowDBError("connection closed", "closed");
+        let error = err ?? new PowDBError("connection closed", "closed");
+        // A teardown before ConnectOk is a handshake failure: everything queued
+        // (the handshake entry and any eagerly pipelined queries) rejects with
+        // the handshake error. Auth/protocol errors already carry the precise
+        // cause; anything else becomes a retryable connect failure.
+        if (!this.handshakeComplete &&
+            !(isPowDBError(error) &&
+                (error.code === "auth_failed" || error.code === "protocol_error"))) {
+            error = new PowDBError("connection closed during handshake", "connect_failed", { cause: err ?? undefined });
+        }
+        this.closeError = error;
         while (this.pending.length > 0) {
             const entry = this.pending.shift();
             if (!entry.settled) {
@@ -804,5 +981,6 @@ export { encode, tryDecode } 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 { PowDBError, isPowDBError } from "./errors.js";
+export { splitStatements } from "./script.js";
+export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
 export { coerceValue, coerceRow, coerceRows, } from "./typed.js";

package/dist/pool.d.ts

@@ -19,7 +19,7 @@
  *
  *     await pool.close();
  */
-import { Client, type ClientOptions } from "./index.js";
+import { Client, type ClientOptions, type QueryResult, type ScriptStatementOutcome } from "./index.js";
 export interface PoolOptions extends ClientOptions {
     /** Maximum concurrent clients. Default 10. */
     max?: number;
@@ -110,6 +110,23 @@ export declare class Pool {
      * to leak a client on an unhandled exception.
      */
     withClient<T>(fn: (c: Client) => Promise<T>): Promise<T>;
+    /**
+     * Run a multi-statement PowQL script on ONE pooled connection, pipelined.
+     *
+     * Checks out a single client for the whole script (statement order —
+     * and `transactional: true` — therefore holds), delegates to
+     * {@link Client.execScript}, and releases the client on success or
+     * destroys it on error — same lifecycle as {@link withClient}.
+     */
+    execScript(script: string, opts?: {
+        continueOnError?: false;
+        transactional?: boolean;
+        signal?: AbortSignal;
+    }): Promise<QueryResult[]>;
+    execScript(script: string, opts: {
+        continueOnError: true;
+        signal?: AbortSignal;
+    }): Promise<ScriptStatementOutcome[]>;
     /**
      * Close the pool. Rejects all pending waiters, awaits `close()` on every
      * idle client, and marks the pool closed. Subsequent `acquire` calls

package/dist/pool.js

@@ -19,7 +19,7 @@
  *
  *     await pool.close();
  */
-import { Client } from "./index.js";
+import { Client, } from "./index.js";
 import { isPowDBError } from "./errors.js";
 /**
  * Is this error worth retrying? Only the transient connect-phase errors
@@ -251,6 +251,23 @@ export class Pool {
             throw err;
         }
     }
+    async execScript(script, opts) {
+        if (opts?.continueOnError === true) {
+            return this.withClient((c) => c.execScript(script, {
+                continueOnError: true,
+                ...(opts.transactional !== undefined
+                    ? { transactional: opts.transactional }
+                    : {}),
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            }));
+        }
+        return this.withClient((c) => c.execScript(script, {
+            ...(opts?.transactional !== undefined
+                ? { transactional: opts.transactional }
+                : {}),
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+        }));
+    }
     /**
      * Close the pool. Rejects all pending waiters, awaits `close()` on every
      * idle client, and marks the pool closed. Subsequent `acquire` calls

package/dist/script.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+/**
+ * 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).
+ */
+export declare function splitStatements(input: string): string[];

package/dist/script.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * 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).
+ */
+export 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/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
@@ -47,7 +54,9 @@
     "@types/node": { "optional": true }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }) + '\\n')\"",
     "test": "tsx test/run-with-server.ts test/client.test.ts",
     "test:escape": "tsx test/escape.test.ts",
     "test:protocol": "tsx test/protocol.test.ts",
@@ -56,6 +65,9 @@
     "test:pool": "tsx test/run-with-server.ts test/pool.test.ts",
     "test:typed": "tsx test/typed.test.ts",
     "test:errors": "tsx test/errors.test.ts",
+    "test:script": "tsx test/script.test.ts",
+    "test:eager": "tsx test/run-with-server.ts test/eager.test.ts",
+    "test:exec-script": "tsx test/run-with-server.ts test/exec-script.test.ts",
     "demo": "tsx demo/demo.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"