turbine-orm 0.60.1 → 0.62.0

package/dist/powql.js

@@ -41,6 +41,10 @@ import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isPowdbDatetim
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
+// The privilege sentinel and its resolver: `includePii` / `allowFullTableScan`
+// are unlocked ONLY by the UNSAFE symbol, on this engine exactly as on the SQL
+// engines, so a spread request body cannot turn either on here either.
+import { assertDirectionToken, resolveUnsafeFlag, UNSAFE } from './query/types.js';
 import { escapeLike } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
@@ -954,6 +958,21 @@ export class PowqlInterface {
      * contract): for identical cross-engine results pass `nulls: 'last'`
      * explicitly on Postgres, which defaults nulls-first for `desc`.
      */
+    /**
+     * Validate one orderBy direction token and return the PowQL keyword.
+     *
+     * Every direction site on this engine used to be spelled
+     * `x === 'desc' ? 'desc' : 'asc'`, so `'DESC'`, a token the CORE explicitly
+     * accepts and honours, compiled to `asc` here: identical application code
+     * sorted one way on Postgres and silently the opposite way on PowDB. The rule
+     * is core's {@link assertDirectionToken}, reused rather than re-derived, so
+     * the two engines cannot drift again. `undefined` stays "not specified"
+     * (defaults asc); `null` is a VALUE and is refused like any other bad token.
+     */
+    dirKeyword(value, context) {
+        assertDirectionToken(value, context);
+        return typeof value === 'string' && value.toLowerCase() === 'desc' ? 'desc' : 'asc';
+    }
     buildOrder(orderBy, params, alias) {
         if (!orderBy)
             return '';
@@ -974,7 +993,7 @@ export class PowqlInterface {
                     if (spec.nulls === 'first') {
                         throw new UnsupportedFeatureError('NULLS FIRST placement', 'PowDB', `field "${field}": PowDB orders NULLs / missing keys LAST in both directions`);
                     }
-                    return `${this.ref(field, alias)} ${spec.sort === 'desc' ? 'desc' : 'asc'}`;
+                    return `${this.ref(field, alias)} ${this.dirKeyword(spec.sort, `orderBy on "${field}"`)}`;
                 }
                 // Name the actual feature in the refusal, a pick-row ordering
                 // reported as "vector / distance ordering" sends users hunting for
@@ -990,7 +1009,7 @@ export class PowqlInterface {
                                 : 'object-valued ordering';
                 throw new UnsupportedFeatureError(feature, 'PowDB', `field "${field}"`);
             }
-            return `${this.ref(field, alias)} ${dir === 'desc' ? 'desc' : 'asc'}`;
+            return `${this.ref(field, alias)} ${this.dirKeyword(dir, `orderBy on "${field}"`)}`;
         });
         return ` order ${parts.join(', ')}`;
     }
@@ -1008,7 +1027,7 @@ export class PowqlInterface {
         // `type: 'numeric'` casts a JSON STRING number for numeric ordering; native
         // JSON numbers already order numerically without a cast.
         const expr = spec.type === 'numeric' ? `cast(${pathExpr}, "float")` : pathExpr;
-        return `${expr} ${spec.direction === 'desc' ? 'desc' : 'asc'}`;
+        return `${expr} ${this.dirKeyword(spec.direction, `JSON-path orderBy on "${field}"`)}`;
     }
     // -------------------------------------------------------------------------
     // Execution plumbing
@@ -1153,7 +1172,7 @@ export class PowqlInterface {
             if (linkPlans.length)
                 this.attachLinkRows(entities, linkPlans, native);
             if (residualWith) {
-                await this.loadRelations(entities, residualWith, args.timeout, 0, { args, resolvedWhere }, args.includePii === true);
+                await this.loadRelations(entities, residualWith, args.timeout, 0, { args, resolvedWhere }, resolveUnsafeFlag(args.includePii, 'includePii'));
             }
             return entities;
         });
