turbine-orm 0.33.0 → 0.34.0

package/dist/query/builder.js

@@ -4491,7 +4491,18 @@ export class QueryInterface {
         const extract = this.dialect.buildJsonPathExtract(`${prefix}${this.q(col)}`, this.p(params.length));
         const lhs = spec.type === 'numeric' ? this.castJsonNumeric(extract) : extract;
         const dir = spec.direction?.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-        return `${lhs} ${dir}${this.nullsSuffix(spec.nulls)}`;
+        // Rows whose document lacks the path extract to NULL. Without a nulls
+        // clause, Postgres DESC defaults to NULLS FIRST, which both diverges from
+        // pick-row ordering (NULLS LAST both directions since 0.33) and from
+        // engines whose path ordering is nulls-last in both directions. Default to
+        // NULLS LAST in BOTH directions unless the caller set `nulls` explicitly;
+        // the grammar gate matches nullsSuffix.
+        const nullsSql = spec.nulls
+            ? this.nullsSuffix(spec.nulls)
+            : this.dialect.name === 'postgresql' || this.dialect.name === 'sqlite'
+                ? ' NULLS LAST'
+                : '';
+        return `${lhs} ${dir}${nullsSql}`;
     }
     /**
      * Compile a relation ordering term. For a to-many relation the only allowed

package/dist/query/types.d.ts

@@ -618,6 +618,11 @@ export interface JsonPathGroupKey {
  * json/jsonb column, e.g. `SUM((col #>> $n::text[])::numeric)`. The arg key
  * is the result alias. `_sum`/`_avg` always cast numeric (a text sum is
  * meaningless); `_min`/`_max` compare as text unless `type: 'numeric'`.
+ *
+ * Engine note: when a group has NO value at the path, SQL engines return
+ * `null` for `_sum` (SUM over zero rows), while PowDB returns `0` (engine
+ * sum semantics). Treat `null` and `0` totals as equivalent when a group can
+ * be empty at the path.
  */
 export interface JsonPathAggregateTarget {
     /** json/jsonb column (camelCase field name, columnMap-resolved). */
@@ -758,15 +763,37 @@ export interface RelationFilter {
     is?: Record<string, unknown>;
     isNot?: Record<string, unknown>;
 }
-/** JSONB query operators for where clauses */
+/**
+ * JSONB query operators for where clauses.
+ *
+ * PowDB (`turbine-orm/powdb`) semantic deltas. The PowDB engine evaluates
+ * `->` path filters with full type knowledge, so a few behaviours differ from
+ * the Postgres `#>>`-text driver (documented, never silently wrong):
+ *   - `{ path, equals: null }` matches JSON null OR a MISSING key on PowDB
+ *     (compiles to `is null`), whereas the PG driver compares extracted text
+ *     against the string `'null'` and matches only a JSON string `"null"`.
+ *   - equality is TYPE-STRICT on PowDB: `{ path, equals: 7 }` matches a stored
+ *     JSON int `7` but not `7.0` or the JSON string `"7"` (PG text-extraction
+ *     matches `equals: 7` against the string `"7"`). Range ops (`gt`/`lt`/…)
+ *     still coerce int/float numerically.
+ *   - a digit-only path segment (`path: ['tags', '0']`) is an ARRAY INDEX on
+ *     both PowDB and the SQL engines (a json object key that is literally `"0"`
+ *     is likewise addressed by index).
+ *   - `contains`, and `equals` WITHOUT a `path` (whole-document containment),
+ *     throw `UnsupportedFeatureError` (E017) on PowDB: PowQL has no containment
+ *     operator.
+ */
 export interface JsonFilter {
-    /** Access nested path via #>> operator */
+    /**
+     * Access nested path via `#>>` operator (Postgres) / `->` path (PowDB). A
+     * digit-only segment (`'0'`) is treated as an array index on every engine.
+     */
     path?: string[];
-    /** Exact match: column @> value::jsonb (containment) */
+    /** Exact match: `column @> value::jsonb` (containment). On PowDB, requires `path` and compares the typed value (throws E017 without `path`). */
     equals?: unknown;
-    /** Containment check: column @> value::jsonb */
+    /** Containment check: `column @> value::jsonb`. Unsupported on PowDB (E017: PowQL has no containment operator). */
     contains?: unknown;
-    /** Key existence check: column ? key */
+    /** Key existence check: `column ? key`. */
     hasKey?: string;
     /**
      * Greater-than comparison of the value at `path` (required). Numbers cast
@@ -897,7 +924,13 @@ export interface JsonPathOrderBy {
     direction?: OrderDirection;
     /** Comparison kind for the extracted value. Defaults to `'text'`; `'numeric'` adds a numeric cast. */
     type?: 'numeric' | 'text';
-    /** NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}). */
+    /**
+     * NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}).
+     * Rows whose document lacks the path extract to NULL and sort LAST in BOTH
+     * directions by default (matching pick-row ordering and the PowDB engine
+     * contract, so ordering is predictable across drivers); set `nulls` to
+     * override on PostgreSQL / SQLite.
+     */
     nulls?: 'first' | 'last';
 }
 /**

package/dist/schema-builder.d.ts

@@ -126,6 +126,42 @@ export interface CheckDef {
     /** Raw SQL boolean expression, e.g. `price > cost`. */
     expression: string;
 }
