turbine-orm 0.75.0 → 0.76.0

package/dist/pipeline.js

@@ -18,6 +18,7 @@
  * Sequential fallback covers HTTP-based drivers (Neon HTTP, Vercel Postgres, Cloudflare
  * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
  */
+import { postgresDialect } from './dialect.js';
 import { PipelineError, wrapPgError } from './errors.js';
 import { runPipelined, supportsExtendedPipeline } from './pipeline-submittable.js';
 /**
@@ -28,7 +29,7 @@ import { runPipelined, supportsExtendedPipeline } from './pipeline-submittable.j
  * The caller is responsible for acquiring the client and releasing it after
  * this function completes (in the finally block).
  */
-async function runSequential(client, queries, options = {}) {
+async function runSequential(client, queries, dialect, options = {}) {
     const { transactional = true } = options;
     if (!transactional)
         return runIndependent(client, queries);
@@ -40,7 +41,7 @@ async function runSequential(client, queries, options = {}) {
         // `TURBINE_E004` nor a retryable flag for the one failure that is most
         // worth retrying.
         try {
-            await client.query('BEGIN');
+            await client.query(dialect.beginStatement());
         }
         catch (err) {
             throw wrapPgError(err);
@@ -57,7 +58,7 @@ async function runSequential(client, queries, options = {}) {
             results.push(q.transform(raw));
         }
         try {
-            await client.query('COMMIT');
+            await client.query(dialect.commitStatement());
         }
         catch (err) {
             throw wrapPgError(err);
@@ -66,7 +67,7 @@ async function runSequential(client, queries, options = {}) {
     }
     catch (err) {
         try {
-            await client.query('ROLLBACK');
+            await client.query(dialect.rollbackStatement());
         }
         catch {
             // Best-effort rollback
@@ -74,6 +75,40 @@ async function runSequential(client, queries, options = {}) {
         throw err;
     }
 }
+/**
+ * The dialect whose transaction keywords this batch must use.
+ *
+ * `executePipeline` is handed a POOL and nothing else, so the pool is the only
+ * place the engine can be read from; the engine pool shims are the objects that
+ * know their own dialect, and one of them (`MssqlPool`) publishes it for exactly
+ * this. Anything else, a real `pg.Pool`, a serverless HTTP pool, a test mock,
+ * keeps PostgreSQL, which is what every one of them already spoke.
+ *
+ * This existed as three hard-coded strings, `BEGIN` / `COMMIT` / `ROLLBACK`,
+ * which is the one engine-specific decision in this file and the one it was not
+ * making. On SQL Server a bare `BEGIN` opens a statement BLOCK, not a
+ * transaction: `MssqlTxClient` matches the dialect's `BEGIN TRANSACTION` and
+ * nothing else, so a bare `BEGIN` missed that branch, reached the server as a
+ * block opener with no `END`, and was rejected; the `COMMIT` and `ROLLBACK`
+ * that followed then found no open transaction and silently did nothing. A
+ * pipeline that documents itself as atomic was neither atomic nor rolled back.
+ *
+ * Duck-typed rather than `instanceof`, deliberately: importing an engine module
+ * here would pull an optional peer's whole module graph into the Postgres path.
+ * The three methods tested are exactly the three called below, so a partial
+ * object can never be accepted and then fail at the call site.
+ */
+function poolDialect(pool) {
+    const candidate = pool.dialect;
+    if (candidate !== null &&
+        typeof candidate === 'object' &&
+        typeof candidate.beginStatement === 'function' &&
+        typeof candidate.commitStatement === 'function' &&
+        typeof candidate.rollbackStatement === 'function') {
+        return candidate;
+    }
+    return postgresDialect;
+}
 /**
  * Sequential fallback for `{ transactional: false }`: each query is
  * INDEPENDENT, which is what that option promises and what the real pipeline
@@ -177,8 +212,11 @@ export async function executePipeline(pool, queries, options) {
             const results = await runPipelined(client, queries, pipelineOptions);
             return results;
         }
-        // Sequential fallback, reuses the same client
-        return await runSequential(client, queries, options);
+        // Sequential fallback, reuses the same client. This is the path every
+        // non-Postgres engine takes (none of their clients expose pg's wire
+        // internals), so it is the one that has to speak the engine's transaction
+        // keywords rather than Postgres's.
+        return await runSequential(client, queries, poolDialect(pool), options);
     }
     finally {
         client.release();

package/dist/powql.js

@@ -40,14 +40,14 @@ import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './query/compound-unique.js';
-import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
+import { ARRAY_OPERATOR_KEYS, isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { warnUnknownQueryOptions } from './query/option-surface.js';
 import { applyStableRelationOrderTo, normalizeWithClause } from './query/relation-names.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, resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './query/types.js';
-import { escapeLike, normalizePagination, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
+import { availableClause, escapeLike, normalizePagination, ownLookup, relationInProjectionMessage, resolveColumnName, resolveRelationDef, selectNamesNothingMessage, selectOmitExclusiveMessage, } from './query/utils.js';
 import { assertJsonFilterKeys, jsonStringEntries, resolveGlobalFilterFrom } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -149,8 +149,17 @@ function rejectUnsupportedFilter(value, field) {
     if ('path' in value || 'hasKey' in value) {
         throw new UnsupportedFeatureError('JSON path/key filters', 'PowDB', `field "${field}"`);
     }
-    if ('hasEvery' in value || 'hasSome' in value || 'isEmpty' in value) {
-        throw new UnsupportedFeatureError('array filters', 'PowDB', `field "${field}"`);
+    // Enumerated from the SHARED {@link ARRAY_OPERATOR_KEYS} rather than
+    // re-listed here, because the hand-written copy had already drifted from it:
+    // `has` was missing, so `{ tags: { has: 'x' } }` was not recognised as an
+    // array filter at all, fell through to the bare-object equality branch, and
+    // bound the whole `{ has: 'x' }` OBJECT as a scalar parameter. A silent wrong
+    // answer where its three siblings raise E017. Two lists is how that happened;
+    // reading the one the SQL side reads is what stops it happening again.
+    for (const key of ARRAY_OPERATOR_KEYS) {
+        if (key in value) {
+            throw new UnsupportedFeatureError('array filters', 'PowDB', `field "${field}"`);
+        }
     }
     if ('search' in value) {
         throw new UnsupportedFeatureError('full-text search filters', 'PowDB', `field "${field}"`);
@@ -180,7 +189,7 @@ export class PowqlInterface {
         this.options = options;
         const meta = schema.tables[table];
         if (!meta) {
-            throw new ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+            throw new ValidationError(`[turbine] Unknown table "${table}". ${availableClause(Object.keys(schema.tables), 'The schema has no tables.')}`);
         }
         this.meta = meta;
         this.defaultLimit = options.defaultLimit;
@@ -1153,8 +1162,18 @@ export class PowqlInterface {
     stripWritePii(entity) {
         if (!entity)
             return entity;
+        // Same PRIMARY-KEY exemption as the SQL engines' `piiColumns` / `piiFields`
+        // (query/writes.ts), and for the same measured reason: the returned row has
+        // to stay ADDRESSABLE. Without it a PII-tagged key column came back deleted,
+        // so the caller's follow-up `update`/`delete` built its where from a partial
+        // key, the empty-where guard did not fire (the other member was present),
+        // and the write hit every row sharing the remaining member. The policy is
+        // "tag sensitive data, not keys": a PII PK is documented out of scope for
+        // stripping. This docstring already cross-referenced the SQL rule; only the
+        // exemption itself was missing.
+        const pk = new Set(this.meta.primaryKey);
         for (const col of this.meta.columns) {
-            if (col.pii)
+            if (col.pii && !pk.has(col.name))
                 delete entity[col.field];
         }
         return entity;
@@ -1422,18 +1441,40 @@ export class PowqlInterface {
         if (args.cursor) {
             throw new UnsupportedFeatureError('cursor pagination', 'PowDB', 'use limit/offset instead');
         }
+        // `distinct` names COLUMNS: Postgres compiles it to `SELECT DISTINCT ON
+        // (col)`, one row per distinct value of those columns. PowQL's `distinct`
+        // keyword is ROW-WIDE (`SELECT DISTINCT *`) and takes no column list, and
+        // the language has no window functions to rebuild per-column distinct with,
+        // so there is nothing faithful to emit. Accepting the option and emitting
+        // the row-wide keyword returned a DIFFERENT row set under the same
+        // argument, with no error and no warning, which is the one outcome the
+        // dialect seam exists to prevent.
+        //
+        // Refused with the same E017 the other non-Postgres engines already raise
+        // (query/builder.ts's `dialect.name !== 'postgresql'` gate) and in the same
+        // words, so `distinct` now means one thing across every engine and matches
+        // what the README documents. Refused BEFORE the column names are resolved,
+        // matching that gate's position, so `distinct: ['nope']` reports the
+        // unsupported feature rather than the typo on every engine alike.
+        if (args.distinct?.length) {
+            throw new UnsupportedFeatureError('DISTINCT ON (findMany distinct)', 'PowDB', "findMany({ distinct }) requires PostgreSQL: PowQL's `distinct` is row-wide, not per-column. " +
+                'Group in application code, or use groupBy({ by }) for one row per combination.');
+        }
         const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
         const { cols, forcedPk } = this.projectionPlan(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
-        // collides with a projected parent column stays on the loaders (its block
-        // key would duplicate the column's).
+        // A relation whose field name collides with a projected parent column stays
+        // on the loaders (its block key would duplicate the column's). A parent
+        // `distinct` used to be a third exclusion here (distinct over a row
+        // containing a JSON array is not a defined comparison); the refusal above
+        // now settles that one statement earlier, so the branch cannot be reached
+        // with a `distinct` present and testing for it again would be dead code
+        // implying the option is still accepted.
         const withClause = args.with;
         const nestedPlans = [];
         const linkPlans = [];
         let residualWith = withClause;
-        if (withClause && !args.distinct?.length && this.nestedProjectionsPreferred(args)) {
+        if (withClause && this.nestedProjectionsPreferred(args)) {
             const residue = {};
             for (const [relName, opt] of Object.entries(withClause)) {
                 if (!opt)
@@ -1464,13 +1505,6 @@ export class PowqlInterface {
         const alias = nest ? 't0' : undefined;
         let where = this.buildWhere(resolvedWhere, params, alias);
         where = this.applyGlobalFilter(where, params, args.skipGlobalFilters, alias);
-        // PowQL's `distinct` is row-wide, so these names never reach the emitted
-        // statement. They are still caller-supplied names, and a name resolves or
-        // throws: reading the array for its LENGTH alone let `distinct: ['nope']`
-        // succeed here while every SQL engine refuses it. Validation only.
-        for (const key of args.distinct ?? [])
-            this.column(key);
-        const distinct = args.distinct?.length ? ' distinct' : '';
         const filter = where ? ` filter ${where}` : '';
         const order = this.buildOrder(args.orderBy, params, alias);
         const limit = this.effectiveLimit(args);
@@ -1498,7 +1532,7 @@ export class PowqlInterface {
         else {
             projection = this.projection(cols);
         }
-        const powql = `${this.qt}${nest ? ' as t0' : ''}${distinct}${filter}${order}${limitClause}${offsetClause} ${projection}`;
+        const powql = `${this.qt}${nest ? ' as t0' : ''}${filter}${order}${limitClause}${offsetClause} ${projection}`;
         return { powql, resolvedWhere, nestedPlans, linkPlans, residualWith, forcedPk };
     }
     /** Build + run the findMany select; returns raw rows, the serving wire, the resolved where, and the `with` partition. */

package/dist/query/batched-loader.js

@@ -56,7 +56,7 @@
 import { CircularRelationError, RelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { normalizeKeyColumns } from '../schema.js';
 import { dedupeOrderEntries, isOrderBySpec, isRelationPickOrderBy, orderByEntries, sortedEntries } from './filters.js';
-import { markInternalCombinator, ownLookup, resolveColumnName, selectNamesNothingMessage, selectOmitExclusiveMessage, sqlToPreparedName, } from './utils.js';
+import { availableClause, markInternalCombinator, ownLookup, resolveColumnName, selectNamesNothingMessage, selectOmitExclusiveMessage, sqlToPreparedName, } from './utils.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
  * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit, it
@@ -419,7 +419,7 @@ export function resolveCountRelations(parentMeta, countSpec) {
         const rel = ownLookup(parentMeta.relations, relName);
         if (!rel) {
             throw new RelationError(`[turbine] Unknown relation "${relName}" in _count on table "${parentMeta.name}". ` +
-                `Available: ${Object.keys(parentMeta.relations).join(', ')}`);
+                availableClause(Object.keys(parentMeta.relations), 'It has no relations.'));
         }
         if (!isToMany(rel)) {
             throw new ValidationError(`[turbine] _count is only supported for to-many relations; "${relName}" on ` +
@@ -495,7 +495,7 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
             // E005 for this exact shape (relations.ts), and under 'auto' the two
             // must refuse identically or the error CODE depends on table size.
             throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
-                `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}`);
+                availableClause(Object.keys(ctx.parentMeta.relations), 'It has no relations.'));
         }
         resolved.push({ relName, rel, options: spec === true ? {} : spec });
     }
@@ -523,7 +523,7 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
     // not a line in a correctness fix. Until then both strategies say no.
     if (hasCount && depth > 0) {
         throw new RelationError(`[turbine] Unknown relation "_count" on table "${ctx.parentMeta.name}". ` +
-            `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}. ` +
+            `${availableClause(Object.keys(ctx.parentMeta.relations), 'It has no relations.')} ` +
             '(`_count` is supported on the top-level `with` only, on every relationLoadStrategy.)');
     }
     // Fix key order BEFORE anything is awaited: the loads below all write their

package/dist/query/builder.js

@@ -23,7 +23,7 @@ import { warnUnknownQueryOptions } from './option-surface.js';
 import { applyStableRelationOrderTo, normalizeWithClause } from './relation-names.js';
 import * as relationsMod from './relations.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';
-import { isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
+import { availableClause, isTemporalInfinity, LRUCache, normalizePagination, ownLookup, parseDbDate, resolveColumnName, resolveRelation, resolveRelationDef, sqlToPreparedName, unknownFieldMessage, warnRedundantSortTerm, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -669,7 +669,7 @@ export class QueryInterface {
         this.schema = schema;
         const meta = schema.tables[table];
         if (!meta) {
-            throw new ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+            throw new ValidationError(`[turbine] Unknown table "${table}". ${availableClause(Object.keys(schema.tables), 'The schema has no tables.')}`);
         }
         this.tableMeta = meta;
         this.middlewares = middlewares ?? [];

package/dist/query/relations.d.ts

@@ -71,6 +71,11 @@ export declare function resolveProjection(qi: BuilderCtx, table: string, meta: T
  * the existing call sites in builder.ts.
  */
 export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
+/**
+ * Read a relation spec as options. See {@link EMPTY_WITH_OPTIONS} for why this
+ * is a shared authority rather than a guard repeated per walker.
+ */
+export declare function relationOptions(spec: true | WithOptions): WithOptions;
 /**
  * Produce a fingerprint for a `with` clause tree. Recursion mirrors
  * buildSelectWithRelations / buildRelationSubquery.