@zvndev/powdb-client 0.3.3 → 0.4.0

package/src/errors.ts

@@ -1,54 +0,0 @@
-/**
- * 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.
- */
-
-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 class PowDBError extends Error {
-  readonly code: PowDBErrorCode;
-
-  constructor(message: string, code: PowDBErrorCode, options?: { cause?: unknown }) {
-    // ErrorOptions.cause is supported in Node 16.9+; we require Node 18+.
-    super(message, options as ErrorOptions);
-    this.name = "PowDBError";
-    this.code = code;
-    // Preserve the prototype chain across `target: es2020` and friends.
-    Object.setPrototypeOf(this, PowDBError.prototype);
-  }
-}
-
-/**
- * Narrow `unknown` to a PowDBError. Useful in catch blocks where you want
- * to branch on `.code` but TypeScript sees `unknown`.
- */
-export function isPowDBError(err: unknown): err is PowDBError {
-  return err instanceof PowDBError;
-}

package/src/escape.ts

@@ -1,141 +0,0 @@
-/**
- * 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).
- */
-
-const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-
-/** Wrapper marking a string as an identifier (vs a literal) for `powql` tagged templates. */
-export class PowqlIdent {
-  constructor(public readonly name: string) {}
-}
-
-/** Factory for {@link PowqlIdent}. Prefer this over `new PowqlIdent(...)` at call sites. */
-export function ident(name: string): PowqlIdent {
-  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_]*`).
- */
-export function escapeIdent(name: string): string {
-  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`
- */
-export function escapeLiteral(
-  value: string | number | bigint | boolean | null
-): string {
-  if (value === null) return "null";
-
-  const t = typeof value;
-
-  if (t === "string") {
-    const escaped = (value as string)
-      .replace(/\\/g, "\\\\")
-      .replace(/"/g, '\\"');
-    return `"${escaped}"`;
-  }
-
-  if (t === "number") {
-    const n = value as number;
-    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 as bigint).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} }`;
- */
-export function powql(
-  strings: TemplateStringsArray,
-  ...values: unknown[]
-): string {
-  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: unknown): string {
-  if (value instanceof PowqlIdent) {
-    return escapeIdent(value.name);
-  }
-  // `escapeLiteral` enforces the allowed set — for anything else it throws.
-  return escapeLiteral(value as string | number | bigint | boolean | null);
-}
-
-function describe(value: unknown): string {
-  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;
-}