@zvndev/powdb-client 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to `@zvndev/powdb-client`.
 
 | Client version | Compatible PowDB server | Notes |
 |---|---|---|
+| 0.5.x | 0.4.7+ | Adds `client.query(powql, params)` for `$N` parameter binding. The `QueryWithParams` (`0x04`) wire message is only understood by server ≥0.4.7; parameterized queries against an older server error out. Plain `query(powql)` calls remain compatible with 0.3.x–0.4.x. |
 | 0.4.x | 0.3.x – 0.4.x | Wire protocol v1 plus the optional Connect `username` field. **Multi-user mode requires client ≥0.4.0 AND server ≥0.4.6** (the server enforces roles as of 0.4.6; 0.4.5 accepted the username but did not enforce `readonly`). When `user` is omitted the Connect frame is byte-identical to the 0.3.x shape, so legacy shared-password and no-auth servers work unchanged. |
 | 0.3.x | 0.3.x – 0.4.x | Wire protocol v1. The client warns only on a major-version mismatch, so any `0.x` server connects. Minor server bumps may add new opcodes; the client tolerates unknown response codes by surfacing `PowDBError`. Pin both ends. **Caveat:** the 0.3.x client has no `user` option, so it cannot authenticate to a 0.4.5+ server running in **multi-user mode** (the server requires a username once any named user is defined). Shared-password mode works fine. |
 
@@ -13,6 +14,20 @@ The client warns on major-version mismatch with the server during the
 handshake. Within `0.x`, treat any minor-version skew between client and
 server as best-effort and pin both ends.
 
+## [0.5.0] — 2026-06-10
+
+### Added
+- **Parameter binding** — `client.query(powql, params)` accepts a second
+  argument of positional values bound to `$1`, `$2`, … placeholders in the
+  PowQL text. Values are sent as a typed parameter list in the new
+  `QueryWithParams` (`0x04`) wire message and bound at the token level on the
+  server, so they are injection-inert and byte-faithful (a value containing
+  PowQL syntax is stored verbatim, never re-parsed). Requires server ≥0.4.7.
+
+### Compatibility
+- Parameterized queries require **server ≥0.4.7**. Plain `query(powql)` (no
+  params) is unchanged and still works against 0.3.x–0.4.x servers.
+
 ## [0.4.0] — 2026-06-09
 
 ### Added

package/README.md

@@ -60,6 +60,27 @@ escapeIdent("User");        // → "User" (throws on invalid)
 
 `escapeLiteral` accepts `string | number | bigint | boolean | null`. It rejects `NaN`/`Infinity`, `undefined`, objects, arrays, symbols, and `Date` — convert those yourself before passing them in.
 
+### Parameter binding (`$N`)
+
+For the strongest separation between code and data, pass values as positional `$N` parameters instead of interpolating them. The server binds each placeholder at the **token level** — a string becomes a literal token, never interpolated text — so an injection-shaped value is inert and can never change the query's shape. Placeholders are 1-based (`?` is not a placeholder; `??` is the COALESCE operator).
+
+```typescript
+// Values are passed as the second argument, in $1, $2, … order.
+await client.query("insert User { name := $1, email := $2, age := $3 }", [
+  name,
+  email,
+  age,
+]);
+
+const r = await client.query("User filter .email = $1 { .name }", [email]);
+
+// null binds PowQL null; numbers bind as int when integral, float otherwise;
+// bigint always binds as int.
+await client.query("insert User { name := $1, age := $2 }", ["Dana", null]);
+```
+
+`QueryParam` is `string | number | bigint | boolean | null`. The params form sends the `QueryWithParams` (0x04) wire message and **requires powdb-server >= 0.4.7**. The plain `query(q)` and `query(q, { signal })` forms are unchanged.
+
 ## Authentication
 
 For servers using the legacy shared password (`POWDB_PASSWORD`), pass
@@ -277,7 +298,7 @@ Returns a `Promise<Client>`. Options:
 > **Multi-user servers:** requires client ≥0.4.0 (`user` option) and server
 > ≥0.4.6 (enforced roles). See the version matrix under Authentication.
 
-### `client.query(query, opts?)`
+### `client.query(query, params?, opts?)`
 
 Sends a PowQL query and returns a `Promise<QueryResult>`:
 
@@ -285,6 +306,8 @@ Sends a PowQL query and returns a `Promise<QueryResult>`:
 - `{ kind: "scalar", value: string }` — for aggregates (`count`, `sum`, `avg`, etc.)
 - `{ kind: "ok", affected: bigint }` — for mutations (`insert`, `update`, `delete`)
 
+`params?: QueryParam[]` — positional values bound to `$1`, `$2`, … placeholders (see Parameter binding above; requires server ≥0.4.7). When omitted, the plain query path is used. The legacy two-argument `query(q, { signal })` form is still accepted — an array second argument is treated as params, an object as options.
+
 `opts.signal?: AbortSignal` — aborts the returned promise (see Cancellation above).
 
 Throws a `PowDBError` (see Structured errors above) on any failure.

