turbine-orm 0.75.0 → 0.76.0

package/dist/cjs/pipeline.js

@@ -22,6 +22,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executePipeline = executePipeline;
 exports.pipelineSupported = pipelineSupported;
+const dialect_js_1 = require("./dialect.js");
 const errors_js_1 = require("./errors.js");
 const pipeline_submittable_js_1 = require("./pipeline-submittable.js");
 /**
@@ -32,7 +33,7 @@ const pipeline_submittable_js_1 = require("./pipeline-submittable.js");
  * 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);
@@ -44,7 +45,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 (0, errors_js_1.wrapPgError)(err);
@@ -61,7 +62,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 (0, errors_js_1.wrapPgError)(err);
@@ -70,7 +71,7 @@ async function runSequential(client, queries, options = {}) {
     }
     catch (err) {
         try {
-            await client.query('ROLLBACK');
+            await client.query(dialect.rollbackStatement());
         }
         catch {
             // Best-effort rollback
@@ -78,6 +79,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 dialect_js_1.postgresDialect;
+}
 /**
  * Sequential fallback for `{ transactional: false }`: each query is
  * INDEPENDENT, which is what that option promises and what the real pipeline
@@ -181,8 +216,11 @@ async function executePipeline(pool, queries, options) {
             const results = await (0, pipeline_submittable_js_1.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/cjs/powql.js

@@ -185,8 +185,17 @@ function rejectUnsupportedFilter(value, field) {
     if ('path' in value || 'hasKey' in value) {
         throw new errors_js_1.UnsupportedFeatureError('JSON path/key filters', 'PowDB', `field "${field}"`);
     }
-    if ('hasEvery' in value || 'hasSome' in value || 'isEmpty' in value) {
-        throw new errors_js_1.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 filters_js_1.ARRAY_OPERATOR_KEYS) {
+        if (key in value) {
+            throw new errors_js_1.UnsupportedFeatureError('array filters', 'PowDB', `field "${field}"`);
+        }
     }
     if ('search' in value) {
         throw new errors_js_1.UnsupportedFeatureError('full-text search filters', 'PowDB', `field "${field}"`);
@@ -216,7 +225,7 @@ class PowqlInterface {
         this.options = options;
         const meta = schema.tables[table];
         if (!meta) {
-            throw new errors_js_1.ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+            throw new errors_js_1.ValidationError(`[turbine] Unknown table "${table}". ${(0, utils_js_1.availableClause)(Object.keys(schema.tables), 'The schema has no tables.')}`);
         }
         this.meta = meta;
         this.defaultLimit = options.defaultLimit;
@@ -1189,8 +1198,18 @@ 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;
@@ -1458,18 +1477,40 @@ class PowqlInterface {
         if (args.cursor) {
             throw new errors_js_1.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 errors_js_1.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, (0, types_js_1.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)
@@ -1500,13 +1541,6 @@ 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);
@@ -1534,7 +1568,7 @@ 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/cjs/query/batched-loader.js

@@ -429,7 +429,7 @@ function resolveCountRelations(parentMeta, countSpec) {
         const rel = (0, utils_js_1.ownLookup)(parentMeta.relations, relName);
         if (!rel) {
             throw new errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" in _count on table "${parentMeta.name}". ` +
-                `Available: ${Object.keys(parentMeta.relations).join(', ')}`);
+                (0, utils_js_1.availableClause)(Object.keys(parentMeta.relations), 'It has no relations.'));
         }
         if (!isToMany(rel)) {
             throw new errors_js_1.ValidationError(`[turbine] _count is only supported for to-many relations; "${relName}" on ` +
@@ -505,7 +505,7 @@ async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0
             // 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 errors_js_1.RelationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
-                `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}`);
+                (0, utils_js_1.availableClause)(Object.keys(ctx.parentMeta.relations), 'It has no relations.'));
         }
         resolved.push({ relName, rel, options: spec === true ? {} : spec });
     }
@@ -533,7 +533,7 @@ async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0
     // not a line in a correctness fix. Until then both strategies say no.
     if (hasCount && depth > 0) {
         throw new errors_js_1.RelationError(`[turbine] Unknown relation "_count" on table "${ctx.parentMeta.name}". ` +
-            `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}. ` +
+            `${(0, utils_js_1.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/cjs/query/builder.js

@@ -707,7 +707,7 @@ class QueryInterface {
         this.schema = schema;
         const meta = schema.tables[table];
         if (!meta) {
-            throw new errors_js_1.ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+            throw new errors_js_1.ValidationError(`[turbine] Unknown table "${table}". ${(0, utils_js_1.availableClause)(Object.keys(schema.tables), 'The schema has no tables.')}`);
         }
         this.tableMeta = meta;
         this.middlewares = middlewares ?? [];

package/dist/cjs/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.