@@ -1176,7 +1195,7 @@ export class PowqlInterface {
             throw new UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
-        const cols = this.projectedColumns(args.select, args.omit, args.includePii === true);
+        const cols = this.projectedColumns(args.select, args.omit, resolveUnsafeFlag(args.includePii, 'includePii'));
         // Partition the `with` clause: nested-projection blocks vs loader residue.
         // A parent `distinct` never nests (distinct over a row containing a JSON
         // array is not a defined comparison), and a relation whose field name
@@ -1192,7 +1211,9 @@ export class PowqlInterface {
                 if (!opt)
                     continue;
                 const rel = this.meta.relations[relName];
-                const plan = rel && !cols.includes(relName) ? this.planNestedRelation(relName, rel, opt, args.includePii === true) : null;
+                const plan = rel && !cols.includes(relName)
+                    ? this.planNestedRelation(relName, rel, opt, resolveUnsafeFlag(args.includePii, 'includePii'))
+                    : null;
                 if (plan) {
                     nestedPlans.push(plan);
                     continue;
@@ -1202,7 +1223,7 @@ export class PowqlInterface {
                 // inside, only when a genuine candidate reaches it), else it stays on the
                 // loaders.
                 const linkPlan = rel && !cols.includes(relName)
-                    ? await this.planLinkPathRelation(relName, rel, opt, args.includePii === true, cols, linkPlans.length + 1)
+                    ? await this.planLinkPathRelation(relName, rel, opt, resolveUnsafeFlag(args.includePii, 'includePii'), cols, linkPlans.length + 1)
                     : null;
                 if (linkPlan)
                     linkPlans.push(linkPlan);
@@ -1295,7 +1316,7 @@ export class PowqlInterface {
             if (linkPlans.length)
                 this.attachLinkRows(entities, linkPlans, native);
             if (residualWith)
-                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
+                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, resolveUnsafeFlag(args.includePii, 'includePii'));
             return entities[0];
         });
     }
@@ -1311,7 +1332,7 @@ export class PowqlInterface {
             if (linkPlans.length)
                 this.attachLinkRows(entities, linkPlans, native);
             if (residualWith)
-                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, args.includePii === true);
+                await this.loadRelations(entities, residualWith, args.timeout, 0, undefined, resolveUnsafeFlag(args.includePii, 'includePii'));
             return entities[0];
         });
     }
@@ -1431,7 +1452,9 @@ export class PowqlInterface {
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
-                    includePii,
+                    // Re-entering the public findMany, so the opt-in has to be spelled
+                    // in its PUBLIC form (the sentinel); a plain `true` is refused there.
+                    includePii: includePii ? UNSAFE : undefined,
                 }));
                 for (const child of children) {
                     const k = this.joinKey(child[childKeyField]);
@@ -1536,7 +1559,8 @@ export class PowqlInterface {
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
-                includePii,
+                // Public findMany, so the sentinel form. See loadRelation above.
+                includePii: includePii ? UNSAFE : undefined,
             }));
             for (const t of targets)
                 targetByPk.set(String(t[targetPkField]), t);
@@ -2293,7 +2317,7 @@ export class PowqlInterface {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, args.allowFullTableScan, 'updateMany');
+            this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'updateMany');
             const setClause = this.buildUpdateAssignments(args.data, params);
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.qt}${filter} update { ${setClause} }`, params, args.timeout, 'updateMany');
@@ -2443,7 +2467,7 @@ export class PowqlInterface {
             const params = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);
-            this.assertCompiledWhere(where, args.allowFullTableScan, 'deleteMany');
+            this.assertCompiledWhere(where, resolveUnsafeFlag(args.allowFullTableScan, 'allowFullTableScan'), 'deleteMany');
             const filter = where ? ` filter ${where}` : '';
             const { rowCount } = await this.exec(`${this.qt}${filter} delete`, params, args.timeout, 'deleteMany');
             return { count: rowCount };
@@ -2582,7 +2606,7 @@ export class PowqlInterface {
                     const powfn = fn.slice(1); // sum/avg/min/max
                     // Same PII contract as the SQL engines: _min/_max return a stored cell.
                     if (fn === '_min' || fn === '_max') {
-                        assertAggregatePiiOptIn(this.table, this.meta, field, this.column(field).name, `aggregate ${fn}`, args.includePii);
+                        assertAggregatePiiOptIn(this.table, this.meta, field, this.column(field).name, `aggregate ${fn}`, resolveUnsafeFlag(args.includePii, 'includePii'));
                     }
                     acc[field] = await scalar(`${powfn}(${this.qt}${filter} { ${this.ref(field)} })`);
                 }
@@ -2636,7 +2660,7 @@ export class PowqlInterface {
             for (const entry of args.by) {
                 if (typeof entry === 'string') {
                     const col = this.column(entry);
-                    assertAggregatePiiOptIn(this.table, this.meta, entry, col.name, 'groupBy `by` key', args.includePii);
+                    assertAggregatePiiOptIn(this.table, this.meta, entry, col.name, 'groupBy `by` key', resolveUnsafeFlag(args.includePii, 'includePii'));
                     claim(entry, `column "${col.name}"`);
                     if (col.name !== entry)
                         claim(col.name, `column "${col.name}"`);
@@ -2650,7 +2674,7 @@ export class PowqlInterface {
                     if (!isJsonColumn(col)) {
                         throw new ValidationError(`[turbine] groupBy JSON group key on "${entry.field}" (table "${this.table}") requires a json column.`);
                     }
-                    assertAggregatePiiOptIn(this.table, this.meta, entry.field, col.name, 'groupBy JSON `by` key', args.includePii);
+                    assertAggregatePiiOptIn(this.table, this.meta, entry.field, col.name, 'groupBy JSON `by` key', resolveUnsafeFlag(args.includePii, 'includePii'));
                     this.assertJsonPath('group key', entry.field, entry.path);
                     const pathExpr = this.jsonPathExpr(col, entry.path, params);
                     const alias = entry.alias ?? String(entry.path[entry.path.length - 1]);
@@ -2701,7 +2725,7 @@ export class PowqlInterface {
                     if (target === true) {
                         const col = this.column(key);
                         if (fn === '_min' || fn === '_max') {
-                            assertAggregatePiiOptIn(this.table, this.meta, key, col.name, `groupBy ${fn}`, args.includePii);
+                            assertAggregatePiiOptIn(this.table, this.meta, key, col.name, `groupBy ${fn}`, resolveUnsafeFlag(args.includePii, 'includePii'));
                         }
                         claim(`${fn}_${col.name}`, `${fn} of column "${col.name}"`);
                         const inner = `.${col.name}`;
@@ -2716,7 +2740,7 @@ export class PowqlInterface {
                             throw new ValidationError(`[turbine] groupBy ${fn} target "${key}" on "${target.field}" (table "${this.table}") requires a json column.`);
                         }
                         if (fn === '_min' || fn === '_max') {
-                            assertAggregatePiiOptIn(this.table, this.meta, target.field, col.name, `groupBy ${fn} JSON target`, args.includePii);
+                            assertAggregatePiiOptIn(this.table, this.meta, target.field, col.name, `groupBy ${fn} JSON target`, resolveUnsafeFlag(args.includePii, 'includePii'));
                         }
                         this.assertJsonPath(`${fn} target "${key}"`, target.field, target.path);
                         const alwaysNumeric = fn === '_sum' || fn === '_avg';
@@ -2916,9 +2940,9 @@ export class PowqlInterface {
             if (spec.nulls === 'first') {
                 throw new UnsupportedFeatureError('NULLS FIRST placement', 'PowDB', `groupBy orderBy "${keyForMsg}": PowDB orders NULLs / missing keys LAST in both directions`);
             }
-            return spec.sort === 'desc' ? 'desc' : 'asc';
+            return this.dirKeyword(spec.sort, `groupBy orderBy "${keyForMsg}"`);
         }
-        return value === 'desc' ? 'desc' : 'asc';
+        return this.dirKeyword(value, `groupBy orderBy "${keyForMsg}"`);
     }
     // -------------------------------------------------------------------------
     // Streaming / unsupported
@@ -2955,7 +2979,8 @@ export class PowqlInterface {
         if (compiledWhere.length > 0)
             return;
         throw new ValidationError(`[turbine] ${action} on "${this.table}" refused: the \`where\` clause is empty. ` +
