@zvndev/powdb-client 0.9.0 → 0.10.0

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;
+}