turbine-orm 0.52.0 → 0.53.0

package/dist/cjs/prisma-compat.js

@@ -38,7 +38,15 @@
  * These cannot be faithfully translated and are not attempted; each throws or is
  * documented rather than silently returning wrong data:
  *
- * - `$extends` / client extensions, `$use` with Prisma's middleware param shape.
+ * - **`$extends` beyond `client` + `model`.** Client extensions ARE supported for
+ *   those two components (plus the `Prisma.defineExtension` callback form), and
+ *   return a new client whose delegates, `$transaction` and raw surface all
+ *   survive. The `query` (interception) and `result` (computed fields)
+ *   components, and any component this adapter does not recognize, throw an
+ *   {@link UnsupportedFeatureError} naming the component AT `$extends` TIME
+ *   rather than being accepted and quietly not applied.
+ * - `$use` with Prisma's middleware param shape (Turbine's own `client.$use` is
+ *   the supported interception seam).
  * - `instanceof PrismaClientKnownRequestError`, `.meta`/message byte parity
  *   (opt into `prismaErrorCodes` for a `.code` like `P2002`, without pretending
  *   `instanceof` identity).
@@ -153,6 +161,23 @@ exports.Prisma = {
     },
     /** An empty fragment. */
     empty: makeSql([''], []),
