@zvndev/powdb-client 0.11.0 → 0.12.0

package/README.md

@@ -298,21 +298,31 @@ import { Client } from "@zvndev/powdb-client";
 const client = await Client.connect({ host: "localhost", port: 5433 });
 
 const rows = await client.queryTyped(
-  "User { .id, .name, .age, .active, .created_at }",
+  "User { .id, .name, .age, .active, .created_at, .prefs }",
   {
     id: "int",        // number — or bigint if > Number.MAX_SAFE_INTEGER
     age: "int",
     active: "bool",
     created_at: "datetime",
+    prefs: "json",    // parsed with JSON.parse into an object/array/scalar
     // columns not in the schema (like `name`) pass through as strings
   },
 );
 
 rows[0].age;         // typeof number
 rows[0].created_at;  // instanceof Date
+rows[0].prefs;       // parsed JSON value (object, array, or scalar)
 ```
 
-Supported column types: `int` | `float` | `bool` | `str` | `datetime` | `uuid`.
+Supported column types: `int` | `float` | `bool` | `str` | `datetime` | `uuid` | `json`.
+
+`json` columns render as canonical JSON text on the wire (keys sorted
+bytewise, no whitespace) and are parsed with `JSON.parse`. A JSON `null`
+document decodes to `null`. Unlike the other typed columns, a parse failure
+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.

package/dist/cjs/index.d.ts

@@ -19,7 +19,7 @@ import { EventEmitter } from "node:events";
 import { type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus } 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.11.0";
+export declare const CLIENT_VERSION = "0.12.0";
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -390,4 +390,4 @@ export { splitStatements } from "./script.js";
 export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
 export type { PowDBErrorCode } from "./errors.js";
 export { coerceValue, coerceRow, coerceRows, } from "./typed.js";
-export type { ColumnType, TypedSchema, TypedRow, Coerced, } from "./typed.js";
+export type { ColumnType, TypedSchema, TypedRow, Coerced, JsonValue, } from "./typed.js";

package/dist/cjs/index.js

@@ -58,7 +58,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.11.0";
+exports.CLIENT_VERSION = "0.12.0";
 /** Transaction-control statements a `transactional` script may not contain. */
 const TX_CONTROL_RE = /^(begin|commit|rollback)\b/i;
 /**

package/dist/cjs/typed.d.ts

@@ -9,6 +9,7 @@
  *   Str      → raw UTF-8 (may contain anything)
  *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
  *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Json     → canonical JSON text (keys sorted bytewise, no whitespace)
  *   Bytes    → "<N bytes>" (LOSSY — see note below)
  *
  * `queryTyped` takes a user-supplied schema and coerces each column string
@@ -24,14 +25,18 @@
  * schema if you just want the `<N bytes>` placeholder.
  */
 /**
- * Supported column types. Mirrors the server's `DataType` enum minus the
+ * Supported column types. Mirrors the server's `TypeId` enum minus the
  * `Bytes` variant, which is intentionally unsupported here.
  */
-export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid";
+export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid" | "json";
 /** Map of column name → declared type. Columns not in the map pass through as strings. */
 export type TypedSchema = Record<string, ColumnType>;
+/** Any value produced by `JSON.parse` of a canonical JSON document. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /** Coerced value type. `int` may return `bigint` if the value exceeds Number.MAX_SAFE_INTEGER. */
-export type Coerced = number | bigint | boolean | string | Date | null;
+export type Coerced = number | bigint | boolean | string | Date | null | JsonValue;
 /** A row of coerced values keyed by column name. */
 export type TypedRow = Record<string, Coerced>;
 /**

package/dist/cjs/typed.js

@@ -10,6 +10,7 @@
  *   Str      → raw UTF-8 (may contain anything)
  *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
  *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Json     → canonical JSON text (keys sorted bytewise, no whitespace)
  *   Bytes    → "<N bytes>" (LOSSY — see note below)
  *
  * `queryTyped` takes a user-supplied schema and coerces each column string
@@ -85,6 +86,25 @@ function coerceValue(column, raw, type) {
             }
             return raw;
         }
+        case "json": {
+            // The server renders json cells as canonical JSON text, so JSON.parse
+            // reconstructs the document (object, array, or scalar). A JSON `null`
+            // document already returned above via the shared null-sentinel guard.
+            //
+            // Unlike the other typed columns, a parse failure does NOT throw: it
+            // returns the raw string. Rationale: json is the one column type whose
+            // wire text is not a fixed, server-controlled shape a client can fully
+            // predict, and a future server that ever emits a non-canonical cell (or
+            // a proxy that rewrites it) must not turn a readable result into an
+            // exception. Canonical output always parses, so this fallback is inert
+            // in normal operation and exists purely as a safety net.
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return raw;
+            }
+        }
     }
 }
 /**

package/dist/index.d.ts

@@ -19,7 +19,7 @@ import { EventEmitter } from "node:events";
 import { type SyncRepairAction, type WireRetainedUnit, type WireSyncStatus } 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.11.0";
+export declare const CLIENT_VERSION = "0.12.0";
 export type QueryResult = {
     kind: "rows";
     columns: string[];
@@ -390,4 +390,4 @@ export { splitStatements } from "./script.js";
 export { PowDBError, isPowDBError, PowDBScriptError, isPowDBScriptError, } from "./errors.js";
 export type { PowDBErrorCode } from "./errors.js";
 export { coerceValue, coerceRow, coerceRows, } from "./typed.js";
-export type { ColumnType, TypedSchema, TypedRow, Coerced, } from "./typed.js";
+export type { ColumnType, TypedSchema, TypedRow, Coerced, JsonValue, } from "./typed.js";

package/dist/index.js

@@ -22,7 +22,7 @@ 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.11.0";
+export const CLIENT_VERSION = "0.12.0";
 /** Transaction-control statements a `transactional` script may not contain. */
 const TX_CONTROL_RE = /^(begin|commit|rollback)\b/i;
 /**

package/dist/typed.d.ts

@@ -9,6 +9,7 @@
  *   Str      → raw UTF-8 (may contain anything)
  *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
  *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Json     → canonical JSON text (keys sorted bytewise, no whitespace)
  *   Bytes    → "<N bytes>" (LOSSY — see note below)
  *
  * `queryTyped` takes a user-supplied schema and coerces each column string
@@ -24,14 +25,18 @@
  * schema if you just want the `<N bytes>` placeholder.
  */
 /**
- * Supported column types. Mirrors the server's `DataType` enum minus the
+ * Supported column types. Mirrors the server's `TypeId` enum minus the
  * `Bytes` variant, which is intentionally unsupported here.
  */
-export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid";
+export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid" | "json";
 /** Map of column name → declared type. Columns not in the map pass through as strings. */
 export type TypedSchema = Record<string, ColumnType>;
+/** Any value produced by `JSON.parse` of a canonical JSON document. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /** Coerced value type. `int` may return `bigint` if the value exceeds Number.MAX_SAFE_INTEGER. */
-export type Coerced = number | bigint | boolean | string | Date | null;
+export type Coerced = number | bigint | boolean | string | Date | null | JsonValue;
 /** A row of coerced values keyed by column name. */
 export type TypedRow = Record<string, Coerced>;
 /**

package/dist/typed.js

@@ -9,6 +9,7 @@
  *   Str      → raw UTF-8 (may contain anything)
  *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
  *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Json     → canonical JSON text (keys sorted bytewise, no whitespace)
  *   Bytes    → "<N bytes>" (LOSSY — see note below)
  *
  * `queryTyped` takes a user-supplied schema and coerces each column string
@@ -80,6 +81,25 @@ export function coerceValue(column, raw, type) {
             }
             return raw;
         }
+        case "json": {
+            // The server renders json cells as canonical JSON text, so JSON.parse
+            // reconstructs the document (object, array, or scalar). A JSON `null`
+            // document already returned above via the shared null-sentinel guard.
+            //
+            // Unlike the other typed columns, a parse failure does NOT throw: it
+            // returns the raw string. Rationale: json is the one column type whose
+            // wire text is not a fixed, server-controlled shape a client can fully
+            // predict, and a future server that ever emits a non-canonical cell (or
+            // a proxy that rewrites it) must not turn a readable result into an
+            // exception. Canonical output always parses, so this fallback is inert
+            // in normal operation and exists purely as a safety net.
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return raw;
+            }
+        }
     }
 }
 /**

package/package.json

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