@zvndev/powdb-client 0.12.0 → 0.13.0

package/README.md

@@ -287,10 +287,80 @@ const client = await Client.connect({
 });
 ```
 
-## Typed rows
+## Native typed results
 
-The wire protocol serialises every value as a string. If you want JS types
-back (numbers, `Date`, booleans), call `queryTyped` with a schema:
+Use `queryNative` when values must cross the wire without legacy string
+rendering:
+
+```typescript
+const result = await client.queryNative(
+  "Post filter .id = $1 { .id, .data, raw: .attachment }",
+  [42],
+);
+
+if (result.kind === "rows") {
+  const [id, data, raw] = result.rows[0];
+  // id: number, or bigint outside JavaScript's safe integer range
+  // data: recursively decoded JSON
+  // raw: Uint8Array
+}
+
+const sqlResult = await client.querySqlNative(
+  "SELECT data->'author' FROM Post WHERE id = 42",
+);
+```
+
+Native results preserve each cell's actual type. Integers become `number` when
+safe and `bigint` otherwise; floats and booleans remain primitives; `bytes`
+become `Uint8Array`; UUIDs become canonical strings; datetimes remain epoch
+microseconds as `bigint`; and PJ1 JSON is decoded recursively without a JSON
+text round trip. Empty cells become `null`.
+
+`queryNative` accepts the same `$N` parameter array and `AbortSignal` options
+as `query`. `querySqlNative` is the corresponding SQL method. Neither method
+silently replays a request through the legacy string protocol, because replay
+would be unsafe for a mutation after an ambiguous response.
+
+Legacy `query` and `querySql` keep their existing string result shapes for
+wire compatibility.
+
+### Fully lossless access with `queryNativeRaw`
+
+`queryNative` is friendly, but its convenience conversion erases a few
+storage-level distinctions: it maps every empty cell, JSON `null`, and even a
+successful decode to a plain JavaScript `null`, and it drops the raw PJ1 bytes
+that back a JSON value. When you need that fidelity, use `queryNativeRaw`, which
+returns every cell as the raw `WireValue` tagged union straight off the wire:
+
+```typescript
+const raw = await client.queryNativeRaw(
+  "Doc filter .id = $1 { .note, .missing, .data }",
+  [1],
+);
+
+if (raw.kind === "rows") {
+  const [note, missing, data] = raw.rows[0];
+  // note:    { type: "str", value: "null" }   : the string "null"
+  // missing: { type: "empty" }                : an absent value
+  // data:    { type: "json", value: null, pj1: Uint8Array }  : a JSON null
+}
+```
+
+Reach for `queryNativeRaw` when you need:
+
+- **Storage-level identity**: telling an absent value (`{ type: "empty" }`)
+  apart from the string `"null"` and a JSON `null`, all of which `queryNative`
+  collapses to `null`.
+- **Raw PJ1 bytes**: the `pj1: Uint8Array` on a `json` cell is the exact
+  on-wire binary JSON, for byte-identical storage, hashing, or re-encoding.
+
+It accepts the same `$N` parameter array and `AbortSignal` options as
+`queryNative`. For ordinary reads, prefer `queryNative`.
+
+## Schema-coerced rows
+
+The legacy wire protocol serialises every value as a string. If you want JS
+types back using a caller-supplied schema, call `queryTyped`:
 
 ```typescript
 import { Client } from "@zvndev/powdb-client";
@@ -323,9 +393,8 @@ does not throw: it returns the raw string, so a malformed or non-canonical
 cell can never turn a readable result into an exception (canonical server
 output always parses, so this fallback is inert in normal use).
 
-Bytes columns are intentionally unsupported (the wire format is lossy —
-it renders `<N bytes>`) and throw on coercion. Declare `str` if you just
-want the placeholder.
+Bytes columns are intentionally unsupported by `queryTyped` because the
+legacy wire format renders `<N bytes>`. Use `queryNative` for exact bytes.
 
 ## Structured errors
 