+    /**
+     * The extension context of `this` inside a client / model extension method.
+     * Turbine binds extension members directly onto the client and delegate
+     * objects, so the context IS `this`; the identity function exists so migrated
+     * `Prisma.getExtensionContext(this).$name` call sites keep working.
+     */
+    getExtensionContext(that) {
+        return that;
+    },
+    /**
+     * Type-preserving passthrough for `Prisma.defineExtension(ext)`. Prisma uses
+     * it purely for inference; the value is returned unchanged, so both the object
+     * and the callback form reach `$extends` intact.
+     */
+    defineExtension(ext) {
+        return ext;
+    },
 };
 /** Turbine error code → nearest Prisma `PXXXX` code. */
 const PRISMA_ERROR_CODE = {
@@ -1365,6 +1390,7 @@ function makeRawSurface(exec, ph) {
  */
 const CLIENT_RESERVED_KEY_MAP = {
     $transaction: true,
+    $extends: true,
     $queryRaw: true,
     $queryRawUnsafe: true,
     $executeRaw: true,
@@ -1437,6 +1463,109 @@ function junctionModels(ctx, map, tableToModel) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// $extends, client extensions
+// ---------------------------------------------------------------------------
+/** The `model` key whose members apply to every delegate. */
+const ALL_MODELS = '$allModels';
+/**
+ * Why each unsupported extension component is refused, and what to do instead.
+ * Both are refused AT `$extends` TIME, not at the first query, so the failure is
+ * a full message at boot rather than a surprise mid-request.
+ */
+const UNSUPPORTED_COMPONENTS = {
+    query: {
+        feature: '$extends `query` (query interception)',
+        hint: [
+            'Use the core middleware seam instead: `client.$use((params, next) => ...)` sees every query, or',
+            'wrap the call site; `$allOperations` hooks have no equivalent.',
+            'The `client` and `model` components ARE supported.',
+        ].join(' '),
+    },
+    result: {
+        feature: '$extends `result` (computed fields)',
+        hint: [
+            'Prisma implements it by rewriting the projection to satisfy `needs` and stripping the injected',
+            'columns back out at every nesting level, which cannot be done safely on top of the PII projection',
+            'rules (a `needs` field on a pii-tagged column would arrive undefined and the computed value would',
+            'be silently wrong). Compute the field in application code, or add a generated column so it comes',
+            'back as a real column. The `client` and `model` components ARE supported.',
+        ].join(' '),
+    },
+};
+const EMPTY_EXTENSIONS = { client: {}, model: new Map(), allModels: {} };
+/**
+ * Validate one extension against the client's real shape and fold it into a NEW
+ * {@link ExtensionState} (the previous one is never mutated, so the client
+ * `$extends` was called on keeps working unchanged).
+ *
+ * Everything this adapter cannot honour throws here: an unsupported component
+ * ({@link UNSUPPORTED_COMPONENTS}), a component name we do not recognize at all
+ * (`@prisma/extension-accelerate`, Pulse, read replicas, ...), a `client` member
+ * that would shadow a delegate or a client-level method, or a `model` key that
+ * names no model in the map. Extension-over-extension overrides are allowed and
+ * last-wins, as in Prisma.
+ *
+ * @param modelKeys - every accepted `model` key spelling -> canonical model name.
+ * @param clientKeys - names already taken on the client (delegates + reserved).
+ */
+function applyExtension(prev, ext, modelKeys, clientKeys) {
+    if (typeof ext !== 'object' || ext === null) {
+        throw new errors_js_1.ValidationError('[turbine] prisma-compat: $extends expects an extension object or a function ' +
+            `(Prisma.defineExtension callback form), received ${ext === null ? 'null' : typeof ext}.`);
+    }
+    for (const [component, value] of Object.entries(ext)) {
+        if (component === 'name' || component === 'client' || component === 'model')
+            continue;
+        // An explicitly-undefined component asked for nothing (a spread of a partial
+        // extension object), so there is nothing to refuse.
+        if (value === undefined)
+            continue;
+        const known = UNSUPPORTED_COMPONENTS[component];
+        throw new errors_js_1.UnsupportedFeatureError(known?.feature ?? `$extends extension component "${component}"`, 'prisma-compat', known?.hint ??
+            'Only the `client` and `model` components are supported (Accelerate / Pulse / read-replica ' +
+                'extensions are not).');
+    }
+    const client = { ...prev.client };
+    for (const [name, member] of Object.entries(ext.client ?? {})) {
+        if (clientKeys.has(name)) {
+            throw new errors_js_1.ValidationError(`[turbine] prisma-compat: $extends \`client\` member "${name}" would shadow an existing client ` +
+                'member (a model delegate or a client-level method). Rename it.');
+        }
+        client[name] = member;
+    }
+    const model = new Map(prev.model);
+    const allModels = { ...prev.allModels };
+    for (const [key, members] of Object.entries(ext.model ?? {})) {
+        if (key === ALL_MODELS) {
+            Object.assign(allModels, members);
+            continue;
+        }
+        const canonical = modelKeys.get(key);
+        if (!canonical) {
+            throw new errors_js_1.ValidationError(`[turbine] prisma-compat: $extends \`model\` key "${key}" is not a model on this client. ` +
+                `Known models: ${[...new Set(modelKeys.values())].sort().join(', ') || '(none)'}.`);
+        }
+        model.set(canonical, { ...(model.get(canonical) ?? {}), ...members });
+    }
+    return { client, model, allModels };
+}
+/**
+ * Overlay an extension's members on one delegate. Returns the delegate itself
+ * when the extension contributes nothing to it, so an unextended client and an
+ * extended one that only adds `client` members share the exact same delegates.
+ *
+ * The members are copied onto a shallow copy, so `this` inside an extension
+ * method is the extended delegate (what `Prisma.getExtensionContext(this)`
+ * returns), and `$name` carries the Prisma model name as Prisma's model context
+ * does.
+ */
+function extendDelegate(delegate, prismaModel, exts) {
+    const own = exts.model.get(prismaModel);
+    if (!own && Object.keys(exts.allModels).length === 0)
+        return delegate;
+    return Object.assign({ $name: prismaModel }, delegate, exts.allModels, own ?? {});
+}
 /**
  * Create a PrismaClient-surface adapter over a {@link TurbineClient}, driven by a
  * {@link PrismaCompatMap} (the `prisma-map.ts` that `turbine
@@ -1480,10 +1609,23 @@ function createPrismaCompatClient(client, map, options = {}) {
         ...Object.entries(map.models),
         ...junctionModels(ctx, map, tableToModel),
     ];
+    // Every spelling a `$extends` `model` key may use -> the canonical model name.
+    // Canonical names are registered first so a model can never lose its own key
+    // to another model's lowercased alias.
+    const modelKeys = new Map();
+    for (const [prismaModel] of delegateModels)
+        modelKeys.set(prismaModel, prismaModel);
+    for (const [prismaModel] of delegateModels) {
+        const alias = prismaPropertyAlias(prismaModel);
+        if (alias && !modelKeys.has(alias))
+            modelKeys.set(alias, prismaModel);
+    }
+    // Names a `$extends` `client` member must not shadow.
+    const clientKeys = new Set([...exports.CLIENT_RESERVED_KEYS, ...modelKeys.keys()]);
     // Delegates bound to the base client (each call reads db.table(...) lazily).
-    const delegates = new Map();
+    const baseDelegates = new Map();
     for (const [prismaModel, mm] of delegateModels) {
-        delegates.set(prismaModel, makeDelegate(ctx, mm, () => db.table(mm.table), (fn) => db.$transaction((tx) => fn((n) => tx.table(n)))));
+        baseDelegates.set(prismaModel, makeDelegate(ctx, mm, () => db.table(mm.table), (fn) => db.$transaction((tx) => fn((n) => tx.table(n)))));
     }
     const ph = placeholderOf(db);
     const runRaw = async (text, params) => {
@@ -1515,79 +1657,112 @@ function createPrismaCompatClient(client, map, options = {}) {
             throw decorate((0, errors_js_1.wrapPgError)(err), ctx.options.prismaErrorCodes);
         }
     };
-    const base = {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        $transaction: ((arg, txOptions) => {
-            // Array (lazy batch) form. Wrapped so validation/build errors REJECT the
-            // returned promise (Prisma's $transaction is always thenable) rather than
-            // throwing synchronously.
-            if (Array.isArray(arg)) {
-                return (async () => {
-                    try {
-                        const batchables = arg.map((p, i) => {
-                            const b = batchableOf(p);
-                            if (!b) {
-                                throw new errors_js_1.ValidationError(`[turbine] prisma-compat: $transaction([...]) item ${i} is not a lazy model call. Pass un-awaited delegate calls (e.g. prisma.User.create(...)).`);
+    /**
+     * Assemble one client for a set of already-validated extensions. `$extends`
+     * calls this again with a folded {@link ExtensionState}, so an extended client
+     * is a genuinely NEW object built by the SAME path: delegates (extended),
+     * `$transaction` (whose tx-scoped delegates get the same `model` members, the
+     * one place a naive implementation would silently diverge), the raw surface,
+     * and `$extends` itself, which is why extending stays chainable.
+     *
+     * Client-level `client` members are deliberately NOT copied onto the
+     * transaction client: such a member usually closes over the base client, so
+     * reaching it through `tx` would silently run its queries OUTSIDE the
+     * transaction. Absent, it is a TypeError at the call site instead.
+     */
+    const build = (exts) => {
+        // Delegates bound to the base client, extended where the extension has
+        // members for them. `baseDelegates` is built ONCE (outside), so a client
+        // whose extension only adds `client` members shares the very same delegate
+        // objects: extending costs nothing on the query path.
+        const delegates = new Map();
+        for (const [prismaModel, delegate] of baseDelegates) {
+            delegates.set(prismaModel, extendDelegate(delegate, prismaModel, exts));
+        }
+        const base = {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            $transaction: ((arg, txOptions) => {
+                // Array (lazy batch) form. Wrapped so validation/build errors REJECT the
+                // returned promise (Prisma's $transaction is always thenable) rather than
+                // throwing synchronously.
+                if (Array.isArray(arg)) {
+                    return (async () => {
+                        try {
+                            const batchables = arg.map((p, i) => {
+                                const b = batchableOf(p);
+                                if (!b) {
+                                    throw new errors_js_1.ValidationError(`[turbine] prisma-compat: $transaction([...]) item ${i} is not a lazy model call. Pass un-awaited delegate calls (e.g. prisma.User.create(...)).`);
+                                }
+                                return b;
+                            });
+                            // Nested write data (or a lookup-first upsert) cannot run as a
+                            // single deferred statement. Prisma's array form still supports
+                            // those, so fall back to running the WHOLE array sequentially
+                            // inside one transaction; ordering and atomicity are preserved.
+                            if (batchables.some((b) => b.nested())) {
+                                return await db.$transaction(async (tx) => {
+                                    const out = [];
+                                    for (const b of batchables)
+                                        out.push(await b.execInTx((n) => tx.table(n)));
+                                    return out;
+                                }, txOptions);
                             }
-                            return b;
-                        });
-                        // Nested write data (or a lookup-first upsert) cannot run as a
-                        // single deferred statement. Prisma's array form still supports
-                        // those, so fall back to running the WHOLE array sequentially
-                        // inside one transaction; ordering and atomicity are preserved.
-                        if (batchables.some((b) => b.nested())) {
-                            return await db.$transaction(async (tx) => {
-                                const out = [];
-                                for (const b of batchables)
-                                    out.push(await b.execInTx((n) => tx.table(n)));
-                                return out;
-                            }, txOptions);
+                            const deferreds = batchables.map((b) => b.build());
+                            const results = (await db.$transaction(deferreds));
+                            return results.map((raw, i) => batchables[i].reshape(raw));
                         }
-                        const deferreds = batchables.map((b) => b.build());
-                        const results = (await db.$transaction(deferreds));
-                        return results.map((raw, i) => batchables[i].reshape(raw));
-                    }
-                    catch (err) {
-                        throw decorate(err, ctx.options.prismaErrorCodes);
-                    }
-                })();
-            }
-            // Callback form: hand the user a compat client bound to the tx connection.
-            const fn = arg;
-            return db.$transaction((tx) => {
-                const txDelegates = {};
-                for (const [prismaModel, mm] of delegateModels) {
-                    txDelegates[prismaModel] = makeDelegate(ctx, mm, () => tx.table(mm.table), (fn) => fn((n) => tx.table(n)));
-                    const alias = prismaPropertyAlias(prismaModel);
-                    if (alias && !(alias in map.models) && !(alias in txDelegates)) {
-                        txDelegates[alias] = txDelegates[prismaModel];
-                    }
+                        catch (err) {
+                            throw decorate(err, ctx.options.prismaErrorCodes);
+                        }
+                    })();
                 }
-                // Raw SQL on the transaction's own connection. Prisma's tx client
-                // carries these four, and code that mixes `$transaction` with raw SQL is
-                // the common case in a migrated codebase. No model can shadow them: a
-                // Prisma model name cannot start with `$`, and junction accessors skip
-                // every CLIENT_RESERVED_KEYS name.
-                const txClient = { ...txDelegates, ...makeRawSurface(txRunRaw(tx), ph) };
-                return fn(txClient);
-            }, txOptions);
-        }),
-        ...makeRawSurface(runRaw, ph),
-        $connect: async () => { },
-        $disconnect: async () => { },
+                // Callback form: hand the user a compat client bound to the tx connection.
+                const fn = arg;
+                return db.$transaction((tx) => {
+                    const txDelegates = {};
+                    for (const [prismaModel, mm] of delegateModels) {
+                        txDelegates[prismaModel] = extendDelegate(makeDelegate(ctx, mm, () => tx.table(mm.table), (fn) => fn((n) => tx.table(n))), prismaModel, exts);
+                        const alias = prismaPropertyAlias(prismaModel);
+                        if (alias && !(alias in map.models) && !(alias in txDelegates)) {
+                            txDelegates[alias] = txDelegates[prismaModel];
+                        }
+                    }
+                    // Raw SQL on the transaction's own connection. Prisma's tx client
+                    // carries these four, and code that mixes `$transaction` with raw SQL is
+                    // the common case in a migrated codebase. No model can shadow them: a
+                    // Prisma model name cannot start with `$`, and junction accessors skip
+                    // every CLIENT_RESERVED_KEYS name.
+                    const txClient = { ...txDelegates, ...makeRawSurface(txRunRaw(tx), ph) };
+                    return fn(txClient);
+                }, txOptions);
+            }),
+            $extends: ((extension) => {
+                // Prisma's callback form: `client.$extends(fn)` IS `fn(client)`.
+                if (typeof extension === 'function')
+                    return extension(result);
+                return build(applyExtension(exts, extension, modelKeys, clientKeys));
+            }),
+            ...makeRawSurface(runRaw, ph),
+            $connect: async () => { },
+            $disconnect: async () => { },
+        };
+        // Assemble the result: model delegates keyed by Prisma model name, plus the
+        // client-level base methods. A plain object suffices, every model is a known
+        // key from the map, so no dynamic-access proxy is needed.
+        const result = { ...base };
+        for (const [prismaModel, delegate] of delegates)
+            result[prismaModel] = delegate;
+        // Prisma-spelling aliases (`prisma.user` for `model User`). Skipped when the
+        // lowercased name is itself a model or already taken (never shadow a real key).
+        for (const [prismaModel, delegate] of delegates) {
+            const alias = prismaPropertyAlias(prismaModel);
+            if (alias && !(alias in result))
+                result[alias] = delegate;
+        }
+        // Extension `client` members last: every name was checked against the real
+        // client keys in applyExtension, so this can never overwrite a delegate.
+        Object.assign(result, exts.client);
+        return result;
     };
