turbine-orm 0.40.1 → 0.41.0

package/dist/prisma-compat.js

@@ -0,0 +1,1143 @@
+/**
+ * turbine-orm/prisma-compat, a typed PrismaClient-surface adapter over a
+ * {@link TurbineClient}.
+ *
+ * This subpath lets a codebase that speaks Prisma's `db.model.findMany(...)`
+ * surface run on Turbine with minimal churn. It is a **pure TypeScript shim**:
+ * zero new runtime dependencies, never imported by Turbine core, and driven
+ * entirely by the {@link PrismaCompatMap} that `turbine migrate-from-prisma`
+ * emits (`prisma-map.ts`). Every Prisma model / field / relation / compound
+ * unique name in the map was resolved against live introspected metadata, so
+ * the adapter only ever translates names it can prove exist.
+ *
+ * ## What it does
+ *
+ * - **Model delegates** under both the Prisma model name (`compat.User`) and
+ *   Prisma's client-property spelling with the first letter lowercased
+ *   (`compat.user`, what generated Prisma call sites actually use),
+ *   translating args recursively: `include`→`with`, `select` split into scalar
+ *   selection + relations, field/relation renames both ways through the map,
+ *   `take`/`skip`→`limit`/`offset`, cursor pagination, and compound-unique
+ *   selectors (including custom `@@unique(name:)` names the core `findUnique`
+ *   derivation cannot know).
+ * - **`$transaction`** in both forms: a callback (`$transaction(async (tx) => …)`)
+ *   and Prisma's lazy array batching (`$transaction([a.create(...), b.update(...)])`)
+ *  , the un-awaited delegate calls defer to Turbine's `build*()` methods and
+ *   run atomically through the core batch `$transaction([...])` path.
+ * - **Raw SQL**: `$queryRaw` / `$executeRaw` tagged templates (with
+ *   `Prisma.sql`-style nested-fragment flattening) and the `*Unsafe` variants.
+ * - **Result reshaping**: `_count` objects keyed back to Prisma relation names,
+ *   and to-one relations surfaced as `object | null`.
+ *
+ * ## What it deliberately does NOT do (documented divergences)
+ *
+ * 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.
+ * - `instanceof PrismaClientKnownRequestError`, `.meta`/message byte parity
+ *   (opt into `prismaErrorCodes` for a `.code` like `P2002`, without pretending
+ *   `instanceof` identity).
+ * - `Prisma.join` / `Prisma.raw` composition beyond plain fragment flattening.
+ * - Fluent relation chaining (`prisma.user.findUnique().posts()`).
+ * - Accelerate / Pulse / driver-adapter preview features, the Mongo API, and the
+ *   `prisma migrate`/`db` CLI family (Turbine ships its own migrations).
+ * - **Inclusive bare cursors whose field is not the sort key**, see
+ *   {@link translateCursor}. A bare Prisma cursor is inclusive; translating it
+ *   correctly needs the anchor row's sort-key value. When the cursor field is
+ *   the single `orderBy` field (or the cursor is the single-column PK with no
+ *   `orderBy`) it compiles to a `gte`/`lte` keyset predicate; **otherwise it
+ *   throws** an {@link UnsupportedFeatureError} rather than emit an off-by-one
+ *   page. Pair the cursor with `skip: 1` (Prisma's idiom) for the exact
+ *   exclusive-cursor + `offset` translation.
+ * - **Negative `take`** (take-from-end) and **`skip` on a nested relation
+ *   include** throw, Turbine's `with` clause has no offset and no reverse-take.
+ *
+ * ## Type dependencies (0.41.0)
+ *
+ * - Field-name identity fast path pairs with the generator's
+ *   `--keep-column-names` output (byte-shaped like a snake_case Prisma client).
+ * - Compound-unique default selectors are handled by the core
+ *   `findUnique`-family derivation; this adapter only translates custom
+ *   `@@unique(name:)` names on top.
+ * - To-one relations return `object | null` natively once the unique-FK hasOne
+ *   introspection default is in effect (0.41.0). Until a schema is regenerated,
+ *   the map's `cardinality: 'one'` still drives the first-element-or-null guard,
+ *   so the surface is correct either way.
+ *
+ * @example
+ * ```ts
+ * import { TurbineClient } from 'turbine-orm';
+ * import { createPrismaCompatClient } from 'turbine-orm/prisma-compat';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ * import { PRISMA_MAP } from './generated/turbine/prisma-map.js';
+ *
+ * const db = new TurbineClient({ connectionString: process.env.DATABASE_URL }, SCHEMA);
+ * const prisma = createPrismaCompatClient(db, PRISMA_MAP);
+ *
+ * const users = await prisma.User.findMany({
+ *   where: { email: { contains: '@acme.com' } },
+ *   include: { posts: { orderBy: { createdAt: 'desc' }, take: 5 } },
+ * });
+ * ```
+ */
+import { TurbineError, TurbineErrorCode, UnsupportedFeatureError, ValidationError, wrapPgError } from './errors.js';
+// ---------------------------------------------------------------------------
+// Prisma.sql-style raw fragments (local, minimal, never imports @prisma/client)
+// ---------------------------------------------------------------------------
+const SQL_FRAGMENT = Symbol.for('turbine.prismaCompat.sqlFragment');
+function isSqlFragment(x) {
+    return typeof x === 'object' && x !== null && x[SQL_FRAGMENT] === true;
+}
+function makeSql(strings, values) {
+    return { strings, values, [SQL_FRAGMENT]: true };
+}
+/**
+ * `Prisma`-compatible raw-SQL helpers, a minimal local implementation so
+ * migrated `Prisma.sql\`…\`` / `Prisma.join(...)` / `Prisma.raw(...)` calls keep
+ * composing. Fragments are flattened at execution time into a single
+ * parameterized statement (values become `$N`), so composition is injection-safe
+ * by construction.
+ */
+export const Prisma = {
+    /** Tagged-template fragment: `Prisma.sql\`id = ${id}\``. */
+    sql(strings, ...values) {
+        return makeSql(strings, values);
+    },
+    /**
+     * Join fragments/values with a separator: `Prisma.join([1, 2, 3])` →
+     * `$1, $2, $3`. Each element that is not already a fragment becomes a bound
+     * value.
+     */
+    join(items, separator = ',', prefix = '', suffix = '') {
+        if (items.length === 0)
+            return makeSql([`${prefix}${suffix}`], []);
+        const strings = [prefix];
+        const values = [];
+        items.forEach((item, i) => {
+            values.push(item);
+            strings.push(i === items.length - 1 ? suffix : separator);
+        });
+        return makeSql(strings, values);
+    },
+    /**
+     * A raw, unparameterized SQL fragment. The string is spliced verbatim, never
+     * pass user input here (matches Prisma's `Prisma.raw` contract).
+     */
+    raw(sql) {
+        return makeSql([sql], []);
+    },
+    /** An empty fragment. */
+    empty: makeSql([''], []),
+};
+/** Turbine error code → nearest Prisma `PXXXX` code. */
+const PRISMA_ERROR_CODE = {
+    [TurbineErrorCode.UNIQUE_VIOLATION]: 'P2002',
+    [TurbineErrorCode.NOT_FOUND]: 'P2025',
+    [TurbineErrorCode.FOREIGN_KEY_VIOLATION]: 'P2003',
+    [TurbineErrorCode.NOT_NULL_VIOLATION]: 'P2011',
+    [TurbineErrorCode.TIMEOUT]: 'P2024',
+};
+/** Attach a Prisma-style `.code` to a TurbineError when the option is on. */
+function decorate(err, prismaErrorCodes) {
+    if (prismaErrorCodes && err instanceof TurbineError) {
+        const p = PRISMA_ERROR_CODE[err.code];
+        if (p)
+            err.code = p;
+    }
+    return err;
+}
+function buildLookups(mm) {
+    const reverseFields = {};
+    let identityFields = true;
+    for (const [prismaField, turbineField] of Object.entries(mm.fields)) {
+        reverseFields[turbineField] = prismaField;
+        if (prismaField !== turbineField)
+            identityFields = false;
+    }
+    const reverseRelations = {};
+    for (const [prismaRel, rel] of Object.entries(mm.relations)) {
+        reverseRelations[rel.name] = { prismaName: prismaRel, cardinality: rel.cardinality };
+    }
+    return { reverseFields, identityFields, reverseRelations };
+}
+function lookupsFor(ctx, mm) {
+    let l = ctx.lookups.get(mm.table);
+    if (!l) {
+        l = buildLookups(mm);
+        ctx.lookups.set(mm.table, l);
+    }
+    return l;
+}
+/** Resolve a turbine relation's target Prisma model map (for nested translation). */
+function relTargetModel(ctx, mm, turbineRel) {
+    const rd = ctx.schema.tables[mm.table]?.relations?.[turbineRel];
+    if (!rd)
+        return undefined;
+    const modelName = ctx.tableToModel.get(rd.to);
+    return modelName ? ctx.map.models[modelName] : undefined;
+}
+// ---------------------------------------------------------------------------
+// Argument translation
+// ---------------------------------------------------------------------------
+const COMBINATORS = new Set(['AND', 'OR', 'NOT']);
+const RELATION_QUANTIFIERS = new Set(['some', 'every', 'none']);
+/** Whether a value is a plain object usable as a compound-unique selector. */
+function isPlainObject(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        !Array.isArray(v) &&
+        !(v instanceof Date) &&
+        !(typeof Buffer !== 'undefined' && Buffer.isBuffer(v)));
+}
+function renameField(mm, prismaField) {
+    return mm.fields[prismaField] ?? prismaField;
+}
+/**
+ * Translate a Prisma `where` (or nested relation where) into a Turbine `where`.
+ * Renames scalar field keys and relation keys through the map, recurses into
+ * `AND`/`OR`/`NOT`, translates relation quantifier filters (`some`/`every`/
+ * `none`) against the target model, and rewrites compound-unique selectors -
+ * including custom `@@unique(name:)` names, into the core-derived selector form
+ * so Turbine's `findUnique`-family expansion handles them uniformly.
+ */
+function translateWhere(ctx, mm, where) {
+    if (!isPlainObject(where))
+        return where;
+    const out = {};
+    for (const [key, val] of Object.entries(where)) {
+        if (COMBINATORS.has(key)) {
+            out[key] = Array.isArray(val) ? val.map((v) => translateWhere(ctx, mm, v)) : translateWhere(ctx, mm, val);
+            continue;
+        }
+        // Compound-unique selector (custom or default Prisma name).
+        const compound = mm.compoundUniques[key];
+        if (compound && isPlainObject(val) && !mm.fields[key] && !mm.relations[key]) {
+            const inner = {};
+            for (const [pk, pv] of Object.entries(val))
+                inner[renameField(mm, pk)] = pv;
+            // Turbine's core derives the selector name from the underscore-join of the
+            // member FIELD names, so re-key custom names onto that canonical form.
+            out[compound.join('_')] = inner;
+            continue;
+        }
+        // Relation filter.
+        const rel = mm.relations[key];
+        if (rel) {
+            const target = relTargetModel(ctx, mm, rel.name);
+            out[rel.name] = translateRelationFilter(ctx, target, val);
+            continue;
+        }
+        // Scalar field, key renamed, value (literal or operator object) passes
+        // through unchanged (Prisma operator names match Turbine's).
+        out[renameField(mm, key)] = val;
+    }
+    return out;
+}
+function translateRelationFilter(ctx, target, val) {
+    if (!isPlainObject(val))
+        return val;
+    const keys = Object.keys(val);
+    const hasQuantifier = keys.some((k) => RELATION_QUANTIFIERS.has(k) || k === 'is' || k === 'isNot');
+    if (hasQuantifier) {
+        const out = {};
+        for (const [k, v] of Object.entries(val)) {
+            out[k] =
+                target && (RELATION_QUANTIFIERS.has(k) || k === 'is' || k === 'isNot') ? translateWhere(ctx, target, v) : v;
+        }
+        return out;
+    }
+    // A bare object filter on a to-one relation: translate its body.
+    return target ? translateWhere(ctx, target, val) : val;
+}
+/** Translate a Prisma `orderBy` (object / array) into a Turbine `orderBy`. */
+function translateOrderBy(ctx, mm, ob) {
+    if (Array.isArray(ob))
+        return ob.map((o) => translateOrderBy(ctx, mm, o));
+    if (!isPlainObject(ob))
+        return ob;
+    const out = {};
+    for (const [key, val] of Object.entries(ob)) {
+        if (key === '_count') {
+            out._count = val;
+            continue;
+        }
+        const rel = mm.relations[key];
+        if (rel) {
+            const target = relTargetModel(ctx, mm, rel.name);
+            out[rel.name] = isPlainObject(val) && !('_count' in val) && target ? translateOrderBy(ctx, target, val) : val;
+            continue;
+        }
+        out[renameField(mm, key)] = val;
+    }
+    return out;
+}
+/** Map a Prisma `take` to a Turbine `limit`. Negative take is unsupported. */
+function mapTake(take) {
+    if (take < 0) {
+        throw new UnsupportedFeatureError('negative take (take-from-end pagination)', 'prisma-compat', 'Turbine has no reverse-take; reverse your orderBy and use a positive take instead.');
+    }
+    return take;
+}
+/**
+ * Translate Prisma `include` / `select` into Turbine `{ select, with }`.
+ * `include` keeps all scalars and adds relations; `select` narrows scalars and
+ * may also pull relations + `_count`. The two are mutually exclusive.
+ */
+function translateProjection(ctx, mm, args) {
+    const include = args.include;
+    const select = args.select;
+    if (include && select) {
+        throw new ValidationError('[turbine] prisma-compat: `include` and `select` are mutually exclusive.');
+    }
+    const withClause = {};
+    let hasWith = false;
+    if (include) {
+        for (const [key, val] of Object.entries(include)) {
+            if (val === false || val == null)
+                continue;
+            if (key === '_count') {
+                withClause._count = translateCountSelect(mm, val);
+                hasWith = true;
+                continue;
+            }
+            const rel = mm.relations[key];
+            if (!rel) {
+                throw new ValidationError(`[turbine] prisma-compat: unknown relation "${key}" in include on model "${modelName(ctx, mm)}".`);
+            }
+            withClause[rel.name] = translateWithOption(ctx, mm, rel.name, val);
+            hasWith = true;
+        }
+        return { with: hasWith ? withClause : undefined };
+    }
+    if (select) {
+        const scalar = {};
+        let hasScalar = false;
+        for (const [key, val] of Object.entries(select)) {
+            if (val === false || val == null)
+                continue;
+            if (key === '_count') {
+                withClause._count = translateCountSelect(mm, val);
+                hasWith = true;
+                continue;
+            }
+            const rel = mm.relations[key];
+            if (rel) {
+                withClause[rel.name] = translateWithOption(ctx, mm, rel.name, val);
+                hasWith = true;
+                continue;
+            }
+            scalar[renameField(mm, key)] = true;
+            hasScalar = true;
+        }
+        return { select: hasScalar ? scalar : undefined, with: hasWith ? withClause : undefined };
+    }
+    return {};
+}
+/** Translate a Prisma relation include payload into a Turbine `WithOptions`. */
+function translateWithOption(ctx, mm, turbineRel, val) {
+    if (val === true)
+        return true;
+    if (!isPlainObject(val))
+        return true;
+    const target = relTargetModel(ctx, mm, turbineRel);
+    const opt = {};
+    if (val.where !== undefined)
+        opt.where = target ? translateWhere(ctx, target, val.where) : val.where;
+    if (val.orderBy !== undefined)
+        opt.orderBy = target ? translateOrderBy(ctx, target, val.orderBy) : val.orderBy;
+    if (val.take !== undefined)
+        opt.limit = mapTake(val.take);
+    if (val.skip !== undefined) {
+        throw new UnsupportedFeatureError('skip (offset) on a nested relation include', 'prisma-compat', "Turbine's `with` clause has no offset, page the relation with a separate query.");
+    }
+    if (target && (val.select !== undefined || val.include !== undefined)) {
+        const proj = translateProjection(ctx, target, val);
+        if (proj.select)
+            opt.select = proj.select;
+        if (proj.with)
+            opt.with = proj.with;
+    }
+    return opt;
+}
+/** Translate a Prisma `_count: { select: { rel: true } }` / `true` into Turbine `with._count`. */
+function translateCountSelect(mm, val) {
+    if (val === true)
+        return true;
+    if (isPlainObject(val) && isPlainObject(val.select)) {
+        const out = {};
+        for (const [key, v] of Object.entries(val.select)) {
+            if (!v)
+                continue;
+            const rel = mm.relations[key];
+            if (rel)
+                out[rel.name] = true;
+        }
+        return out;
+    }
+    return true;
+}
+function modelName(ctx, mm) {
+    return ctx.tableToModel.get(mm.table) ?? mm.table;
+}
+/**
+ * Assemble Turbine findMany-family args from Prisma read args. Order matters:
+ * `where` / `orderBy` are translated first so the cursor step (which may inject
+ * a keyset predicate) operates in the translated turbine-field space.
+ */
+function translateReadArgs(ctx, mm, prismaArgs) {
+    const t = {};
+    if (prismaArgs.where !== undefined)
+        t.where = translateWhere(ctx, mm, prismaArgs.where);
+    if (prismaArgs.orderBy !== undefined)
+        t.orderBy = translateOrderBy(ctx, mm, prismaArgs.orderBy);
+    const proj = translateProjection(ctx, mm, prismaArgs);
+    if (proj.select)
+        t.select = proj.select;
+    if (proj.with)
+        t.with = proj.with;
+    if (Array.isArray(prismaArgs.distinct)) {
+        t.distinct = prismaArgs.distinct.map((f) => renameField(mm, f));
+    }
+    if (prismaArgs.relationLoadStrategy !== undefined)
+        t.relationLoadStrategy = prismaArgs.relationLoadStrategy;
+    if (typeof prismaArgs.timeout === 'number')
+        t.timeout = prismaArgs.timeout;
+    if (ctx.options.stablePkOrder)
+        t.stableRelationOrder = true;
+    translateCursor(ctx, mm, prismaArgs, t);
+    return t;
+}
+/** turbine field names of the model's single-column primary key, if any. */
+function singleColumnPkField(ctx, mm) {
+    const pk = ctx.schema.tables[mm.table]?.primaryKey;
+    if (pk && pk.length === 1) {
+        const col = pk[0];
+        return ctx.schema.tables[mm.table]?.reverseColumnMap?.[col] ?? col;
+    }
+    return undefined;
+}
+/**
+ * Translate Prisma cursor + take/skip onto Turbine args (operating on already
+ * translated `t.where` / `t.orderBy` in turbine-field space).
+ *
+ * - **No cursor:** `skip`→`offset`, `take`→`limit`.
+ * - **Cursor + `skip: n` (n≥1):** the idiomatic exclusive-pagination case →
+ *   Turbine's exclusive `cursor` + `offset: n-1` (skip:1 → offset 0, an exact
+ *   match).
+ * - **Bare inclusive cursor** (skip absent/0): a Prisma cursor is INCLUSIVE, so
+ *   it needs the anchor's sort-key value. Compiled to a `gte`/`lte` keyset
+ *   predicate merged into `where` ONLY when the cursor is single-field AND that
+ *   field is the single `orderBy` field (or, with no `orderBy`, is the
+ *   single-column PK). Any other shape THROWS rather than emit a wrong page -
+ *   pair the cursor with `skip: 1` for the exact exclusive translation.
+ */
+function translateCursor(ctx, mm, prismaArgs, t) {
+    const cursor = prismaArgs.cursor;
+    const skip = prismaArgs.skip;
+    const take = prismaArgs.take;
+    if (take !== undefined)
+        t.limit = mapTake(take);
+    if (cursor === undefined) {
+        if (skip !== undefined)
+            t.offset = skip;
+        return;
+    }
+    // Translate cursor field names (and expand a compound-unique selector cursor).
+    const tcursor = {};
+    for (const [key, val] of Object.entries(cursor)) {
+        if (val === undefined)
+            continue;
+        const compound = mm.compoundUniques[key];
+        if (compound && isPlainObject(val)) {
+            for (const [pk, pv] of Object.entries(val))
+                tcursor[renameField(mm, pk)] = pv;
+        }
+        else {
+            tcursor[renameField(mm, key)] = val;
+        }
+    }
+    const cursorFields = Object.keys(tcursor);
+    if (skip !== undefined && skip >= 1) {
+        t.cursor = tcursor;
+        t.offset = skip - 1;
+        return;
+    }
+    // Bare inclusive cursor (skip absent or 0).
+    if (cursorFields.length !== 1) {
+        throw new UnsupportedFeatureError('inclusive multi-field cursor without skip', 'prisma-compat', 'Pair the cursor with `skip: 1` (the Prisma idiom) so it maps to an exact exclusive cursor.');
+    }
+    const field = cursorFields[0];
+    const value = tcursor[field];
+    const obEntries = orderByPairs(t.orderBy);
+    let desc = false;
+    if (obEntries.length === 0) {
+        const pkField = singleColumnPkField(ctx, mm);
+        if (!pkField || field !== pkField) {
+            throw new UnsupportedFeatureError('inclusive cursor without orderBy on a non-PK field', 'prisma-compat', `A bare Prisma cursor is inclusive; translating it needs the cursor field "${field}" to be the single-column primary key, or to be the single orderBy field. Pair the cursor with \`skip: 1\`.`);
+        }
+        t.orderBy = { [field]: 'asc' };
+    }
+    else {
+        if (obEntries.length !== 1 || obEntries[0][0] !== field) {
+            throw new UnsupportedFeatureError('inclusive cursor whose field is not the sort key', 'prisma-compat', `A bare Prisma cursor is inclusive; translating it needs the cursor field "${field}" to be the single orderBy field. Order by "${field}", or pair the cursor with \`skip: 1\`.`);
+        }
+        desc = obEntries[0][1];
+    }
+    const op = desc ? 'lte' : 'gte';
+    t.where = mergeKeyset(t.where ?? {}, field, op, value);
+}
+/** Flatten a Turbine orderBy (object or single-object array) into [field, isDesc] pairs. */
+function orderByPairs(ob) {
+    const one = Array.isArray(ob) ? (ob.length === 1 ? ob[0] : undefined) : ob;
+    if (!isPlainObject(one))
+        return [];
+    const out = [];
+    for (const [k, v] of Object.entries(one)) {
+        const dir = isPlainObject(v) ? v.sort : v;
+        out.push([k, dir === 'desc']);
+    }
+    return out;
+}
+/** Merge a `{ field: { gte|lte: value } }` keyset predicate into a where object. */
+function mergeKeyset(where, field, op, value) {
+    const merged = { ...where };
+    const existing = merged[field];
+    if (isPlainObject(existing)) {
+        merged[field] = { ...existing, [op]: value };
+    }
+    else if (existing !== undefined) {
+        const prevAnd = merged.AND;
+        const andList = Array.isArray(prevAnd) ? prevAnd : prevAnd !== undefined ? [prevAnd] : [];
+        merged.AND = [...andList, { [field]: { [op]: value } }];
+    }
+    else {
+        merged[field] = { [op]: value };
+    }
+    return merged;
+}
+// --- write-data translation (nested writes) -------------------------------
+const NESTED_WRITE_OPS = new Set([
+    'create',
+    'createMany',
+    'connect',
+    'connectOrCreate',
+    'disconnect',
+    'set',
+    'delete',
+    'deleteMany',
+    'update',
+    'updateMany',
+    'upsert',
+]);
+/**
+ * Translate Prisma create/update `data` (including nested relation write ops)
+ * into Turbine's shape. Scalar keys are renamed via the map; relation keys are
+ * renamed to their Turbine relation name and their nested-write payloads are
+ * translated against the target model (op names match Prisma's).
+ */
+function translateWriteData(ctx, mm, data) {
+    if (!isPlainObject(data))
+        return data;
+    const out = {};
+    for (const [key, val] of Object.entries(data)) {
+        const rel = mm.relations[key];
+        if (rel && isPlainObject(val) && Object.keys(val).some((k) => NESTED_WRITE_OPS.has(k))) {
+            const target = relTargetModel(ctx, mm, rel.name);
+            out[rel.name] = translateNestedWrite(ctx, target, val);
+            continue;
+        }
+        out[renameField(mm, key)] = val;
+    }
+    return out;
+}
+function translateNestedWrite(ctx, target, ops) {
+    const out = {};
+    for (const [op, payload] of Object.entries(ops)) {
+        switch (op) {
+            case 'create':
+            case 'createMany':
+                out[op] = mapMaybeArray(payload, (p) => (target ? translateWriteData(ctx, target, p) : p));
+                break;
+            case 'connect':
+            case 'disconnect':
+            case 'delete':
+            case 'set':
+                out[op] = mapMaybeArray(payload, (p) => (target ? translateWhere(ctx, target, p) : p));
+                break;
+            case 'deleteMany':
+            case 'updateMany':
+                out[op] = mapMaybeArray(payload, (p) => translateWhereDataPair(ctx, target, p));
+                break;
+            case 'update':
+                out[op] = mapMaybeArray(payload, (p) => translateWhereDataPair(ctx, target, p));
+                break;
+            case 'connectOrCreate':
+                out[op] = mapMaybeArray(payload, (p) => translateConnectOrCreate(ctx, target, p));
+                break;
+            case 'upsert':
+                out[op] = mapMaybeArray(payload, (p) => translateUpsertNested(ctx, target, p));
+                break;
+            default:
+                out[op] = payload;
+        }
+    }
+    return out;
+}
+function mapMaybeArray(val, fn) {
+    return Array.isArray(val) ? val.map(fn) : fn(val);
+}
+/** A `{ where?, data }` pair (nested update/updateMany), or a bare data object. */
+function translateWhereDataPair(ctx, target, p) {
+    if (!isPlainObject(p))
+        return p;
+    if ('data' in p || 'where' in p) {
+        const out = {};
+        if (p.where !== undefined)
+            out.where = target ? translateWhere(ctx, target, p.where) : p.where;
+        if (p.data !== undefined)
+            out.data = target ? translateWriteData(ctx, target, p.data) : p.data;
+        return out;
+    }
+    return target ? translateWriteData(ctx, target, p) : p;
+}
+function translateConnectOrCreate(ctx, target, p) {
+    if (!isPlainObject(p))
+        return p;
+    const out = {};
+    if (p.where !== undefined)
+        out.where = target ? translateWhere(ctx, target, p.where) : p.where;
+    if (p.create !== undefined)
+        out.create = target ? translateWriteData(ctx, target, p.create) : p.create;
+    return out;
+}
+function translateUpsertNested(ctx, target, p) {
+    if (!isPlainObject(p))
+        return p;
+    const out = {};
+    if (p.where !== undefined)
+        out.where = target ? translateWhere(ctx, target, p.where) : p.where;
+    if (p.create !== undefined)
+        out.create = target ? translateWriteData(ctx, target, p.create) : p.create;
+    if (p.update !== undefined)
+        out.update = target ? translateWriteData(ctx, target, p.update) : p.update;
+    return out;
+}
+// --- aggregate / groupBy translation --------------------------------------
+const AGG_FIELD_BLOCKS = ['_sum', '_avg', '_min', '_max'];
+function translateAggregateArgs(ctx, mm, args, isGroupBy) {
+    const t = {};
+    if (args.where !== undefined)
+        t.where = translateWhere(ctx, mm, args.where);
+    if (args._count !== undefined)
+        t._count = renameAggBlock(mm, args._count, true);
+    for (const block of AGG_FIELD_BLOCKS) {
+        if (args[block] !== undefined)
+            t[block] = renameAggBlock(mm, args[block], false);
+    }
+    if (typeof args.timeout === 'number')
+        t.timeout = args.timeout;
+    if (isGroupBy) {
+        if (Array.isArray(args.by))
+            t.by = args.by.map((f) => renameField(mm, f));
+        if (args.orderBy !== undefined)
+            t.orderBy = translateOrderBy(ctx, mm, args.orderBy);
+        if (args.having !== undefined)
+            t.having = renameHaving(mm, args.having);
+        if (typeof args.take === 'number')
+            t.limit = mapTake(args.take);
+        if (typeof args.skip === 'number')
+            t.offset = args.skip;
+    }
+    return t;
+}
+/** Rename field keys inside an aggregate block; `_count`'s `_all` passes through. */
+function renameAggBlock(mm, block, isCount) {
+    if (block === true || !isPlainObject(block))
+        return block;
+    const out = {};
+    for (const [key, val] of Object.entries(block)) {
+        if (isCount && key === '_all') {
+            out._all = val;
+            continue;
+        }
+        out[renameField(mm, key)] = val;
+    }
+    return out;
+}
+function renameHaving(mm, having) {
+    if (!isPlainObject(having))
+        return having;
+    const out = {};
+    for (const [key, val] of Object.entries(having)) {
+        if (COMBINATORS.has(key)) {
+            out[key] = Array.isArray(val) ? val.map((v) => renameHaving(mm, v)) : renameHaving(mm, val);
+            continue;
+        }
+        if (key === '_count') {
+            out._count = val;
+            continue;
+        }
+        out[renameField(mm, key)] = val;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Result reshaping (turbine field/relation names → prisma names)
+// ---------------------------------------------------------------------------
+function reshapeRows(ctx, mm, rows) {
+    return Array.isArray(rows) ? rows.map((r) => reshapeRow(ctx, mm, r)) : rows;
+}
+function reshapeRowOrNull(ctx, mm, row) {
+    return row == null ? null : reshapeRow(ctx, mm, row);
+}
+function reshapeRow(ctx, mm, row) {
+    if (!isPlainObject(row))
+        return row;
+    const l = lookupsFor(ctx, mm);
+    const out = {};
+    for (const [key, val] of Object.entries(row)) {
+        if (key === '_count') {
+            out._count = reshapeCount(l, val);
+            continue;
+        }
+        const rel = l.reverseRelations[key];
+        if (rel) {
+            const target = relTargetModel(ctx, mm, key);
+            let rv;
+            if (Array.isArray(val)) {
+                const mapped = target ? val.map((x) => reshapeRow(ctx, target, x)) : val;
+                // To-one guard: legacy 'many' metadata may still surface an array; the
+                // map's cardinality is authoritative → first element or null.
+                rv = rel.cardinality === 'one' ? (mapped.length ? mapped[0] : null) : mapped;
+            }
+            else if (isPlainObject(val)) {
+                rv = target ? reshapeRow(ctx, target, val) : val;
+            }
+            else {
+                rv = val; // null to-one
+            }
+            out[rel.prismaName] = rv;
+            continue;
+        }
+        out[l.identityFields ? key : (l.reverseFields[key] ?? key)] = val;
+    }
+    return out;
+}
+function reshapeCount(l, count) {
+    if (!isPlainObject(count))
+        return count;
+    const out = {};
+    for (const [key, val] of Object.entries(count)) {
+        if (key === '_all') {
+            out._all = val;
+            continue;
+        }
+        out[l.reverseRelations[key]?.prismaName ?? key] = val;
+    }
+    return out;
+}
+/** Reshape an aggregate result: field keys inside blocks → prisma names. */
+function reshapeAggregate(ctx, mm, res) {
+    if (!isPlainObject(res))
+        return res;
+    const l = lookupsFor(ctx, mm);
+    const out = {};
+    for (const [key, val] of Object.entries(res)) {
+        if (key === '_count') {
+            out._count = reshapeAggFieldBlock(l, val, true);
+            continue;
+        }
+        if (AGG_FIELD_BLOCKS.includes(key)) {
+            out[key] = reshapeAggFieldBlock(l, val, false);
+            continue;
+        }
+        out[l.identityFields ? key : (l.reverseFields[key] ?? key)] = val;
+    }
+    return out;
+}
+function reshapeAggFieldBlock(l, block, isCount) {
+    if (!isPlainObject(block))
+        return block;
+    const out = {};
+    for (const [key, val] of Object.entries(block)) {
+        if (isCount && key === '_all') {
+            out._all = val;
+            continue;
+        }
+        out[l.reverseFields[key] ?? key] = val;
+    }
+    return out;
+}
+/** Reshape a groupBy row: by-field keys + aggregate blocks → prisma names. */
+function reshapeGroupRow(ctx, mm, row) {
+    if (!isPlainObject(row))
+        return row;
+    const l = lookupsFor(ctx, mm);
+    const out = {};
+    for (const [key, val] of Object.entries(row)) {
+        if (key === '_count') {
+            out._count = reshapeAggFieldBlock(l, val, true);
+            continue;
+        }
+        if (AGG_FIELD_BLOCKS.includes(key)) {
+            out[key] = reshapeAggFieldBlock(l, val, false);
+            continue;
+        }
+        out[l.identityFields ? key : (l.reverseFields[key] ?? key)] = val;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Lazy PrismaPromise-style thenable + $transaction array batching seam
+// ---------------------------------------------------------------------------
+/** Symbol under which a lazy delegate call exposes its batchable plan. */
+export const COMPAT_DEFERRED = Symbol.for('turbine.prismaCompat.deferred');
+/**
+ * A lazy, Prisma-style promise: the underlying query does not run until the
+ * value is awaited (`.then`), and a `$transaction([...])` array can instead pull
+ * the batchable plan via {@link COMPAT_DEFERRED} to run it atomically.
+ */
+class CompatPromise {
+    run;
+    promise;
+    /** Absent for calls that cannot be a single DeferredQuery (rare). */
+    [COMPAT_DEFERRED];
+    constructor(run, batchable) {
+        this.run = run;
+        this[COMPAT_DEFERRED] = batchable;
+    }
+    exec() {
+        this.promise ??= this.run();
+        return this.promise;
+    }
+    // biome-ignore lint/suspicious/noThenProperty: a `then` member is the point, this is an intentional PrismaPromise-style thenable.
+    then(onFulfilled, onRejected) {
+        return this.exec().then(onFulfilled, onRejected);
+    }
+    catch(onRejected) {
+        return this.exec().catch(onRejected);
+    }
+    finally(onFinally) {
+        return this.exec().finally(onFinally);
+    }
+}
+function batchableOf(v) {
+    return v instanceof CompatPromise ? v[COMPAT_DEFERRED] : undefined;
+}
+/**
+ * Prisma's client-property spelling of a model name: first letter lowercased
+ * (`model User` -> `prisma.user`). Returns null when the spelling is identical
+ * (already lowercase) so callers can skip the alias.
+ */
+function prismaPropertyAlias(model) {
+    const alias = model.charAt(0).toLowerCase() + model.slice(1);
+    return alias === model ? null : alias;
+}
+// ---------------------------------------------------------------------------
+// Delegate construction
+// ---------------------------------------------------------------------------
+/**
+ * Build one model delegate over a query-interface accessor. `getQI` returns the
+ * QueryInterface for this model's table on the active connection (the base pool,
+ * or a transaction's connection inside `$transaction(callback)`).
+ */
+function makeDelegate(ctx, mm, getQI) {
+    const pe = ctx.options.prismaErrorCodes;
+    const lift = (run, batchable) => new CompatPromise(async () => {
+        try {
+            return await run();
+        }
+        catch (err) {
+            throw decorate(err, pe);
+        }
+    }, batchable);
+    const requireWhere = (args, op) => {
+        if (!args || args.where === undefined) {
+            throw new ValidationError(`[turbine] prisma-compat: ${op} on "${modelName(ctx, mm)}" requires a \`where\`.`);
+        }
+        return args;
+    };
+    return {
+        findMany: (args = {}) => {
+            const t = translateReadArgs(ctx, mm, args);
+            return lift(() => getQI()
+                .findMany(t)
+                .then((r) => reshapeRows(ctx, mm, r)), { build: () => getQI().buildFindMany(t), reshape: (raw) => reshapeRows(ctx, mm, raw) });
+        },
+        findFirst: (args = {}) => {
+            const t = translateReadArgs(ctx, mm, args);
+            return lift(() => getQI()
+                .findFirst(t)
+                .then((r) => reshapeRowOrNull(ctx, mm, r)), { build: () => getQI().buildFindFirst(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) });
+        },
+        findUnique: (args) => {
+            const t = translateReadArgs(ctx, mm, requireWhere(args, 'findUnique'));
+            return lift(() => getQI()
+                .findUnique(t)
+                .then((r) => reshapeRowOrNull(ctx, mm, r)), { build: () => getQI().buildFindUnique(t), reshape: (raw) => reshapeRowOrNull(ctx, mm, raw) });
+        },
+        findFirstOrThrow: (args = {}) => {
+            const t = translateReadArgs(ctx, mm, args);
+            return lift(() => getQI()
+                .findFirstOrThrow(t)
+                .then((r) => reshapeRow(ctx, mm, r)), { build: () => getQI().buildFindFirstOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) });
+        },
+        findUniqueOrThrow: (args) => {
+            const t = translateReadArgs(ctx, mm, requireWhere(args, 'findUniqueOrThrow'));
+            return lift(() => getQI()
+                .findUniqueOrThrow(t)
+                .then((r) => reshapeRow(ctx, mm, r)), { build: () => getQI().buildFindUniqueOrThrow(t), reshape: (raw) => reshapeRow(ctx, mm, raw) });
+        },
+        create: (args) => {
+            const t = { data: translateWriteData(ctx, mm, args.data) };
+            if (typeof args.timeout === 'number')
+                t.timeout = args.timeout;
+            return lift(() => getQI()
+                .create(t)
+                .then((r) => reshapeRow(ctx, mm, r)), { build: () => getQI().buildCreate(t), reshape: (raw) => reshapeRow(ctx, mm, raw) });
+        },
+        createMany: (args) => {
+            const data = args.data;
+            const rows = Array.isArray(data) ? data.map((d) => translateWriteData(ctx, mm, d)) : [];
+            const t = { data: rows };
+            if (args.skipDuplicates)
+                t.skipDuplicates = true;
+            return lift(() => getQI()
+                .createMany(t)
+                .then((r) => ({ count: r.length })), { build: () => getQI().buildCreateMany(t), reshape: (raw) => ({ count: raw.length }) });
+        },
+        update: (args) => {
+            const a = requireWhere(args, 'update');
+            const t = { where: translateWhere(ctx, mm, a.where), data: translateWriteData(ctx, mm, a.data) };
+            return lift(() => getQI()
+                .update(t)
+                .then((r) => reshapeRow(ctx, mm, r)), { build: () => getQI().buildUpdate(t), reshape: (raw) => reshapeRow(ctx, mm, raw) });
+        },
+        updateMany: (args) => {
+            const a = args;
+            const t = { where: translateWhere(ctx, mm, a.where ?? {}), data: translateWriteData(ctx, mm, a.data) };
+            if (a.where === undefined)
+                t.allowFullTableScan = true;
+            return lift(() => getQI().updateMany(t), {
+                build: () => getQI().buildUpdateMany(t),
+                reshape: (raw) => raw,
+            });
+        },
+        delete: (args) => {
+            const a = requireWhere(args, 'delete');
+            const t = { where: translateWhere(ctx, mm, a.where) };
+            return lift(() => getQI()
+                .delete(t)
+                .then((r) => reshapeRow(ctx, mm, r)), { build: () => getQI().buildDelete(t), reshape: (raw) => reshapeRow(ctx, mm, raw) });
+        },
+        deleteMany: (args = {}) => {
+            const a = args;
+            const t = { where: translateWhere(ctx, mm, a.where ?? {}) };
+            if (a.where === undefined)
+                t.allowFullTableScan = true;
+            return lift(() => getQI().deleteMany(t), {
+                build: () => getQI().buildDeleteMany(t),
+                reshape: (raw) => raw,
+            });
+        },
+        upsert: (args) => {
+            const a = requireWhere(args, 'upsert');
+            const t = {
+                where: translateWhere(ctx, mm, a.where),
+                create: translateWriteData(ctx, mm, a.create),
+                update: translateWriteData(ctx, mm, a.update),
+            };
+            return lift(() => getQI()
+                .upsert(t)
+                .then((r) => reshapeRow(ctx, mm, r)), { build: () => getQI().buildUpsert(t), reshape: (raw) => reshapeRow(ctx, mm, raw) });
+        },
+        count: (args = {}) => {
+            const t = {};
+            if (args.where !== undefined)
+                t.where = translateWhere(ctx, mm, args.where);
+            if (typeof args.timeout === 'number')
+                t.timeout = args.timeout;
+            return lift(() => getQI().count(t), {
+                build: () => getQI().buildCount(t),
+                reshape: (raw) => raw,
+            });
+        },
+        aggregate: (args) => {
+            const t = translateAggregateArgs(ctx, mm, args, false);
+            return lift(() => getQI()
+                .aggregate(t)
+                .then((r) => reshapeAggregate(ctx, mm, r)), { build: () => getQI().buildAggregate(t), reshape: (raw) => reshapeAggregate(ctx, mm, raw) });
+        },
+        groupBy: (args) => {
+            const t = translateAggregateArgs(ctx, mm, args, true);
+            return lift(() => getQI()
+                .groupBy(t)
+                .then((rows) => rows.map((r) => reshapeGroupRow(ctx, mm, r))), {
+                build: () => getQI().buildGroupBy(t),
+                reshape: (raw) => raw.map((r) => reshapeGroupRow(ctx, mm, r)),
+            });
+        },
+    };
+}
+function poolOf(db) {
+    const pool = db.pool;
+    if (!pool)
+        throw new ValidationError('[turbine] prisma-compat: raw SQL needs a TurbineClient with an active pool.');
+    return pool;
+}
+function placeholderOf(db) {
+    const dialect = db.dialect;
+    return dialect ? (n) => dialect.paramPlaceholder(n) : (n) => `$${n}`;
+}
+/**
+ * Flatten a Prisma-style tagged template, including nested {@link Sql}
+ * fragments, into a single `{ text, params }` pair. Values only ever become
+ * bound `$N` params (never string-concatenated), so composition is
+ * injection-safe. `Prisma.raw(...)` fragments are the sole verbatim splice, by
+ * contract.
+ */
+function flattenTemplate(strings, values, ph) {
+    const params = [];
+    let text = '';
+    const append = (segStrings, segValues) => {
+        for (let i = 0; i < segStrings.length; i++) {
+            text += segStrings[i];
+            if (i < segValues.length) {
+                const v = segValues[i];
+                if (isSqlFragment(v)) {
+                    append(v.strings, v.values);
+                }
+                else {
+                    params.push(v);
+                    text += ph(params.length);
+                }
+            }
+        }
+    };
+    append(strings, values);
+    return { text, params };
+}
+// ---------------------------------------------------------------------------
+// createPrismaCompatClient
+// ---------------------------------------------------------------------------
+/**
+ * Create a PrismaClient-surface adapter over a {@link TurbineClient}, driven by a
+ * {@link PrismaCompatMap} (the `prisma-map.ts` that `turbine
+ * migrate-from-prisma` emits).
+ *
+ * The returned object exposes a delegate per Prisma model name (by the map's
+ * keys) plus the client-level `$transaction` / `$queryRaw` / `$executeRaw`
+ * surface. Model and field names are translated through the map in both
+ * directions; when field names are identity (the `--keep-column-names` pairing)
+ * result rekeying is skipped entirely.
+ *
+ * @typeParam S - Per-model type bundles (from your generated entity types) for
+ *   full autocompletion. Defaults to a permissive shape.
+ * @param client - The TurbineClient (or generated subclass / `turbineHttp` client).
+ * @param map - The resolved `PRISMA_MAP`.
+ * @param options - {@link PrismaCompatOptions}.
+ */
+export function createPrismaCompatClient(client, map, options = {}) {
+    // The adapter only ever needs the narrow {@link CompatTurbineClient} surface;
+    // the real client satisfies it structurally (the cast just relaxes the strict
+    // callback-param variance on `$transaction`).
+    const db = client;
+    const tableToModel = new Map();
+    for (const [prismaModel, mm] of Object.entries(map.models))
+        tableToModel.set(mm.table, prismaModel);
+    const ctx = {
+        map,
+        schema: db.schema,
+        tableToModel,
+        lookups: new Map(),
+        options: {
+            stablePkOrder: options.stablePkOrder ?? false,
+            prismaErrorCodes: options.prismaErrorCodes ?? false,
+        },
+    };
+    // Delegates bound to the base client (each call reads db.table(...) lazily).
+    const delegates = new Map();
+    for (const [prismaModel, mm] of Object.entries(map.models)) {
+        delegates.set(prismaModel, makeDelegate(ctx, mm, () => db.table(mm.table)));
+    }
+    const ph = placeholderOf(db);
+    const runRaw = async (text, params) => {
+        try {
+            return await poolOf(db).query(text, params);
+        }
+        catch (err) {
+            throw decorate(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 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;
+                        });
+                        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 Object.entries(map.models)) {
+                    txDelegates[prismaModel] = makeDelegate(ctx, mm, () => tx.table(mm.table));
+                    const alias = prismaPropertyAlias(prismaModel);
+                    if (alias && !(alias in map.models) && !(alias in txDelegates)) {
+                        txDelegates[alias] = txDelegates[prismaModel];
+                    }
+                }
+                return fn(txDelegates);
+            }, txOptions);
+        }),
+        $queryRaw: async (strings, ...values) => {
+            const { text, params } = flattenTemplate(strings, values, ph);
+            return (await runRaw(text, params)).rows;
+        },
+        $queryRawUnsafe: async (sql, ...params) => {
+            return (await runRaw(sql, params)).rows;
+        },
+        $executeRaw: async (strings, ...values) => {
+            const { text, params } = flattenTemplate(strings, values, ph);
+            return (await runRaw(text, params)).rowCount ?? 0;
+        },
+        $executeRawUnsafe: async (sql, ...params) => {
+            return (await runRaw(sql, params)).rowCount ?? 0;
+        },
+        $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;
+    }
+    return result;
+}