@zvndev/powdb-client 0.3.0

package/dist/protocol.js

@@ -0,0 +1,188 @@
+/**
+ * PowDB wire protocol.
+ *
+ * Frame format: [type(1)][flags(1)][len(4 LE)][payload]
+ * Strings are encoded as [len(4 LE)][utf-8 bytes].
+ *
+ * This mirrors crates/server/src/protocol.rs — keep them in sync.
+ */
+export const MSG_CONNECT = 0x01;
+export const MSG_CONNECT_OK = 0x02;
+export const MSG_QUERY = 0x03;
+export const MSG_RESULT_ROWS = 0x07;
+export const MSG_RESULT_SCALAR = 0x08;
+export const MSG_RESULT_OK = 0x09;
+export const MSG_ERROR = 0x0a;
+export const MSG_DISCONNECT = 0x10;
+// ───── Size limits (mirror crates/server/src/protocol.rs) ──────────────────
+/** Maximum payload size accepted from the wire (64 MB). */
+export const MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
+/** Maximum number of rows allowed in a single result message. */
+export const MAX_ROWS = 10_000_000;
+/** Maximum number of columns allowed in a result set. */
+export const MAX_COLUMNS = 4096;
+// ───── Encoding ────────────────────────────────────────────────────────────
+export function encode(msg) {
+    let msgType;
+    let payload;
+    switch (msg.type) {
+        case "Connect": {
+            const dbBuf = encodeString(msg.dbName);
+            const pwBuf = msg.password === null ? u32LE(0) : encodeString(msg.password);
+            payload = Buffer.concat([dbBuf, pwBuf]);
+            msgType = MSG_CONNECT;
+            break;
+        }
+        case "ConnectOk":
+            payload = encodeString(msg.version);
+            msgType = MSG_CONNECT_OK;
+            break;
+        case "Query":
+            payload = encodeString(msg.query);
+            msgType = MSG_QUERY;
+            break;
+        case "ResultRows": {
+            const parts = [];
+            const colCount = Buffer.alloc(2);
+            colCount.writeUInt16LE(msg.columns.length, 0);
+            parts.push(colCount);
+            for (const col of msg.columns)
+                parts.push(encodeString(col));
+            parts.push(u32LE(msg.rows.length));
+            for (const row of msg.rows) {
+                for (const val of row)
+                    parts.push(encodeString(val));
+            }
+            payload = Buffer.concat(parts);
+            msgType = MSG_RESULT_ROWS;
+            break;
+        }
+        case "ResultScalar":
+            payload = encodeString(msg.value);
+            msgType = MSG_RESULT_SCALAR;
+            break;
+        case "ResultOk": {
+            payload = Buffer.alloc(8);
+            payload.writeBigUInt64LE(msg.affected, 0);
+            msgType = MSG_RESULT_OK;
+            break;
+        }
+        case "Error":
+            payload = encodeString(msg.message);
+            msgType = MSG_ERROR;
+            break;
+        case "Disconnect":
+            payload = Buffer.alloc(0);
+            msgType = MSG_DISCONNECT;
+            break;
+    }
+    const frame = Buffer.alloc(6 + payload.length);
+    frame.writeUInt8(msgType, 0);
+    frame.writeUInt8(0, 1); // flags
+    frame.writeUInt32LE(payload.length, 2);
+    payload.copy(frame, 6);
+    return frame;
+}
+// ───── Decoding ────────────────────────────────────────────────────────────
+/**
+ * Attempts to parse a single frame from the start of `buf`. Returns the parsed
+ * message and the number of bytes consumed, or `null` if the buffer does not
+ * yet contain a complete frame.
+ */
+export function tryDecode(buf) {
+    if (buf.length < 6)
+        return null;
+    const msgType = buf.readUInt8(0);
+    // flags byte at offset 1 is currently unused
+    const payloadLen = buf.readUInt32LE(2);
+    if (payloadLen > MAX_PAYLOAD_SIZE) {
+        throw new Error(`payload too large: ${payloadLen} bytes (max ${MAX_PAYLOAD_SIZE})`);
+    }
+    if (buf.length < 6 + payloadLen)
+        return null;
+    const payload = buf.subarray(6, 6 + payloadLen);
+    const msg = decodePayload(msgType, payload);
+    return { msg, consumed: 6 + payloadLen };
+}
+function decodePayload(msgType, payload) {
+    const cursor = { pos: 0 };
+    switch (msgType) {
+        case MSG_CONNECT: {
+            const dbName = decodeString(payload, cursor);
+            let password = null;
+            if (cursor.pos < payload.length) {
+                const p = decodeString(payload, cursor);
+                password = p.length === 0 ? null : p;
+            }
+            return { type: "Connect", dbName, password };
+        }
+        case MSG_CONNECT_OK:
+            return { type: "ConnectOk", version: decodeString(payload, cursor) };
+        case MSG_QUERY:
+            return { type: "Query", query: decodeString(payload, cursor) };
+        case MSG_RESULT_ROWS: {
+            const colCount = payload.readUInt16LE(cursor.pos);
+            cursor.pos += 2;
+            if (colCount > MAX_COLUMNS) {
+                throw new Error(`too many columns: ${colCount} (max ${MAX_COLUMNS})`);
+            }
+            const columns = [];
+            for (let i = 0; i < colCount; i++) {
+                columns.push(decodeString(payload, cursor));
+            }
+            const rowCount = payload.readUInt32LE(cursor.pos);
+            cursor.pos += 4;
+            if (rowCount > MAX_ROWS) {
+                throw new Error(`too many rows: ${rowCount} (max ${MAX_ROWS})`);
+            }
+            const rows = [];
+            for (let r = 0; r < rowCount; r++) {
+                const row = [];
+                for (let c = 0; c < colCount; c++) {
+                    row.push(decodeString(payload, cursor));
+                }
+                rows.push(row);
+            }
+            return { type: "ResultRows", columns, rows };
+        }
+        case MSG_RESULT_SCALAR:
+            return { type: "ResultScalar", value: decodeString(payload, cursor) };
+        case MSG_RESULT_OK: {
+            const affected = payload.readBigUInt64LE(0);
+            return { type: "ResultOk", affected };
+        }
+        case MSG_ERROR:
+            return { type: "Error", message: decodeString(payload, cursor) };
+        case MSG_DISCONNECT:
+            return { type: "Disconnect" };
+        default:
+            throw new Error(`unknown message type: 0x${msgType.toString(16)}`);
+    }
+}
+// ───── String helpers ──────────────────────────────────────────────────────
+function encodeString(s) {
+    const bytes = Buffer.from(s, "utf8");
+    const out = Buffer.alloc(4 + bytes.length);
+    out.writeUInt32LE(bytes.length, 0);
+    bytes.copy(out, 4);
+    return out;
+}
+function decodeString(buf, cursor) {
+    if (cursor.pos + 4 > buf.length) {
+        throw new Error("truncated string length");
+    }
+    const len = buf.readUInt32LE(cursor.pos);
+    cursor.pos += 4;
+    if (cursor.pos + len > buf.length) {
+        throw new Error("truncated string data");
+    }
+    const s = buf.toString("utf8", cursor.pos, cursor.pos + len);
+    cursor.pos += len;
+    return s;
+}
+function u32LE(n) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(n, 0);
+    return b;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/typed.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Optional row-level type coercion for `queryTyped`.
+ *
+ * The server's wire format serialises every value to a string (see
+ * `crates/server/src/handler.rs::value_to_display`):
+ *   Int      → decimal digits, e.g. "42" or "-7"
+ *   Float    → Rust `{}` format, e.g. "3.14"
+ *   Bool     → "true" / "false"
+ *   Str      → raw UTF-8 (may contain anything)
+ *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
+ *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Bytes    → "<N bytes>" (LOSSY — see note below)
+ *
+ * `queryTyped` takes a user-supplied schema and coerces each column string
+ * into the corresponding JS value. Rationale for requiring the caller to
+ * supply the schema (rather than introspecting): PowDB has no `describe`
+ * statement yet, and going via `select` off a system catalog is one extra
+ * round trip per typed query. When schema introspection lands, a helper
+ * that builds the schema object can be added without changing this API.
+ *
+ * Bytes caveat: the current wire format is lossy for byte columns (renders
+ * `<N bytes>`). Until the wire protocol grows a binary column type, this
+ * module throws on `bytes` columns rather than guessing — use `str` in the
+ * schema if you just want the `<N bytes>` placeholder.
+ */
+/**
+ * Supported column types. Mirrors the server's `DataType` enum minus the
+ * `Bytes` variant, which is intentionally unsupported here.
+ */
+export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid";
+/** Map of column name → declared type. Columns not in the map pass through as strings. */
+export type TypedSchema = Record<string, ColumnType>;
+/** Coerced value type. `int` may return `bigint` if the value exceeds Number.MAX_SAFE_INTEGER. */
+export type Coerced = number | bigint | boolean | string | Date | null;
+/** A row of coerced values keyed by column name. */
+export type TypedRow = Record<string, Coerced>;
+/**
+ * Coerce a single string value to the JS type declared in `schema`. `null`
+ * is returned for the conventional null sentinel — see note at call site.
+ * Unknown column types fall through as strings.
+ */
+export declare function coerceValue(column: string, raw: string, type: ColumnType | undefined): Coerced;
+/**
+ * Coerce a single result row (a string tuple) into a typed object keyed by
+ * column name.
+ */
+export declare function coerceRow(columns: string[], values: string[], schema: TypedSchema): TypedRow;
+/** Coerce every row in a rows-result into typed objects. */
+export declare function coerceRows(columns: string[], rows: string[][], schema: TypedSchema): TypedRow[];
+//# sourceMappingURL=typed.d.ts.map