-    // Assemble the result: model delegates keyed by Prisma model name, plus the
-    // client-level base methods. A plain object suffices, every model is a known
-    // key from the map, so no dynamic-access proxy is needed.
-    const result = { ...base };
-    for (const [prismaModel, delegate] of delegates)
-        result[prismaModel] = delegate;
-    // Prisma-spelling aliases (`prisma.user` for `model User`). Skipped when the
-    // lowercased name is itself a model or already taken (never shadow a real key).
-    for (const [prismaModel, delegate] of delegates) {
-        const alias = prismaPropertyAlias(prismaModel);
-        if (alias && !(alias in result))
-            result[alias] = delegate;
-    }
-    return result;
+    return build(EMPTY_EXTENSIONS);
 }

package/dist/cjs/query/aggregates.d.ts

@@ -10,7 +10,7 @@
  */
 import type { TableMetadata } from '../schema.js';
 import type { DeferredQuery } from './deferred.js';
-import type { AggregateArgs, AggregateResult, GroupByArgs, GroupByOrderBy, HavingClause, HavingFilter } from './types.js';
+import type { AggregateArgs, AggregateResult, GroupByArgs, GroupByOrderBy, HavingClause } from './types.js';
 import type { BuilderCtx } from './where.js';
 /**
  * Enforce the PII contract on the aggregate surface. A PII-tagged
@@ -65,28 +65,52 @@ export declare function resolveJsonPathTarget(qi: BuilderCtx, context: string, f
  * JSON paths push their text[] param here, after the WHERE params.
  */
 export declare function buildDistinctOnSource<T extends object>(qi: BuilderCtx, distinctOn: NonNullable<GroupByArgs<T>['distinctOn']>, whereSql: string, params: unknown[]): string;
