@zvndev/powdb-client 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## Unreleased
+
+## 0.20.0 - 2026-07-25
+
+- **Security (medium): bounded result allocation.** A hostile or MITM'd server
+  could declare 10,000,000 single-column rows backed by a ~40 MB frame of empty
+  cells and make the client allocate roughly 1.9 GB (measured), since a cell
+  costs 4 bytes on the wire but far more as a JS value. Result decoding now
+  enforces `MAX_RESULT_CELLS` (2,000,000 cells per frame) on both the legacy and
+  native paths. Results larger than that must be paged with `limit`/`offset`.
+- `queryTyped` is now generic and takes positional `$N` parameters:
+  `queryTyped<User>(q, schema, params?, opts?)`. Typed rows and injection-safe
+  binding were previously mutually exclusive. The old
+  `queryTyped(q, schema, opts?)` form is unchanged.
+- New `queryObjects<Row>(query, params?, opts?)`: object rows keyed by column
+  name on the LOSSLESS native path, so no schema is needed (bytes stay bytes,
+  JSON stays recursive data, out-of-range integers stay `bigint`).
+  `querySqlObjects<Row>(query, opts?)` is the SQL counterpart. New `NativeRow`
+  type.
+- New SQL composition helpers in `escape.ts`: `sql` tagged template,
+  `sqlIdent`, `escapeSqlLiteral`, `escapeSqlIdent`. PowDB's SQL frontend has NO
+  parameter binding on any wire frame, so string concatenation was previously
+  the only way to build SQL with user input. These escape for PowDB's own SQL
+  lexer (`''` doubling plus backslash escaping, identifiers validated rather
+  than quoted). Escaping is weaker than binding: prefer PowQL `$N` parameters
+  for untrusted input.
+
 ## 0.19.1 - 2026-07-24
 
 - `SUPPORTED_CATALOG_VERSION` raised from 6 to 7: sync/replica clients are now

package/README.md

@@ -1,6 +1,6 @@
 # @zvndev/powdb-client
 
