@zvndev/powdb-client 0.8.0 → 0.9.0

package/README.md

@@ -81,6 +81,101 @@ await client.query("insert User { name := $1, age := $2 }", ["Dana", null]);
 
 `QueryParam` is `string | number | bigint | boolean | null`. The params form sends the `QueryWithParams` (0x04) wire message and **requires powdb-server >= 0.4.7**. The plain `query(q)` and `query(q, { signal })` forms are unchanged.
 
+## Multi-statement scripts (`execScript`)
+
+`execScript` runs a whole `;`-separated PowQL script down one connection,
+**pipelined**: every statement is written back-to-back without waiting for
+the previous reply, so an N-statement script costs one round trip instead of
+N. Splitting is statement-aware with the exact semantics of the CLI's script
+path — `;` inside `"..."` string literals or `#` comments never splits, and
+empty statements are dropped. (The splitter is exported as
+`splitStatements(script)` if you need it standalone.)
+
+```typescript
+const results = await client.execScript(`
+  type User { required name: str, age: int };
+  insert User { name := "Alice", age := 30 };  # seed; more to come
+  insert User { name := "Bob;Bobby", age := 25 };
+  count(User)
+`);
+// results: QueryResult[] in statement order — results[3].value === "2"
+```
+
+By default execution is **fail-fast**: the first failed statement rejects the
+promise with a `PowDBScriptError` carrying `statementIndex`, the failing
+`statement` text, and the successful `results` so far. Because dispatch is
+pipelined, statements already on the wire when the error reply arrives
+(typically the whole script) still execute server-side — use
+`transactional: true` if you need all-or-nothing behavior. 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.
+
+With `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.
+Transactional scripts may not contain their own `begin`/`commit`/`rollback`,
+and the option is mutually exclusive with `continueOnError`. On failure the
+`PowDBScriptError`'s `results` are the replies received before rollback —
+their effects are not persisted.
+
+```typescript
+// Either every statement commits, or none do.
+await client.execScript(seedScript, { transactional: true });
+```
+
+```typescript
+import { isPowDBScriptError } from "@zvndev/powdb-client";
+
+try {
+  await client.execScript(script);
+} catch (err) {
+  if (isPowDBScriptError(err)) {
+    console.error(`statement ${err.statementIndex} failed: ${err.statement}`);
+    console.error(`${err.results.length} statements succeeded before it`);
+  }
+}
+```
+
+With `continueOnError: true`, every statement runs regardless of failures and
+you get a dense per-statement outcome array instead of a throw:
+
+```typescript
+const outcomes = await client.execScript(script, { continueOnError: true });
+for (const o of outcomes) {
+  if (o.ok) console.log(o.result.kind);
+  else console.warn(`failed: ${o.statement} — ${o.error.message}`);
+}
+```
+
+`Pool.execScript(script, opts?)` does the same through a pool, checking out a
+single connection for the whole script (so statement order — and
+`transactional: true` — holds).
+
+## Eager (pipelined) connect
+
+`Client.connect` normally performs a blocking Connect→ConnectOk handshake, so
+every fresh connection pays a protocol round trip before its first query.
+With `eager: true` the promise resolves as soon as the socket is open and the
+Connect frame is written; queries issued immediately are queued right behind
+the Connect frame on the wire, and the server answers everything in order.
+For connection-per-request callers this removes the handshake round trip
+entirely:
+
+```typescript
+const client = await Client.connect({ host, port, eager: true });
+// No extra round trip — this query rides directly behind the Connect frame.
+const result = await client.query("count(User)");
+```
+
+If the handshake then fails (bad password, protocol mismatch), every queued
+query rejects with the handshake error (`code: "auth_failed"`, etc.) and the
+client closes. Two things to know:
+
+- `client.serverVersion` is `""` until the ConnectOk arrives.
+- `await client.ready()` waits for the handshake outcome explicitly — it
+  resolves on ConnectOk and rejects with the handshake error. (For non-eager
+  clients it has already settled by the time `connect` returns.)
+
 ## Experimental embedded sync protocol helpers
 
 The client exposes experimental low-level helpers for the private authenticated
@@ -255,6 +350,11 @@ The full taxonomy: `connect_failed`, `auth_failed`, `query_failed`,
 `aborted`, `size_exceeded`, `protocol_error`, `closed`, `timeout`,
 `type_coercion_failed`.
 
+`execScript` failures throw `PowDBScriptError`, a `PowDBError` subclass whose
+`code` mirrors the failing statement's error and which adds
+`statementIndex`, `statement`, and `results` (see Multi-statement scripts
+above). Narrow with `isPowDBScriptError(err)`.
+
 ## Polling watch
 
 For simple change-polling (the server doesn't ship a subscription
@@ -322,11 +422,12 @@ try {
 }
 ```
 
