@zvndev/powdb-client 0.9.0 → 0.11.0

package/dist/cjs/script.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Statement-aware PowQL script splitting.
+ *
+ * Mirrors the server-side splitter (`powdb_query::lexer::split_statements`)
+ * exactly, so a script file behaves the same whether it is fed to the CLI's
+ * `--exec` / `.powql` path or to {@link Client.execScript} over the wire:
+ *
+ *   - `;` splits statements only at the top level.
+ *   - `;` inside a `"..."` string literal never splits. A backslash inside a
+ *     string consumes the next character unconditionally (mirroring the
+ *     PowQL lexer), so `\"` and `\;` stay inside the string.
+ *   - `#` starts a comment that runs to end-of-line; a `;` inside a comment
+ *     never splits.
+ *   - Segments are trimmed; empty segments (leading/doubled/trailing `;`,
+ *     blank lines) are dropped.
+ *   - Never errors: an unterminated string simply makes the rest of the
+ *     input the final segment.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitStatements = splitStatements;
+/**
+ * Split a PowQL script into individual statements.
+ *
+ * String-literal- and `#`-comment-aware `;` splitting with the exact
+ * semantics of the CLI/server splitter (see module docs above).
+ */
+function splitStatements(input) {
+    const out = [];
+    let start = 0;
+    let state = "normal";
+    for (let i = 0; i < input.length; i++) {
+        const c = input[i];
+        switch (state) {
+            case "normal":
+                if (c === ";") {
+                    const seg = input.slice(start, i).trim();
+                    if (seg.length > 0)
+                        out.push(seg);
+                    start = i + 1;
+                }
+                else if (c === '"') {
+                    state = "in-string";
+                }
+                else if (c === "#") {
+                    state = "in-comment";
+                }
+                break;
+            case "in-string":
+                // Mirror the lexer: a backslash consumes the next char
+                // unconditionally, so `\"` and `\;` stay inside the string.
+                if (c === "\\") {
+                    i++;
+                }
+                else if (c === '"') {
+                    state = "normal";
+                }
+                break;
+            case "in-comment":
+                if (c === "\n")
+                    state = "normal";
+                break;
+        }
+    }
+    const seg = input.slice(start).trim();
+    if (seg.length > 0)
+        out.push(seg);
+    return out;
+}

package/dist/cjs/typed.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Optional row-level type coercion for `queryTyped`.
+ *
+ * The server's wire format serialises every value to a string (see
+ * `crates/server/src/handler.rs::value_to_display`):
+ *   Int      → decimal digits, e.g. "42" or "-7"
+ *   Float    → Rust `{}` format, e.g. "3.14"
+ *   Bool     → "true" / "false"
+ *   Str      → raw UTF-8 (may contain anything)
+ *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
+ *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Bytes    → "<N bytes>" (LOSSY — see note below)
+ *
+ * `queryTyped` takes a user-supplied schema and coerces each column string
+ * into the corresponding JS value. Rationale for requiring the caller to
+ * supply the schema (rather than introspecting): PowDB has no `describe`
+ * statement yet, and going via `select` off a system catalog is one extra
+ * round trip per typed query. When schema introspection lands, a helper
+ * that builds the schema object can be added without changing this API.
+ *
+ * Bytes caveat: the current wire format is lossy for byte columns (renders
+ * `<N bytes>`). Until the wire protocol grows a binary column type, this
+ * module throws on `bytes` columns rather than guessing — use `str` in the
+ * schema if you just want the `<N bytes>` placeholder.
+ */
+/**
+ * Supported column types. Mirrors the server's `DataType` enum minus the
+ * `Bytes` variant, which is intentionally unsupported here.
+ */
+export type ColumnType = "int" | "float" | "bool" | "str" | "datetime" | "uuid";
+/** Map of column name → declared type. Columns not in the map pass through as strings. */
+export type TypedSchema = Record<string, ColumnType>;
+/** Coerced value type. `int` may return `bigint` if the value exceeds Number.MAX_SAFE_INTEGER. */
+export type Coerced = number | bigint | boolean | string | Date | null;
+/** A row of coerced values keyed by column name. */
+export type TypedRow = Record<string, Coerced>;
+/**
+ * Coerce a single string value to the JS type declared in `schema`. `null`
+ * is returned for the conventional null sentinel — see note at call site.
+ * Unknown column types fall through as strings.
+ */
+export declare function coerceValue(column: string, raw: string, type: ColumnType | undefined): Coerced;
+/**
+ * Coerce a single result row (a string tuple) into a typed object keyed by
+ * column name.
+ */
+export declare function coerceRow(columns: string[], values: string[], schema: TypedSchema): TypedRow;
+/** Coerce every row in a rows-result into typed objects. */
+export declare function coerceRows(columns: string[], rows: string[][], schema: TypedSchema): TypedRow[];

