@zvndev/powdb-client 0.8.1 → 0.10.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
@@ -344,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.
@@ -380,6 +481,26 @@ const result = await client.querySql("SELECT name, age FROM User WHERE age > 27"
 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
@@ -395,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)
 
@@ -409,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
@@ -418,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/cjs/errors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Structured error taxonomy for the PowDB client.
+ *
+ * Every error thrown by the client is a `PowDBError` with a stable `.code`
+ * so callers can branch without string-matching the message. The taxonomy
+ * 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"
+/** Server rejected the Connect handshake (bad password, unknown db). Not transient. */
+ | "auth_failed"
+/** Server returned an `Error` frame in response to a query. Not transient. */
+ | "query_failed"
+/** Caller's AbortSignal fired. Never retry — the caller asked to stop. */
+ | "aborted"
+/** Peer sent a frame that exceeds one of the configured caps. Likely a bug/attack — do not retry. */
+ | "size_exceeded"
+/** Wire protocol violation (bad framing, unknown message type, truncated payload). */
+ | "protocol_error"
+/** `close()` has been called on the client or pool. */
+ | "closed"
+/** An operation exceeded its configured time budget. */
+ | "timeout"
+/** Type coercion on a row failed (queryTyped). */
+ | "type_coercion_failed";
+/**
+ * All errors thrown by `@zvndev/powdb-client` are instances of this class.
+ * Use `err.code` to branch; `err.cause` optionally carries the underlying
+ * cause (e.g. the Node socket error).
+ */
+export declare class PowDBError extends Error {
+    readonly code: PowDBErrorCode;
+    constructor(message: string, code: PowDBErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Narrow `unknown` to a PowDBError. Useful in catch blocks where you want
+ * 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/cjs/errors.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Structured error taxonomy for the PowDB client.
+ *
+ * Every error thrown by the client is a `PowDBError` with a stable `.code`
+ * so callers can branch without string-matching the message. The taxonomy
+ * is intentionally small — new codes are added only when a caller has a
+ * legitimate reason to handle them differently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PowDBScriptError = exports.PowDBError = void 0;
+exports.isPowDBError = isPowDBError;
+exports.isPowDBScriptError = isPowDBScriptError;
+/**
+ * All errors thrown by `@zvndev/powdb-client` are instances of this class.
+ * Use `err.code` to branch; `err.cause` optionally carries the underlying
+ * cause (e.g. the Node socket error).
+ */
+class PowDBError extends Error {
+    code;
+    constructor(message, code, options) {
+        // ErrorOptions.cause is supported in Node 16.9+; we require Node 18+.
+        super(message, options);
+        this.name = "PowDBError";
+        this.code = code;
+        // Preserve the prototype chain across `target: es2020` and friends.
+        Object.setPrototypeOf(this, PowDBError.prototype);
+    }
+}
+exports.PowDBError = PowDBError;
+/**
+ * Narrow `unknown` to a PowDBError. Useful in catch blocks where you want
+ * to branch on `.code` but TypeScript sees `unknown`.
+ */
+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.
+ */
+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);
+    }
+}
+exports.PowDBScriptError = PowDBScriptError;
+/** Narrow `unknown` to a PowDBScriptError. */
+function isPowDBScriptError(err) {
+    return err instanceof PowDBScriptError;
+}