-TypeScript client for [PowDB](https://github.com/zvndev/powdb) — speaks the native binary wire protocol over TCP (or TLS).
+TypeScript client for [PowDB](https://github.com/ZVN-DEV/powdb). Speaks the native binary wire protocol over TCP (or TLS).
 
 ## Install
 
@@ -60,6 +60,24 @@ 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.
 
+### SQL composition (`sql`, `sqlIdent`, `escapeSqlLiteral`)
+
+**The SQL frontend has no parameter binding.** `querySql`, `querySqlNative`, and `querySqlObjects` take a statement and nothing else: there is no `QuerySqlParams` wire frame, so `$N` placeholders cannot be bound on the SQL path. Prefer PowQL with `$N` parameters for anything built from untrusted input.
+
+When you must build SQL, use the `sql` tagged template rather than concatenation. It escapes for PowDB's own SQL lexer: `'` is doubled and a backslash is escaped (PowDB's SQL lexer honours backslash escapes, unlike standard SQL). Identifiers are validated, not quoted, because the lexer reads a double-quoted run as a string literal.
+
+```typescript
+import { sql, sqlIdent, escapeSqlLiteral, escapeSqlIdent } from "@zvndev/powdb-client";
+
+const q = sql`SELECT name FROM ${sqlIdent("User")} WHERE name = ${userName}`;
+await client.querySql(q);
+
+escapeSqlLiteral("o'neil");   // → "'o''neil'"
+escapeSqlIdent("User");       // → "User" (throws on anything else)
+```
+
+Escaping is a weaker guarantee than binding: it depends on the value landing in a string or number position, and it cannot make an identifier or keyword safe. Track the missing `QuerySqlParams` frame if you need real binding on the SQL path.
+
 ### 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).
@@ -412,6 +430,45 @@ output always parses, so this fallback is inert in normal use).
 Bytes columns are intentionally unsupported by `queryTyped` because the
 legacy wire format renders `<N bytes>`. Use `queryNative` for exact bytes.
 
+## Object rows on the lossless path (`queryObjects`)
+
+`queryTyped` coerces the legacy stringly-typed path with a caller-supplied
+schema. `queryObjects` needs no schema: it runs on the **native** wire surface,
+where the server states each cell's type, and returns objects keyed by column
+name. It accepts `$N` parameters and an abort signal exactly like `query`.
+
+```typescript
+interface User {
+  name: string;
+  age: number;
+  prefs: unknown;
+}
+
+const users = await client.queryObjects<User>(
+  "User filter .age > $1 { .name, .age, .prefs }",
+  [25],
+);
+
+users[0].age;    // number (bigint when outside the safe integer range)
+users[0].prefs;  // recursively decoded JSON, not a string
+```
+
+`querySqlObjects<Row>(sql, opts?)` is the SQL counterpart. `queryTyped` is also
+generic and takes parameters, so typed rows and injection-safe binding compose:
+
+```typescript
+const rows = await client.queryTyped<User>(
+  "User filter .age > $1 { .name, .age }",
+  { name: "str", age: "int" },
+  [25],
+);
+```
+
+The generic is an unchecked assertion about the query's shape, like a SQL
+driver's row type: nothing validates it at runtime. Duplicate column names
+collapse (last one wins), so alias them in the projection. A non-rows result
+(a count, a write) throws `PowDBError(code="query_failed")`.
+
 ## Structured errors
 
 Every error thrown by the client is a `PowDBError` with a stable `.code`:
@@ -592,10 +649,26 @@ Runs SQL through the native typed wire surface and returns a
 `Promise<NativeQueryResult>`. It has the same no-replay guarantee as
 `queryNative()`.
 
-### `client.queryTyped(query, schema, opts?)`
+### `client.queryTyped<Row>(query, schema, params?, opts?)`
 
 Like `query()`, but coerces each row's string values to JS types using the
-supplied schema and returns `Promise<TypedRow[]>`. See Typed rows above.
+supplied schema and returns `Promise<Row[]>` (`TypedRow[]` when no generic is
+given). Accepts positional `$N` parameters in the same third-argument position
+as `query()`, so typed rows and parameter binding compose. The legacy
+`queryTyped(q, schema, { signal })` form still works. See Schema-coerced rows
+above.
+
+### `client.queryObjects<Row>(query, params?, opts?)`
+
+Runs PowQL on the lossless native surface and returns object rows keyed by
+column name (`Promise<Row[]>`, default `NativeRow[]`). No schema needed.
+Parameters and abort options match `query()`. Throws
+`PowDBError(code="query_failed")` if the result is not rows-shaped.
+
+### `client.querySqlObjects<Row>(query, opts?)`
+
+SQL counterpart of `queryObjects`. The SQL path cannot bind parameters: build
+statements with the `sql` tagged template (see SQL composition above).
 
 ### `client.execScript(script, opts?)`
 
@@ -655,6 +728,10 @@ Getters: `size`, `idle`, `closed`.
 - `ident(name)` — wrap a string so `powql` treats it as an identifier
 - `escapeLiteral(value)` — render a JS value as a PowQL literal
 - `escapeIdent(name)` — validate an identifier (throws `TypeError` on invalid)
+- `sql`: tagged template for the SQL frontend; escapes literals, validates identifiers
+- `sqlIdent(name)`: wrap a string so `sql` treats it as a SQL identifier
+- `escapeSqlLiteral(value)`: render a JS value as a PowDB SQL literal
+- `escapeSqlIdent(name)`: validate a SQL identifier (throws `TypeError` on invalid)
 - `splitStatements(script)` — the statement-aware script splitter used by `execScript`
 
 ## Limits
@@ -664,6 +741,11 @@ The client enforces the same frame limits as the server and throws on violation:
 - `MAX_PAYLOAD_SIZE` — 64 MiB per frame
 - `MAX_ROWS` — 10,000,000 rows per result
 - `MAX_COLUMNS` — 4,096 columns per result
+- `MAX_RESULT_CELLS`: 2,000,000 cells (rows x columns) per result frame. This
+  caps how much heap a server-declared result shape can force the client to
+  allocate: a cell is only 4 bytes on the wire but costs far more as a JS
+  value, so without the cap a ~40 MB frame could expand to roughly 1.9 GB. Page
+  larger results with `limit`/`offset`.
 
 ## Requirements
 

package/dist/cjs/escape.d.ts

@@ -52,3 +52,65 @@ export declare function escapeLiteral(value: string | number | bigint | boolean
  *     const q = powql`insert ${ident(table)} { name := ${userName} }`;
  */
 export declare function powql(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * SQL composition helpers for PowDB's SQL frontend.
+ *
+ * READ THIS FIRST. PowDB's SQL surface has NO parameter binding on any wire
+ * frame: `querySql`/`querySqlNative` take a statement and nothing else, and
+ * there is no `QuerySqlParams` message. The PowQL surface does have real `$N`
+ * binding (`client.query(q, [values])`), where the server substitutes a literal
+ * TOKEN and injection-shaped input is inert.
+ *
+ * So: **prefer PowQL with `$N` parameters for anything built from untrusted
+ * input.** These helpers exist because the SQL path would otherwise leave
+ * string concatenation as the only option, which is strictly worse. They escape
+ * correctly for PowDB's own SQL lexer (`crates/query/src/sql.rs`), but escaping
+ * is a weaker guarantee than binding: it depends on the value landing in a
+ * string/number position, and it cannot make an identifier or a keyword safe.
+ *
+ * PowDB SQL string rules (verified against `lex_sql` in `crates/query/src/sql.rs`):
+ *   - Strings are delimited by `'`.
+ *   - `''` inside a single-quoted string is a literal `'`.
+ *   - A backslash also escapes the next character (`\n`, `\t`, and `\X` → `X`),
+ *     which standard SQL does NOT do, so a literal backslash must be doubled.
+ *   - `"` also opens a string in this lexer, so double quotes cannot be used to
+ *     quote an identifier. Identifiers are therefore validated, never quoted.
+ */
+/**
+ * Render a JS value as a PowDB SQL literal. Same accepted types as
+ * {@link escapeLiteral}: `string`, `number`, `bigint`, `boolean`, `null`.
+ *
+ * - string → `'...'` with `\` doubled and `'` doubled
+ * - number → decimal; rejects `NaN`/`±Infinity`
+ * - bigint → decimal digits
+ * - boolean → `true` / `false`
+ * - null → `null`
+ */
+export declare function escapeSqlLiteral(value: string | number | bigint | boolean | null): string;
+/**
+ * Validate a SQL identifier (table, column, alias). Returns it unchanged on
+ * success and throws `TypeError` otherwise.
+ *
+ * Identifiers are validated rather than quoted because PowDB's SQL lexer reads
+ * `"..."` as a string literal, so there is no identifier-quoting syntax to fall
+ * back on. Only `^[A-Za-z_][A-Za-z0-9_]*$` is accepted.
+ */
+export declare function escapeSqlIdent(name: string): string;
+/** Wrapper marking a string as a SQL identifier for the `sql` tagged template. */
+export declare class SqlIdent {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Factory for {@link SqlIdent}. */
+export declare function sqlIdent(name: string): SqlIdent;
+/**
+ * Tagged template for SQL composition. Interpolated values are escaped as SQL
+ * literals; wrap one in `sqlIdent(...)` to interpolate an identifier.
+ *
+ *     const q = sql`SELECT name FROM ${sqlIdent(table)} WHERE name = ${userName}`;
+ *     await client.querySql(q);
+ *
+ * Escaping, not binding: see the section note above, and prefer PowQL's `$N`
+ * parameters when the input is untrusted.
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): string;

package/dist/cjs/escape.js

@@ -20,11 +20,15 @@
  *     literal backslash must be `\\` (otherwise it would swallow the next char).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PowqlIdent = void 0;
+exports.SqlIdent = exports.PowqlIdent = void 0;
 exports.ident = ident;
 exports.escapeIdent = escapeIdent;
 exports.escapeLiteral = escapeLiteral;
 exports.powql = powql;
+exports.escapeSqlLiteral = escapeSqlLiteral;
+exports.escapeSqlIdent = escapeSqlIdent;
+exports.sqlIdent = sqlIdent;
+exports.sql = sql;
 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 {
@@ -108,8 +112,131 @@ function powql(strings, ...values) {
     return out;
 }
 // ──────────────────────────────────────────────────────────
+// SQL frontend
+// ──────────────────────────────────────────────────────────
+/**
+ * SQL composition helpers for PowDB's SQL frontend.
+ *
+ * READ THIS FIRST. PowDB's SQL surface has NO parameter binding on any wire
+ * frame: `querySql`/`querySqlNative` take a statement and nothing else, and
+ * there is no `QuerySqlParams` message. The PowQL surface does have real `$N`
+ * binding (`client.query(q, [values])`), where the server substitutes a literal
+ * TOKEN and injection-shaped input is inert.
+ *
+ * So: **prefer PowQL with `$N` parameters for anything built from untrusted
+ * input.** These helpers exist because the SQL path would otherwise leave
+ * string concatenation as the only option, which is strictly worse. They escape
+ * correctly for PowDB's own SQL lexer (`crates/query/src/sql.rs`), but escaping
+ * is a weaker guarantee than binding: it depends on the value landing in a
+ * string/number position, and it cannot make an identifier or a keyword safe.
+ *
+ * PowDB SQL string rules (verified against `lex_sql` in `crates/query/src/sql.rs`):
+ *   - Strings are delimited by `'`.
+ *   - `''` inside a single-quoted string is a literal `'`.
+ *   - A backslash also escapes the next character (`\n`, `\t`, and `\X` → `X`),
+ *     which standard SQL does NOT do, so a literal backslash must be doubled.
+ *   - `"` also opens a string in this lexer, so double quotes cannot be used to
+ *     quote an identifier. Identifiers are therefore validated, never quoted.
+ */
+/**
+ * Render a JS value as a PowDB SQL literal. Same accepted types as
+ * {@link escapeLiteral}: `string`, `number`, `bigint`, `boolean`, `null`.
+ *
+ * - string → `'...'` with `\` doubled and `'` doubled
+ * - number → decimal; rejects `NaN`/`±Infinity`
+ * - bigint → decimal digits
+ * - boolean → `true` / `false`
+ * - null → `null`
+ */
+function escapeSqlLiteral(value) {
+    if (value === null)
+        return "null";
+    const t = typeof value;
+    if (t === "string") {
+        // Backslash first: this lexer treats `\` as an escape inside strings, so a
+        // lone backslash would otherwise swallow the quote doubling that follows.
+        const escaped = value
+            .replace(/\\/g, "\\\\")
+            .replace(/'/g, "''");
+        return `'${escaped}'`;
+    }
+    if (t === "number") {
+        const n = value;
+        if (!Number.isFinite(n)) {
+            throw new TypeError(`escapeSqlLiteral: non-finite number ${String(n)} cannot be represented as a SQL literal`);
+        }
+        return String(n);
+    }
+    if (t === "bigint") {
+        return value.toString(10);
+    }
+    if (t === "boolean") {
+        return value ? "true" : "false";
+    }
+    throw new TypeError(`escapeSqlLiteral: unsupported type ${describe(value)}`);
+}
+/**
+ * Validate a SQL identifier (table, column, alias). Returns it unchanged on
+ * success and throws `TypeError` otherwise.
+ *
+ * Identifiers are validated rather than quoted because PowDB's SQL lexer reads
+ * `"..."` as a string literal, so there is no identifier-quoting syntax to fall
+ * back on. Only `^[A-Za-z_][A-Za-z0-9_]*$` is accepted.
+ */
+function escapeSqlIdent(name) {
+    if (typeof name !== "string") {
+        throw new TypeError(`escapeSqlIdent: expected string, got ${typeof name}`);
+    }
+    if (name.length === 0) {
+        throw new TypeError("escapeSqlIdent: identifier must not be empty");
+    }
+    if (!IDENT_RE.test(name)) {
+        throw new TypeError(`escapeSqlIdent: invalid identifier ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`);
+    }
+    return name;
+}
+/** Wrapper marking a string as a SQL identifier for the `sql` tagged template. */
+class SqlIdent {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+exports.SqlIdent = SqlIdent;
+/** Factory for {@link SqlIdent}. */
+function sqlIdent(name) {
+    return new SqlIdent(name);
+}
+/**
+ * Tagged template for SQL composition. Interpolated values are escaped as SQL
+ * literals; wrap one in `sqlIdent(...)` to interpolate an identifier.
+ *
+ *     const q = sql`SELECT name FROM ${sqlIdent(table)} WHERE name = ${userName}`;
+ *     await client.querySql(q);
+ *
+ * Escaping, not binding: see the section note above, and prefer PowQL's `$N`
+ * parameters when the input is untrusted.
+ */
+function sql(strings, ...values) {
+    let out = strings[0] ?? "";
+    for (let i = 0; i < values.length; i++) {
+        out += renderSqlInterpolation(values[i]);
+        out += strings[i + 1] ?? "";
+    }
+    return out;
+}
+// ──────────────────────────────────────────────────────────
 // internals
 // ──────────────────────────────────────────────────────────
+function renderSqlInterpolation(value) {
+    if (value instanceof SqlIdent) {
+        return escapeSqlIdent(value.name);
+    }
+    if (value instanceof PowqlIdent) {
+        throw new TypeError("sql: use sqlIdent(...) for SQL identifiers, not ident(...)");
+    }
+    return escapeSqlLiteral(value);
+}
 function renderInterpolation(value) {
     if (value instanceof PowqlIdent) {
         return escapeIdent(value.name);

package/dist/cjs/index.d.ts

@@ -19,7 +19,7 @@ import { EventEmitter } from "node:events";
 import { type NativeJson, type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus, type WireValue } from "./protocol.js";
 import { type TypedRow, type TypedSchema } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export declare const CLIENT_VERSION = "0.19.1";
+export declare const CLIENT_VERSION = "0.20.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -57,6 +57,11 @@ export type QueryResult = {
 export type { NativeJson } from "./protocol.js";
 /** A value returned by the lossless native wire surface. */
 export type NativeValue = null | number | bigint | boolean | string | Uint8Array | NativeJson;
+/**
+ * One row of a native (lossless) result, keyed by column name. The default row
+ * type of {@link Client.queryObjects} when no generic is supplied.
+ */
+export type NativeRow = Record<string, NativeValue>;
 export type NativeQueryResult = {
     kind: "rows";
     columns: string[];
@@ -382,13 +387,62 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * 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.
+     * Returns `Row[]`, an array of objects keyed by column name (`TypedRow[]`
+     * when no generic is supplied). The generic is an unchecked assertion about
+     * the query's shape: the schema drives coercion, nothing validates the type.
+     * Positional `$N` parameters are accepted in the same position as
+     * {@link query}, so typed rows and injection-safe binding compose.
+     *
+     * This is the LEGACY stringly-typed path plus schema coercion. For lossless
+     * object rows with no schema at all, use {@link queryObjects}.
+     *
      * Throws `PowDBError(code="query_failed")` if the query is not a
      * rows-returning query.
      */
-    queryTyped(query: string, schema: TypedSchema, opts?: {
+    queryTyped<Row extends TypedRow = TypedRow>(query: string, schema: TypedSchema, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<Row[]>;
+    /**
+     * Run PowQL on the LOSSLESS native wire surface and return object rows keyed
+     * by column name.
+     *
+     * This is {@link queryNative} plus the row-to-object step, so no schema is
+     * needed: the server states each cell's type, bytes stay bytes, JSON stays
+     * recursive data, and out-of-range integers stay `bigint`. Contrast with
+     * {@link queryTyped}, which coerces the legacy stringly-typed path using a
+     * caller-supplied schema.
+     *
+     *     interface User { name: string; age: number }
+     *     const users = await client.queryObjects<User>(
+     *       "User filter .age > $1 { .name, .age }",
+     *       [25],
+     *     );
+     *
+     * The generic is an unchecked assertion about the query's shape, exactly like
+     * a SQL driver's row type: nothing validates it at runtime. Duplicate column
+     * names collapse (last one wins), so alias them in the projection.
+     *
+     * Throws `PowDBError(code="query_failed")` if the query is not rows-returning.
+     */
+    queryObjects<Row = NativeRow>(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<Row[]>;
+    /**
+     * SQL counterpart of {@link queryObjects}: runs SQL on the lossless native
+     * surface and returns object rows keyed by column name.
+     *
+     * The SQL frontend cannot bind parameters on any wire frame yet, so build SQL
+     * with {@link escapeSqlLiteral} / {@link sqlIdent} (or the `sql` tagged
+     * template) rather than string concatenation. For parameter binding, use the
+     * PowQL surface, which has real `$N` placeholders.
+     */
+    querySqlObjects<Row = NativeRow>(query: string, opts?: {
         signal?: AbortSignal;
-    }): Promise<TypedRow[]>;
+    }): Promise<Row[]>;
     /**
      * Execute a multi-statement PowQL script on this connection, pipelined.
      *
@@ -472,8 +526,8 @@ export declare class Client extends EventEmitter<ClientEvents> {
 }
 export { encode, tryDecode } from "./protocol.js";
 export type { Message, SyncRepairAction, WireValue, WireParam, WireRetainedUnit, WireSyncStatus, } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
-export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_RESULT_CELLS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
+export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, escapeSqlLiteral, escapeSqlIdent, sqlIdent, sql, SqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";
 export { splitStatements } from "./script.js";

package/dist/cjs/index.js

@@ -49,7 +49,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.WIRE_ERROR_CLASS = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = exports.errorCodeForWireClass = 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.SUPPORTED_CATALOG_VERSION = exports.CLIENT_VERSION = void 0;
+exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.WIRE_ERROR_CLASS = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = exports.errorCodeForWireClass = exports.splitStatements = exports.Pool = exports.SqlIdent = exports.sql = exports.sqlIdent = exports.escapeSqlIdent = exports.escapeSqlLiteral = 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_RESULT_CELLS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.tryDecode = exports.encode = exports.Client = exports.SUPPORTED_CATALOG_VERSION = exports.CLIENT_VERSION = void 0;
 exports.assertServerCatalogVersionSupported = assertServerCatalogVersionSupported;
 const net = __importStar(require("node:net"));
 const tls = __importStar(require("node:tls"));
@@ -59,7 +59,7 @@ 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.19.1";
+exports.CLIENT_VERSION = "0.20.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -163,6 +163,24 @@ function nativeQueryResult(reply) {
             throw new errors_js_1.PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
     }
 }
+/**
+ * Turn a rows-shaped native result into object rows keyed by column name.
+ * Non-rows results are a caller mistake, not a server error, so they raise the
+ * same `query_failed` code `queryTyped` uses.
+ */
+function nativeRowObjects(result, method) {
+    if (result.kind !== "rows") {
+        throw new errors_js_1.PowDBError(`${method}: expected rows result, got ${result.kind}`, "query_failed");
+    }
+    const { columns, rows } = result;
+    return rows.map((values) => {
+        const row = {};
+        for (let i = 0; i < columns.length; i++) {
+            row[columns[i]] = values[i] ?? null;
+        }
+        return row;
+    });
+}
 function rawNativeQueryResult(reply) {
     switch (reply.type) {
         case "ResultRowsNative":
@@ -710,17 +728,74 @@ class Client extends node_events_1.EventEmitter {
      * 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.
+     * Returns `Row[]`, an array of objects keyed by column name (`TypedRow[]`
+     * when no generic is supplied). The generic is an unchecked assertion about
+     * the query's shape: the schema drives coercion, nothing validates the type.
+     * Positional `$N` parameters are accepted in the same position as
+     * {@link query}, so typed rows and injection-safe binding compose.
+     *
+     * This is the LEGACY stringly-typed path plus schema coercion. For lossless
+     * object rows with no schema at all, use {@link queryObjects}.
+     *
      * 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);
+    async queryTyped(query, schema, paramsOrOpts, maybeOpts) {
+        // Same overload disambiguation as `query`, so typed rows and `$N`
+        // parameter binding are usable together:
+        //   queryTyped(q, schema)                  no params, no opts
+        //   queryTyped(q, schema, opts)            legacy 3-arg opts form
+        //   queryTyped(q, schema, params)          positional $N parameters
+        //   queryTyped(q, schema, params, opts)    params plus opts
+        const result = Array.isArray(paramsOrOpts)
+            ? await this.query(query, paramsOrOpts, maybeOpts)
+            : await this.query(query, paramsOrOpts);
         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);
     }
+    /**
+     * Run PowQL on the LOSSLESS native wire surface and return object rows keyed
+     * by column name.
+     *
+     * This is {@link queryNative} plus the row-to-object step, so no schema is
+     * needed: the server states each cell's type, bytes stay bytes, JSON stays
+     * recursive data, and out-of-range integers stay `bigint`. Contrast with
+     * {@link queryTyped}, which coerces the legacy stringly-typed path using a
+     * caller-supplied schema.
+     *
+     *     interface User { name: string; age: number }
+     *     const users = await client.queryObjects<User>(
+     *       "User filter .age > $1 { .name, .age }",
+     *       [25],
+     *     );
+     *
+     * The generic is an unchecked assertion about the query's shape, exactly like
+     * a SQL driver's row type: nothing validates it at runtime. Duplicate column
+     * names collapse (last one wins), so alias them in the projection.
+     *
+     * Throws `PowDBError(code="query_failed")` if the query is not rows-returning.
+     */
+    async queryObjects(query, paramsOrOpts, maybeOpts) {
+        const result = Array.isArray(paramsOrOpts)
+            ? await this.queryNative(query, paramsOrOpts, maybeOpts)
+            : await this.queryNative(query, paramsOrOpts);
+        return nativeRowObjects(result, "queryObjects");
+    }
+    /**
+     * SQL counterpart of {@link queryObjects}: runs SQL on the lossless native
+     * surface and returns object rows keyed by column name.
+     *
+     * The SQL frontend cannot bind parameters on any wire frame yet, so build SQL
+     * with {@link escapeSqlLiteral} / {@link sqlIdent} (or the `sql` tagged
+     * template) rather than string concatenation. For parameter binding, use the
+     * PowQL surface, which has real `$N` placeholders.
+     */
+    async querySqlObjects(query, opts) {
+        const result = await this.querySqlNative(query, opts);
+        return nativeRowObjects(result, "querySqlObjects");
+    }
     async execScript(script, opts) {
         const statements = (0, script_js_1.splitStatements)(script);
         const continueOnError = opts?.continueOnError === true;
@@ -1216,6 +1291,7 @@ Object.defineProperty(exports, "tryDecode", { enumerable: true, get: function ()
 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_RESULT_CELLS", { enumerable: true, get: function () { return protocol_js_3.MAX_RESULT_CELLS; } });
 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; } });
@@ -1227,6 +1303,11 @@ Object.defineProperty(exports, "escapeIdent", { enumerable: true, get: function
 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; } });
+Object.defineProperty(exports, "escapeSqlLiteral", { enumerable: true, get: function () { return escape_js_1.escapeSqlLiteral; } });
+Object.defineProperty(exports, "escapeSqlIdent", { enumerable: true, get: function () { return escape_js_1.escapeSqlIdent; } });
+Object.defineProperty(exports, "sqlIdent", { enumerable: true, get: function () { return escape_js_1.sqlIdent; } });
+Object.defineProperty(exports, "sql", { enumerable: true, get: function () { return escape_js_1.sql; } });
+Object.defineProperty(exports, "SqlIdent", { enumerable: true, get: function () { return escape_js_1.SqlIdent; } });
 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");

package/dist/cjs/protocol.d.ts

@@ -43,6 +43,23 @@ 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 decoded cells (rows x columns) in one result frame.
+ *
+ * MAX_ROWS and the per-frame byte-shape check are not enough on their own: a
+ * cell costs 4 bytes on the wire at minimum (an empty string's length prefix)
+ * but far more than that in JS heap, since every row is its own array. A
+ * hostile or MITM'd server could therefore declare 10M single-column rows,
+ * back them with a ~40 MB frame of empty cells, and make the client allocate
+ * roughly 1.9 GB (measured) before anything downstream could react. The
+ * default transport is plaintext, so this is reachable by anyone on the path.
+ *
+ * This cap bounds that allocation absolutely instead of trusting the declared
+ * count: a result frame can never expand past a few hundred MB whatever the
+ * server claims. Results genuinely larger than this must be paged with
+ * `limit`/`offset`.
+ */
+export declare const MAX_RESULT_CELLS = 2000000;
 /** Maximum number of bound parameters in a QueryWithParams message. */
 export declare const MAX_PARAMS = 4096;
 /** Maximum retained units accepted in one sync pull result. */

package/dist/cjs/protocol.js

@@ -8,7 +8,7 @@
  * This mirrors crates/server/src/protocol.rs — keep them in sync.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.MSG_RESULT_SCALAR_NATIVE = exports.MSG_RESULT_ROWS_NATIVE = exports.MSG_QUERY_SQL_NATIVE = exports.MSG_QUERY_PARAMS_NATIVE = exports.MSG_QUERY_NATIVE = exports.MSG_PONG = exports.MSG_PING = exports.MSG_DISCONNECT = exports.MSG_RESULT_MSG = exports.MSG_ERROR = exports.MSG_RESULT_OK = exports.MSG_RESULT_SCALAR = exports.MSG_RESULT_ROWS = exports.MSG_SYNC_ACK_RESULT = exports.MSG_SYNC_PULL_RESULT = exports.MSG_SYNC_STATUS_RESULT = exports.MSG_SYNC_ACK = exports.MSG_SYNC_PULL = exports.MSG_SYNC_STATUS = exports.MSG_QUERY_SQL = exports.MSG_QUERY_PARAMS = exports.MSG_QUERY = exports.MSG_CONNECT_OK = exports.MSG_CONNECT = void 0;
+exports.MAX_SYNC_PULL_BYTES = exports.MAX_SYNC_PULL_UNITS = exports.MAX_SYNC_UNITS = exports.MAX_PARAMS = exports.MAX_RESULT_CELLS = exports.MAX_COLUMNS = exports.MAX_ROWS = exports.MAX_PAYLOAD_SIZE = exports.MSG_RESULT_SCALAR_NATIVE = exports.MSG_RESULT_ROWS_NATIVE = exports.MSG_QUERY_SQL_NATIVE = exports.MSG_QUERY_PARAMS_NATIVE = exports.MSG_QUERY_NATIVE = exports.MSG_PONG = exports.MSG_PING = exports.MSG_DISCONNECT = exports.MSG_RESULT_MSG = exports.MSG_ERROR = exports.MSG_RESULT_OK = exports.MSG_RESULT_SCALAR = exports.MSG_RESULT_ROWS = exports.MSG_SYNC_ACK_RESULT = exports.MSG_SYNC_PULL_RESULT = exports.MSG_SYNC_STATUS_RESULT = exports.MSG_SYNC_ACK = exports.MSG_SYNC_PULL = exports.MSG_SYNC_STATUS = exports.MSG_QUERY_SQL = exports.MSG_QUERY_PARAMS = exports.MSG_QUERY = exports.MSG_CONNECT_OK = exports.MSG_CONNECT = void 0;
 exports.encode = encode;
 exports.tryDecode = tryDecode;
 exports.MSG_CONNECT = 0x01;
@@ -49,6 +49,29 @@ exports.MAX_PAYLOAD_SIZE = 64 * 1024 * 1024;
 exports.MAX_ROWS = 10_000_000;
 /** Maximum number of columns allowed in a result set. */
 exports.MAX_COLUMNS = 4096;
+/**
+ * Maximum number of decoded cells (rows x columns) in one result frame.
+ *
+ * MAX_ROWS and the per-frame byte-shape check are not enough on their own: a
+ * cell costs 4 bytes on the wire at minimum (an empty string's length prefix)
+ * but far more than that in JS heap, since every row is its own array. A
+ * hostile or MITM'd server could therefore declare 10M single-column rows,
+ * back them with a ~40 MB frame of empty cells, and make the client allocate
+ * roughly 1.9 GB (measured) before anything downstream could react. The
+ * default transport is plaintext, so this is reachable by anyone on the path.
+ *
+ * This cap bounds that allocation absolutely instead of trusting the declared
+ * count: a result frame can never expand past a few hundred MB whatever the
+ * server claims. Results genuinely larger than this must be paged with
+ * `limit`/`offset`.
+ */
+exports.MAX_RESULT_CELLS = 2_000_000;
+/** Reject a declared result shape whose cell count exceeds MAX_RESULT_CELLS. */
+function checkResultCells(rowCount, colCount) {
+    if (rowCount * colCount > exports.MAX_RESULT_CELLS) {
+        throw new Error(`result too large: ${rowCount * colCount} cells (${rowCount} rows x ${colCount} columns, max ${exports.MAX_RESULT_CELLS})`);
+    }
+}
 /** Maximum number of bound parameters in a QueryWithParams message. */
 exports.MAX_PARAMS = 4096;
 /** Maximum retained units accepted in one sync pull result. */
@@ -490,6 +513,7 @@ function decodePayload(msgType, payload) {
             if (remaining < minRowBytes) {
                 throw new Error(`row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
             }
+            checkResultCells(rowCount, colCount);
             const rows = [];
             for (let r = 0; r < rowCount; r++) {
                 const row = [];
@@ -522,6 +546,7 @@ function decodePayload(msgType, payload) {
             if (BigInt(payload.length - cursor.pos) < minimumBytes) {
                 throw new Error(`native row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
             }
+            checkResultCells(rowCount, colCount);
             const rows = [];
             for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
                 const row = [];

package/dist/escape.d.ts

@@ -52,3 +52,65 @@ export declare function escapeLiteral(value: string | number | bigint | boolean
  *     const q = powql`insert ${ident(table)} { name := ${userName} }`;
  */
 export declare function powql(strings: TemplateStringsArray, ...values: unknown[]): string;
+/**
+ * SQL composition helpers for PowDB's SQL frontend.
+ *
+ * READ THIS FIRST. PowDB's SQL surface has NO parameter binding on any wire
+ * frame: `querySql`/`querySqlNative` take a statement and nothing else, and
+ * there is no `QuerySqlParams` message. The PowQL surface does have real `$N`
+ * binding (`client.query(q, [values])`), where the server substitutes a literal
+ * TOKEN and injection-shaped input is inert.
+ *
+ * So: **prefer PowQL with `$N` parameters for anything built from untrusted
+ * input.** These helpers exist because the SQL path would otherwise leave
+ * string concatenation as the only option, which is strictly worse. They escape
+ * correctly for PowDB's own SQL lexer (`crates/query/src/sql.rs`), but escaping
+ * is a weaker guarantee than binding: it depends on the value landing in a
+ * string/number position, and it cannot make an identifier or a keyword safe.
+ *
+ * PowDB SQL string rules (verified against `lex_sql` in `crates/query/src/sql.rs`):
+ *   - Strings are delimited by `'`.
+ *   - `''` inside a single-quoted string is a literal `'`.
+ *   - A backslash also escapes the next character (`\n`, `\t`, and `\X` → `X`),
+ *     which standard SQL does NOT do, so a literal backslash must be doubled.
+ *   - `"` also opens a string in this lexer, so double quotes cannot be used to
+ *     quote an identifier. Identifiers are therefore validated, never quoted.
+ */
+/**
+ * Render a JS value as a PowDB SQL literal. Same accepted types as
+ * {@link escapeLiteral}: `string`, `number`, `bigint`, `boolean`, `null`.
+ *
+ * - string → `'...'` with `\` doubled and `'` doubled
+ * - number → decimal; rejects `NaN`/`±Infinity`
+ * - bigint → decimal digits
+ * - boolean → `true` / `false`
+ * - null → `null`
+ */
+export declare function escapeSqlLiteral(value: string | number | bigint | boolean | null): string;
+/**
+ * Validate a SQL identifier (table, column, alias). Returns it unchanged on
+ * success and throws `TypeError` otherwise.
+ *
+ * Identifiers are validated rather than quoted because PowDB's SQL lexer reads
+ * `"..."` as a string literal, so there is no identifier-quoting syntax to fall
+ * back on. Only `^[A-Za-z_][A-Za-z0-9_]*$` is accepted.
+ */
+export declare function escapeSqlIdent(name: string): string;
+/** Wrapper marking a string as a SQL identifier for the `sql` tagged template. */
+export declare class SqlIdent {
+    readonly name: string;
+    constructor(name: string);
+}
+/** Factory for {@link SqlIdent}. */
+export declare function sqlIdent(name: string): SqlIdent;
+/**
+ * Tagged template for SQL composition. Interpolated values are escaped as SQL
+ * literals; wrap one in `sqlIdent(...)` to interpolate an identifier.
+ *
+ *     const q = sql`SELECT name FROM ${sqlIdent(table)} WHERE name = ${userName}`;
+ *     await client.querySql(q);
+ *
+ * Escaping, not binding: see the section note above, and prefer PowQL's `$N`
+ * parameters when the input is untrusted.
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): string;

package/dist/escape.js

@@ -100,8 +100,130 @@ export function powql(strings, ...values) {
     return out;
 }
 // ──────────────────────────────────────────────────────────
+// SQL frontend
+// ──────────────────────────────────────────────────────────
+/**
+ * SQL composition helpers for PowDB's SQL frontend.
+ *
+ * READ THIS FIRST. PowDB's SQL surface has NO parameter binding on any wire
+ * frame: `querySql`/`querySqlNative` take a statement and nothing else, and
+ * there is no `QuerySqlParams` message. The PowQL surface does have real `$N`
+ * binding (`client.query(q, [values])`), where the server substitutes a literal
+ * TOKEN and injection-shaped input is inert.
+ *
+ * So: **prefer PowQL with `$N` parameters for anything built from untrusted
+ * input.** These helpers exist because the SQL path would otherwise leave
+ * string concatenation as the only option, which is strictly worse. They escape
+ * correctly for PowDB's own SQL lexer (`crates/query/src/sql.rs`), but escaping
+ * is a weaker guarantee than binding: it depends on the value landing in a
+ * string/number position, and it cannot make an identifier or a keyword safe.
+ *
+ * PowDB SQL string rules (verified against `lex_sql` in `crates/query/src/sql.rs`):
+ *   - Strings are delimited by `'`.
+ *   - `''` inside a single-quoted string is a literal `'`.
+ *   - A backslash also escapes the next character (`\n`, `\t`, and `\X` → `X`),
+ *     which standard SQL does NOT do, so a literal backslash must be doubled.
+ *   - `"` also opens a string in this lexer, so double quotes cannot be used to
+ *     quote an identifier. Identifiers are therefore validated, never quoted.
+ */
+/**
+ * Render a JS value as a PowDB SQL literal. Same accepted types as
+ * {@link escapeLiteral}: `string`, `number`, `bigint`, `boolean`, `null`.
+ *
+ * - string → `'...'` with `\` doubled and `'` doubled
+ * - number → decimal; rejects `NaN`/`±Infinity`
+ * - bigint → decimal digits
+ * - boolean → `true` / `false`
+ * - null → `null`
+ */
+export function escapeSqlLiteral(value) {
+    if (value === null)
+        return "null";
+    const t = typeof value;
+    if (t === "string") {
+        // Backslash first: this lexer treats `\` as an escape inside strings, so a
+        // lone backslash would otherwise swallow the quote doubling that follows.
+        const escaped = value
+            .replace(/\\/g, "\\\\")
+            .replace(/'/g, "''");
+        return `'${escaped}'`;
+    }
+    if (t === "number") {
+        const n = value;
+        if (!Number.isFinite(n)) {
+            throw new TypeError(`escapeSqlLiteral: non-finite number ${String(n)} cannot be represented as a SQL literal`);
+        }
+        return String(n);
+    }
+    if (t === "bigint") {
+        return value.toString(10);
+    }
+    if (t === "boolean") {
+        return value ? "true" : "false";
+    }
+    throw new TypeError(`escapeSqlLiteral: unsupported type ${describe(value)}`);
+}
+/**
+ * Validate a SQL identifier (table, column, alias). Returns it unchanged on
+ * success and throws `TypeError` otherwise.
+ *
+ * Identifiers are validated rather than quoted because PowDB's SQL lexer reads
+ * `"..."` as a string literal, so there is no identifier-quoting syntax to fall
+ * back on. Only `^[A-Za-z_][A-Za-z0-9_]*$` is accepted.
+ */
+export function escapeSqlIdent(name) {
+    if (typeof name !== "string") {
+        throw new TypeError(`escapeSqlIdent: expected string, got ${typeof name}`);
+    }
+    if (name.length === 0) {
+        throw new TypeError("escapeSqlIdent: identifier must not be empty");
+    }
+    if (!IDENT_RE.test(name)) {
+        throw new TypeError(`escapeSqlIdent: invalid identifier ${JSON.stringify(name)} (must match /^[A-Za-z_][A-Za-z0-9_]*$/)`);
+    }
+    return name;
+}
+/** Wrapper marking a string as a SQL identifier for the `sql` tagged template. */
+export class SqlIdent {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+/** Factory for {@link SqlIdent}. */
+export function sqlIdent(name) {
+    return new SqlIdent(name);
+}
+/**
+ * Tagged template for SQL composition. Interpolated values are escaped as SQL
+ * literals; wrap one in `sqlIdent(...)` to interpolate an identifier.
+ *
+ *     const q = sql`SELECT name FROM ${sqlIdent(table)} WHERE name = ${userName}`;
+ *     await client.querySql(q);
+ *
+ * Escaping, not binding: see the section note above, and prefer PowQL's `$N`
+ * parameters when the input is untrusted.
+ */
+export function sql(strings, ...values) {
+    let out = strings[0] ?? "";
+    for (let i = 0; i < values.length; i++) {
+        out += renderSqlInterpolation(values[i]);
+        out += strings[i + 1] ?? "";
+    }
+    return out;
+}
+// ──────────────────────────────────────────────────────────
 // internals
 // ──────────────────────────────────────────────────────────
+function renderSqlInterpolation(value) {
+    if (value instanceof SqlIdent) {
+        return escapeSqlIdent(value.name);
+    }
+    if (value instanceof PowqlIdent) {
+        throw new TypeError("sql: use sqlIdent(...) for SQL identifiers, not ident(...)");
+    }
+    return escapeSqlLiteral(value);
+}
 function renderInterpolation(value) {
     if (value instanceof PowqlIdent) {
         return escapeIdent(value.name);

package/dist/index.d.ts

@@ -19,7 +19,7 @@ import { EventEmitter } from "node:events";
 import { type NativeJson, type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus, type WireValue } from "./protocol.js";
 import { type TypedRow, type TypedSchema } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export declare const CLIENT_VERSION = "0.19.1";
+export declare const CLIENT_VERSION = "0.20.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -57,6 +57,11 @@ export type QueryResult = {
 export type { NativeJson } from "./protocol.js";
 /** A value returned by the lossless native wire surface. */
 export type NativeValue = null | number | bigint | boolean | string | Uint8Array | NativeJson;
+/**
+ * One row of a native (lossless) result, keyed by column name. The default row
+ * type of {@link Client.queryObjects} when no generic is supplied.
+ */
+export type NativeRow = Record<string, NativeValue>;
 export type NativeQueryResult = {
     kind: "rows";
     columns: string[];
@@ -382,13 +387,62 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * 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.
+     * Returns `Row[]`, an array of objects keyed by column name (`TypedRow[]`
+     * when no generic is supplied). The generic is an unchecked assertion about
+     * the query's shape: the schema drives coercion, nothing validates the type.
+     * Positional `$N` parameters are accepted in the same position as
+     * {@link query}, so typed rows and injection-safe binding compose.
+     *
+     * This is the LEGACY stringly-typed path plus schema coercion. For lossless
+     * object rows with no schema at all, use {@link queryObjects}.
+     *
      * Throws `PowDBError(code="query_failed")` if the query is not a
      * rows-returning query.
      */
-    queryTyped(query: string, schema: TypedSchema, opts?: {
+    queryTyped<Row extends TypedRow = TypedRow>(query: string, schema: TypedSchema, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<Row[]>;
+    /**
+     * Run PowQL on the LOSSLESS native wire surface and return object rows keyed
+     * by column name.
+     *
+     * This is {@link queryNative} plus the row-to-object step, so no schema is
+     * needed: the server states each cell's type, bytes stay bytes, JSON stays
+     * recursive data, and out-of-range integers stay `bigint`. Contrast with
+     * {@link queryTyped}, which coerces the legacy stringly-typed path using a
+     * caller-supplied schema.
+     *
+     *     interface User { name: string; age: number }
+     *     const users = await client.queryObjects<User>(
+     *       "User filter .age > $1 { .name, .age }",
+     *       [25],
+     *     );
+     *
+     * The generic is an unchecked assertion about the query's shape, exactly like
+     * a SQL driver's row type: nothing validates it at runtime. Duplicate column
+     * names collapse (last one wins), so alias them in the projection.
+     *
+     * Throws `PowDBError(code="query_failed")` if the query is not rows-returning.
+     */
+    queryObjects<Row = NativeRow>(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<Row[]>;
+    /**
+     * SQL counterpart of {@link queryObjects}: runs SQL on the lossless native
+     * surface and returns object rows keyed by column name.
+     *
+     * The SQL frontend cannot bind parameters on any wire frame yet, so build SQL
+     * with {@link escapeSqlLiteral} / {@link sqlIdent} (or the `sql` tagged
+     * template) rather than string concatenation. For parameter binding, use the
+     * PowQL surface, which has real `$N` placeholders.
+     */
+    querySqlObjects<Row = NativeRow>(query: string, opts?: {
         signal?: AbortSignal;
-    }): Promise<TypedRow[]>;
+    }): Promise<Row[]>;
     /**
      * Execute a multi-statement PowQL script on this connection, pipelined.
      *
@@ -472,8 +526,8 @@ export declare class Client extends EventEmitter<ClientEvents> {
 }
 export { encode, tryDecode } from "./protocol.js";
 export type { Message, SyncRepairAction, WireValue, WireParam, WireRetainedUnit, WireSyncStatus, } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
-export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_RESULT_CELLS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
+export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, escapeSqlLiteral, escapeSqlIdent, sqlIdent, sql, SqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export type { PoolOptions } from "./pool.js";
 export { splitStatements } from "./script.js";

package/dist/index.js

@@ -22,7 +22,7 @@ import { errorCodeForWireClass, isPowDBError, PowDBError, PowDBScriptError, } fr
 import { splitStatements } from "./script.js";
 import { coerceRows, } from "./typed.js";
 /** Client library version. Compared to the server's reported version. */
-export const CLIENT_VERSION = "0.19.1";
+export const CLIENT_VERSION = "0.20.0";
 /**
  * The maximum catalog format version this client can read. State this as the
  * `catalogVersion` in sync pull requests: the server accepts any replica whose
@@ -126,6 +126,24 @@ function nativeQueryResult(reply) {
             throw new PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
     }
 }
+/**
+ * Turn a rows-shaped native result into object rows keyed by column name.
+ * Non-rows results are a caller mistake, not a server error, so they raise the
+ * same `query_failed` code `queryTyped` uses.
+ */
+function nativeRowObjects(result, method) {
+    if (result.kind !== "rows") {
+        throw new PowDBError(`${method}: expected rows result, got ${result.kind}`, "query_failed");
+    }
+    const { columns, rows } = result;
+    return rows.map((values) => {
+        const row = {};
+        for (let i = 0; i < columns.length; i++) {
+            row[columns[i]] = values[i] ?? null;
+        }
+        return row;
+    });
+}
 function rawNativeQueryResult(reply) {
     switch (reply.type) {
         case "ResultRowsNative":
@@ -673,17 +691,74 @@ export class Client extends EventEmitter {
      * 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.
+     * Returns `Row[]`, an array of objects keyed by column name (`TypedRow[]`
+     * when no generic is supplied). The generic is an unchecked assertion about
+     * the query's shape: the schema drives coercion, nothing validates the type.
+     * Positional `$N` parameters are accepted in the same position as
+     * {@link query}, so typed rows and injection-safe binding compose.
+     *
+     * This is the LEGACY stringly-typed path plus schema coercion. For lossless
+     * object rows with no schema at all, use {@link queryObjects}.
+     *
      * 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);
+    async queryTyped(query, schema, paramsOrOpts, maybeOpts) {
+        // Same overload disambiguation as `query`, so typed rows and `$N`
+        // parameter binding are usable together:
+        //   queryTyped(q, schema)                  no params, no opts
+        //   queryTyped(q, schema, opts)            legacy 3-arg opts form
+        //   queryTyped(q, schema, params)          positional $N parameters
+        //   queryTyped(q, schema, params, opts)    params plus opts
+        const result = Array.isArray(paramsOrOpts)
+            ? await this.query(query, paramsOrOpts, maybeOpts)
+            : await this.query(query, paramsOrOpts);
         if (result.kind !== "rows") {
             throw new PowDBError(`queryTyped: expected rows result, got ${result.kind}`, "query_failed");
         }
         return coerceRows(result.columns, result.rows, schema);
     }
+    /**
+     * Run PowQL on the LOSSLESS native wire surface and return object rows keyed
+     * by column name.
+     *
+     * This is {@link queryNative} plus the row-to-object step, so no schema is
+     * needed: the server states each cell's type, bytes stay bytes, JSON stays
+     * recursive data, and out-of-range integers stay `bigint`. Contrast with
+     * {@link queryTyped}, which coerces the legacy stringly-typed path using a
+     * caller-supplied schema.
+     *
+     *     interface User { name: string; age: number }
+     *     const users = await client.queryObjects<User>(
+     *       "User filter .age > $1 { .name, .age }",
+     *       [25],
+     *     );
+     *
+     * The generic is an unchecked assertion about the query's shape, exactly like
+     * a SQL driver's row type: nothing validates it at runtime. Duplicate column
+     * names collapse (last one wins), so alias them in the projection.
+     *
+     * Throws `PowDBError(code="query_failed")` if the query is not rows-returning.
+     */
+    async queryObjects(query, paramsOrOpts, maybeOpts) {
+        const result = Array.isArray(paramsOrOpts)
+            ? await this.queryNative(query, paramsOrOpts, maybeOpts)
+            : await this.queryNative(query, paramsOrOpts);
+        return nativeRowObjects(result, "queryObjects");
+    }
+    /**
+     * SQL counterpart of {@link queryObjects}: runs SQL on the lossless native
+     * surface and returns object rows keyed by column name.
+     *
+     * The SQL frontend cannot bind parameters on any wire frame yet, so build SQL
+     * with {@link escapeSqlLiteral} / {@link sqlIdent} (or the `sql` tagged
+     * template) rather than string concatenation. For parameter binding, use the
+     * PowQL surface, which has real `$N` placeholders.
+     */
+    async querySqlObjects(query, opts) {
+        const result = await this.querySqlNative(query, opts);
+        return nativeRowObjects(result, "querySqlObjects");
+    }
     async execScript(script, opts) {
         const statements = splitStatements(script);
         const continueOnError = opts?.continueOnError === true;
@@ -1173,8 +1248,8 @@ function openSocket(target, timeoutMs, tlsOpt) {
     });
 }
 export { encode, tryDecode } from "./protocol.js";
-export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
-export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, } from "./escape.js";
+export { MAX_PAYLOAD_SIZE, MAX_ROWS, MAX_RESULT_CELLS, MAX_COLUMNS, MAX_PARAMS, MAX_SYNC_UNITS, MAX_SYNC_PULL_UNITS, MAX_SYNC_PULL_BYTES, } from "./protocol.js";
+export { escapeLiteral, escapeIdent, ident, powql, PowqlIdent, escapeSqlLiteral, escapeSqlIdent, sqlIdent, sql, SqlIdent, } from "./escape.js";
 export { Pool } from "./pool.js";
 export { splitStatements } from "./script.js";
 export { errorCodeForWireClass, PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, WIRE_ERROR_CLASS, } from "./errors.js";

package/dist/protocol.d.ts

@@ -43,6 +43,23 @@ 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 decoded cells (rows x columns) in one result frame.
+ *
+ * MAX_ROWS and the per-frame byte-shape check are not enough on their own: a
+ * cell costs 4 bytes on the wire at minimum (an empty string's length prefix)
+ * but far more than that in JS heap, since every row is its own array. A
+ * hostile or MITM'd server could therefore declare 10M single-column rows,
+ * back them with a ~40 MB frame of empty cells, and make the client allocate
+ * roughly 1.9 GB (measured) before anything downstream could react. The
+ * default transport is plaintext, so this is reachable by anyone on the path.
+ *
+ * This cap bounds that allocation absolutely instead of trusting the declared
+ * count: a result frame can never expand past a few hundred MB whatever the
+ * server claims. Results genuinely larger than this must be paged with
+ * `limit`/`offset`.
+ */
+export declare const MAX_RESULT_CELLS = 2000000;
 /** Maximum number of bound parameters in a QueryWithParams message. */
 export declare const MAX_PARAMS = 4096;
 /** Maximum retained units accepted in one sync pull result. */

package/dist/protocol.js

@@ -44,6 +44,29 @@ 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 decoded cells (rows x columns) in one result frame.
+ *
+ * MAX_ROWS and the per-frame byte-shape check are not enough on their own: a
+ * cell costs 4 bytes on the wire at minimum (an empty string's length prefix)
+ * but far more than that in JS heap, since every row is its own array. A
+ * hostile or MITM'd server could therefore declare 10M single-column rows,
+ * back them with a ~40 MB frame of empty cells, and make the client allocate
+ * roughly 1.9 GB (measured) before anything downstream could react. The
+ * default transport is plaintext, so this is reachable by anyone on the path.
+ *
+ * This cap bounds that allocation absolutely instead of trusting the declared
+ * count: a result frame can never expand past a few hundred MB whatever the
+ * server claims. Results genuinely larger than this must be paged with
+ * `limit`/`offset`.
+ */
+export const MAX_RESULT_CELLS = 2_000_000;
+/** Reject a declared result shape whose cell count exceeds MAX_RESULT_CELLS. */
+function checkResultCells(rowCount, colCount) {
+    if (rowCount * colCount > MAX_RESULT_CELLS) {
+        throw new Error(`result too large: ${rowCount * colCount} cells (${rowCount} rows x ${colCount} columns, max ${MAX_RESULT_CELLS})`);
+    }
+}
 /** Maximum number of bound parameters in a QueryWithParams message. */
 export const MAX_PARAMS = 4096;
 /** Maximum retained units accepted in one sync pull result. */
@@ -485,6 +508,7 @@ function decodePayload(msgType, payload) {
             if (remaining < minRowBytes) {
                 throw new Error(`row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
             }
+            checkResultCells(rowCount, colCount);
             const rows = [];
             for (let r = 0; r < rowCount; r++) {
                 const row = [];
@@ -517,6 +541,7 @@ function decodePayload(msgType, payload) {
             if (BigInt(payload.length - cursor.pos) < minimumBytes) {
                 throw new Error(`native row data too short for declared shape: ${rowCount} rows x ${colCount} columns`);
             }
+            checkResultCells(rowCount, colCount);
             const rows = [];
             for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
                 const row = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",