package/dist/typed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../src/typed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhF,0FAA0F;AAC1F,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAErD,kGAAkG;AAClG,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvE,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,GAAG,SAAS,GAC3B,OAAO,CAqET;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,WAAW,GAClB,QAAQ,CAOV;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,EAAE,MAAM,EAAE,EAAE,EAChB,MAAM,EAAE,WAAW,GAClB,QAAQ,EAAE,CAEZ"}

package/dist/typed.js

@@ -0,0 +1,101 @@
+/**
+ * Optional row-level type coercion for `queryTyped`.
+ *
+ * The server's wire format serialises every value to a string (see
+ * `crates/server/src/handler.rs::value_to_display`):
+ *   Int      → decimal digits, e.g. "42" or "-7"
+ *   Float    → Rust `{}` format, e.g. "3.14"
+ *   Bool     → "true" / "false"
+ *   Str      → raw UTF-8 (may contain anything)
+ *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
+ *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Bytes    → "<N bytes>" (LOSSY — see note below)
+ *
+ * `queryTyped` takes a user-supplied schema and coerces each column string
+ * into the corresponding JS value. Rationale for requiring the caller to
+ * supply the schema (rather than introspecting): PowDB has no `describe`
+ * statement yet, and going via `select` off a system catalog is one extra
+ * round trip per typed query. When schema introspection lands, a helper
+ * that builds the schema object can be added without changing this API.
+ *
+ * Bytes caveat: the current wire format is lossy for byte columns (renders
+ * `<N bytes>`). Until the wire protocol grows a binary column type, this
+ * module throws on `bytes` columns rather than guessing — use `str` in the
+ * schema if you just want the `<N bytes>` placeholder.
+ */
+import { PowDBError } from "./errors.js";
+/**
+ * Coerce a single string value to the JS type declared in `schema`. `null`
+ * is returned for the conventional null sentinel — see note at call site.
+ * Unknown column types fall through as strings.
+ */
+export function coerceValue(column, raw, type) {
+    // The server's wire format distinguishes NULL from empty string by the
+    // literal "null" bareword in scalar displays. For typed columns we treat
+    // the single token "null" as NULL; empty string remains empty string for
+    // `str` columns (can be an intentional empty value).
+    if (type !== "str" && raw === "null")
+        return null;
+    switch (type) {
+        case undefined:
+        case "str":
+            return raw;
+        case "int": {
+            if (!/^-?\d+$/.test(raw)) {
+                throw new PowDBError(`queryTyped: column "${column}" declared int but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            // Promote to BigInt when the value doesn't round-trip through Number.
+            const n = Number(raw);
+            if (Number.isSafeInteger(n))
+                return n;
+            return BigInt(raw);
+        }
+        case "float": {
+            const n = Number(raw);
+            if (!Number.isFinite(n)) {
+                throw new PowDBError(`queryTyped: column "${column}" declared float but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            return n;
+        }
+        case "bool":
+            if (raw === "true")
+                return true;
+            if (raw === "false")
+                return false;
+            throw new PowDBError(`queryTyped: column "${column}" declared bool but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+        case "datetime": {
+            if (!/^-?\d+$/.test(raw)) {
+                throw new PowDBError(`queryTyped: column "${column}" declared datetime but got ${JSON.stringify(raw)} (expected microseconds since epoch)`, "type_coercion_failed");
+            }
+            // Server sends microseconds since epoch. JS Date uses milliseconds.
+            // BigInt division avoids float precision loss for far-future dates.
+            const micros = BigInt(raw);
+            const millis = Number(micros / 1000n);
+            return new Date(millis);
+        }
+        case "uuid": {
+            // Canonical 8-4-4-4-12 hex, lowercase (per server format).
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(raw)) {
+                throw new PowDBError(`queryTyped: column "${column}" declared uuid but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            return raw;
+        }
+    }
+}
+/**
+ * Coerce a single result row (a string tuple) into a typed object keyed by
+ * column name.
+ */
+export function coerceRow(columns, values, schema) {
+    const out = {};
+    for (let i = 0; i < columns.length; i++) {
+        const col = columns[i];
+        out[col] = coerceValue(col, values[i] ?? "null", schema[col]);
+    }
+    return out;
+}
+/** Coerce every row in a rows-result into typed objects. */
+export function coerceRows(columns, rows, schema) {
+    return rows.map((r) => coerceRow(columns, r, schema));
+}
+//# sourceMappingURL=typed.js.map

package/dist/typed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.js","sourceRoot":"","sources":["../src/typed.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@zvndev/powdb-client",
+  "version": "0.3.0",
+  "description": "TypeScript client for PowDB (PowQL wire protocol)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zvndev/powdb",
+    "directory": "clients/ts"
+  },
+  "keywords": ["powdb", "database", "client", "powql"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsx test/client.test.ts",
+    "test:escape": "tsx test/escape.test.ts",
+    "test:protocol": "tsx test/protocol.test.ts",
+    "test:pool": "tsx test/pool.test.ts",
+    "test:typed": "tsx test/typed.test.ts",
+    "test:errors": "tsx test/errors.test.ts",
+    "demo": "tsx demo/demo.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5.6"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,54 @@
+/**
+ * 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

@@ -0,0 +1,141 @@
+/**
+ * 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;
+}