turbine-orm 0.40.1 → 0.41.0

package/dist/prisma-compat.d.ts

@@ -0,0 +1,281 @@
+/**
+ * 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 type { TurbineClient } from './client.js';
+import type { DeferredQuery } from './query/index.js';
+import type { PrismaCompatMap, SchemaMetadata } from './schema.js';
+/** A build-only query object with the `build*` methods the adapter drives. */
+export interface CompatQueryInterface {
+    findMany(args?: Record<string, unknown>): Promise<unknown>;
+    findFirst(args?: Record<string, unknown>): Promise<unknown>;
+    findUnique(args: Record<string, unknown>): Promise<unknown>;
+    findFirstOrThrow(args?: Record<string, unknown>): Promise<unknown>;
+    findUniqueOrThrow(args: Record<string, unknown>): Promise<unknown>;
+    create(args: Record<string, unknown>): Promise<unknown>;
+    createMany(args: Record<string, unknown>): Promise<unknown[]>;
+    update(args: Record<string, unknown>): Promise<unknown>;
+    updateMany(args: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    delete(args: Record<string, unknown>): Promise<unknown>;
+    deleteMany(args: Record<string, unknown>): Promise<{
+        count: number;
+    }>;
+    upsert(args: Record<string, unknown>): Promise<unknown>;
+    count(args?: Record<string, unknown>): Promise<number>;
+    aggregate(args: Record<string, unknown>): Promise<unknown>;
+    groupBy(args: Record<string, unknown>): Promise<unknown[]>;
+    buildFindMany(args?: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindFirst(args?: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindUnique(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindFirstOrThrow(args?: Record<string, unknown>): DeferredQuery<unknown>;
+    buildFindUniqueOrThrow(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildCreate(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildCreateMany(args: Record<string, unknown>): DeferredQuery<unknown[]>;
+    buildUpdate(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildUpdateMany(args: Record<string, unknown>): DeferredQuery<{
+        count: number;
+    }>;
+    buildDelete(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildDeleteMany(args: Record<string, unknown>): DeferredQuery<{
+        count: number;
+    }>;
+    buildUpsert(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildCount(args?: Record<string, unknown>): DeferredQuery<number>;
+    buildAggregate(args: Record<string, unknown>): DeferredQuery<unknown>;
+    buildGroupBy(args: Record<string, unknown>): DeferredQuery<unknown[]>;
+}
+/** A transaction-scoped client handed to a `$transaction(callback)`. */
+export interface CompatTransactionClient {
+    table(name: string): CompatQueryInterface;
+}
+/** The minimal `TurbineClient` surface the adapter consumes. */
+export interface CompatTurbineClient extends CompatTransactionClient {
+    readonly schema: SchemaMetadata;
+    $transaction<R>(fn: (tx: CompatTransactionClient) => Promise<R>, options?: unknown): Promise<R>;
+    $transaction(queries: readonly DeferredQuery<unknown>[]): Promise<unknown[]>;
+}
+declare const SQL_FRAGMENT: unique symbol;
+/** A composable SQL fragment, the local stand-in for `Prisma.Sql`. */
+export interface Sql {
+    /** Literal string segments; `strings.length === values.length + 1`. */
+    readonly strings: readonly string[];
+    /** Interpolated values, one between each pair of `strings`. */
+    readonly values: readonly unknown[];
+    readonly [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 declare const Prisma: {
+    /** Tagged-template fragment: `Prisma.sql\`id = ${id}\``. */
+    sql(strings: TemplateStringsArray, ...values: unknown[]): Sql;
+    /**
+     * 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: readonly unknown[], separator?: string, prefix?: string, suffix?: string): Sql;
+    /**
+     * A raw, unparameterized SQL fragment. The string is spliced verbatim, never
+     * pass user input here (matches Prisma's `Prisma.raw` contract).
+     */
+    raw(sql: string): Sql;
+    /** An empty fragment. */
+    empty: Sql;
+};
+/** Options for {@link createPrismaCompatClient}. */
+export interface PrismaCompatOptions {
+    /**
+     * When `true`, every to-many `with` relation lacking an explicit `orderBy` is
+     * loaded ordered by the target table's primary key ascending (Prisma's
+     * relation rows come back in a stable order). This passes through to Turbine's
+     * core `stableRelationOrder` flag, it never re-walks the `with` tree. An
+     * explicit per-relation `orderBy` always wins. Default `false`.
+     */
+    stablePkOrder?: boolean;
+    /**
+     * When `true`, thrown {@link TurbineError}s are decorated with a `.code` equal
+     * to the nearest Prisma error code (e.g. `P2002` for a unique violation),
+     * WITHOUT pretending `instanceof PrismaClientKnownRequestError`. Default
+     * `false` (Turbine's own `TURBINE_E0NN` codes are preserved untouched).
+     */
+    prismaErrorCodes?: boolean;
+}
+/** Symbol under which a lazy delegate call exposes its batchable plan. */
+export declare const COMPAT_DEFERRED: unique symbol;
+/**
+ * The per-model type bundle a consumer supplies to type a model delegate.
+ * Populate `Row` (and optionally the arg shapes) from the generated entity
+ * types; unspecified members fall back to permissive shapes.
+ */
+export interface PrismaModelTypes {
+    Row: object;
+    Create?: object;
+    Update?: object;
+    Where?: object;
+    OrderBy?: object;
+    Select?: object;
+    Include?: object;
+}
+type Args = Record<string, unknown>;
+/** A typed model delegate mirroring Prisma's `db.model.*` surface. */
+export interface PrismaModelDelegate<M extends PrismaModelTypes> {
+    findMany(args?: Args): Promise<M['Row'][]>;
+    findFirst(args?: Args): Promise<M['Row'] | null>;
+    findUnique(args: Args): Promise<M['Row'] | null>;
+    findFirstOrThrow(args?: Args): Promise<M['Row']>;
+    findUniqueOrThrow(args: Args): Promise<M['Row']>;
+    create(args: Args): Promise<M['Row']>;
+    createMany(args: Args): Promise<{
+        count: number;
+    }>;
+    update(args: Args): Promise<M['Row']>;
+    updateMany(args: Args): Promise<{
+        count: number;
+    }>;
+    delete(args: Args): Promise<M['Row']>;
+    deleteMany(args?: Args): Promise<{
+        count: number;
+    }>;
+    upsert(args: Args): Promise<M['Row']>;
+    count(args?: Args): Promise<number>;
+    aggregate(args: Args): Promise<Record<string, unknown>>;
+    groupBy(args: Args): Promise<Record<string, unknown>[]>;
+}
+/** The client-level surface (`$transaction` / raw), added to the model map. */
+export interface PrismaCompatClientBase<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> {
+    $transaction<R>(fn: (tx: PrismaCompatTransactionClient<S>) => Promise<R>, options?: PrismaCompatTxOptions): Promise<R>;
+    $transaction<P extends readonly PromiseLike<unknown>[]>(promises: readonly [...P]): Promise<{
+        [K in keyof P]: Awaited<P[K]>;
+    }>;
+    $queryRaw<T = unknown>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    $queryRawUnsafe<T = unknown>(sql: string, ...params: unknown[]): Promise<T[]>;
+    $executeRaw(strings: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+    $executeRawUnsafe(sql: string, ...params: unknown[]): Promise<number>;
+    $connect(): Promise<void>;
+    $disconnect(): Promise<void>;
+}
+/** Options accepted by the callback form of `$transaction`. */
+export interface PrismaCompatTxOptions {
+    isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable';
+    timeout?: number;
+    maxWait?: number;
+}
+/** The transaction-scoped client handed to a `$transaction(callback)`. */
+export type PrismaCompatTransactionClient<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> = {
+    [K in keyof S]: PrismaModelDelegate<S[K]>;
+};
+/**
+ * The full typed compat client: a model delegate per Prisma model name, plus the
+ * client-level `$transaction` / raw surface. Parameterize `S` with your
+ * generated entity types for full autocompletion.
+ */
+export type PrismaCompatClient<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>> = {
+    [K in keyof S]: PrismaModelDelegate<S[K]>;
+} & {
+    [K in keyof S as Uncapitalize<K & string>]: PrismaModelDelegate<S[K]>;
+} & PrismaCompatClientBase<S>;
+/**
+ * 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 declare function createPrismaCompatClient<S extends Record<string, PrismaModelTypes> = Record<string, PrismaModelTypes>>(client: TurbineClient, map: PrismaCompatMap, options?: PrismaCompatOptions): PrismaCompatClient<S>;
+export {};