package/dist/index.d.ts

@@ -33,6 +33,15 @@ export type QueryResult = {
     kind: "message";
     message: string;
 };
+/**
+ * A value bound to a positional `$N` placeholder in {@link Client.query}.
+ *
+ * The server binds these at the token level — a string is substituted as a
+ * literal token, never interpolated — so injection-shaped input is inert.
+ * Numbers bind as ints when integral and floats otherwise; `bigint` always
+ * binds as an int; `null` binds PowQL `null`.
+ */
+export type QueryParam = string | number | bigint | boolean | null;
 export interface ClientOptions {
     host: string;
     port: number;
@@ -100,7 +109,9 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * destroyed — the server will still eventually send its reply, which we
      * silently discard so other in-flight queries keep working.
      */
-    query(query: string, opts?: {
+    query(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
         signal?: AbortSignal;
     }): Promise<QueryResult>;
     /**
@@ -148,8 +159,8 @@ export declare class Client extends EventEmitter<ClientEvents> {
     private onClose;
 }
 export { encode, tryDecode } from "./protocol.js";
-export type { Message } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, } from "./protocol.js";
+export type { Message, WireParam } from "./protocol.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, } from "./protocol.js";
 export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";

package/dist/index.js

@@ -17,11 +17,30 @@
 import * as net from "node:net";
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
-import { encode, tryDecode } from "./protocol.js";
+import { encode, tryDecode, } from "./protocol.js";
 import { PowDBError } from "./errors.js";
 import { coerceRows, } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
 export const CLIENT_VERSION = "0.4.0";
+/** 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 PowDBError(`unsupported query parameter type: ${typeof p}`, "protocol_error");
+    }
+}
 /** 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". */
@@ -143,10 +162,23 @@ export class Client extends EventEmitter {
      * destroyed — the server will still eventually send its reply, which we
      * silently discard so other in-flight queries keep working.
      */
-    async query(query, opts) {
+    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 reply = await this.send({ type: "Query", query }, opts);
+            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":
@@ -515,7 +547,7 @@ function openSocket(host, port, timeoutMs, tlsOpt) {
     });
 }
 export { encode, tryDecode } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, } from "./protocol.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, } from "./protocol.js";
 export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export { PowDBError, isPowDBError } from "./errors.js";

package/dist/protocol.d.ts

@@ -9,6 +9,12 @@
 export declare const MSG_CONNECT = 1;
 export declare const MSG_CONNECT_OK = 2;
 export declare const MSG_QUERY = 3;
+/**
+ * Query carrying positional `$N` parameters. Pure protocol addition: old
+ * servers reject it with the existing "unknown message type" error, and the
+ * plain `MSG_QUERY` frame is unchanged. Requires powdb-server ≥ 0.4.7.
+ */
+export declare const MSG_QUERY_PARAMS = 4;
 export declare const MSG_RESULT_ROWS = 7;
 export declare const MSG_RESULT_SCALAR = 8;
 export declare const MSG_RESULT_OK = 9;
@@ -23,6 +29,32 @@ export declare const MAX_PAYLOAD_SIZE: number;
 export declare const MAX_ROWS = 10000000;
 /** Maximum number of columns allowed in a result set. */
 export declare const MAX_COLUMNS = 4096;
+/** Maximum number of bound parameters in a QueryWithParams message. */
+export declare const MAX_PARAMS = 4096;
+/**
+ * A positional parameter value for {@link MSG_QUERY_PARAMS}. Wire encoding
+ * per param: a 1-byte tag followed by the body —
+ *   `0` null (no body), `1` int (8B LE i64), `2` float (8B LE f64),
+ *   `3` bool (1B), `4` str (length-prefixed UTF-8).
+ *
+ * Integral numbers are sent as ints, non-integral numbers as floats; `null`
+ * binds PowQL `null`. `bigint` is always an int.
+ */
+export type WireParam = {
+    tag: "null";
+} | {
+    tag: "int";
+    value: bigint;
+} | {
+    tag: "float";
+    value: number;
+} | {
+    tag: "bool";
+    value: boolean;
+} | {
+    tag: "str";
+    value: string;
+};
 export type Message = {
     type: "Connect";
     dbName: string;
@@ -41,6 +73,10 @@ export type Message = {
 } | {
     type: "Query";
     query: string;
+} | {
+    type: "QueryWithParams";
+    query: string;
+    params: WireParam[];
 } | {
     type: "ResultRows";
     columns: string[];

package/dist/protocol.js

@@ -9,6 +9,12 @@
 export const MSG_CONNECT = 0x01;
 export const MSG_CONNECT_OK = 0x02;
 export const MSG_QUERY = 0x03;
+/**
+ * Query carrying positional `$N` parameters. Pure protocol addition: old
+ * servers reject it with the existing "unknown message type" error, and the
+ * plain `MSG_QUERY` frame is unchanged. Requires powdb-server ≥ 0.4.7.
+ */
+export const MSG_QUERY_PARAMS = 0x04;
 export const MSG_RESULT_ROWS = 0x07;
 export const MSG_RESULT_SCALAR = 0x08;
 export const MSG_RESULT_OK = 0x09;
@@ -24,6 +30,8 @@ export const MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
 export const MAX_ROWS = 10_000_000;
 /** Maximum number of columns allowed in a result set. */
 export const MAX_COLUMNS = 4096;
+/** Maximum number of bound parameters in a QueryWithParams message. */
+export const MAX_PARAMS = 4096;
 // ───── Encoding ────────────────────────────────────────────────────────────
 export function encode(msg) {
     let msgType;
@@ -52,6 +60,42 @@ export function encode(msg) {
             payload = encodeString(msg.query);
             msgType = MSG_QUERY;
             break;
+        case "QueryWithParams": {
+            const parts = [encodeString(msg.query)];
+            const count = Buffer.alloc(2);
+            count.writeUInt16LE(msg.params.length, 0);
+            parts.push(count);
+            for (const p of msg.params) {
+                switch (p.tag) {
+                    case "null":
+                        parts.push(Buffer.from([0]));
+                        break;
+                    case "int": {
+                        const b = Buffer.alloc(9);
+                        b.writeUInt8(1, 0);
+                        b.writeBigInt64LE(p.value, 1);
+                        parts.push(b);
+                        break;
+                    }
+                    case "float": {
+                        const b = Buffer.alloc(9);
+                        b.writeUInt8(2, 0);
+                        b.writeDoubleLE(p.value, 1);
+                        parts.push(b);
+                        break;
+                    }
+                    case "bool":
+                        parts.push(Buffer.from([3, p.value ? 1 : 0]));
+                        break;
+                    case "str":
+                        parts.push(Buffer.from([4]), encodeString(p.value));
+                        break;
+                }
+            }
+            payload = Buffer.concat(parts);
+            msgType = MSG_QUERY_PARAMS;
+            break;
+        }
         case "ResultRows": {
             const parts = [];
             const colCount = Buffer.alloc(2);
@@ -150,6 +194,37 @@ function decodePayload(msgType, payload) {
             return { type: "ConnectOk", version: decodeString(payload, cursor) };
         case MSG_QUERY:
             return { type: "Query", query: decodeString(payload, cursor) };
+        case MSG_QUERY_PARAMS: {
+            const query = decodeString(payload, cursor);
+            const count = readU16(payload, cursor, "param count");
+            if (count > MAX_PARAMS) {
+                throw new Error(`too many parameters: ${count} (max ${MAX_PARAMS})`);
+            }
+            const params = [];
+            for (let i = 0; i < count; i++) {
+                const tag = readU8(payload, cursor, "param tag");
+                switch (tag) {
+                    case 0:
+                        params.push({ tag: "null" });
+                        break;
+                    case 1:
+                        params.push({ tag: "int", value: readI64(payload, cursor, "int param") });
+                        break;
+                    case 2:
+                        params.push({ tag: "float", value: readF64(payload, cursor, "float param") });
+                        break;
+                    case 3:
+                        params.push({ tag: "bool", value: readU8(payload, cursor, "bool param") !== 0 });
+                        break;
+                    case 4:
+                        params.push({ tag: "str", value: decodeString(payload, cursor) });
+                        break;
+                    default:
+                        throw new Error(`unknown param tag: ${tag}`);
+                }
+            }
+            return { type: "QueryWithParams", query, params };
+        }
         case MSG_RESULT_ROWS: {
             const colCount = readU16(payload, cursor, "column count");
             if (colCount > MAX_COLUMNS) {
@@ -213,6 +288,30 @@ function decodeString(buf, cursor) {
     cursor.pos += len;
     return s;
 }
+function readU8(buf, cursor, label) {
+    if (cursor.pos + 1 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readUInt8(cursor.pos);
+    cursor.pos += 1;
+    return value;
+}
+function readI64(buf, cursor, label) {
+    if (cursor.pos + 8 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readBigInt64LE(cursor.pos);
+    cursor.pos += 8;
+    return value;
+}
+function readF64(buf, cursor, label) {
+    if (cursor.pos + 8 > buf.length) {
+        throw new Error(`truncated ${label}`);
+    }
+    const value = buf.readDoubleLE(cursor.pos);
+    cursor.pos += 8;
+    return value;
+}
 function readU16(buf, cursor, label) {
     if (cursor.pos + 2 > buf.length) {
         throw new Error(`truncated ${label}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",
@@ -60,8 +60,8 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "@types/node": "^22",
+    "@types/node": "^25",
     "tsx": "^4",
-    "typescript": "^5.6"
+    "typescript": "^6.0"
   }
 }