turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/powdb.js

@@ -200,8 +200,11 @@ exports.PowdbFloatParam = PowdbFloatParam;
  */
 class PowdbJsonParam {
     value;
-    constructor(value) {
+    column;
+    /** `column` is diagnostic only: it names the target column when serialization fails. */
+    constructor(value, column) {
         this.value = value;
+        this.column = column;
     }
 }
 exports.PowdbJsonParam = PowdbJsonParam;
@@ -657,9 +660,10 @@ function powqlSchemaDDL(schema, opts = {}) {
         // Declared indexes: PowDB doc-field expression indexes (docPath) and plain
         // single-column indexes. A doc-field index MUST be parenthesized (the engine
         // rejects a bare JSON path); string path segments emit lexer-exact via the
-        // shared `encodePowqlString`, integer array indexes emit bare. A json
-        // document column reference stays dotted-bare (`.col`), which bypasses
-        // keyword lookup on every engine version exactly like a filter path.
+        // shared `encodePowqlString`, integer array indexes emit bare. The json
+        // document column goes through `quotePowqlIdent` exactly like the plain
+        // index branch below, so a keyword or non-bare identifier is backtick-quoted
+        // instead of being spliced raw into the statement.
         for (const idx of meta.indexes) {
             const kind = idx.unique ? 'unique' : 'index';
             if (idx.docPath) {
@@ -670,7 +674,7 @@ function powqlSchemaDDL(schema, opts = {}) {
                     throw new errors_js_1.ValidationError(`[turbine] Doc-field index "${idx.name}" on ${meta.name} has no target json column.`);
                 }
                 const segs = idx.docPath.map((s) => (typeof s === 'number' ? `->${s}` : `->${encodePowqlString(s)}`)).join('');
-                stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} (.${column}${segs})`);
+                stmts.push(`alter ${quotePowqlIdent(meta.name)} add ${kind} (.${quotePowqlIdent(column)}${segs})`);
             }
             else {
                 // Plain column index. PowDB has no composite index (`add index` takes a
@@ -778,6 +782,36 @@ async function listPowdbLinks(exec) {
 function powdbCell(v) {
     return v === null || v === undefined ? '' : String(v);
 }
+/**
+ * Serialize a json-column value to the canonical JSON text both transports
+ * send. `JSON.stringify` can throw (circular structure, a BigInt cell, a
+ * throwing `toJSON`) and can return `undefined` (a value that serializes to
+ * nothing, e.g. a `toJSON` returning undefined); both surface as a typed E003
+ * naming the column instead of a raw TypeError or an undefined param.
+ */
+function powdbJsonText(param, position) {
+    const where = `for column "${param.column ?? '(unknown)'}"${position ? ` (${position})` : ''}`;
+    let json;
+    try {
+        json = JSON.stringify(param.value);
+    }
+    catch (err) {
+        throw new errors_js_1.ValidationError(`[turbine] The json value ${where} cannot be serialized for PowDB: ${err.message}`);
+    }
+    if (json === undefined) {
+        throw new errors_js_1.ValidationError(`[turbine] The json value ${where} serializes to nothing (JSON.stringify returned undefined); ` +
+            'write `null` explicitly instead.');
+    }
+    return json;
+}
+/** Convert a Date to PowDB epoch micros, refusing an invalid Date (getTime() is NaN). */
+function powdbDateMicros(value, position) {
+    const ms = value.getTime();
+    if (!Number.isFinite(ms)) {
+        throw new errors_js_1.ValidationError(`[turbine] Invalid Date${position ? ` (${position})` : ''} cannot be encoded as a PowDB timestamp.`);
+    }
+    return BigInt(ms) * 1000n;
+}
 /** Coerce a JS value into a PowDB positional param (the write side). */
 function toPowdbParam(value, col) {
     if (value instanceof PowdbFloatParam)
@@ -785,11 +819,11 @@ function toPowdbParam(value, col) {
     // json document: serialize to canonical JSON text and bind as a str param,
     // the engine validates it as JSON and stores the canonical binary form.
     if (value instanceof PowdbJsonParam)
-        return JSON.stringify(value.value);
+        return powdbJsonText(value);
     if (value === undefined || value === null)
         return null;
     if (value instanceof Date)
-        return BigInt(value.getTime()) * 1000n; // ms → micros (int column)
+        return powdbDateMicros(value); // ms → micros (int column)
     if (col && isDateColumn(col) && typeof value === 'number')
         return BigInt(value) * 1000n;
     if (typeof value === 'boolean' ||
@@ -1646,36 +1680,74 @@ function normalizeEmbeddedResult(r) {
  * quotes, backslashes, `$N`, `"); drop … --`, raw CR, and emoji all round-trip
  * as data and cannot break out of the literal or inject a second statement.
  */
-function encodePowqlLiteral(value) {
+function encodePowqlLiteral(value, position) {
+    const at = position ? ` (${position})` : '';
     if (value instanceof PowdbFloatParam) {
         const n = value.value;
         if (!Number.isFinite(n))
-            throw new errors_js_1.ValidationError(`[turbine] Non-finite float cannot be encoded for PowDB.`);
+            throw new errors_js_1.ValidationError(`[turbine] Non-finite float cannot be encoded for PowDB${at}.`);
         // Force a float-form literal so an integer-valued float column stays a float.
-        return Number.isInteger(n) ? `${n}.0` : String(n);
+        const text = powqlNumberText(n);
+        return text.includes('.') ? text : `${text}.0`;
     }
     // json document: emit the canonical JSON text as a PowQL string literal (the
     // embedded engine validates and stores it as a json document).
     if (value instanceof PowdbJsonParam)
-        return encodePowqlString(JSON.stringify(value.value));
+        return encodePowqlString(powdbJsonText(value, position), position);
     if (value === undefined || value === null)
         return 'null';
     if (value instanceof Date)
-        return `${BigInt(value.getTime()) * 1000n}`; // epoch micros (int column)
+        return `${powdbDateMicros(value, position)}`; // epoch micros (int column)
     if (typeof value === 'boolean')
         return value ? 'true' : 'false';
     if (typeof value === 'bigint')
         return value.toString();
     if (typeof value === 'number') {
         if (!Number.isFinite(value))
-            throw new errors_js_1.ValidationError(`[turbine] Non-finite number cannot be encoded for PowDB.`);
-        // `String(n)` renders an integer as an int literal (`42`) and a fractional
-        // number as a float literal (`4.2`) — PowQL distinguishes them by the dot.
-        return String(value);
+            throw new errors_js_1.ValidationError(`[turbine] Non-finite number cannot be encoded for PowDB${at}.`);
+        // Renders an integer as an int literal (`42`) and a fractional number as a
+        // float literal (`4.2`); PowQL distinguishes them by the dot.
+        return powqlNumberText(value);
     }
     if (typeof value === 'string')
-        return encodePowqlString(value);
-    throw new errors_js_1.ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal.`);
+        return encodePowqlString(value, position);
+    throw new errors_js_1.ValidationError(`[turbine] Value of type ${typeof value} cannot be encoded as a PowDB literal${at}.`);
+}
+/**
+ * Render a finite JS number as PowQL numeric text.
+ *
+ * `String(n)` is used verbatim for every ordinary magnitude (an integer becomes
+ * `42`, a fractional number `4.2`), but it switches to exponential notation at
+ * `1e21` and below `1e-6` (`1e+21`, `1.5e-7`), which the PowQL lexer does not
+ * accept as a number token (and which the float path would further mangle into
+ * `1e+21.0`). Those two ranges are expanded into plain decimal digits so any
+ * finite double round-trips to a literal the engine can parse.
+ */
+function powqlNumberText(n) {
+    const s = String(n);
+    if (!s.includes('e') && !s.includes('E'))
+        return s;
+    // Integer-valued doubles (|n| >= 1e21) expand exactly through BigInt.
+    if (Number.isInteger(n))
+        return BigInt(n).toString();
+    const m = /^(-?)(\d+)(?:\.(\d+))?[eE]([+-]?\d+)$/.exec(s);
+    if (!m) {
+        throw new errors_js_1.ValidationError(`[turbine] Number ${s} cannot be rendered as a PowDB literal.`);
+    }
+    const sign = m[1] ?? '';
+    const intPart = m[2] ?? '';
+    const fracPart = m[3] ?? '';
+    const exp = Number(m[4]);
+    const digits = intPart + fracPart;
+    const pointPos = intPart.length + exp;
+    let body;
+    if (pointPos <= 0)
+        body = `0.${'0'.repeat(-pointPos)}${digits}`;
+    else if (pointPos >= digits.length)
+        body = digits + '0'.repeat(pointPos - digits.length);
+    else
+        body = `${digits.slice(0, pointPos)}.${digits.slice(pointPos)}`;
+    return sign + body;
 }
 /**
  * The newest PowDB engine LINE (major.minor) whose lexer escape handling
@@ -1707,8 +1779,21 @@ function encodePowqlLiteral(value) {
  * already covers every 0.19.x patch — no bump is needed for 0.19.1.
  */
 exports.POWQL_LEXER_TESTED_CEILING = '0.19';
-/** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
-function encodePowqlString(s) {
+/**
+ * Escape a string into a PowQL `"…"` literal, matching the engine lexer's
+ * escape rules.
+ *
+ * A raw NUL (U+0000) is REFUSED rather than emitted: the lexer defines no `\0`
+ * escape (its escape set is exactly `\"`, `\\`, `\n`, `\t`, see
+ * {@link POWQL_LEXER_TESTED_CEILING}), so a NUL would travel into the query
+ * text as a raw byte and any layer that treats that text as a C string would
+ * silently truncate the statement there.
+ */
+function encodePowqlString(s, position) {
+    if (s.includes('\0')) {
+        throw new errors_js_1.ValidationError(`[turbine] String value${position ? ` (${position})` : ''} contains a NUL byte (U+0000), which PowQL string ` +
+            'literals cannot represent. Strip it before writing.');
+    }
     let out = '"';
     for (const ch of s) {
         if (ch === '\\')
@@ -1738,7 +1823,7 @@ function materializePowql(powql, params) {
         if (idx < 0 || idx >= params.length) {
             throw new errors_js_1.ValidationError(`[turbine] PowQL placeholder $${n} has no bound parameter (have ${params.length}).`);
         }
-        return encodePowqlLiteral(params[idx]);
+        return encodePowqlLiteral(params[idx], `parameter $${n}`);
     });
 }
 /**