@zvndev/powdb-client 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.15.0 - 2026-07-16
+
+- Version-alignment release in lockstep with workspace v0.15.0 (per-index
+  statistics and cardinality-aware conjunction index choice). No TypeScript
+  API changes; `explain` result rows now include selectivity tokens
+  (`est_rows=... entries=... distinct=...`) on chosen index-scan lines.
+
+## 0.14.0 - 2026-07-16
+
+- Version-alignment release in lockstep with workspace v0.14.0 (conjunction
+  index selection, embedded typed results, read-only snapshot serving). No
+  TypeScript API changes; servers in read-only mode return a terminal
+  "readonly mode: statement requires a writer" error for mutations, which
+  surfaces through the existing error path.
+
+## 0.13.0 - 2026-07-15
+
+- Added the **lossless native typed result API**: `queryNative(powql)`,
+  `querySqlNative(sql)`, and low-level `queryNativeRaw(...)` returning tagged
+  `WireValue` cells. Native results preserve exact cell types: 64-bit ints as
+  `bigint`, raw `bytes`, and JSON documents as parsed values plus the exact
+  PJ1 bytes (`pj1`). Empty (SQL NULL / missing) is distinct from JSON `null`
+  and from the string `"null"` in raw results.
+- Added native parameterized queries over the new typed request frames.
+- Added `SUPPORTED_CATALOG_VERSION` and `assertServerCatalogVersionSupported`
+  so clients fail with a clear error against servers newer than they support.
+- Legacy `query()` / `querySql()` string results are unchanged and remain
+  byte-compatible; see README for when to prefer the native API.
+
+## 0.12.0 - 2026-07-14
+
+- Typed API: `"json"` column kind for the server's native JSON (PJ1) type.
+  JSON cells arrive as canonical JSON text on the legacy protocol.
+- No breaking changes; released in lockstep with workspace v0.12.0.
+
+## 0.11.0 - 2026-07-13
+
+- Version-alignment release in lockstep with workspace v0.11.0 (overflow
+  pages, grouped aggregates). No TypeScript API changes.
+
+## 0.10.0 - 2026-07-13
+
+- Version-alignment release in lockstep with workspace v0.10.0. No
+  TypeScript API changes.
+
+## 0.9.0 - 2026-07-12
+
+- Added `execScript(...)`: transactional, statement-aware script execution
+  with all-or-nothing semantics.
+- Connect is now pipelined and eager, reducing first-query latency.
+
 ## 0.8.0 - 2026-07-02
 
 - Released in lockstep with PowDB workspace v0.8.0 (Embedded Sync Milestone 0).

package/README.md

@@ -357,6 +357,22 @@ Reach for `queryNativeRaw` when you need:
 It accepts the same `$N` parameter array and `AbortSignal` options as
 `queryNative`. For ordinary reads, prefer `queryNative`.
 
+### Null vs missing: which API sees what
+
+The legacy string protocol renders an absent value, a JSON `null`, and the
+string `"null"` as the identical string `null`. This is frozen wire behavior:
+existing decoders depend on it, so it will not change. If your application
+(or a driver you maintain) needs to tell these apart, migrate reads to
+`queryNativeRaw`, which is the sanctioned lossless surface.
+
+One engine-level caveat applies to every API, native included: extracting a
+scalar with `->` (for example `.data->maybe->leaf`) collapses "path missing"
+and "explicit JSON null at the leaf" into the same empty value before results
+are produced. When that distinction matters, either project the enclosing
+JSON value (a `json` cell preserves `null` exactly) or ask the engine with
+`json_type(.data->maybe->leaf)`, which returns the string `"null"` for an
+explicit JSON null and an empty value for a missing path.
+
 ## Schema-coerced rows
 
 The legacy wire protocol serialises every value as a string. If you want JS

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.13.0";
+export declare const CLIENT_VERSION = "0.15.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

package/dist/cjs/index.js

@@ -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.13.0";
+exports.CLIENT_VERSION = "0.15.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

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.13.0";
+export declare const CLIENT_VERSION = "0.15.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

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.13.0";
+export const CLIENT_VERSION = "0.15.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

package/package.json

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