package/dist/cjs/escape.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Safe PowQL composition helpers: literal and identifier escaping, plus a
+ * tagged-template convenience for building queries without string splicing.
+ *
+ *     const q = powql`insert ${ident("User")} { name := ${userName}, age := ${age} }`;
+ *     await client.query(q);
+ *
+ * Security model:
+ *   - Literals are rendered with quoting/escaping so interpolated values
+ *     cannot break out of the surrounding literal.
+ *   - Identifiers are validated against `^[A-Za-z_][A-Za-z0-9_]*$` and passed
+ *     through unchanged. Anything else throws a `TypeError`.
+ *
+ * PowQL string-escape rules (verified against `crates/query/src/lexer.rs`):
+ *   - Strings are delimited by `"`.
+ *   - `\\` → `\`, `\"` → `"`, `\n` → newline, `\t` → tab.
+ *   - For any other `\X`, the backslash is dropped and `X` is kept literally.
+ *   - A bare `"` terminates the string, so `"` inside must be `\"` and any
+ *     literal backslash must be `\\` (otherwise it would swallow the next char).
+ */
+/** Wrapper marking a string as an identifier (vs a literal) for `powql` tagged templates. */
+export declare class PowqlIdent {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Factory for {@link PowqlIdent}. Prefer this over `new PowqlIdent(...)` at call sites. */
+export declare function ident(name: string): PowqlIdent;
+/**
+ * Validate a PowQL identifier (table name, field name, alias). Returns the
+ * identifier unchanged on success; throws `TypeError` on any invalid input
+ * (non-string, empty, or containing characters outside `[A-Za-z_][A-Za-z0-9_]*`).
+ */
+export declare function escapeIdent(name: string): string;
+/**
+ * Render a JS value as a PowQL literal. Supports `string`, `number`, `bigint`,
+ * `boolean`, and `null`. Rejects `NaN`/`±Infinity`, `undefined`, symbols,
+ * objects, and arrays with `TypeError`.
+ *
+ * - string → `"..."` with `\` and `"` backslash-escaped (C-style, per the
+ *   PowQL lexer). Backslash must be escaped first to avoid double-processing.
+ * - number → decimal; rejects non-finite
+ * - bigint → decimal digits
+ * - boolean → `true` / `false`
+ * - null   → `null`
+ */
+export declare function escapeLiteral(value: string | number | bigint | boolean | null): string;
+/**
+ * Tagged template for safe PowQL composition. Each interpolated value is
+ * escaped as a literal by default; wrap it in `ident(...)` to interpolate as
+ * an identifier.
+ *
+ *     const q = powql`insert ${ident(table)} { name := ${userName} }`;
+ */
+export declare function powql(strings: TemplateStringsArray, ...values: unknown[]): string;

package/dist/cjs/escape.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Safe PowQL composition helpers: literal and identifier escaping, plus a
+ * tagged-template convenience for building queries without string splicing.
+ *
+ *     const q = powql`insert ${ident("User")} { name := ${userName}, age := ${age} }`;
+ *     await client.query(q);
+ *
+ * Security model:
+ *   - Literals are rendered with quoting/escaping so interpolated values
+ *     cannot break out of the surrounding literal.
+ *   - Identifiers are validated against `^[A-Za-z_][A-Za-z0-9_]*$` and passed
+ *     through unchanged. Anything else throws a `TypeError`.
+ *
+ * PowQL string-escape rules (verified against `crates/query/src/lexer.rs`):
+ *   - Strings are delimited by `"`.
+ *   - `\\` → `\`, `\"` → `"`, `\n` → newline, `\t` → tab.
+ *   - For any other `\X`, the backslash is dropped and `X` is kept literally.
+ *   - A bare `"` terminates the string, so `"` inside must be `\"` and any
+ *     literal backslash must be `\\` (otherwise it would swallow the next char).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PowqlIdent = void 0;
+exports.ident = ident;
+exports.escapeIdent = escapeIdent;
+exports.escapeLiteral = escapeLiteral;
+exports.powql = powql;
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Wrapper marking a string as an identifier (vs a literal) for `powql` tagged templates. */
+class PowqlIdent {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+exports.PowqlIdent = PowqlIdent;
+/** Factory for {@link PowqlIdent}. Prefer this over `new PowqlIdent(...)` at call sites. */
+function ident(name) {
+    return new PowqlIdent(name);
+}
+/**
+ * Validate a PowQL identifier (table name, field name, alias). Returns the
+ * identifier unchanged on success; throws `TypeError` on any invalid input
+ * (non-string, empty, or containing characters outside `[A-Za-z_][A-Za-z0-9_]*`).
+ */
+function escapeIdent(name) {
+    if (typeof name !== "string") {
+        throw new TypeError(`escapeIdent: expected string, got ${typeof name}`);
+    }
+    if (name.length === 0) {
+        throw new TypeError("escapeIdent: identifier must not be empty");
+    }
+    if (!IDENT_RE.test(name)) {
+        throw new TypeError(`escapeIdent: invalid identifier ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`);
+    }
+    return name;
+}
+/**
+ * Render a JS value as a PowQL literal. Supports `string`, `number`, `bigint`,
+ * `boolean`, and `null`. Rejects `NaN`/`±Infinity`, `undefined`, symbols,
+ * objects, and arrays with `TypeError`.
+ *
+ * - string → `"..."` with `\` and `"` backslash-escaped (C-style, per the
+ *   PowQL lexer). Backslash must be escaped first to avoid double-processing.
+ * - number → decimal; rejects non-finite
+ * - bigint → decimal digits
+ * - boolean → `true` / `false`
+ * - null   → `null`
+ */
+function escapeLiteral(value) {
+    if (value === null)
+        return "null";
+    const t = typeof value;
+    if (t === "string") {
+        const escaped = value
+            .replace(/\\/g, "\\\\")
+            .replace(/"/g, '\\"');
+        return `"${escaped}"`;
+    }
+    if (t === "number") {
+        const n = value;
+        if (!Number.isFinite(n)) {
+            throw new TypeError(`escapeLiteral: non-finite number ${String(n)} cannot be represented as a PowQL literal`);
+        }
+        return String(n);
+    }
+    if (t === "bigint") {
+        return value.toString(10);
+    }
+    if (t === "boolean") {
+        return value ? "true" : "false";
+    }
+    throw new TypeError(`escapeLiteral: unsupported type ${describe(value)}`);
+}
+/**
+ * Tagged template for safe PowQL composition. Each interpolated value is
+ * escaped as a literal by default; wrap it in `ident(...)` to interpolate as
+ * an identifier.
+ *
+ *     const q = powql`insert ${ident(table)} { name := ${userName} }`;
+ */
+function powql(strings, ...values) {
+    let out = strings[0] ?? "";
+    for (let i = 0; i < values.length; i++) {
+        out += renderInterpolation(values[i]);
+        out += strings[i + 1] ?? "";
+    }
+    return out;
+}
+// ──────────────────────────────────────────────────────────
+// internals
+// ──────────────────────────────────────────────────────────
+function renderInterpolation(value) {
+    if (value instanceof PowqlIdent) {
+        return escapeIdent(value.name);
+    }
+    // `escapeLiteral` enforces the allowed set — for anything else it throws.
+    return escapeLiteral(value);
+}
+function describe(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    const t = typeof value;
+    if (t === "object")
+        return "object";
+    return t;
+}