+/**
+ * How one groupBy group key is addressed from a `having` SCALAR filter: a
+ * plain `by` column (compiled by the shared WHERE machinery, by field name) or
+ * a JSON-path group key (its SELECT/GROUP BY extract expression, re-emitted
+ * verbatim with its already-bound path placeholder).
+ */
+export type HavingGroupKey = {
+    kind: 'column';
+    field: string;
+} | {
+    kind: 'expr';
+    expr: string;
+    label: string;
+};
 /**
  * Build the SQL fragments for a {@link HavingClause}.
  *
+ * A field entry carries an AGGREGATE filter (`{ _sum: { gt: 100 } }`), a
+ * SCALAR filter on the grouped value itself (`{ not: null }`, `{ in: [...] }`,
+ * or a bare value as equality shorthand), or both in one object (ANDed,
+ * scalar first). `AND` / `OR` / `NOT` combine predicates at any depth.
+ *
  * Each aggregate expression (`COUNT(*)`, `SUM("col")`, etc.) is constructed
  * from a **schema-validated, quoted** column identifier: `qi.toColumn()`
  * throws {@link ValidationError} for unknown fields and `qi.q()` quotes via
  * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
  * comparison value is pushed onto the shared `params` array and referenced by
- * a `$N` placeholder via {@link buildHavingNumericClauses}, there is no string
- * interpolation of user values.
+ * a `$N` placeholder via {@link buildHavingNumericClauses} (aggregates) or the
+ * shared WHERE compiler (scalars), there is no string interpolation of user
+ * values.
  *
  * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
  * exact aggregate expression a JSON-path aggregate emitted in SELECT
  * (including its already-bound path placeholder), so HAVING on a JSON-path
  * aggregate alias reuses the same expression instead of resolving the alias
- * as a column.
+ * as a column. `groupKeys` is the resolved `by` key set (see
+ * {@link HavingGroupKey}): a scalar filter is legal ONLY on a group key,
+ * because a non-grouped column cannot be referenced in HAVING at all.
  */