-            `Pass \`allowFullTableScan: true\` to opt in, or check that your filter values are defined.`);
+            "Pass `allowFullTableScan: UNSAFE` to opt in (import { UNSAFE } from 'turbine-orm'), " +
+            'or check that your filter values are defined.');
     }
 }
 /** Coerce a group-key scalar string by the column's TS type (numbers/bools). */

package/dist/prisma-compat.d.ts

@@ -40,6 +40,11 @@
  *   by this layer, and a key that is neither a Prisma arg nor a turbine option
  *   gets a dev-mode warning instead of vanishing (see
  *   {@link PRISMA_ARG_KEYS} and `warnUnknownQueryOptions`).
+ *   The three PRIVILEGE options among them (`skipGlobalFilters`, `includePii`,
+ *   `allowFullTableScan`) are forwarded VERBATIM, which is what makes them safe
+ *   here: core accepts only the `UNSAFE` sentinel, so a Prisma-shaped args
+ *   object carrying `includePii: true` reaches core and is refused there, and
+ *   this layer never needs its own copy of that rule.
  *
  * ## What it deliberately does NOT do (documented divergences)
  *
@@ -75,11 +80,16 @@
  * - **`limit` on `updateMany` / `deleteMany`** (Prisma 6.7+) throws. Turbine has
  *   no row-bounded mass mutation, and dropping a SAFETY BOUND with a warning
  *   would turn "change at most 10 rows" into "change every matching row".
- * - **Write projections** (`select` / `include` / `omit` on
- *   create/update/delete/upsert), **`select` on `count`**, and
- *   **`orderBy` / `cursor` / `take` / `skip` on `aggregate`** are accepted and
- *   IGNORED (they are legitimate Prisma, so they never warn); the full row / a
- *   plain number comes back.
+ * - **Write projections**: `select` / `omit` on create/update/delete/upsert
+ *   narrow the RETURNED OBJECT (see {@link resolveWriteProjection}); they do
+ *   NOT narrow the statement's `RETURNING` list, so the column still crosses
+ *   the wire, and `pii: true` remains the SQL-level control. A relation key in
+ *   either (or any `include` on a write) THROWS, since a write returns its own
+ *   row only. `omit` on READS is translated to core's own `omit`, see
+ *   {@link translateOmit}.
+ * - **`select` on `count`** and **`orderBy` / `cursor` / `take` / `skip` on
+ *   `aggregate`** are accepted and IGNORED (they are legitimate Prisma, so they
+ *   never warn); a plain number / the aggregate comes back.
  *
  * ## Type dependencies (0.41.0)
  *