-If you abort with a custom reason (`ctrl.abort(myError)`) and that reason is
-an `Error`, it is thrown as-is instead. Otherwise the client throws a
-`PowDBError` with `code === "aborted"`.
+A plain `ctrl.abort()` throws a `PowDBError` with `code === "aborted"`. If you
+abort with a custom `Error` reason (`ctrl.abort(myError)`), that error is thrown
+as-is; any non-`Error` reason is wrapped in a `PowDBError` (`code === "aborted"`).
 
-The socket stays open — the server's reply is silently discarded so other in-flight queries keep working.
+The socket stays open — the aborted query's reply is silently discarded when it
+arrives, and every other in-flight query still receives its own result.
 
 ## API
 
@@ -343,6 +444,7 @@ Returns a `Promise<Client>`. Options:
 | `user` | `string` | *(omitted)* | User name for multi-user servers (see Authentication above). Omit for shared-password / no-auth servers |
 | `connectTimeoutMs` | `number` | `5000` | Connection timeout in milliseconds |
 | `tls` | `boolean \| tls.ConnectionOptions` | `false` | Enable TLS; `true` uses system defaults, or pass a `tls.connect` options object |
+| `eager` | `boolean` | `false` | Resolve as soon as the Connect frame is written instead of waiting for ConnectOk; queries pipeline behind the handshake (see Eager connect above) |
 
 > **Multi-user servers:** requires client ≥0.4.0 (`user` option) and server
 > ≥0.4.6 (enforced roles). See the version matrix under Authentication.
@@ -361,11 +463,44 @@ Sends a PowQL query and returns a `Promise<QueryResult>`:
 
 Throws a `PowDBError` (see Structured errors above) on any failure.
 
+### `client.querySql(query, opts?)`
+
+Runs a statement through the server's **SQL frontend** and returns a
+`Promise<QueryResult>` — the same result shape as `query()`. The plain
+`query()` method stays PowQL for wire compatibility; `querySql()` sends the
+dedicated `QuerySql` wire message. Requires server ≥0.5.0 (the SQL frontend was
+added in 0.5.0); see `docs/SQL.md` for the supported subset. `opts.signal?:
+AbortSignal` cancels the query (see Cancellation above).
+
+```typescript
+const result = await client.querySql("SELECT name, age FROM User WHERE age > 27");
+```
+
 ### `client.queryTyped(query, schema, opts?)`
 
 Like `query()`, but coerces each row's string values to JS types using the
 supplied schema and returns `Promise<TypedRow[]>`. See Typed rows above.
 
+### `client.execScript(script, opts?)`
+
+Splits `script` into statements (statement-aware — see Multi-statement
+scripts above) and executes them all down this connection, pipelined.
+Returns `Promise<QueryResult[]>` in statement order; rejects with a
+`PowDBScriptError` on the first failed statement. With
+`opts.transactional: true`, runs the whole script atomically (commit only
+after every reply; rollback on any failure; embedded
+`begin`/`commit`/`rollback` rejected; mutually exclusive with
+`continueOnError`). With `opts.continueOnError: true`, returns
+`Promise<ScriptStatementOutcome[]>` (`{ statement, ok: true, result }` or
+`{ statement, ok: false, error }`) and never rejects for statement failures.
+`opts.signal?: AbortSignal` aborts the remaining statements.
+
+### `client.ready()`
+
+Resolves once the Connect→ConnectOk handshake has completed; rejects with
+the handshake error if it failed. Only interesting for eager connects — for
+default connects it has settled before `Client.connect` returns.
+
 ### `client.watch(query, options)`
 
 Re-runs `query` every `intervalMs` and passes each `QueryResult` to
@@ -381,7 +516,7 @@ Sends a disconnect message and closes the TCP socket.
 
 ### `client.serverVersion`
 
-The PowDB server version string (e.g., `"0.4.4"`). On connect, the client warns once per `host:port` if the server's major version differs from the client's.
+The PowDB server version string (e.g., `"0.4.4"`). On connect, the client warns once per `host:port` if the server's major version differs from the client's. For an eager connect this is `""` until the ConnectOk arrives (await `client.ready()` to guarantee it is populated).
 
 ### `Pool` (class)
 
@@ -395,7 +530,7 @@ Constructor options extend `ClientOptions` with:
 | `connectBackoffMs` | `number` | `100` | Initial delay between connect retries; doubles each attempt |
 | `connectMaxBackoffMs` | `number` | `2000` | Cap on the exponential backoff |
 
