@zvndev/powdb-client 0.9.0 → 0.10.0

package/dist/cjs/index.js

@@ -0,0 +1,1046 @@
+"use strict";
+/**
+ * PowDB TypeScript client.
+ *
+ * Thin async wrapper around a TCP (or TLS) socket speaking the PowDB wire
+ * protocol.
+ *
+ *     const client = await Client.connect({
+ *       host: "127.0.0.1",
+ *       port: 5433,
+ *       dbName: "default",
+ *       password: process.env.POWDB_PASSWORD,
+ *     });
+ *
+ *     const result = await client.query("User filter .age > 27 { .name, .age }");
+ *     await client.close();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = exports.splitStatements = exports.Pool = exports.PowqlIdent = exports.powql = exports.ident = exports.escapeIdent = exports.escapeLiteral = exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.tryDecode = exports.encode = exports.Client = exports.CLIENT_VERSION = void 0;
+const net = __importStar(require("node:net"));
+const tls = __importStar(require("node:tls"));
+const node_events_1 = require("node:events");
+const protocol_js_1 = require("./protocol.js");
+const errors_js_1 = require("./errors.js");
+const script_js_1 = require("./script.js");
+const typed_js_1 = require("./typed.js");
+/** Client library version. Compared to the server's reported version. */
+exports.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;
+}
+/** Map a JS {@link QueryParam} to its wire encoding. */
+function toWireParam(p) {
+    if (p === null)
+        return { tag: "null" };
+    switch (typeof p) {
+        case "string":
+            return { tag: "str", value: p };
+        case "boolean":
+            return { tag: "bool", value: p };
+        case "bigint":
+            return { tag: "int", value: p };
+        case "number":
+            return Number.isInteger(p)
+                ? { tag: "int", value: BigInt(p) }
+                : { tag: "float", value: p };
+        default:
+            throw new errors_js_1.PowDBError(`unsupported query parameter type: ${typeof p}`, "protocol_error");
+    }
+}
+function toU64(value, label) {
+    if (typeof value === "bigint") {
+        if (value < 0n || value > 0xffffffffffffffffn) {
+            throw new errors_js_1.PowDBError(`${label} must fit in u64`, "protocol_error");
+        }
+        return value;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new errors_js_1.PowDBError(`${label} must be a safe non-negative integer or bigint`, "protocol_error");
+    }
+    return BigInt(value);
+}
+function toU16(value, label) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+        throw new errors_js_1.PowDBError(`${label} must fit in u16`, "protocol_error");
+    }
+    return value;
+}
+function toSyncMaxUnits(value) {
+    if (!Number.isInteger(value) ||
+        value < 1 ||
+        value > protocol_js_1.MAX_SYNC_PULL_UNITS) {
+        throw new errors_js_1.PowDBError(`maxUnits must be between 1 and ${protocol_js_1.MAX_SYNC_PULL_UNITS}`, "protocol_error");
+    }
+    return value;
+}
+function toSyncMaxBytes(value) {
+    const bytes = toU64(value, "maxBytes");
+    if (bytes < 1n || bytes > BigInt(protocol_js_1.MAX_SYNC_PULL_BYTES)) {
+        throw new errors_js_1.PowDBError(`maxBytes must be between 1 and ${protocol_js_1.MAX_SYNC_PULL_BYTES}`, "protocol_error");
+    }
+    return bytes;
+}
+function toDatabaseId(value) {
+    if (typeof value === "string") {
+        if (!/^[0-9a-fA-F]{32}$/.test(value)) {
+            throw new errors_js_1.PowDBError("databaseId string must be exactly 32 hex characters", "protocol_error");
+        }
+        return Buffer.from(value, "hex");
+    }
+    const bytes = Buffer.from(value);
+    if (bytes.length !== 16) {
+        throw new errors_js_1.PowDBError(`databaseId must be exactly 16 bytes, got ${bytes.length}`, "protocol_error");
+    }
+    return bytes;
+}
+/** Module-level set of host:port pairs we've already warned about. */
+const versionWarnings = new Set();
+/** Extract the major component of a dotted version string, e.g. "0.2.0" → "0". */
+function majorOf(version) {
+    const dot = version.indexOf(".");
+    return dot === -1 ? version : version.slice(0, dot);
+}
+/**
+ * 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;
+        const isDefaultAbort = r instanceof DOMException && r.name === "AbortError";
+        if (r instanceof Error && !isDefaultAbort)
+            return r;
+        return new errors_js_1.PowDBError(isDefaultAbort ? "query was aborted" : String(r), "aborted");
+    }
+    return new errors_js_1.PowDBError("query was aborted", "aborted");
+}
+class Client extends node_events_1.EventEmitter {
+    socket;
+    /** FIFO of raw chunks; concatenated lazily when we try to decode. */
+    chunks = [];
+    /** Cached length of everything currently in `chunks`. */
+    totalLen = 0;
+    pending = [];
+    closed = false;
+    closeError = null;
+    /** 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.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, 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, eager = false, } = opts;
+        if (path === undefined && (host === undefined || port === undefined)) {
+            throw new errors_js_1.PowDBError("connect requires either { path } (Unix socket) or { host, port } (TCP)", "connect_failed");
+        }
+        const socket = await openSocket({ host, port, path }, connectTimeoutMs, tlsOpt);
+        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 errors_js_1.PowDBError(`connect failed: ${reply.message}`, "auth_failed");
+            }
+            if (reply.type !== "ConnectOk") {
+                throw new errors_js_1.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(exports.CLIENT_VERSION);
+            if (serverMajor !== clientMajor) {
+                if (!versionWarnings.has(versionWarnKey)) {
+                    versionWarnings.add(versionWarnKey);
+                    console.warn(`[powdb] server version ${reply.version} major (${serverMajor}) ` +
+                        `differs from client ${exports.CLIENT_VERSION} major (${clientMajor}); ` +
+                        `behaviour may be inconsistent.`);
+                }
+            }
+        }, (err) => {
+            // The connection dropped before a handshake reply — surface it as a
+            // connect failure (transient, retryable) rather than a bare close.
+            if ((0, errors_js_1.isPowDBError)(err) && err.code === "closed") {
+                throw new errors_js_1.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();
+        });
+    }
+    /**
+     * Run a PowQL statement and return the typed result.
+     *
+     * When `opts.signal` is provided and fires, the returned promise rejects
+     * with the signal's `reason` (or an `AbortError`). The socket is NOT
+     * destroyed — the server will still eventually send its reply, which we
+     * silently discard so other in-flight queries keep working.
+     */
+    async query(query, paramsOrOpts, maybeOpts) {
+        // Disambiguate the two overloads:
+        //   query(q)                       — no params, no opts
+        //   query(q, opts)                 — legacy 2-arg opts form (back-compat)
+        //   query(q, params)               — positional $N parameters
+        //   query(q, params, opts)         — params + opts
+        const hasParams = Array.isArray(paramsOrOpts);
+        const params = hasParams ? paramsOrOpts : undefined;
+        const opts = hasParams
+            ? maybeOpts
+            : paramsOrOpts;
+        const start = Date.now();
+        try {
+            const request = params === undefined
+                ? { type: "Query", query }
+                : { type: "QueryWithParams", query, params: params.map(toWireParam) };
+            const reply = await this.send(request, opts);
+            let result;
+            switch (reply.type) {
+                case "ResultRows":
+                    result = { kind: "rows", columns: reply.columns, rows: reply.rows };
+                    break;
+                case "ResultScalar":
+                    result = { kind: "scalar", value: reply.value };
+                    break;
+                case "ResultOk":
+                    result = { kind: "ok", affected: reply.affected };
+                    break;
+                case "ResultMessage":
+                    result = { kind: "message", message: reply.message };
+                    break;
+                case "Error":
+                    throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+                default:
+                    throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: true,
+                kind: result.kind,
+            });
+            return result;
+        }
+        catch (err) {
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /**
+     * Run a SQL statement through the server-side SQL frontend. The plain
+     * {@link query} method remains PowQL for wire compatibility.
+     */
+    async querySql(query, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({ type: "QuerySql", query }, opts);
+            let result;
+            switch (reply.type) {
+                case "ResultRows":
+                    result = { kind: "rows", columns: reply.columns, rows: reply.rows };
+                    break;
+                case "ResultScalar":
+                    result = { kind: "scalar", value: reply.value };
+                    break;
+                case "ResultOk":
+                    result = { kind: "ok", affected: reply.affected };
+                    break;
+                case "ResultMessage":
+                    result = { kind: "message", message: reply.message };
+                    break;
+                case "Error":
+                    throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+                default:
+                    throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: true,
+                kind: result.kind,
+            });
+            return result;
+        }
+        catch (err) {
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /**
+     * Fetch primary-side sync status for one embedded replica cursor.
+     *
+     * This speaks the private authenticated sync frame added for the embedded
+     * replica product. Servers without sync support return a protocol/query
+     * error; unauthenticated or readonly users are rejected server-side.
+     */
+    async syncStatus(replicaId, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({ type: "SyncStatus", replicaId }, opts);
+            if (reply.type === "Error") {
+                throw new errors_js_1.PowDBError(`sync status failed: ${reply.message}`, "query_failed");
+            }
+            if (reply.type !== "SyncStatusResult") {
+                throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("sync", {
+                operation: "status",
+                replicaId,
+                durationMs: Date.now() - start,
+                ok: true,
+                status: reply.status,
+                stale: reply.status.stale,
+                repairAction: reply.status.repairAction,
+            });
+            return reply.status;
+        }
+        catch (err) {
+            this.emit("sync", {
+                operation: "status",
+                replicaId,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /**
+     * Pull a bounded retained-unit chunk after this replica's primary-side cursor.
+     *
+     * The caller supplies the database identity and format versions from the
+     * sync bootstrap metadata. The server rejects mismatches and non-applyable
+     * transaction cuts instead of returning ambiguous history.
+     */
+    async syncPull(request, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({
+                type: "SyncPull",
+                replicaId: request.replicaId,
+                sinceLsn: toU64(request.sinceLsn, "sinceLsn"),
+                maxUnits: toSyncMaxUnits(request.maxUnits),
+                maxBytes: toSyncMaxBytes(request.maxBytes),
+                databaseId: toDatabaseId(request.databaseId),
+                primaryGeneration: toU64(request.primaryGeneration, "primaryGeneration"),
+                walFormatVersion: toU16(request.walFormatVersion, "walFormatVersion"),
+                catalogVersion: toU16(request.catalogVersion, "catalogVersion"),
+                segmentFormatVersion: toU16(request.segmentFormatVersion, "segmentFormatVersion"),
+            }, opts);
+            if (reply.type === "Error") {
+                throw new errors_js_1.PowDBError(`sync pull failed: ${reply.message}`, "query_failed");
+            }
+            if (reply.type !== "SyncPullResult") {
+                throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("sync", {
+                operation: "pull",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: true,
+                status: reply.status,
+                stale: reply.status.stale,
+                repairAction: reply.status.repairAction,
+                units: reply.units.length,
+            });
+            return {
+                status: reply.status,
+                units: reply.units,
+                hasMore: reply.hasMore,
+            };
+        }
+        catch (err) {
+            this.emit("sync", {
+                operation: "pull",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /** Acknowledge that the replica applied retained history through `appliedLsn`. */
+    async syncAck(request, opts) {
+        const start = Date.now();
+        try {
+            const reply = await this.send({
+                type: "SyncAck",
+                replicaId: request.replicaId,
+                appliedLsn: toU64(request.appliedLsn, "appliedLsn"),
+                remoteLsn: toU64(request.remoteLsn, "remoteLsn"),
+            }, opts);
+            if (reply.type === "Error") {
+                throw new errors_js_1.PowDBError(`sync ack failed: ${reply.message}`, "query_failed");
+            }
+            if (reply.type !== "SyncAckResult") {
+                throw new errors_js_1.PowDBError(`unexpected reply: ${reply.type}`, "protocol_error");
+            }
+            this.emit("sync", {
+                operation: "ack",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: true,
+                status: reply.status,
+                stale: reply.status.stale,
+                repairAction: reply.status.repairAction,
+                advanced: reply.advanced,
+            });
+            return {
+                previousAppliedLsn: reply.previousAppliedLsn,
+                appliedLsn: reply.appliedLsn,
+                remoteLsn: reply.remoteLsn,
+                advanced: reply.advanced,
+                status: reply.status,
+            };
+        }
+        catch (err) {
+            this.emit("sync", {
+                operation: "ack",
+                replicaId: request.replicaId,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /**
+     * Like {@link query}, but coerces string result columns to typed JS values
+     * using the caller-supplied schema. See `./typed.ts` for the coercion
+     * rules and supported column types.
+     *
+     * Returns a `TypedRow[]` — an array of objects keyed by column name.
+     * Throws `PowDBError(code="query_failed")` if the query is not a
+     * rows-returning query.
+     */
+    async queryTyped(query, schema, opts) {
+        const result = await this.query(query, opts);
+        if (result.kind !== "rows") {
+            throw new errors_js_1.PowDBError(`queryTyped: expected rows result, got ${result.kind}`, "query_failed");
+        }
+        return (0, typed_js_1.coerceRows)(result.columns, result.rows, schema);
+    }
+    async execScript(script, opts) {
+        const statements = (0, script_js_1.splitStatements)(script);
+        const continueOnError = opts?.continueOnError === true;
+        const transactional = opts?.transactional === true;
+        const signal = opts?.signal;
+        if (transactional && continueOnError) {
+            throw new errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.PowDBScriptError(`script failed at statement ${firstFailureIndex + 1}/${statements.length}: ${cause.message}`, (0, errors_js_1.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 errors_js_1.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 —
+     * `onRows` fires every interval, even if the rows are unchanged.
+     *
+     * Pragmatic first-cut live-data. If a query takes longer than
+     * `intervalMs`, the next tick waits for the in-flight one to finish
+     * (no pile-up). Errors fire `onError` (if provided) without stopping
+     * the watcher unless `stopOnError: true`.
+     */
+    watch(query, opts) {
+        if (!(opts.intervalMs > 0)) {
+            throw new errors_js_1.PowDBError(`watch: intervalMs must be > 0, got ${opts.intervalMs}`, "protocol_error");
+        }
+        let stopped = false;
+        let inFlight = false;
+        const tick = async () => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            try {
+                const r = await this.query(query);
+                if (!stopped)
+                    opts.onRows(r);
+            }
+            catch (err) {
+                if (stopped)
+                    return;
+                if (opts.onError)
+                    opts.onError(err);
+                if (opts.stopOnError) {
+                    stopped = true;
+                    clearInterval(handle);
+                    return;
+                }
+            }
+            finally {
+                inFlight = false;
+            }
+        };
+        // Run immediately so callers don't wait a full interval for the first
+        // emission, then every `intervalMs`.
+        void tick();
+        const handle = setInterval(tick, opts.intervalMs);
+        if (typeof handle.unref === "function")
+            handle.unref();
+        return {
+            stop: () => {
+                stopped = true;
+                clearInterval(handle);
+            },
+        };
+    }
+    /**
+     * Send Disconnect and tear down the socket. Waits for the remote FIN-ack
+     * (`socket.end` callback) but falls back to `destroy()` after a bounded
+     * timeout so an unresponsive peer cannot make `close()` hang forever.
+     */
+    async close() {
+        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((0, protocol_js_1.encode)({ type: "Disconnect" }));
+        }
+        catch {
+            // socket may already be half-closed; ignore
+        }
+        this.closed = true;
+        await new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                // Peer didn't ack FIN in time — force-close so we don't hang.
+                this.socket.destroy();
+                finish();
+            }, 5_000);
+            if (typeof timer.unref === "function")
+                timer.unref();
+            this.socket.end(finish);
+        });
+    }
+    // ───── internals ─────────────────────────────────────────────────────────
+    send(msg, opts) {
+        if (this.closed) {
+            return Promise.reject(this.closeError ?? new errors_js_1.PowDBError("client is closed", "closed"));
+        }
+        const signal = opts?.signal;
+        // Pre-check: if already aborted, reject immediately and do not enqueue.
+        // This matches fetch() semantics for pre-aborted signals.
+        if (signal?.aborted) {
+            return Promise.reject(abortError(signal));
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                resolve: (m) => {
+                    entry.settled = true;
+                    resolve(m);
+                },
+                reject: (e) => {
+                    entry.settled = true;
+                    reject(e);
+                },
+                settled: false,
+            };
+            this.pending.push(entry);
+            let onAbort = null;
+            if (signal) {
+                onAbort = () => {
+                    if (entry.settled)
+                        return;
+                    // Mark settled but DO NOT remove the entry from the queue — the
+                    // server will still send a reply, and onData drops replies for
+                    // already-settled entries at the head of the queue.
+                    entry.settled = true;
+                    reject(abortError(signal));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+                // Strip the listener once the entry resolves/rejects naturally.
+                const origResolve = entry.resolve;
+                const origReject = entry.reject;
+                entry.resolve = (m) => {
+                    if (onAbort)
+                        signal.removeEventListener("abort", onAbort);
+                    origResolve(m);
+                };
+                entry.reject = (e) => {
+                    if (onAbort)
+                        signal.removeEventListener("abort", onAbort);
+                    origReject(e);
+                };
+            }
+            this.socket.write((0, protocol_js_1.encode)(msg), (err) => {
+                if (err) {
+                    if (entry.settled)
+                        return;
+                    // Writer error — the promise will also be rejected by onClose,
+                    // but rejecting here gives a faster, more specific failure.
+                    //
+                    // Splicing an entry from the middle of `pending` is only safe
+                    // because a write-callback error implies the bytes never reached
+                    // the server — no reply will ever come for this slot, so FIFO
+                    // alignment with subsequent entries is preserved.
+                    const idx = this.pending.indexOf(entry);
+                    if (idx !== -1)
+                        this.pending.splice(idx, 1);
+                    entry.reject(err);
+                }
+            });
+        });
+    }
+    /**
+     * 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.
+        this.chunks.push(chunk);
+        this.totalLen += chunk.length;
+        while (this.totalLen > 0) {
+            // Fast path: if the first chunk already contains a full frame, we
+            // can decode without concatenating.
+            let view;
+            if (this.chunks.length === 1) {
+                view = this.chunks[0];
+            }
+            else {
+                // Peek at the header if we don't already have >=6 bytes up front.
+                // We need up to 6 bytes to read payloadLen, then enough to hold
+                // the full frame. Coalesce lazily.
+                if (this.chunks[0].length < 6 && this.totalLen >= 6) {
+                    this.coalesce();
+                }
+                // If the first chunk still has a full frame, great. Otherwise
+                // coalesce the whole queue so tryDecode sees contiguous bytes.
+                const first = this.chunks[0];
+                if (first.length >= 6) {
+                    const payloadLen = first.readUInt32LE(2);
+                    if (first.length >= 6 + payloadLen) {
+                        view = first;
+                    }
+                    else if (this.totalLen >= 6 + payloadLen) {
+                        this.coalesce();
+                        view = this.chunks[0];
+                    }
+                    else {
+                        // Not enough bytes yet for the full frame — wait for more data.
+                        break;
+                    }
+                }
+                else {
+                    // Still short of a header even after coalesce attempt above.
+                    break;
+                }
+            }
+            let decoded;
+            try {
+                decoded = (0, protocol_js_1.tryDecode)(view);
+            }
+            catch (err) {
+                this.onClose(err);
+                return;
+            }
+            if (decoded === null)
+                break;
+            // Advance past the consumed bytes without copying the trailing data.
+            this.consume(decoded.consumed);
+            // Handle Ping frames: auto-reply with Pong and continue decoding.
+            if (decoded.msg.type === "Ping") {
+                this.socket.write((0, protocol_js_1.encode)({ type: "Pong" }));
+                continue;
+            }
+            // 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 errors_js_1.PowDBError("received unexpected frame from server", "protocol_error"));
+                return;
+            }
+            if (entry.settled)
+                continue;
+            entry.resolve(decoded.msg);
+        }
+    }
+    /** Collapse the chunk queue into a single Buffer. */
+    coalesce() {
+        if (this.chunks.length <= 1)
+            return;
+        const merged = Buffer.concat(this.chunks, this.totalLen);
+        this.chunks.length = 0;
+        this.chunks.push(merged);
+    }
+    /** Drop the first `n` bytes off the chunk queue. */
+    consume(n) {
+        let remaining = n;
+        while (remaining > 0 && this.chunks.length > 0) {
+            const head = this.chunks[0];
+            if (head.length <= remaining) {
+                remaining -= head.length;
+                this.totalLen -= head.length;
+                this.chunks.shift();
+            }
+            else {
+                this.chunks[0] = head.subarray(remaining);
+                this.totalLen -= remaining;
+                remaining = 0;
+            }
+        }
+    }
+    onClose(err) {
+        const firstClose = !this.closed;
+        if (this.closed && err === null)
+            return;
+        this.closed = true;
+        let error = err ?? new errors_js_1.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 &&
+            !((0, errors_js_1.isPowDBError)(error) &&
+                (error.code === "auth_failed" || error.code === "protocol_error"))) {
+            error = new errors_js_1.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) {
+                entry.reject(error);
+            }
+        }
+        if (firstClose) {
+            // Best-effort: surface the close event once. Late listeners on a
+            // closed client miss it, which matches Node socket semantics.
+            this.emit("close", { error: err });
+        }
+    }
+}
+exports.Client = Client;
+function openSocket(target, timeoutMs, tlsOpt) {
+    return new Promise((resolve, reject) => {
+        let socket;
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new errors_js_1.PowDBError(`connect timeout after ${timeoutMs}ms`, "timeout"));
+        }, timeoutMs);
+        const onConnect = () => {
+            clearTimeout(timer);
+            socket.setNoDelay(true);
+            // Enable keepalive on the underlying OS socket so dead peers are detected
+            // even when the app is otherwise idle. (No-op for Unix sockets.)
+            socket.setKeepAlive(true, 30_000);
+            resolve(socket);
+        };
+        const onError = (err) => {
+            clearTimeout(timer);
+            // Wrap raw socket errors in the PowDBError taxonomy — callers can
+            // branch on `.code === "connect_failed"` rather than string-matching.
+            reject(new errors_js_1.PowDBError(`connect failed: ${err.message}`, "connect_failed", { cause: err }));
+        };
+        if (target.path !== undefined) {
+            // Unix domain socket: no TLS (local, same-host), no host/port.
+            socket = new net.Socket();
+            socket.once("connect", onConnect);
+            socket.once("error", onError);
+            socket.connect(target.path);
+        }
+        else if (tlsOpt) {
+            // TLS path: `tls.connect` wraps an underlying net.Socket. `secureConnect`
+            // fires once the TLS handshake is complete — that is the right hook for
+            // "ready to send application data".
+            const tlsOptions = tlsOpt === true ? {} : tlsOpt;
+            const tlsSock = tls.connect(target.port, target.host, tlsOptions);
+            socket = tlsSock;
+            tlsSock.once("secureConnect", onConnect);
+            tlsSock.once("error", onError);
+        }
+        else {
+            socket = new net.Socket();
+            socket.once("connect", onConnect);
+            socket.once("error", onError);
+            socket.connect(target.port, target.host);
+        }
+    });
+}
+var protocol_js_2 = require("./protocol.js");
+Object.defineProperty(exports, "encode", { enumerable: true, get: function () { return protocol_js_2.encode; } });
+Object.defineProperty(exports, "tryDecode", { enumerable: true, get: function () { return protocol_js_2.tryDecode; } });
+var protocol_js_3 = require("./protocol.js");
+Object.defineProperty(exports, "MAX_PAYLOAD_SIZE", { enumerable: true, get: function () { return protocol_js_3.MAX_PAYLOAD_SIZE; } });
+Object.defineProperty(exports, "MAX_ROWS", { enumerable: true, get: function () { return protocol_js_3.MAX_ROWS; } });
+Object.defineProperty(exports, "MAX_COLUMNS", { enumerable: true, get: function () { return protocol_js_3.MAX_COLUMNS; } });
+Object.defineProperty(exports, "MAX_PARAMS", { enumerable: true, get: function () { return protocol_js_3.MAX_PARAMS; } });
+Object.defineProperty(exports, "MAX_SYNC_UNITS", { enumerable: true, get: function () { return protocol_js_3.MAX_SYNC_UNITS; } });
+Object.defineProperty(exports, "MAX_SYNC_PULL_UNITS", { enumerable: true, get: function () { return protocol_js_3.MAX_SYNC_PULL_UNITS; } });
+Object.defineProperty(exports, "MAX_SYNC_PULL_BYTES", { enumerable: true, get: function () { return protocol_js_3.MAX_SYNC_PULL_BYTES; } });
+var escape_js_1 = require("./escape.js");
+Object.defineProperty(exports, "escapeLiteral", { enumerable: true, get: function () { return escape_js_1.escapeLiteral; } });
+Object.defineProperty(exports, "escapeIdent", { enumerable: true, get: function () { return escape_js_1.escapeIdent; } });
+Object.defineProperty(exports, "ident", { enumerable: true, get: function () { return escape_js_1.ident; } });
+Object.defineProperty(exports, "powql", { enumerable: true, get: function () { return escape_js_1.powql; } });
+Object.defineProperty(exports, "PowqlIdent", { enumerable: true, get: function () { return escape_js_1.PowqlIdent; } });
+var pool_js_1 = require("./pool.js");
+Object.defineProperty(exports, "Pool", { enumerable: true, get: function () { return pool_js_1.Pool; } });
+var script_js_2 = require("./script.js");
+Object.defineProperty(exports, "splitStatements", { enumerable: true, get: function () { return script_js_2.splitStatements; } });
+var errors_js_2 = require("./errors.js");
+Object.defineProperty(exports, "PowDBError", { enumerable: true, get: function () { return errors_js_2.PowDBError; } });
+Object.defineProperty(exports, "isPowDBError", { enumerable: true, get: function () { return errors_js_2.isPowDBError; } });
+Object.defineProperty(exports, "PowDBScriptError", { enumerable: true, get: function () { return errors_js_2.PowDBScriptError; } });
+Object.defineProperty(exports, "isPowDBScriptError", { enumerable: true, get: function () { return errors_js_2.isPowDBScriptError; } });
+var typed_js_2 = require("./typed.js");
+Object.defineProperty(exports, "coerceValue", { enumerable: true, get: function () { return typed_js_2.coerceValue; } });
+Object.defineProperty(exports, "coerceRow", { enumerable: true, get: function () { return typed_js_2.coerceRow; } });
+Object.defineProperty(exports, "coerceRows", { enumerable: true, get: function () { return typed_js_2.coerceRows; } });