+/** A plain (column-list) index declaration. */
+export interface ColumnIndexDef {
+    /** camelCase field name(s) the index covers. */
+    columns: string[];
+    /** Whether the index enforces uniqueness. */
+    unique?: boolean;
+    /** Optional explicit index name (auto-derived when omitted). */
+    name?: string;
+}
+/**
+ * A doc-field expression index on a JSON document column (PowDB ≥ 0.13).
+ * Indexes the value at `docField-><path>` inside the json document, so a
+ * `JsonFilter`/`orderBy` on that path can use an index instead of a scan.
+ */
+export interface DocFieldIndexDef {
+    /** camelCase field name of the json document column. */
+    docField: string;
+    /** JSON path into the document: string keys and integer array indexes. */
+    path: (string | number)[];
+    /** Whether the expression index enforces uniqueness. */
+    unique?: boolean;
+    /** Optional explicit index name (auto-derived when omitted). */
+    name?: string;
+}
+/**
+ * A single index declaration on a table: either a plain column-list index
+ * ({@link ColumnIndexDef}) or a doc-field expression index into a json column
+ * ({@link DocFieldIndexDef}).
+ *
+ * Consumed today by the PowDB DDL generator (`powqlSchemaDDL`) and carried onto
+ * {@link import('./schema.js').IndexMetadata} by `schemaDefToMetadata`. The SQL
+ * DDL generators (`schema-sql.ts` / `schemaDiff`) do NOT consume these yet.
+ */
+export type SchemaIndexDef = ColumnIndexDef | DocFieldIndexDef;
+/** Type guard: is this index declaration a doc-field expression index? */
+export declare function isDocFieldIndexDef(idx: SchemaIndexDef): idx is DocFieldIndexDef;
 export interface TableDef {
     /**
      * DDL-facing table name (snake_case). This is the name used when generating
@@ -159,6 +195,13 @@ export interface TableDef {
     manyToMany?: readonly ManyToManyDef[];
     /** Table-level `CHECK` constraints. */
     checks?: readonly CheckDef[];
+    /**
+     * Index declarations for this table (plain column indexes and/or PowDB
+     * doc-field expression indexes). Consumed by the PowDB DDL generator
+     * (`powqlSchemaDDL`) and carried onto `IndexMetadata` by
+     * `schemaDefToMetadata`; the SQL DDL generators do not consume them yet.
+     */
+    indexes?: readonly SchemaIndexDef[];
 }
 /**
  * User-facing input shape for a single table when using the object format.
@@ -171,8 +214,10 @@ export interface TableInput {
     manyToMany?: readonly ManyToManyDef[];
     /** Optional table-level CHECK constraints */
     checks?: readonly CheckDef[];
+    /** Optional index declarations (plain column and/or doc-field expression) */
+    indexes?: readonly SchemaIndexDef[];
     /** Column definitions keyed by camelCase field name */
