turbine-orm 0.78.0 → 0.79.0-next.c53fa34

package/dist/cjs/client.d.ts

@@ -648,9 +648,11 @@ export declare class TransactionClient {
      * inside the same BEGIN/COMMIT (and any active SAVEPOINT) as every other
      * statement in the callback. Driver errors are translated by `wrapPgError`,
      * exactly as pool-scoped and table-scoped queries are. Like {@link raw}, it
-     * emits no `$on('query')` event and runs no middleware.
+     * runs no middleware, and it emits one `$on('query')` event with model
+     * `'$raw'` and `action` set to the optional `action` label (the adapter
+     * passes `'$queryRaw'` / `'$executeRaw'` ...; default `'rawQuery'`).
      */
-    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[]): Promise<{
+    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[], action?: string): Promise<{
         rows: T[];
         rowCount: number | null;
     }>;
@@ -986,6 +988,16 @@ export declare class TurbineClient {
      * On HTTP-based drivers it falls back to sequential execution.
      */
     pipeline<T extends readonly DeferredQuery<unknown>[]>(...args: T | [T, PipelineOptions?]): Promise<PipelineResults<T>>;
+    /**
+     * {@link pipeline} with one `$on('query')` event per statement. Only taken
+     * when a listener is registered, so an unobserved pipeline runs exactly as
+     * before. Each statement's `transform` is wrapped to capture the driver's
+     * row count on the way through (the pipeline returns transformed values, not
+     * driver results). The statements share one round trip, so the batch's wall
+     * time is split evenly across them and each event carries
+     * `batch: 'pipeline'`.
+     */
+    private reportedPipeline;
     /**
      * Check whether the underlying pool supports the real pipeline protocol.
      * Returns `true` for standard pg.Pool TCP connections, `false` for HTTP
@@ -1005,6 +1017,39 @@ export declare class TurbineClient {
      * ```
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    /**
+     * @internal The `turbine-orm/prisma-compat` adapter's pool-level raw seam,
+     * the twin of {@link TransactionClient.rawQuery}. NOT application API: use
+     * {@link raw} or {@link sql}, whose tagged templates make concatenating a
+     * value into the SQL text impossible. It exists so the adapter's
+     * `$queryRaw` / `$executeRaw` statements emit a `$on('query')` event (model
+     * `'$raw'`, `action` the adapter's label) instead of running unobserved on
+     * the pool. Errors are translated by `wrapPgError`, like {@link raw}.
+     */
+    rawQuery<T extends object = Record<string, unknown>>(text: string, params?: readonly unknown[], action?: string): Promise<{
+        rows: T[];
+        rowCount: number | null;
+    }>;
+    /**
+     * Run `fn` with `tag` attached to every `$on('query')` event it causes, so a
+     * listener can attribute queries to the feature or code path that issued
+     * them. The scope follows async context: queries in awaited helpers,
+     * transactions, pipelines and raw SQL inside `fn` are all tagged. An inner
+     * `$tag` replaces an outer one for its own duration. The tag is event
+     * metadata only and never reaches SQL.
+     *
+     * Throws {@link ValidationError} (E003) for an empty tag or one longer than
+     * {@link MAX_QUERY_TAG_LENGTH} (128) characters.
+     *
+     * @example
+     * ```ts
+     * const order = await db.$tag('checkout', async () => {
+     *   const cart = await db.carts.findUnique({ where: { id } });
+     *   return db.orders.create({ data: { cartId: cart.id } });
+     * });
+     * ```
+     */
+    $tag<R>(tag: string, fn: () => R): R;
     /**
      * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
      *

package/dist/cjs/client.js

@@ -37,6 +37,7 @@ const pipeline_js_1 = require("./pipeline.js");
 const index_js_1 = require("./query/index.js");
 const utils_js_1 = require("./query/utils.js");
 const warn_registry_js_1 = require("./query/warn-registry.js");
+const query_events_js_1 = require("./query-events.js");
 const realtime_js_1 = require("./realtime.js");
 const typed_sql_js_1 = require("./typed-sql.js");
 async function withRetry(fn, options) {
@@ -538,13 +539,8 @@ class TransactionClient {
                 sql += this.dialect.paramPlaceholder(i + 1);
             }
         });
-        try {
-            const result = await this.client.query(sql, values);
-            return result.rows;
-        }
-        catch (err) {
-            throw (0, errors_js_1.wrapPgError)(err);
-        }
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions?._onQuery, (0, query_events_js_1.rawIdentity)('raw'), sql, values, () => this.client.query(sql, values), errors_js_1.wrapPgError);
+        return result.rows;
     }
     /**
      * @internal The `turbine-orm/prisma-compat` adapter's transaction seam. NOT
@@ -568,16 +564,13 @@ class TransactionClient {
      * inside the same BEGIN/COMMIT (and any active SAVEPOINT) as every other
      * statement in the callback. Driver errors are translated by `wrapPgError`,
      * exactly as pool-scoped and table-scoped queries are. Like {@link raw}, it
-     * emits no `$on('query')` event and runs no middleware.
+     * runs no middleware, and it emits one `$on('query')` event with model
+     * `'$raw'` and `action` set to the optional `action` label (the adapter
+     * passes `'$queryRaw'` / `'$executeRaw'` ...; default `'rawQuery'`).
      */
-    async rawQuery(text, params = []) {
-        try {
-            const result = await this.client.query(text, params);
-            return { rows: result.rows, rowCount: result.rowCount };
-        }
-        catch (err) {
-            throw (0, errors_js_1.wrapPgError)(err);
-        }
+    async rawQuery(text, params = [], action = 'rawQuery') {
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions?._onQuery, (0, query_events_js_1.rawIdentity)(action), text, params, () => this.client.query(text, params), errors_js_1.wrapPgError);
+        return { rows: result.rows, rowCount: result.rowCount };
     }
     /**
      * Create a pool-like wrapper around the transaction client.
@@ -908,7 +901,11 @@ class TurbineClient {
             _onQuery: (event) => {
                 if (this.queryListeners.size === 0)
                     return;
-                const emitted = this.queryParamsVisible ? event : { ...event, params: event.params.map(() => '[REDACTED]') };
+                // The $tag() scope is read here, at the one seam every emitter shares,
+                // so a tag reaches model, raw, pipeline and batch events alike.
+                const tag = event.tag ?? (0, query_events_js_1.currentQueryTag)();
+                const tagged = tag === undefined || event.tag !== undefined ? event : { ...event, tag };
+                const emitted = this.queryParamsVisible ? tagged : { ...tagged, params: tagged.params.map(() => '[REDACTED]') };
                 for (const listener of this.queryListeners) {
                     try {
                         listener(emitted);
@@ -1520,7 +1517,63 @@ class TurbineClient {
         // where VALUES as soon as any verbose client existed in the process. The
         // scope is established around the await, so every continuation of the batch
         // resolves this client's mode.
-        return this.withErrorMode(() => (0, pipeline_js_1.executePipeline)(this.pool, queries, options));
+        const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
+        if (!sink)
+            return this.withErrorMode(() => (0, pipeline_js_1.executePipeline)(this.pool, queries, options));
+        return this.withErrorMode(() => this.reportedPipeline(sink, queries, options));
+    }
+    /**
+     * {@link pipeline} with one `$on('query')` event per statement. Only taken
+     * when a listener is registered, so an unobserved pipeline runs exactly as
+     * before. Each statement's `transform` is wrapped to capture the driver's
+     * row count on the way through (the pipeline returns transformed values, not
+     * driver results). The statements share one round trip, so the batch's wall
+     * time is split evenly across them and each event carries
+     * `batch: 'pipeline'`.
+     */
+    async reportedPipeline(sink, queries, options) {
+        const rowCounts = new Array(queries.length).fill(undefined);
+        const observed = queries.map((q, i) => ({
+            ...q,
+            transform: (raw) => {
+                rowCounts[i] = (0, query_events_js_1.resultRowCount)(raw);
+                return q.transform(raw);
+            },
+        }));
+        const start = performance.now();
+        let failure;
+        try {
+            return await (0, pipeline_js_1.executePipeline)(this.pool, observed, options);
+        }
+        catch (err) {
+            failure = err;
+            throw err;
+        }
+        finally {
+            const duration = (performance.now() - start) / queries.length;
+            // PipelineError names the failing slot; any other failure (connect,
+            // BEGIN) is charged to the first statement that produced no result.
+            const failedIndex = failure === undefined
+                ? -1
+                : failure instanceof errors_js_1.PipelineError && failure.failedIndex !== undefined
+                    ? failure.failedIndex
+                    : rowCounts.indexOf(undefined);
+            queries.forEach((q, i) => {
+                const failed = i === failedIndex;
+                // A slot that never ran (or rolled back unseen) is not reported.
+                if (failed || rowCounts[i] !== undefined) {
+                    (0, query_events_js_1.emitStatementEvent)(sink, {
+                        sql: q.sql,
+                        params: q.params,
+                        duration,
+                        ...(0, query_events_js_1.deferredIdentity)(q.tag),
+                        rows: rowCounts[i] ?? 0,
+                        batch: 'pipeline',
+                        ...(failed ? { error: failure instanceof Error ? failure : new Error(String(failure)) } : {}),
+                    });
+                }
+            });
+        }
     }
     /**
      * Check whether the underlying pool supports the real pipeline protocol.
@@ -1556,13 +1609,43 @@ class TurbineClient {
         if (this.logging) {
             console.log(`[turbine] Raw SQL: ${sql.trim().substring(0, 120)}...`);
         }
-        try {
-            const result = await this.pool.query(sql, values);
-            return result.rows;
-        }
-        catch (err) {
-            throw this.withErrorMode(() => (0, errors_js_1.wrapPgError)(err));
-        }
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions._onQuery, (0, query_events_js_1.rawIdentity)('raw'), sql, values, () => this.pool.query(sql, values), (err) => this.withErrorMode(() => (0, errors_js_1.wrapPgError)(err)));
+        return result.rows;
+    }
+    /**
+     * @internal The `turbine-orm/prisma-compat` adapter's pool-level raw seam,
+     * the twin of {@link TransactionClient.rawQuery}. NOT application API: use
+     * {@link raw} or {@link sql}, whose tagged templates make concatenating a
+     * value into the SQL text impossible. It exists so the adapter's
+     * `$queryRaw` / `$executeRaw` statements emit a `$on('query')` event (model
+     * `'$raw'`, `action` the adapter's label) instead of running unobserved on
+     * the pool. Errors are translated by `wrapPgError`, like {@link raw}.
+     */
+    async rawQuery(text, params = [], action = 'rawQuery') {
+        const result = await (0, query_events_js_1.runReportedStatement)(this.queryOptions._onQuery, (0, query_events_js_1.rawIdentity)(action), text, params, () => this.pool.query(text, params), (err) => this.withErrorMode(() => (0, errors_js_1.wrapPgError)(err)));
+        return { rows: result.rows, rowCount: result.rowCount };
+    }
+    /**
+     * Run `fn` with `tag` attached to every `$on('query')` event it causes, so a
+     * listener can attribute queries to the feature or code path that issued
+     * them. The scope follows async context: queries in awaited helpers,
+     * transactions, pipelines and raw SQL inside `fn` are all tagged. An inner
+     * `$tag` replaces an outer one for its own duration. The tag is event
+     * metadata only and never reaches SQL.
+     *
+     * Throws {@link ValidationError} (E003) for an empty tag or one longer than
+     * {@link MAX_QUERY_TAG_LENGTH} (128) characters.
+     *
+     * @example
+     * ```ts
+     * const order = await db.$tag('checkout', async () => {
+     *   const cart = await db.carts.findUnique({ where: { id } });
+     *   return db.orders.create({ data: { cartId: cart.id } });
+     * });
+     * ```
+     */
+    $tag(tag, fn) {
+        return (0, query_events_js_1.runWithQueryTag)(tag, fn);
     }
     /**
      * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
@@ -1602,7 +1685,7 @@ class TurbineClient {
         // `withErrorMode` docstring already claimed to cover the typed-SQL builder
         // and did not, which left two raw-SQL entry points disagreeing about the
         // same statement, since the adjacent `raw` tag WAS scoped.
-        return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn));
+        return new typed_sql_js_1.TypedSqlQuery(this.pool, sql, params, this.logging, (fn) => this.withErrorMode(fn), this.queryOptions._onQuery);
     }
     // -------------------------------------------------------------------------
     // Transaction support (raw, legacy)
@@ -1842,13 +1925,18 @@ class TurbineClient {
         if (queries.length === 0) {
             return [];
         }
+        // One `$on('query')` event per statement, `batch: 'transaction'`, only
+        // when someone is listening; each statement is timed on its own.
+        const sink = this.queryListeners.size > 0 ? this.queryOptions._onQuery : undefined;
+        const reported = (dq, run) => (0, query_events_js_1.runReportedStatement)(sink, { ...(0, query_events_js_1.deferredIdentity)(dq.tag), batch: 'transaction' }, dq.sql, dq.params, run, errors_js_1.wrapPgError);
         return this.transaction(async (client) => {
             const pipelined = client.supportsPipelining === true &&
                 this.dialect.resultStrategy !== 'reselect';
             if (pipelined) {
                 // Dispatch every statement before awaiting any reply. The driver's
-                // FIFO guarantee makes settled[i] the reply to queries[i].
-                const settled = await Promise.allSettled(queries.map((dq) => client.query(dq.sql, dq.params)));
+                // FIFO guarantee makes settled[i] the reply to queries[i]. Each
+                // statement is timed from its dispatch to its own reply.
+                const settled = await Promise.allSettled(queries.map((dq) => reported(dq, () => client.query(dq.sql, dq.params))));
                 const results = [];
                 for (let i = 0; i < settled.length; i++) {
                     const outcome = settled[i];
@@ -1861,19 +1949,12 @@ class TurbineClient {
             }
             const results = [];
             for (const dq of queries) {
-                let raw;
-                try {
-                    // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL)
-                    // attach a reselect plan that runs the write plus a follow-up SELECT;
-                    // running dq.sql alone would transform a row-less write result.
-                    raw =
-                        this.dialect.resultStrategy === 'reselect' && dq.reselect
-                            ? await dq.reselect((sql, params) => client.query(sql, params))
-                            : await client.query(dq.sql, dq.params);
-                }
-                catch (err) {
-                    throw (0, errors_js_1.wrapPgError)(err);
-                }
+                // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL) attach a
+                // reselect plan that runs the write plus a follow-up SELECT; running
+                // dq.sql alone would transform a row-less write result.
+                const raw = await reported(dq, () => this.dialect.resultStrategy === 'reselect' && dq.reselect
+                    ? dq.reselect((sql, params) => client.query(sql, params))
+                    : client.query(dq.sql, dq.params));
                 results.push(dq.transform(raw));
             }
             return results;

package/dist/cjs/index.d.ts

@@ -45,6 +45,7 @@ export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type Me
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
 export { fingerprintPrismaSchema } from './prisma-schema-fingerprint.js';
 export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonEncoding, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderBySpec, type OrderDirection, type PrivilegeOption, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationOrderBy, type RelationOrderByChain, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TemporalInfinityReading, type TextSearchFilter, type TypedWithClause, UNSAFE, type Unsafe, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export { MAX_QUERY_TAG_LENGTH, RAW_QUERY_MODEL } from './query-events.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, PrismaSchemaSource, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';

package/dist/cjs/index.js

@@ -35,7 +35,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_COUNT_BATCH_MIN_PARENT_ROWS = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.fingerprintPrismaSchema = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.REDACTED_DETAIL = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.UNSAFE = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.RAW_QUERY_MODEL = exports.MAX_QUERY_TAG_LENGTH = exports.UNSAFE = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -110,6 +110,10 @@ Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MAX", { enumerable: true,
 Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MIN", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_ROWS_MIN; } });
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
 Object.defineProperty(exports, "UNSAFE", { enumerable: true, get: function () { return index_js_2.UNSAFE; } });
+// $on('query') event metadata: raw-statement model name, $tag() label limit
+var query_events_js_1 = require("./query-events.js");
+Object.defineProperty(exports, "MAX_QUERY_TAG_LENGTH", { enumerable: true, get: function () { return query_events_js_1.MAX_QUERY_TAG_LENGTH; } });
+Object.defineProperty(exports, "RAW_QUERY_MODEL", { enumerable: true, get: function () { return query_events_js_1.RAW_QUERY_MODEL; } });
 // Realtime, LISTEN/NOTIFY pub/sub
 var realtime_js_1 = require("./realtime.js");
 Object.defineProperty(exports, "validateChannel", { enumerable: true, get: function () { return realtime_js_1.validateChannel; } });

package/dist/cjs/powql.d.ts

@@ -155,6 +155,34 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * the two can never disagree about which limit is in force.
      */
     private effectiveLimit;
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    private childOptions?;
+    private loaderChildOptions;
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    private static pageOf;
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -623,9 +651,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
     private joinEligible;
     /**

package/dist/cjs/powql.js

@@ -393,6 +393,42 @@ class PowqlInterface {
     effectiveLimit(args) {
         return args.limit ?? this.defaultLimit;
     }
+    /**
+     * Options for the child-side interfaces the relation loaders and the
+     * relation-filter resolvers build: the client's, with `defaultLimit` cleared
+     * and the unlimited warning off. `defaultLimit` bounds the caller's PAGE; on
+     * an internal fetch that serves that page (a relation's children, a filter's
+     * key set) it would cap the whole page's children, or the key set, at the
+     * page size: a silent wrong answer by another route than the one
+     * {@link pageOf} closes. The SQL batched loader clears it the same way
+     * (`batchedChildOptions` in query/builder.ts).
+     */
+    childOptions;
+    loaderChildOptions() {
+        this.childOptions ??= { ...this.options, defaultLimit: undefined, warnOnUnlimited: false };
+        return this.childOptions;
+    }
+    /**
+     * ONE parent's window of its stitched children: the relation's `offset` and
+     * `limit` applied to that parent's own list.
+     *
+     * A relation `limit` means "at most N on EACH parent". The loaders used to
+     * spread it onto the flat child fetch (`post filter .author_id in (...)
+     * limit 5`), which caps the TOTAL across every parent in the chunk, so ten
+     * parents shared five posts and most got none, with no error. It shipped
+     * for the loaders' whole life because the one test of the shape compared
+     * the join path against the loader path and both were wrong the same way;
+     * the cross-engine benchmark found it, where the wrong answer was the fast
+     * one. Every loader now fetches its children unbounded, WITH the relation
+     * `orderBy` (which decides which rows the window keeps), and applies this
+     * at stitch time: the rule the SQL engines' batched loader has always used.
+     */
+    static pageOf(rows, limit, offset) {
+        if (limit === undefined && !offset)
+            return rows;
+        const start = offset ?? 0;
+        return rows.slice(start, limit === undefined ? undefined : start + limit);
+    }
     /**
      * Reject a negative `limit` / `offset` before it reaches the engine. PowDB
      * casts both with `as usize` at execution, so below engine 0.20 a negative
@@ -974,7 +1010,7 @@ class PowqlInterface {
         const childCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
         const localField = this.meta.reverseColumnMap[localCol] ?? localCol;
         const childField = targetMeta.reverseColumnMap[childCol] ?? childCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collect = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -1013,7 +1049,7 @@ class PowqlInterface {
         const sourceRefField = this.meta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
         const sourceRefColMeta = this.meta.columns.find((c) => c.name === sourceRefCol);
         const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         const collectTargetPks = async (w) => {
             const rows = await targetQi.findMany({
                 where: w,
@@ -1725,7 +1761,7 @@ class PowqlInterface {
             const rel = this.meta.relations[relName];
             if (!rel)
                 throw new errors_js_1.ValidationError(`Unknown relation "${relName}" on "${this.table}".`);
-            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args, parents.length)) {
+            if (strategyIsJoin && parent && this.joinEligible(rel, opt, parent.args)) {
                 if (this.capabilities.serverJoins) {
                     await this.loadRelationViaJoin(parents, rel, relName, opt, parent, timeout, includePii);
                     continue;
@@ -1748,7 +1784,19 @@ class PowqlInterface {
                 throw new errors_js_1.UnsupportedFeatureError('composite-key nested reads', 'PowDB', `relation "${relName}"`);
             }
             const options = (opt === true ? {} : opt);
-            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+            // The relation's own page, applied PER PARENT at stitch time (see pageOf),
+            // never on the flat fetch below.
+            const relLimit = options.limit;
+            const relOffset = options.offset;
+            this.assertPagination(relLimit, relOffset, `relation "${relName}"`);
+            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+            if (relLimit === 0) {
+                // `[]` on every parent by construction: nothing to fetch.
+                for (const parent of parents)
+                    parent[relName] = single ? null : [];
+                continue;
+            }
+            const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
             const targetMeta = this.schema.tables[rel.to];
             // Local key on the parent, remote key on the target child.
             const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
@@ -1806,6 +1854,9 @@ class PowqlInterface {
                 };
                 const children = (await targetQi.findMany({
                     ...fetchOptions,
+                    // Unbounded: the relation limit/offset are per parent, applied below.
+                    limit: undefined,
+                    offset: undefined,
                     where: childWhere,
                     with: options.with,
                     timeout: options.timeout ?? timeout,
@@ -1832,11 +1883,12 @@ class PowqlInterface {
                         delete child[childKeyField];
                 }
             }
-            const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
             for (const parent of parents) {
                 const k = this.joinKey(parent[parentKeyField]);
                 const matches = (k == null ? undefined : childByKey.get(k)) ?? [];
-                parent[relName] = single ? (matches[0] ?? null) : matches;
+                parent[relName] = single
+                    ? (matches[0] ?? null)
+                    : PowqlInterface.pageOf(matches, relLimit, relOffset);
             }
         }
     }
@@ -1902,7 +1954,13 @@ class PowqlInterface {
         }
         // (2) Target rows by PK, honouring the relation's own where/with/select/…
         const options = (opt === true ? {} : opt);
-        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.options);
+        this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
+        if (options.limit === 0) {
+            for (const parent of parents)
+                parent[relName] = [];
+            return;
+        }
+        const targetQi = new PowqlInterface(this.pool, rel.to, this.schema, [], this.loaderChildOptions());
         // This loader stitches on the TARGET's own primary key, so the PK has to be
         // in the fetch even when the caller's select/omit excludes it, and has to
         // come back off afterwards. Exactly the shape `loadRelation` uses for its
@@ -1939,6 +1997,11 @@ class PowqlInterface {
             }
         }
         const targetByPk = new Map();
+        // Position of each target in the fetch, i.e. its rank under the relation's
+        // `orderBy`; the stitch below sorts a parent's children by it when an
+        // orderBy was given, so `limit` keeps that parent's top-N and not its first
+        // N junction rows. Across fetch CHUNKS the rank is fetch order.
+        const targetRank = new Map();
         const targetValList = [...allTargetVals].map((v) => targetPkColMeta ? coerceScalar(v, targetPkColMeta.tsType) : v);
         const targetChunk = this.keyChunkSize(targetMeta, targetPkCol);
         for (let i = 0; i < targetValList.length; i += targetChunk) {
@@ -1949,14 +2012,21 @@ class PowqlInterface {
             };
             const targets = (await targetQi.findMany({
                 ...fetchOptions,
+                // Unbounded: the relation limit/offset are per parent, applied in the stitch.
+                limit: undefined,
+                offset: undefined,
                 where,
                 with: options.with,
                 timeout: options.timeout ?? timeout,
                 // Public findMany, so the sentinel form. See loadRelation above.
                 includePii: includePii ? types_js_1.UNSAFE : undefined,
             }));
-            for (const t of targets)
-                targetByPk.set(String(t[targetPkField]), t);
+            for (const t of targets) {
+                const pk = String(t[targetPkField]);
+                targetByPk.set(pk, t);
+                if (!targetRank.has(pk))
+                    targetRank.set(pk, targetRank.size);
+            }
         }
         // (3) Stitch: each parent → its junction targets (m2m is always a list).
         for (const parent of parents) {
@@ -1968,7 +2038,11 @@ class PowqlInterface {
                 if (child)
                     children.push(child);
             }
-            parent[relName] = children;
+            if (options.orderBy) {
+                const rank = (t) => targetRank.get(String(t[targetPkField])) ?? 0;
+                children.sort((a, b) => rank(a) - rank(b));
+            }
+            parent[relName] = PowqlInterface.pageOf(children, options.limit, options.offset);
         }
         // Stitching is done: take the forced PK back off. Iterating the map rather
         // than the stitched lists is deliberate, one target can be linked from many
@@ -2012,11 +2086,12 @@ class PowqlInterface {
      *     `referenceKey` on the TARGET table (the join's non-fetched side);
      *   - m2m keeps any `orderBy`/`limit`/`offset` on the loader (the junction-order
      *     stitch can't be reproduced by the 3-table join deterministically);
-     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader, as
-     *     does a to-many relation `limit`/`offset` when the parent set spills past
-     *     one loader chunk (the loader limits per chunk, the join once globally).
+     *   - a to-one relation `limit`/`offset` (meaningless) stays on the loader. A
+     *     to-many relation `limit`/`offset` is a PER-PARENT bound on both paths,
+     *     fetched unbounded and sliced per parent at stitch time (`pageOf`), so
+     *     the join statement carries neither clause.
      */
-    joinEligible(rel, opt, args, parentCount) {
+    joinEligible(rel, opt, args) {
         const effLimit = args.limit ?? this.defaultLimit;
         if (effLimit !== undefined || args.offset)
             return false;
@@ -2057,9 +2132,8 @@ class PowqlInterface {
             return false;
         }
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
-        if ((options.limit !== undefined || options.offset) && (single || parentCount > MAX_RELATION_KEYS)) {
+        if ((options.limit !== undefined || options.offset) && single)
             return false;
-        }
         // A `limit 0` relation stays off the join statement for the same reason it
         // stays off a nested projection: PowDB answered `limit 0` with one row below
         // engine 0.20. The loader resolves it client-side, correctly on every version.
@@ -2106,13 +2180,13 @@ class PowqlInterface {
         const { cols: childCols, forcedPk: childForcedPk } = this.joinChildCols(targetQi, options, includePii);
         const filter = await this.joinFilter(targetQi, parent.resolvedWhere, options.where, 'c', params, options.timeout ?? timeout);
         const order = targetQi.buildOrder(options.orderBy, params, 'c');
+        // No limit/offset clause: on the join they would bound the TOTAL child
+        // count across every parent. The relation's page is per parent (pageOf).
         this.assertPagination(options.limit, options.offset, `relation "${relName}"`);
-        const limitClause = options.limit !== undefined ? ` limit ${this.param(options.limit, params)}` : '';
-        const offsetClause = options.offset ? ` offset ${this.param(options.offset, params)}` : '';
         const proj = this.joinProjection(childCols, `p.${(0, powdb_shared_js_1.quotePowqlIdent)(parentKeyCol)}`, 'c');
         const powql = `${targetQi.qt} as c join ${this.qt} as p ` +
             `on c.${(0, powdb_shared_js_1.quotePowqlIdent)(childKeyCol)} = p.${(0, powdb_shared_js_1.quotePowqlIdent)(parentKeyCol)}` +
-            `${filter}${order}${limitClause}${offsetClause} ${proj}`;
+            `${filter}${order} ${proj}`;
         // A READ: thread a read-shaped action through the exec seam.
         const { rows, native } = await targetQi.exec(powql, params, timeout, 'findMany');
         const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
@@ -2120,7 +2194,9 @@ class PowqlInterface {
         for (const p of parents) {
             const key = this.joinKey(p[parentKeyField]);
             const matches = (key == null ? undefined : byKey.get(key)) ?? [];
-            p[relName] = single ? (matches[0] ?? null) : matches;
+            p[relName] = single
+                ? (matches[0] ?? null)
+                : PowqlInterface.pageOf(matches, options.limit, options.offset);
         }
     }
     /**

package/dist/cjs/prisma-compat.d.ts

@@ -174,7 +174,7 @@ export interface CompatTransactionClient {
      * breaks atomicity. Optional only so a test stub can omit it: when it is
      * absent the raw methods throw instead of escaping the transaction.
      */
-    rawQuery?(text: string, params?: readonly unknown[]): Promise<{
+    rawQuery?(text: string, params?: readonly unknown[], action?: string): Promise<{
         rows: unknown[];
         rowCount: number | null;
     }>;