turbine-orm 0.44.0 → 0.45.0

package/dist/cjs/powdb.js

@@ -254,6 +254,7 @@ const POWDB_FEATURE_MIN_VERSION = {
     docFieldIndexes: '0.13',
     serverJoins: '0.13',
     nestedProjections: '0.18',
+    entityLinks: '0.19',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -264,6 +265,9 @@ const POWDB_FEATURE_MIN_VERSION = {
  * never inferred from a bare construction. `nestedProjections` stays OFF for
  * the same reason: it changes the generated PowQL for every `with` query, and
  * an unprobed engine below 0.18 would reject the syntax outright.
+ * `entityLinks` stays OFF for a stronger reason still: declaring a link
+ * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
+ * so it must only ever light up behind a real version probe.
  */
 exports.ALL_POWDB_CAPABILITIES = {
     engineVersion: null,
@@ -272,6 +276,7 @@ exports.ALL_POWDB_CAPABILITIES = {
     introspection: true,
     serverJoins: true,
     nestedProjections: false,
+    entityLinks: false,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -301,6 +306,7 @@ function capabilitiesFromVersion(version, opts = {}) {
             introspection: false,
             serverJoins: false,
             nestedProjections: false,
+            entityLinks: false,
             nativeRaw: false,
         };
     }
@@ -311,6 +317,7 @@ function capabilitiesFromVersion(version, opts = {}) {
         docFieldIndexes: atLeastVersion(sem, 0, 13),
         serverJoins: atLeastVersion(sem, 0, 13),
         nestedProjections: atLeastVersion(sem, 0, 18),
+        entityLinks: atLeastVersion(sem, 0, 19),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -810,6 +817,15 @@ function wrapPowdbError(err) {
         return new errors_js_1.ConnectionError(`[turbine] PowDB could not open the directory read-only: ${msg}. Open it once with a writable handle to ` +
             'flush the WAL (recover the directory), then reopen it read-only for snapshot serving.', { cause: err });
     }
+    // Catalog-version mismatch → ConnectionError (E004). A pre-0.19 binary/addon
+    // cannot open a data directory whose catalog was upgraded to v7 by a `link`
+    // declaration (the upgrade is one-way). It is an open-time connection failure,
+    // not a query defect, so it runs among the connection families BEFORE the
+    // generic validation regexes below.
+    if (/unsupported catalog version/i.test(msg)) {
+        return new errors_js_1.ConnectionError(`[turbine] PowDB could not open the data directory: ${msg}. This directory uses a newer PowDB catalog ` +
+            'format (a `link` declaration upgrades it to v7); upgrade the PowDB addon/server to a version that can read it.', { cause: err });
+    }
     // Per-query deadline → TimeoutError (E002). Message-path so it fires on the
     // embedded transport too (code is always 'GenericFailure' there); retryable.
     // Pass the engine prose through the message override (same pattern as the
@@ -1497,8 +1513,14 @@ function encodePowqlLiteral(value) {
  * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
  * the ceiling yet still routes through the string wire is refused rather than
  * materialized.
+ *
+ * Verification for the 0.19 line: `crates/query/src/lexer.rs` is byte-identical
+ * between v0.18.0 and v0.19.0 (empty git diff), and `link` was already a lexer
+ * keyword at 0.18.0. The 0.19 entity-links surface adds new STATEMENTS built from
+ * pre-existing tokens, so the tokenization / escape surface this ceiling guards is
+ * unmoved.
  */
-exports.POWQL_LEXER_TESTED_CEILING = '0.18';
+exports.POWQL_LEXER_TESTED_CEILING = '0.19';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';

package/dist/cjs/powql.js

@@ -360,7 +360,11 @@ class PowqlInterface {
                     conds.push(opVal === null ? `${ref} is null` : `${lhs} = ${this.bind(opVal, params, insensitive)}`);
                     break;
                 case 'not':
-                    conds.push(opVal === null ? `${ref} is not null` : `not (${lhs} = ${this.bind(opVal, params, insensitive)})`);
+                    // Spell as `lhs != $N` (not `not (lhs = $N)`) so a missing-value row is
+                    // EXCLUDED, matching SQL null semantics on PowDB >= 0.18.2. Behavior-neutral
+                    // on older engines (pre-0.18.2 `!=` MATCHED missing rows exactly like the
+                    // old `not (...)` spelling), so no capability gate is needed.
+                    conds.push(opVal === null ? `${ref} is not null` : `${lhs} != ${this.bind(opVal, params, insensitive)}`);
                     break;
                 case 'gt':
                     conds.push(`${lhs} > ${this.bind(opVal, params, insensitive)}`);
@@ -502,11 +506,17 @@ class PowqlInterface {
     /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
     buildInList(lhs, values, params, insensitive, negate) {
         if (!Array.isArray(values) || values.length === 0) {
-            // `in []` matches nothing; `not in []` matches everything.
+            // `in []` matches nothing; `not in []` matches everything (SQL parity requires a
+            // missing-value row to match `notIn []`, so NO presence guard is appended here).
             return negate ? '(1 = 1)' : this.alwaysFalse();
         }
         const items = values.map((v) => this.bind(v, params, insensitive)).join(', ');
-        return `${lhs} ${negate ? 'not in' : 'in'} (${items})`;
+        if (negate) {
+            // PowQL `not in` matches missing-value rows, so append `and lhs is not null`
+            // for SQL null-semantics parity (non-empty list only, per the empty-list note above).
+            return `(${lhs} not in (${items}) and ${lhs} is not null)`;
+        }
+        return `${lhs} in (${items})`;
     }
     /**
      * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause

package/dist/powdb.d.ts

@@ -261,11 +261,19 @@ export interface PowdbCapabilities {
      * batched loaders.
      */
     nestedProjections: boolean;
+    /**
+     * ≥ 0.19: entity links (`link` DDL, scalar/block traversal). Capability is
+     * recognized (probe-only), but query generation deliberately does NOT consume
+     * links yet: turbine keeps composing its own nested projections (see the
+     * PowDB engine page for the rationale). Declaring a link permanently upgrades
+     * the on-disk catalog to v7, so this stays FALSE in ALL_POWDB_CAPABILITIES.
+     */
+    entityLinks: boolean;
     /** Networked only: server ≥ 0.13 AND the client exposes `queryNativeRaw`. */
     nativeRaw: boolean;
 }
 /** The feature-gate capability keys (everything except the version/nativeRaw metadata). */
-type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections';
+type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serverJoins' | 'nestedProjections' | 'entityLinks';
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
  * for a directly-constructed {@link PowdbPool} / {@link PowdbEmbeddedPool} that
@@ -275,6 +283,9 @@ type PowdbFeatureKey = 'jsonDocs' | 'docFieldIndexes' | 'introspection' | 'serve
  * never inferred from a bare construction. `nestedProjections` stays OFF for
  * the same reason: it changes the generated PowQL for every `with` query, and
  * an unprobed engine below 0.18 would reject the syntax outright.
+ * `entityLinks` stays OFF for a stronger reason still: declaring a link
+ * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
+ * so it must only ever light up behind a real version probe.
  */
 export declare const ALL_POWDB_CAPABILITIES: PowdbCapabilities;
 /**
@@ -610,8 +621,14 @@ export declare function encodePowqlLiteral(value: unknown): string;
  * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
  * the ceiling yet still routes through the string wire is refused rather than
  * materialized.
+ *
+ * Verification for the 0.19 line: `crates/query/src/lexer.rs` is byte-identical
+ * between v0.18.0 and v0.19.0 (empty git diff), and `link` was already a lexer
+ * keyword at 0.18.0. The 0.19 entity-links surface adds new STATEMENTS built from
+ * pre-existing tokens, so the tokenization / escape surface this ceiling guards is
+ * unmoved.
  */
-export declare const POWQL_LEXER_TESTED_CEILING = "0.18";
+export declare const POWQL_LEXER_TESTED_CEILING = "0.19";
 /**
  * Substitute every `$N` placeholder in a generator-produced PowQL template with
  * the encoded literal of `params[N-1]`. Safe because the template is produced by

package/dist/powdb.js

@@ -197,6 +197,7 @@ const POWDB_FEATURE_MIN_VERSION = {
     docFieldIndexes: '0.13',
     serverJoins: '0.13',
     nestedProjections: '0.18',
+    entityLinks: '0.19',
 };
 /**
  * Trusted-caller default: every FEATURE gate on, engine version unknown. Used
@@ -207,6 +208,9 @@ const POWDB_FEATURE_MIN_VERSION = {
  * never inferred from a bare construction. `nestedProjections` stays OFF for
  * the same reason: it changes the generated PowQL for every `with` query, and
  * an unprobed engine below 0.18 would reject the syntax outright.
+ * `entityLinks` stays OFF for a stronger reason still: declaring a link
+ * one-way-upgrades the on-disk catalog to v7 and locks out pre-0.19 binaries,
+ * so it must only ever light up behind a real version probe.
  */
 export const ALL_POWDB_CAPABILITIES = {
     engineVersion: null,
@@ -215,6 +219,7 @@ export const ALL_POWDB_CAPABILITIES = {
     introspection: true,
     serverJoins: true,
     nestedProjections: false,
+    entityLinks: false,
     nativeRaw: false,
 };
 /** Parse a PowDB semver prefix (`0.13.0`, `0.13`, `1.2.3-rc`) into components, or `null`. */
@@ -244,6 +249,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
             introspection: false,
             serverJoins: false,
             nestedProjections: false,
+            entityLinks: false,
             nativeRaw: false,
         };
     }
@@ -254,6 +260,7 @@ export function capabilitiesFromVersion(version, opts = {}) {
         docFieldIndexes: atLeastVersion(sem, 0, 13),
         serverJoins: atLeastVersion(sem, 0, 13),
         nestedProjections: atLeastVersion(sem, 0, 18),
+        entityLinks: atLeastVersion(sem, 0, 19),
         nativeRaw: Boolean(opts.hasNativeRaw) && atLeastVersion(sem, 0, 13),
     };
 }
@@ -753,6 +760,15 @@ export function wrapPowdbError(err) {
         return new ConnectionError(`[turbine] PowDB could not open the directory read-only: ${msg}. Open it once with a writable handle to ` +
             'flush the WAL (recover the directory), then reopen it read-only for snapshot serving.', { cause: err });
     }
+    // Catalog-version mismatch → ConnectionError (E004). A pre-0.19 binary/addon
+    // cannot open a data directory whose catalog was upgraded to v7 by a `link`
+    // declaration (the upgrade is one-way). It is an open-time connection failure,
+    // not a query defect, so it runs among the connection families BEFORE the
+    // generic validation regexes below.
+    if (/unsupported catalog version/i.test(msg)) {
+        return new ConnectionError(`[turbine] PowDB could not open the data directory: ${msg}. This directory uses a newer PowDB catalog ` +
+            'format (a `link` declaration upgrades it to v7); upgrade the PowDB addon/server to a version that can read it.', { cause: err });
+    }
     // Per-query deadline → TimeoutError (E002). Message-path so it fires on the
     // embedded transport too (code is always 'GenericFailure' there); retryable.
     // Pass the engine prose through the message override (same pattern as the
@@ -1439,8 +1455,14 @@ export function encodePowqlLiteral(value) {
  * {@link PowdbEmbeddedPool.exec}): an embedded addon whose engine line exceeds
  * the ceiling yet still routes through the string wire is refused rather than
  * materialized.
+ *
+ * Verification for the 0.19 line: `crates/query/src/lexer.rs` is byte-identical
+ * between v0.18.0 and v0.19.0 (empty git diff), and `link` was already a lexer
+ * keyword at 0.18.0. The 0.19 entity-links surface adds new STATEMENTS built from
+ * pre-existing tokens, so the tokenization / escape surface this ceiling guards is
+ * unmoved.
  */
-export const POWQL_LEXER_TESTED_CEILING = '0.18';
+export const POWQL_LEXER_TESTED_CEILING = '0.19';
 /** Escape a string into a PowQL `"…"` literal, matching the engine lexer's escape rules. */
 function encodePowqlString(s) {
     let out = '"';

package/dist/powql.js

@@ -324,7 +324,11 @@ export class PowqlInterface {
                     conds.push(opVal === null ? `${ref} is null` : `${lhs} = ${this.bind(opVal, params, insensitive)}`);
                     break;
                 case 'not':
-                    conds.push(opVal === null ? `${ref} is not null` : `not (${lhs} = ${this.bind(opVal, params, insensitive)})`);
+                    // Spell as `lhs != $N` (not `not (lhs = $N)`) so a missing-value row is
+                    // EXCLUDED, matching SQL null semantics on PowDB >= 0.18.2. Behavior-neutral
+                    // on older engines (pre-0.18.2 `!=` MATCHED missing rows exactly like the
+                    // old `not (...)` spelling), so no capability gate is needed.
+                    conds.push(opVal === null ? `${ref} is not null` : `${lhs} != ${this.bind(opVal, params, insensitive)}`);
                     break;
                 case 'gt':
                     conds.push(`${lhs} > ${this.bind(opVal, params, insensitive)}`);
@@ -466,11 +470,17 @@ export class PowqlInterface {
     /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
     buildInList(lhs, values, params, insensitive, negate) {
         if (!Array.isArray(values) || values.length === 0) {
-            // `in []` matches nothing; `not in []` matches everything.
+            // `in []` matches nothing; `not in []` matches everything (SQL parity requires a
+            // missing-value row to match `notIn []`, so NO presence guard is appended here).
             return negate ? '(1 = 1)' : this.alwaysFalse();
         }
         const items = values.map((v) => this.bind(v, params, insensitive)).join(', ');
-        return `${lhs} ${negate ? 'not in' : 'in'} (${items})`;
+        if (negate) {
+            // PowQL `not in` matches missing-value rows, so append `and lhs is not null`
+            // for SQL null-semantics parity (non-empty list only, per the empty-list note above).
+            return `(${lhs} not in (${items}) and ${lhs} is not null)`;
+        }
+        return `${lhs} in (${items})`;
     }
     /**
      * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {
@@ -108,8 +108,8 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@types/node": "^26.1.0",
-    "@zvndev/powdb-client": "^0.18.1",
-    "@zvndev/powdb-embedded": "^0.18.1",
+    "@zvndev/powdb-client": "^0.19.0",
+    "@zvndev/powdb-embedded": "^0.19.0",
     "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",