@@ -486,6 +555,27 @@ AbortSignal` cancels the query (see Cancellation above).
 const result = await client.querySql("SELECT name, age FROM User WHERE age > 27");
 ```
 
+### `client.queryNative(query, params?, opts?)`
+
+Runs PowQL through the native typed wire surface and returns a
+`Promise<NativeQueryResult>`. Row and scalar cells retain their actual types,
+including exact bytes and recursively decoded JSON. Parameters and abort
+options match `query()`. The method does not replay through the legacy string
+surface.
+
+### `client.queryNativeRaw(query, params?, opts?)`
+
+Like `queryNative`, but returns every cell as the raw `WireValue` tagged union
+(`Promise<RawNativeQueryResult>`) with no conversion to `NativeValue`. Use it
+for storage-level identity (Empty vs `"null"` vs a JSON null) or the raw PJ1
+bytes of a JSON cell (`pj1`). Parameters and abort options match `queryNative`.
+
+### `client.querySqlNative(query, opts?)`
+
+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?)`
 
 Like `query()`, but coerces each row's string values to JS types using the

package/dist/cjs/index.d.ts

@@ -16,10 +16,24 @@
  */
 import * as tls from "node:tls";
 import { EventEmitter } from "node:events";
-import { type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus } from "./protocol.js";
+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.12.0";
+export declare const CLIENT_VERSION = "0.13.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
+ * maximum is at least its active catalog format and rejects an older replica.
+ * When validating a server-reported catalog version, accept anything at or
+ * below this and reject anything newer (the client cannot read it).
+ */
+export declare const SUPPORTED_CATALOG_VERSION = 6;
+/**
+ * Throw when a server-reported catalog format is newer than this client can
+ * read. Accepts `serverCatalogVersion <= SUPPORTED_CATALOG_VERSION`; rejects a
+ * newer server, which requires upgrading the client.
+ */
+export declare function assertServerCatalogVersionSupported(serverCatalogVersion: number, clientMax?: number): void;
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -34,6 +48,46 @@ export type QueryResult = {
     kind: "message";
     message: string;
 };
+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;
+export type NativeQueryResult = {
+    kind: "rows";
+    columns: string[];
+    rows: NativeValue[][];
+} | {
+    kind: "scalar";
+    value: NativeValue;
+} | {
+    kind: "ok";
+    affected: bigint;
+} | {
+    kind: "message";
+    message: string;
+};
+/**
+ * The fully lossless result of {@link Client.queryNativeRaw}: every cell is the
+ * raw {@link WireValue} tagged union straight off the wire, with no conversion
+ * to {@link NativeValue}. Use this when you need storage-level identity that the
+ * convenience conversion erases: the raw PJ1 bytes of a JSON cell (`pj1`), or
+ * telling an absent value (`{ type: "empty" }`) apart from the string `"null"`
+ * (`{ type: "str", value: "null" }`) or a JSON null (`{ type: "json", value:
+ * null }`), all of which {@link queryNative} collapses to `null`.
+ */
+export type RawNativeQueryResult = {
+    kind: "rows";
+    columns: string[];
+    rows: WireValue[][];
+} | {
+    kind: "scalar";
+    value: WireValue;
+} | {
+    kind: "ok";
+    affected: bigint;
+} | {
+    kind: "message";
+    message: string;
+};
 /**
  * A value bound to a positional `$N` placeholder in {@link Client.query}.
  *
@@ -256,6 +310,32 @@ export declare class Client extends EventEmitter<ClientEvents> {
     }, maybeOpts?: {
         signal?: AbortSignal;
     }): Promise<QueryResult>;
+    /**
+     * Run PowQL over the lossless typed wire surface. Unlike {@link query},
+     * cells are not stringified: bytes remain bytes, JSON is recursive data,
+     * and unsafe integers remain bigint. This method never retries as a legacy
+     * query, because replaying a mutation after an ambiguous response is unsafe.
+     */
+    queryNative(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<NativeQueryResult>;
+    /**
+     * Like {@link queryNative}, but returns every cell as the raw
+     * {@link WireValue} tagged union with no conversion to {@link NativeValue}.
+     *
+     * Reach for this only when the convenience conversion would erase something
+     * you need: the raw PJ1 bytes of a JSON cell (`pj1`), or the distinction
+     * between an absent value (`{ type: "empty" }`), the string `"null"`, and a
+     * JSON null (all three of which {@link queryNative} maps to `null`). For
+     * ordinary reads, {@link queryNative} is friendlier.
+     */
+    queryNativeRaw(query: string, paramsOrOpts?: QueryParam[] | {
+        signal?: AbortSignal;
+    }, maybeOpts?: {
+        signal?: AbortSignal;
+    }): Promise<RawNativeQueryResult>;
     /**
      * Run a SQL statement through the server-side SQL frontend. The plain
      * {@link query} method remains PowQL for wire compatibility.
@@ -263,6 +343,10 @@ export declare class Client extends EventEmitter<ClientEvents> {
     querySql(query: string, opts?: {
         signal?: AbortSignal;
     }): Promise<QueryResult>;
+    /** Run SQL through the lossless typed wire surface without legacy replay. */
+    querySqlNative(query: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<NativeQueryResult>;
     /**
      * Fetch primary-side sync status for one embedded replica cursor.
      *
@@ -381,7 +465,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
     private onClose;
 }
 export { encode, tryDecode } from "./protocol.js";
-export type { Message, SyncRepairAction, WireParam, WireRetainedUnit, WireSyncStatus, } 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 { Pool } from "./pool.js";

package/dist/cjs/index.js

@@ -49,7 +49,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = 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.CLIENT_VERSION = void 0;
+exports.coerceRows = exports.coerceRow = exports.coerceValue = exports.isPowDBScriptError = exports.PowDBScriptError = exports.isPowDBError = exports.PowDBError = 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.assertServerCatalogVersionSupported = assertServerCatalogVersionSupported;
 const net = __importStar(require("node:net"));
 const tls = __importStar(require("node:tls"));
 const node_events_1 = require("node:events");
@@ -58,7 +59,28 @@ 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.12.0";
+exports.CLIENT_VERSION = "0.13.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
+ * maximum is at least its active catalog format and rejects an older replica.
+ * When validating a server-reported catalog version, accept anything at or
+ * below this and reject anything newer (the client cannot read it).
+ */
+exports.SUPPORTED_CATALOG_VERSION = 6;
+/**
+ * Throw when a server-reported catalog format is newer than this client can
+ * read. Accepts `serverCatalogVersion <= SUPPORTED_CATALOG_VERSION`; rejects a
+ * newer server, which requires upgrading the client.
+ */
+function assertServerCatalogVersionSupported(serverCatalogVersion, clientMax = exports.SUPPORTED_CATALOG_VERSION) {
+    if (!Number.isInteger(serverCatalogVersion) || serverCatalogVersion < 1) {
+        throw new Error(`invalid server catalog version ${serverCatalogVersion}`);
+    }
+    if (serverCatalogVersion > clientMax) {
+        throw new Error(`server catalog format v${serverCatalogVersion} is newer than this client supports (max v${clientMax}); upgrade the client`);
+    }
+}
 /** Transaction-control statements a `transactional` script may not contain. */
 const TX_CONTROL_RE = /^(begin|commit|rollback)\b/i;
 /**
@@ -90,6 +112,67 @@ function toWireParam(p) {
             throw new errors_js_1.PowDBError(`unsupported query parameter type: ${typeof p}`, "protocol_error");
     }
 }
+function fromWireValue(value) {
+    switch (value.type) {
+        case "empty":
+            return null;
+        case "int":
+            return value.value >= BigInt(Number.MIN_SAFE_INTEGER) &&
+                value.value <= BigInt(Number.MAX_SAFE_INTEGER)
+                ? Number(value.value)
+                : value.value;
+        case "float":
+        case "bool":
+        case "str":
+            return value.value;
+        case "datetime":
+            return value.value;
+        case "uuid": {
+            const hex = Array.from(value.value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        }
+        case "bytes":
+            return new Uint8Array(value.value);
+        case "json":
+            return value.value;
+    }
+}
+function nativeQueryResult(reply) {
+    switch (reply.type) {
+        case "ResultRowsNative":
+            return {
+                kind: "rows",
+                columns: reply.columns,
+                rows: reply.rows.map((row) => row.map(fromWireValue)),
+            };
+        case "ResultScalarNative":
+            return { kind: "scalar", value: fromWireValue(reply.value) };
+        case "ResultOk":
+            return { kind: "ok", affected: reply.affected };
+        case "ResultMessage":
+            return { kind: "message", message: reply.message };
+        case "Error":
+            throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+        default:
+            throw new errors_js_1.PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
+    }
+}
+function rawNativeQueryResult(reply) {
+    switch (reply.type) {
+        case "ResultRowsNative":
+            return { kind: "rows", columns: reply.columns, rows: reply.rows };
+        case "ResultScalarNative":
+            return { kind: "scalar", value: reply.value };
+        case "ResultOk":
+            return { kind: "ok", affected: reply.affected };
+        case "ResultMessage":
+            return { kind: "message", message: reply.message };
+        case "Error":
+            throw new errors_js_1.PowDBError(`query failed: ${reply.message}`, "query_failed");
+        default:
+            throw new errors_js_1.PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
+    }
+}
 function toU64(value, label) {
     if (typeof value === "bigint") {
         if (value < 0n || value > 0xffffffffffffffffn) {
@@ -325,6 +408,90 @@ class Client extends node_events_1.EventEmitter {
             throw err;
         }
     }
+    /**
+     * Run PowQL over the lossless typed wire surface. Unlike {@link query},
+     * cells are not stringified: bytes remain bytes, JSON is recursive data,
+     * and unsafe integers remain bigint. This method never retries as a legacy
+     * query, because replaying a mutation after an ambiguous response is unsafe.
+     */
+    async queryNative(query, paramsOrOpts, maybeOpts) {
+        const hasParams = Array.isArray(paramsOrOpts);
+        const params = hasParams ? paramsOrOpts : undefined;
+        const opts = hasParams
+            ? maybeOpts
+            : paramsOrOpts;
+        const start = Date.now();
+        try {
+            const request = params === undefined
+                ? { type: "QueryNative", query }
+                : {
+                    type: "QueryWithParamsNative",
+                    query,
+                    params: params.map(toWireParam),
+                };
+            const result = nativeQueryResult(await this.send(request, opts));
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: true,
+                kind: result.kind,
+            });
+            return result;
+        }
+        catch (err) {
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
+    /**
+     * Like {@link queryNative}, but returns every cell as the raw
+     * {@link WireValue} tagged union with no conversion to {@link NativeValue}.
+     *
+     * Reach for this only when the convenience conversion would erase something
+     * you need: the raw PJ1 bytes of a JSON cell (`pj1`), or the distinction
+     * between an absent value (`{ type: "empty" }`), the string `"null"`, and a
+     * JSON null (all three of which {@link queryNative} maps to `null`). For
+     * ordinary reads, {@link queryNative} is friendlier.
+     */
+    async queryNativeRaw(query, paramsOrOpts, maybeOpts) {
+        const hasParams = Array.isArray(paramsOrOpts);
+        const params = hasParams ? paramsOrOpts : undefined;
+        const opts = hasParams
+            ? maybeOpts
+            : paramsOrOpts;
+        const start = Date.now();
+        try {
+            const request = params === undefined
+                ? { type: "QueryNative", query }
+                : {
+                    type: "QueryWithParamsNative",
+                    query,
+                    params: params.map(toWireParam),
+                };
+            const result = rawNativeQueryResult(await this.send(request, opts));
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: true,
+                kind: result.kind,
+            });
+            return result;
+        }
+        catch (err) {
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
     /**
      * Run a SQL statement through the server-side SQL frontend. The plain
      * {@link query} method remains PowQL for wire compatibility.
@@ -370,6 +537,29 @@ class Client extends node_events_1.EventEmitter {
             throw err;
         }
     }
+    /** Run SQL through the lossless typed wire surface without legacy replay. */
+    async querySqlNative(query, opts) {
+        const start = Date.now();
+        try {
+            const result = nativeQueryResult(await this.send({ type: "QuerySqlNative", query }, opts));
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: true,
+                kind: result.kind,
+            });
+            return result;
+        }
+        catch (err) {
+            this.emit("query", {
+                query,
+                durationMs: Date.now() - start,
+                ok: false,
+                error: err,
+            });
+            throw err;
+        }
+    }
     /**
      * Fetch primary-side sync status for one embedded replica cursor.
      *

package/dist/cjs/protocol.d.ts

@@ -32,6 +32,11 @@ export declare const MSG_RESULT_MSG = 11;
 export declare const MSG_DISCONNECT = 16;
 export declare const MSG_PING = 17;
 export declare const MSG_PONG = 18;
+export declare const MSG_QUERY_NATIVE = 19;
+export declare const MSG_QUERY_PARAMS_NATIVE = 20;
+export declare const MSG_QUERY_SQL_NATIVE = 21;
+export declare const MSG_RESULT_ROWS_NATIVE = 22;
+export declare const MSG_RESULT_SCALAR_NATIVE = 23;
 /** Maximum payload size accepted from the wire (64 MB). */
 export declare const MAX_PAYLOAD_SIZE: number;
 /** Maximum number of rows allowed in a single result message. */
@@ -70,6 +75,39 @@ export type WireParam = {
     tag: "str";
     value: string;
 };
+/** Recursively decoded PJ1 JSON. Integers outside JS's safe range are bigint. */
+export type NativeJson = null | boolean | number | bigint | string | NativeJson[] | {
+    [key: string]: NativeJson;
+};
+/** Lossless typed cell used internally by the native result protocol. */
+export type WireValue = {
+    type: "empty";
+} | {
+    type: "int";
+    value: bigint;
+} | {
+    type: "float";
+    value: number;
+} | {
+    type: "bool";
+    value: boolean;
+} | {
+    type: "str";
+    value: string;
+} | {
+    type: "datetime";
+    value: bigint;
+} | {
+    type: "uuid";
+    value: Uint8Array;
+} | {
+    type: "bytes";
+    value: Uint8Array;
+} | {
+    type: "json";
+    value: NativeJson;
+    pj1: Uint8Array;
+};
 export type SyncRepairAction = "none" | "pull" | "awaitArchive" | "rebootstrap";
 export interface WireSyncStatus {
     replicaId: string;
@@ -116,6 +154,16 @@ export type Message = {
     type: "QueryWithParams";
     query: string;
     params: WireParam[];
+} | {
+    type: "QueryNative";
+    query: string;
+} | {
+    type: "QueryWithParamsNative";
+    query: string;
+    params: WireParam[];
+} | {
+    type: "QuerySqlNative";
+    query: string;
 } | {
     type: "SyncStatus";
     replicaId: string;
@@ -157,6 +205,13 @@ export type Message = {
 } | {
     type: "ResultScalar";
     value: string;
+} | {
+    type: "ResultRowsNative";
+    columns: string[];
+    rows: WireValue[][];
+} | {
+    type: "ResultScalarNative";
+    value: WireValue;
 } | {
     type: "ResultOk";
     affected: bigint;