package/dist/cjs/typed.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Optional row-level type coercion for `queryTyped`.
+ *
+ * The server's wire format serialises every value to a string (see
+ * `crates/server/src/handler.rs::value_to_display`):
+ *   Int      → decimal digits, e.g. "42" or "-7"
+ *   Float    → Rust `{}` format, e.g. "3.14"
+ *   Bool     → "true" / "false"
+ *   Str      → raw UTF-8 (may contain anything)
+ *   DateTime → microseconds since Unix epoch as decimal, e.g. "1718928000000000"
+ *   Uuid     → canonical "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ *   Bytes    → "<N bytes>" (LOSSY — see note below)
+ *
+ * `queryTyped` takes a user-supplied schema and coerces each column string
+ * into the corresponding JS value. Rationale for requiring the caller to
+ * supply the schema (rather than introspecting): PowDB has no `describe`
+ * statement yet, and going via `select` off a system catalog is one extra
+ * round trip per typed query. When schema introspection lands, a helper
+ * that builds the schema object can be added without changing this API.
+ *
+ * Bytes caveat: the current wire format is lossy for byte columns (renders
+ * `<N bytes>`). Until the wire protocol grows a binary column type, this
+ * module throws on `bytes` columns rather than guessing — use `str` in the
+ * schema if you just want the `<N bytes>` placeholder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceValue = coerceValue;
+exports.coerceRow = coerceRow;
+exports.coerceRows = coerceRows;
+const errors_js_1 = require("./errors.js");
+/**
+ * Coerce a single string value to the JS type declared in `schema`. `null`
+ * is returned for the conventional null sentinel — see note at call site.
+ * Unknown column types fall through as strings.
+ */
+function coerceValue(column, raw, type) {
+    // The server's wire format distinguishes NULL from empty string by the
+    // literal "null" bareword in scalar displays. For typed columns we treat
+    // the single token "null" as NULL; empty string remains empty string for
+    // `str` columns (can be an intentional empty value).
+    if (type !== "str" && raw === "null")
+        return null;
+    switch (type) {
+        case undefined:
+        case "str":
+            return raw;
+        case "int": {
+            if (!/^-?\d+$/.test(raw)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared int but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            // Promote to BigInt when the value doesn't round-trip through Number.
+            const n = Number(raw);
+            if (Number.isSafeInteger(n))
+                return n;
+            return BigInt(raw);
+        }
+        case "float": {
+            const n = Number(raw);
+            if (!Number.isFinite(n)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared float but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            return n;
+        }
+        case "bool":
+            if (raw === "true")
+                return true;
+            if (raw === "false")
+                return false;
+            throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared bool but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+        case "datetime": {
+            if (!/^-?\d+$/.test(raw)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared datetime but got ${JSON.stringify(raw)} (expected microseconds since epoch)`, "type_coercion_failed");
+            }
+            // Server sends microseconds since epoch. JS Date uses milliseconds.
+            // BigInt division avoids float precision loss for far-future dates.
+            const micros = BigInt(raw);
+            const millis = Number(micros / 1000n);
+            return new Date(millis);
+        }
+        case "uuid": {
+            // Canonical 8-4-4-4-12 hex, lowercase (per server format).
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(raw)) {
+                throw new errors_js_1.PowDBError(`queryTyped: column "${column}" declared uuid but got ${JSON.stringify(raw)}`, "type_coercion_failed");
+            }
+            return raw;
+        }
+    }
+}
+/**
+ * Coerce a single result row (a string tuple) into a typed object keyed by
+ * column name.
+ */
+function coerceRow(columns, values, schema) {
+    const out = {};
+    for (let i = 0; i < columns.length; i++) {
+        const col = columns[i];
+        out[col] = coerceValue(col, values[i] ?? "null", schema[col]);
+    }
+    return out;
+}
+/** Coerce every row in a rows-result into typed objects. */
+function coerceRows(columns, rows, schema) {
+    return rows.map((r) => coerceRow(columns, r, schema));
+}

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.9.0";
+export declare const CLIENT_VERSION = "0.11.0";
 export type QueryResult = {
     kind: "rows";
     columns: string[];

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

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@zvndev/powdb-client",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "TypeScript client for PowDB (PowQL wire protocol)",
   "type": "module",
   "packageManager": "pnpm@10.29.3",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
@@ -47,7 +54,9 @@
     "@types/node": { "optional": true }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }) + '\\n')\"",
     "test": "tsx test/run-with-server.ts test/client.test.ts",
     "test:escape": "tsx test/escape.test.ts",
     "test:protocol": "tsx test/protocol.test.ts",