-Methods: `acquire()`, `release(client)`, `destroy(client)`, `withClient(fn)`, `close()`.
+Methods: `acquire()`, `release(client)`, `destroy(client)`, `withClient(fn)`, `execScript(script, opts?)`, `close()`.
 Getters: `size`, `idle`, `closed`.
 
 ### Safety helpers
@@ -404,6 +539,7 @@ Getters: `size`, `idle`, `closed`.
 - `ident(name)` — wrap a string so `powql` treats it as an identifier
 - `escapeLiteral(value)` — render a JS value as a PowQL literal
 - `escapeIdent(name)` — validate an identifier (throws `TypeError` on invalid)
+- `splitStatements(script)` — the statement-aware script splitter used by `execScript`
 
 ## Limits
 

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.0";
+export declare const CLIENT_VERSION = "0.9.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";

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.0";
+export const CLIENT_VERSION = "0.9.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;
 }
@@ -98,16 +108,19 @@ function majorOf(version) {
     return dot === -1 ? version : version.slice(0, dot);
 }
 /**
- * Build an AbortError. Prefers the caller-supplied `signal.reason` if it is
- * itself an `Error` (matches DOM semantics); otherwise wraps it in a
- * `PowDBError` with code `"aborted"` so catch-blocks can branch uniformly.
+ * Build an AbortError. A caller-supplied custom `Error` reason
+ * (`ctrl.abort(myError)`) passes through as-is to match DOM semantics. The
+ * default abort reason — Node's `DOMException` named `"AbortError"` — and any
+ * non-Error reason are wrapped in a `PowDBError` with code `"aborted"` so the
+ * common `ctrl.abort()` case branches uniformly on `err.code === "aborted"`.
  */
 function abortError(signal) {
     if (signal && signal.reason !== undefined) {
         const r = signal.reason;
-        if (r instanceof Error)
+        const isDefaultAbort = r instanceof DOMException && r.name === "AbortError";
+        if (r instanceof Error && !isDefaultAbort)
             return r;
-        return new PowDBError(String(r), "aborted");
+        return new PowDBError(isDefaultAbort ? "query was aborted" : String(r), "aborted");
     }
     return new PowDBError("query was aborted", "aborted");
 }
@@ -120,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.
@@ -468,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 —
@@ -527,8 +678,17 @@ export class Client extends EventEmitter {
      * timeout so an unresponsive peer cannot make `close()` hang forever.
      */
     async close() {
-        if (this.closed)
+        if (this.closed) {
+            // Already torn down (e.g. an error in onData/onClose closed the client
+            // without destroying the socket). Ensure the socket is released so a
+            // post-teardown close() resolves instead of keeping the event loop
+            // alive. `writableEnded` distinguishes that case from a concurrent
+            // close() mid-graceful-shutdown, which must not be force-destroyed.
+            if (!this.socket.destroyed && !this.socket.writableEnded) {
+                this.socket.destroy();
+            }
             return;
+        }
         try {
             this.socket.write(encode({ type: "Disconnect" }));
         }
@@ -624,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.
@@ -682,19 +862,18 @@ export class Client extends EventEmitter {
                 this.socket.write(encode({ type: "Pong" }));
                 continue;
             }
-            // Find the next non-settled pending entry and hand it the reply.
-            // Settled entries at the head were aborted by the caller but their
-            // reply is arriving now — drop it silently.
-            let entry = this.pending.shift();
-            while (entry && entry.settled) {
-                entry = this.pending.shift();
-            }
-            if (!entry) {
-                // Server sent an unsolicited frame (or we got extra after aborts
-                // with no replacement). Treat as protocol error.
+            // Replies are strictly FIFO: this frame belongs to exactly one pending
+            // entry — the head. Consume one entry per frame. If it was aborted
+            // (settled), its reply is arriving now; drop the frame and keep decoding
+            // rather than delivering it to a later, live query.
+            const entry = this.pending.shift();
+            if (entry === undefined) {
+                // No pending entry at all — the server sent an unsolicited frame.
                 this.onClose(new PowDBError("received unexpected frame from server", "protocol_error"));
                 return;
             }
+            if (entry.settled)
+                continue;
             entry.resolve(decoded.msg);
         }
     }
@@ -728,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) {
@@ -793,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,6 +1,6 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",
@@ -56,12 +56,15 @@
     "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"
   },
   "devDependencies": {
-    "@types/node": "^25",
+    "@types/node": "^26",
     "tsx": "^4",
     "typescript": "^6.0"
   }