-export declare function buildHavingClauses<T extends object>(qi: BuilderCtx, having: HavingClause<T>, params: unknown[], jsonAggExprs?: Map<string, string>): string[];
+export declare function buildHavingClauses<T extends object>(qi: BuilderCtx, having: HavingClause<T>, params: unknown[], jsonAggExprs?: Map<string, string>, groupKeys?: Map<string, HavingGroupKey>): string[];
 /**
- * Convert a single having filter into one or more parameterized SQL
- * comparisons against the given aggregate expression. A bare number is
- * shorthand for equality. Unknown operator keys throw {@link ValidationError}.
+ * Convert a single having aggregate filter into one or more parameterized SQL
+ * comparisons against the given aggregate expression. A bare value is
+ * shorthand for equality. Operands are not numeric-only: `_min` / `_max`
+ * return a stored cell, so `MIN("title") > 'm'` is as valid as
+ * `SUM("views") > 10`. Unknown operator keys throw {@link ValidationError}.
  */
-export declare function buildHavingNumericClauses(qi: BuilderCtx, expr: string, filter: HavingFilter, params: unknown[]): string[];
+export declare function buildHavingNumericClauses(qi: BuilderCtx, expr: string, filter: unknown, params: unknown[]): string[];
 export declare function buildAggregate<T extends object>(qi: BuilderCtx, args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;