turbine-orm 0.32.2 → 0.34.0

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/dist/sqlite.js

@@ -370,6 +370,8 @@ export const sqliteDialect = {
     supportsListenNotify: false,
     supportsRLS: false,
     supportsAdvisoryLock: false,
+    // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
+    supportsLateralJoin: false,
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.32.2",
+  "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",