@zvndev/powdb-client 0.12.0 → 0.13.0

package/dist/index.js

@@ -22,7 +22,28 @@ import { PowDBError, PowDBScriptError, isPowDBError } from "./errors.js";
 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.12.0";
+export 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 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 function assertServerCatalogVersionSupported(serverCatalogVersion, clientMax = 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;
 /**
@@ -54,6 +75,67 @@ function toWireParam(p) {
             throw new 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 PowDBError(`query failed: ${reply.message}`, "query_failed");
+        default:
+            throw new 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 PowDBError(`query failed: ${reply.message}`, "query_failed");
+        default:
+            throw new PowDBError(`unexpected reply to native query: ${reply.type}`, "protocol_error");
+    }
+}
 function toU64(value, label) {
     if (typeof value === "bigint") {
         if (value < 0n || value > 0xffffffffffffffffn) {
@@ -289,6 +371,90 @@ export class Client extends 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.
@@ -334,6 +500,29 @@ export class Client extends 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/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;