-    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | readonly CheckDef[] | undefined;
+    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | readonly CheckDef[] | readonly SchemaIndexDef[] | undefined;
 }
 export interface SchemaDef {
     /**

package/dist/schema-builder.js

@@ -96,6 +96,10 @@ function resolveColumn(def) {
         check: def.check ?? null,
     };
 }
+/** Type guard: is this index declaration a doc-field expression index? */
+export function isDocFieldIndexDef(idx) {
+    return 'docField' in idx && typeof idx.docField === 'string';
+}
 /** Check if a value is a TableDef (from legacy table() builder) */
 function isTableDef(v) {
     return typeof v === 'object' && v !== null && 'columns' in v && 'name' in v;
@@ -139,7 +143,17 @@ export function defineSchema(input, options) {
             let pk;
             let m2m;
             let checks;
+            let indexes;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'indexes') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "indexes" must be an array of index declarations`);
+                        }
+                        indexes = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'manyToMany') {
                     if (def !== undefined) {
                         if (!Array.isArray(def)) {
@@ -199,6 +213,7 @@ export function defineSchema(input, options) {
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
                 ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
                 ...(checks && checks.length > 0 ? { checks } : {}),
+                ...(indexes && indexes.length > 0 ? { indexes } : {}),
             };
         }
     }

package/dist/schema-metadata.d.ts

@@ -24,10 +24,12 @@
  *     the same conservative auto-`manyToMany` treatment as introspection.
  *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
  *     {@link applyManyToManyRelations} (additive, never clobbering).
- *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
- *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
- *     and the dev-mode missing-index warning stay silent instead of
- *     producing blanket false positives.
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
  *
  * @example
  * ```ts
@@ -67,10 +69,14 @@ import { type SchemaDef } from './schema-builder.js';
  *   - Explicit `manyToMany` declarations → merged additively.
  *   - Schema-level `enums`.
  *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
  * What SchemaDef cannot express (and how it degrades):
- *   - Indexes → every table gets `indexes: []`, which keeps
- *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
- *     false positives on code-first metadata.
  *   - Views → never marked (`isView` is introspection-only).
  *   - Composite foreign keys → `references:` is single-column by design.
  */

package/dist/schema-metadata.js

@@ -24,10 +24,12 @@
  *     the same conservative auto-`manyToMany` treatment as introspection.
  *   - Explicit `manyToMany` declarations on the SchemaDef are merged via
  *     {@link applyManyToManyRelations} (additive, never clobbering).
- *   - `indexes` is always `[]` — SchemaDef cannot express indexes, and an
- *     empty list keeps `schemaHasIndexInfo()` false so the index advisor
- *     and the dev-mode missing-index warning stay silent instead of
- *     producing blanket false positives.
+ *   - `indexes` carries any declared `TableDef.indexes` (plain column and/or
+ *     PowDB doc-field expression indexes); a table with none declared gets
+ *     `[]`, which keeps `schemaHasIndexInfo()` false so the index advisor and
+ *     the dev-mode missing-index warning stay silent instead of producing
+ *     blanket false positives. Doc-field (docPath) indexes are ignored by the
+ *     advisor, so a doc-only index set never flips `schemaHasIndexInfo()`.
  *
  * @example
  * ```ts
@@ -42,9 +44,10 @@
  * // → usable anywhere SchemaMetadata is expected (e.g. turbinePowDB, TurbineClient)
  * ```
  */
+import { ValidationError } from './errors.js';
 import { addAutoManyToManyRelations, buildRelationsFromForeignKeys, isUnknownTsType, } from './introspect.js';
 import { camelToSnake, isDateType, pgArrayType, pgTypeToTs, } from './schema.js';
-import { applyManyToManyRelations } from './schema-builder.js';
+import { applyManyToManyRelations, isDocFieldIndexDef, } from './schema-builder.js';
 // ---------------------------------------------------------------------------
 // DDL type → Postgres udt_name (what introspection reads from the catalog)
 // ---------------------------------------------------------------------------
@@ -94,6 +97,67 @@ function resolveColumnName(raw, target) {
     return camelToSnake(raw);
 }
 // ---------------------------------------------------------------------------
+// Index declarations → IndexMetadata
+// ---------------------------------------------------------------------------
+/**
+ * Render a doc-field JSON path into an illustrative PowQL fragment for the
+ * `IndexMetadata.definition` field (debuggability only; the authoritative,
+ * lexer-exact emission lives in `powqlSchemaDDL`). String segments are shown
+ * double-quoted, integer array indexes bare.
+ */
+function docPathFragment(column, path) {
+    const segs = path.map((s) => (typeof s === 'number' ? `->${s}` : `->"${s}"`)).join('');
+    return `(.${column}${segs})`;
+}
+/**
+ * Convert a table's {@link SchemaIndexDef} list into {@link IndexMetadata}.
+ * A doc-field index carries `docPath` and `columns: [<json column>]`; a plain
+ * column index carries its snake_case column list and no `docPath`. Names are
+ * auto-derived (`<table>_<cols>_idx`) when not supplied.
+ */
+function mapIndexes(tableDef, declared) {
+    if (!declared || declared.length === 0)
+        return [];
+    const out = [];
+    for (const idx of declared) {
+        if (isDocFieldIndexDef(idx)) {
+            const column = camelToSnake(idx.docField);
+            const segPart = idx.path.map((s) => (typeof s === 'number' ? String(s) : s)).join('_');
+            const name = idx.name ?? `${tableDef.name}_${column}_${segPart}_idx`;
+            // Validate numeric (array-index) segments up front: PowDB rejects a
+            // negative / fractional / NaN JSON-path index at migration time with an
+            // opaque parse error, so fail here with a typed ValidationError naming the
+            // index instead of emitting malformed PowQL later.
+            for (const seg of idx.path) {
+                if (typeof seg === 'number' && (!Number.isInteger(seg) || seg < 0)) {
+                    throw new ValidationError(`[turbine] Doc-field index "${name}" on "${tableDef.name}": array-index path segment ${seg} must be a ` +
+                        'non-negative integer (a JSON array index). Use a string for an object key.');
+                }
+            }
+            out.push({
+                name,
+                columns: [column],
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}${docPathFragment(column, idx.path)}`,
+                docPath: [...idx.path],
+                declared: true,
+            });
+        }
+        else {
+            const columns = idx.columns.map(camelToSnake);
+            const name = idx.name ?? `${tableDef.name}_${columns.join('_')}_idx`;
+            out.push({
+                name,
+                columns,
+                unique: idx.unique ?? false,
+                definition: `${idx.unique ? 'unique ' : 'index '}(${columns.join(', ')})`,
+                declared: true,
+            });
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
 // The converter
 // ---------------------------------------------------------------------------
 /**
@@ -119,10 +183,14 @@ function resolveColumnName(raw, target) {
  *   - Explicit `manyToMany` declarations → merged additively.
  *   - Schema-level `enums`.
  *
+ * What maps (continued):
+ *   - `indexes` → declared `TableDef.indexes` become `IndexMetadata` (plain
+ *     column indexes and PowDB doc-field expression indexes, the latter
+ *     carrying `docPath`). A table with no declared indexes gets `[]`, keeping
+ *     `schemaHasIndexInfo()` false so index-advisor consumers produce no false
+ *     positives on index-less code-first metadata.
+ *
  * What SchemaDef cannot express (and how it degrades):
- *   - Indexes → every table gets `indexes: []`, which keeps
- *     `schemaHasIndexInfo()` false so index-advisor consumers produce no
- *     false positives on code-first metadata.
  *   - Views → never marked (`isView` is introspection-only).
  *   - Composite foreign keys → `references:` is single-column by design.
  */
@@ -299,9 +367,12 @@ export function schemaDefToMetadata(def) {
             primaryKey: pk,
             uniqueColumns,
             relations: relationsByTable.get(tableDef.name) ?? {},
-            // SchemaDef cannot express indexes. An empty list keeps
-            // schemaHasIndexInfo() false → no index-advisor false positives.
-            indexes: [],
+            // Declared `indexes` (plain column + doc-field expression) carry through;
+            // an undeclared table gets `[]`, which keeps schemaHasIndexInfo() false so
+            // the index advisor stays silent. Doc-field (docPath) indexes are ignored
+            // by the advisor entirely (see index-advisor.ts), so a doc-only index set
+            // never flips schemaHasIndexInfo() and never produces FK false positives.
+            indexes: mapIndexes(tableDef, tableDef.indexes),
         };
     }
     const enums = {};

package/dist/schema.d.ts

@@ -170,6 +170,31 @@ export interface IndexMetadata {
     columns: string[];
     unique: boolean;
     definition: string;
+    /**
+     * Set only for a PowDB doc-field expression index: the JSON path (string keys
+     * and integer array indexes) into the single json document column named by
+     * `columns[0]`. When present, `columns` is `[<json column>]` and the index
+     * targets `columns[0]-><segments>` rather than the raw column.
+     *
+     * Consumed by the PowDB DDL generator (`powqlSchemaDDL` emits
+     * `alter T add index (.col->"seg")`). The missing-FK index advisor ignores
+     * doc-field indexes entirely (a JSON expression index never covers an
+     * equality probe on the raw column). Doc-field indexes are invisible to
+     * `describe`-based introspection, so they do NOT round-trip through
+     * introspection.
+     */
+    docPath?: (string | number)[];
+    /**
+     * Set for indexes DECLARED in a code-first `defineSchema` (`TableDef.indexes`)
+     * rather than read from a live database by introspection. The SQL DDL
+     * generators (`schema-sql.ts` / `schemaDiff`) do NOT emit these yet, so a
+     * declared index does not reflect a real database index on the SQL engines.
+     * The missing-FK index advisor therefore treats declared indexes as
+     * "index-info unknown" (same as an index-less schema): counting them would
+     * both arm blanket FK false positives and suppress warnings for indexes that
+     * were never created. Introspected metadata never sets this.
+     */
+    declared?: boolean;
 }
 /** Map a Postgres type to its TypeScript equivalent */
 export declare function pgTypeToTs(pgType: string, nullable: boolean): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.33.0",
+  "version": "0.34.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": {
@@ -103,11 +103,11 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@types/node": "^26.1.0",
+    "@zvndev/powdb-client": "^0.13.0",
+    "@zvndev/powdb-embedded": "^0.13.0",
     "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",
-    "@zvndev/powdb-client": "^0.8.0",
-    "@zvndev/powdb-embedded": "^0.8.0",
     "mssql": "^12.7.0",
     "mysql2": "^3.22.5",
     "size-limit": "^12.1.0",