turbine-orm 0.14.0 → 0.15.0

package/dist/nested-write.js

@@ -0,0 +1,461 @@
+/**
+ * turbine-orm — Nested write engine
+ *
+ * Tree-walking create/update that resolves relation fields in `data` into
+ * batched SQL operations within a transaction. Supports create, connect,
+ * connectOrCreate, disconnect, set, and delete on related records at
+ * arbitrary depth (capped at 10).
+ *
+ * This module is imported by `query/builder.ts` when the `data` argument
+ * of `create()` or `update()` contains relation fields. It never imports
+ * `client.ts` directly — the transaction handle is passed in via
+ * `NestedWriteContext`.
+ */
+import { CircularRelationError, RelationError, ValidationError } from './errors.js';
+import { normalizeKeyColumns } from './schema.js';
+const MAX_DEPTH = 10;
+const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
+const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete']);
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for testing)
+// ---------------------------------------------------------------------------
+/**
+ * Separates scalar data fields from relation operation fields.
+ *
+ * A key is treated as a relation field only when:
+ * 1. It matches a relation name in `tableMeta.relations`
+ * 2. Its value is a non-null, non-array, non-Date plain object
+ *
+ * Everything else goes into `scalars`.
+ */
+export function extractRelationFields(data, tableMeta) {
+    const scalars = {};
+    const relations = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key in tableMeta.relations &&
+            value !== null &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            !(value instanceof Date)) {
+            relations[key] = value;
+        }
+        else {
+            scalars[key] = value;
+        }
+    }
+    return { scalars, relations };
+}
+/**
+ * Quick check: does `data` contain any relation fields that would trigger
+ * the nested write path? Used by QueryInterface to decide whether to
+ * delegate to the nested write engine or take the fast scalar-only path.
+ */
+export function hasRelationFields(data, tableMeta) {
+    for (const key of Object.keys(data)) {
+        if (key in tableMeta.relations) {
+            const val = data[key];
+            if (val !== null && typeof val === 'object' && !Array.isArray(val) && !(val instanceof Date)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Inject the parent row's PK value(s) as FK field(s) into child data.
+ * Handles composite keys. Returns a new object (does not mutate input).
+ */
+export function injectForeignKey(childData, relation, parentRow, schema) {
+    const fks = normalizeKeyColumns(relation.foreignKey);
+    const refs = normalizeKeyColumns(relation.referenceKey);
+    const childTable = schema.tables[relation.to];
+    const result = { ...childData };
+    for (let i = 0; i < fks.length; i++) {
+        const fkCol = fks[i];
+        const refCol = refs[i];
+        const refField = schema.tables[relation.from]?.reverseColumnMap[refCol] ?? refCol;
+        const fkField = childTable?.reverseColumnMap[fkCol] ?? fkCol;
+        result[fkField] = parentRow[refField];
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Validate that all operation keys in a nested write are recognized and
+ * allowed for the current context (create vs update).
+ */
+function validateOps(relationName, ops, isUpdate) {
+    for (const opName of Object.keys(ops)) {
+        if (!CREATE_ONLY_OPS.has(opName) && !UPDATE_ONLY_OPS.has(opName)) {
+            throw new ValidationError(`[turbine] Unknown nested write operation "${opName}" on relation "${relationName}". ` +
+                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete' : ''}.`);
+        }
+        if (!isUpdate && UPDATE_ONLY_OPS.has(opName)) {
+            throw new ValidationError(`[turbine] Operation "${opName}" on relation "${relationName}" is only valid inside update(), not create().`);
+        }
+    }
+}
+/**
+ * Build a PK-based where clause from a parent row and its table metadata.
+ */
+function pkWhere(tableMeta, row) {
+    const where = {};
+    for (const col of tableMeta.primaryKey) {
+        const field = tableMeta.reverseColumnMap[col] ?? col;
+        where[field] = row[field];
+    }
+    return where;
+}
+// ---------------------------------------------------------------------------
+// executeNestedCreate
+// ---------------------------------------------------------------------------
+/**
+ * Tree-walking create: inserts the parent row, then processes each relation
+ * operation (create, connect, connectOrCreate), and finally reads back the
+ * full tree using `findUnique` with an auto-built `with` clause.
+ */
+export async function executeNestedCreate(ctx, tableName, data, depth = 0, path = []) {
+    if (depth > MAX_DEPTH) {
+        throw new CircularRelationError(path);
+    }
+    const tableMeta = ctx.schema.tables[tableName];
+    if (!tableMeta) {
+        throw new ValidationError(`[turbine] Unknown table "${tableName}".`);
+    }
+    const { scalars, relations } = extractRelationFields(data, tableMeta);
+    // Validate all relation operations
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (!rel) {
+            throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${tableName}". ` +
+                `Available relations: ${Object.keys(tableMeta.relations).join(', ') || '(none)'}.`);
+        }
+        validateOps(relName, ops, false);
+    }
+    // Insert the parent row
+    const parentRow = (await ctx.tx.table(tableName).create({ data: scalars }));
+    // Process each relation
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (rel.type === 'hasMany' || rel.type === 'hasOne') {
+            await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
+        }
+        else if (rel.type === 'belongsTo') {
+            await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
+        }
+    }
+    // Build the `with` clause for the final read to return the full tree
+    const withClause = {};
+    for (const relName of Object.keys(relations)) {
+        withClause[relName] = true;
+    }
+    // Final read using existing json_agg machinery
+    const fullRow = await ctx.tx.table(tableName).findUnique({
+        where: pkWhere(tableMeta, parentRow),
+        with: Object.keys(withClause).length > 0 ? withClause : undefined,
+    });
+    return (fullRow ?? parentRow);
+}
+// ---------------------------------------------------------------------------
+// executeNestedUpdate
+// ---------------------------------------------------------------------------
+/**
+ * Tree-walking update: updates the parent row with scalar data, then
+ * processes each relation operation (create, connect, connectOrCreate,
+ * disconnect, set, delete), and reads back the full tree.
+ */
+export async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path = []) {
+    if (depth > MAX_DEPTH) {
+        throw new CircularRelationError(path);
+    }
+    const tableMeta = ctx.schema.tables[tableName];
+    if (!tableMeta) {
+        throw new ValidationError(`[turbine] Unknown table "${tableName}".`);
+    }
+    const { scalars, relations } = extractRelationFields(data, tableMeta);
+    // Validate all relation operations
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (!rel) {
+            throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${tableName}". ` +
+                `Available relations: ${Object.keys(tableMeta.relations).join(', ') || '(none)'}.`);
+        }
+        validateOps(relName, ops, true);
+    }
+    // Update parent row with scalar data (may be empty if only relation ops)
+    let parentRow;
+    if (Object.keys(scalars).length > 0) {
+        parentRow = (await ctx.tx.table(tableName).update({ where, data: scalars }));
+    }
+    else {
+        parentRow = (await ctx.tx.table(tableName).findUnique({ where }));
+        if (!parentRow) {
+            throw new ValidationError(`[turbine] update: no ${tableName} row found matching ${JSON.stringify(where)}.`);
+        }
+    }
+    // Process each relation
+    for (const [relName, ops] of Object.entries(relations)) {
+        const rel = tableMeta.relations[relName];
+        if (rel.type === 'hasMany' || rel.type === 'hasOne') {
+            // create, connect, connectOrCreate — same as nested create
+            await processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName);
+            // disconnect
+            if (ops.disconnect !== undefined) {
+                await processDisconnect(ctx, rel, ops.disconnect, relName);
+            }
+            // set
+            if (ops.set !== undefined) {
+                await processSet(ctx, rel, ops.set, parentRow);
+            }
+            // delete
+            if (ops.delete !== undefined) {
+                await processDelete(ctx, rel, ops.delete);
+            }
+        }
+        else if (rel.type === 'belongsTo') {
+            await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
+            if (ops.disconnect !== undefined) {
+                // For belongsTo disconnect, null out the FK on the parent
+                const fks = normalizeKeyColumns(rel.foreignKey);
+                const nullable = fks.every((fk) => {
+                    const col = tableMeta.columns.find((c) => c.name === fk);
+                    return col?.nullable ?? false;
+                });
+                if (!nullable) {
+                    throw new ValidationError(`[turbine] Cannot disconnect "${relName}": foreign key column(s) ${fks.join(', ')} are NOT NULL. Use delete instead.`);
+                }
+                const updateData = {};
+                for (const fk of fks) {
+                    const field = tableMeta.reverseColumnMap[fk] ?? fk;
+                    updateData[field] = null;
+                }
+                await ctx.tx.table(tableName).update({
+                    where: pkWhere(tableMeta, parentRow),
+                    data: updateData,
+                });
+            }
+        }
+    }
+    // Final read with all touched relations
+    const withClause = {};
+    for (const relName of Object.keys(relations)) {
+        withClause[relName] = true;
+    }
+    const fullRow = await ctx.tx.table(tableName).findUnique({
+        where: pkWhere(tableMeta, parentRow),
+        with: Object.keys(withClause).length > 0 ? withClause : undefined,
+    });
+    return (fullRow ?? parentRow);
+}
+// ---------------------------------------------------------------------------
+// hasMany/hasOne create operations
+// ---------------------------------------------------------------------------
+async function processHasManyCreate(ctx, rel, ops, parentRow, depth, path, relName) {
+    // create
+    if (ops.create !== undefined) {
+        const items = toArray(ops.create);
+        if (items.length > 0) {
+            // Check if any items have nested relations (need per-row recursion)
+            const childTable = ctx.schema.tables[rel.to];
+            const hasNested = childTable && items.some((item) => Object.keys(item).some((k) => k in (childTable.relations ?? {})));
+            if (hasNested) {
+                // Per-row recursive create for items with nested relations
+                for (const item of items) {
+                    const injected = injectForeignKey(item, rel, parentRow, ctx.schema);
+                    await executeNestedCreate(ctx, rel.to, injected, depth + 1, [...path, relName]);
+                }
+            }
+            else {
+                // Batch via createMany (UNNEST) — fast path
+                const injected = items.map((item) => injectForeignKey(item, rel, parentRow, ctx.schema));
+                await ctx.tx.table(rel.to).createMany({ data: injected });
+            }
+        }
+    }
+    // connect
+    if (ops.connect !== undefined) {
+        const items = toArray(ops.connect);
+        if (items.length > 0) {
+            await batchConnect(ctx, rel, items, parentRow);
+        }
+    }
+    // connectOrCreate
+    if (ops.connectOrCreate !== undefined) {
+        const items = toArray(ops.connectOrCreate);
+        for (const item of items) {
+            const op = item;
+            await connectOrCreate(ctx, rel, op, parentRow);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// belongsTo create operations
+// ---------------------------------------------------------------------------
+async function processBelongsToCreate(ctx, rel, ops, parentRow, parentTable, depth, path, relName) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    // create — insert the related row, then update parent's FK
+    if (ops.create !== undefined) {
+        const items = toArray(ops.create);
+        if (items.length > 0) {
+            const relatedRow = (await executeNestedCreate(ctx, rel.to, items[0], depth + 1, [...path, relName]));
+            const updateData = {};
+            const relatedTable = ctx.schema.tables[rel.to];
+            for (let i = 0; i < fks.length; i++) {
+                const fkField = ctx.schema.tables[parentTable]?.reverseColumnMap[fks[i]] ?? fks[i];
+                const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+                updateData[fkField] = relatedRow[refField];
+            }
+            const parentMeta = ctx.schema.tables[parentTable];
+            await ctx.tx.table(parentTable).update({
+                where: pkWhere(parentMeta, parentRow),
+                data: updateData,
+            });
+        }
+    }
+    // connect — validate existence, update parent's FK
+    if (ops.connect !== undefined) {
+        const items = toArray(ops.connect);
+        if (items.length > 0) {
+            const target = items[0];
+            const existing = await ctx.tx.table(rel.to).findUnique({ where: target });
+            if (!existing) {
+                throw new ValidationError(`[turbine] connect on "${relName}": no ${rel.to} row found matching ${JSON.stringify(target)}.`);
+            }
+            const updateData = {};
+            const relatedTable = ctx.schema.tables[rel.to];
+            for (let i = 0; i < fks.length; i++) {
+                const fkField = ctx.schema.tables[parentTable]?.reverseColumnMap[fks[i]] ?? fks[i];
+                const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+                updateData[fkField] = existing[refField];
+            }
+            const parentMeta = ctx.schema.tables[parentTable];
+            await ctx.tx.table(parentTable).update({
+                where: pkWhere(parentMeta, parentRow),
+                data: updateData,
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// connect, connectOrCreate, disconnect, set, delete helpers
+// ---------------------------------------------------------------------------
+async function batchConnect(ctx, rel, items, parentRow) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const childTable = ctx.schema.tables[rel.to];
+    if (!childTable)
+        return;
+    // Validate all targets exist
+    for (const target of items) {
+        const existing = await ctx.tx.table(rel.to).findUnique({ where: target });
+        if (!existing) {
+            throw new ValidationError(`[turbine] connect: no ${rel.to} row found matching ${JSON.stringify(target)}.`);
+        }
+    }
+    // Build FK update data to point children at parent
+    const updateData = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = ctx.schema.tables[rel.from]?.reverseColumnMap[refs[i]] ?? refs[i];
+        updateData[fkField] = parentRow[refField];
+    }
+    // Update each matching child
+    for (const target of items) {
+        await ctx.tx.table(rel.to).update({ where: target, data: updateData });
+    }
+}
+async function connectOrCreate(ctx, rel, op, parentRow) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const childTable = ctx.schema.tables[rel.to];
+    if (!childTable)
+        return;
+    // Try to find existing
+    let row = (await ctx.tx.table(rel.to).findUnique({ where: op.where }));
+    if (!row) {
+        // Create with FK injected
+        const injected = injectForeignKey(op.create, rel, parentRow, ctx.schema);
+        row = (await ctx.tx.table(rel.to).create({ data: injected }));
+    }
+    else {
+        // Update FK to point to parent
+        const updateData = {};
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = ctx.schema.tables[rel.from]?.reverseColumnMap[refs[i]] ?? refs[i];
+            updateData[fkField] = parentRow[refField];
+        }
+        await ctx.tx.table(rel.to).update({ where: op.where, data: updateData });
+    }
+}
+async function processDisconnect(ctx, rel, disconnectArg, relName) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const childTable = ctx.schema.tables[rel.to];
+    if (!childTable)
+        return;
+    // Check FK nullability
+    const nullable = fks.every((fk) => {
+        const col = childTable.columns.find((c) => c.name === fk);
+        return col?.nullable ?? false;
+    });
+    if (!nullable) {
+        throw new ValidationError(`[turbine] Cannot disconnect "${relName}": foreign key column(s) ${fks.join(', ')} on "${rel.to}" are NOT NULL. Use delete instead.`);
+    }
+    const items = toArray(disconnectArg);
+    const nullData = {};
+    for (const fk of fks) {
+        const field = childTable.reverseColumnMap[fk] ?? fk;
+        nullData[field] = null;
+    }
+    for (const target of items) {
+        await ctx.tx.table(rel.to).update({ where: target, data: nullData });
+    }
+}
+async function processSet(ctx, rel, setItems, parentRow) {
+    const fks = normalizeKeyColumns(rel.foreignKey);
+    const refs = normalizeKeyColumns(rel.referenceKey);
+    const childTable = ctx.schema.tables[rel.to];
+    if (!childTable)
+        return;
+    // Build parent FK match for finding current children
+    const parentWhere = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = ctx.schema.tables[rel.from]?.reverseColumnMap[refs[i]] ?? refs[i];
+        parentWhere[fkField] = parentRow[refField];
+    }
+    // Disconnect all current children
+    const nullData = {};
+    for (const fk of fks) {
+        const field = childTable.reverseColumnMap[fk] ?? fk;
+        nullData[field] = null;
+    }
+    await ctx.tx.table(rel.to).updateMany({
+        where: parentWhere,
+        data: nullData,
+        allowFullTableScan: true,
+    });
+    // Connect the specified items
+    const updateData = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = childTable.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = ctx.schema.tables[rel.from]?.reverseColumnMap[refs[i]] ?? refs[i];
+        updateData[fkField] = parentRow[refField];
+    }
+    for (const target of setItems) {
+        await ctx.tx.table(rel.to).update({ where: target, data: updateData });
+    }
+}
+async function processDelete(ctx, rel, deleteArg) {
+    const items = toArray(deleteArg);
+    for (const target of items) {
+        await ctx.tx.table(rel.to).delete({ where: target });
+    }
+}
+//# sourceMappingURL=nested-write.js.map

package/dist/query/builder.d.ts

@@ -13,7 +13,7 @@
 import type pg from 'pg';
 import type { Dialect } from '../dialect.js';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause, WithResult } from './types.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 export interface DeferredQuery<T> {
     /** SQL text with $1, $2 placeholders */
     sql: string;
@@ -67,6 +67,8 @@ export interface QueryInterfaceOptions {
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. */
     dialect?: Dialect;
+    /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
+    _txScoped?: boolean;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
@@ -98,6 +100,10 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly columnArrayTypeMap;
     /** Tracks tables that have already triggered a deep-with warning (one-time) */
     private readonly deepWithWarned;
+    /** True when this QI runs inside an active transaction (set via _txScoped option). */
+    private readonly txScoped;
+    /** Original options reference — forwarded to child QIs in nested writes. */
+    private readonly options?;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /** Quote an identifier through the active SQL dialect. */
     private q;
@@ -143,9 +149,9 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * To intercept queries before SQL generation, use the raw() method instead.
      */
     private executeWithMiddleware;
-    findUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
-    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T | null>;
-    findMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>[]>;
+    findUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
     /**
      * Emit a one-time `console.warn` when {@link findMany} is called without an
      * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
@@ -162,7 +168,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Used by the dev-only deep-with warning guard.
      */
     private measureWithDepth;
-    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
+    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T[]>;
     /**
      * Stream rows from a findMany query using PostgreSQL cursors.
      * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
@@ -190,19 +196,24 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * }
      * ```
      */
-    findManyStream<W extends TypedWithClause<R> = {}>(args?: FindManyStreamArgs<T, R, W>): AsyncGenerator<WithResult<T, R, W>, void, undefined>;
-    findFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
-    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T | null>;
-    findFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>>;
-    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T>;
-    findUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W>>;
-    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T>;
+    findManyStream<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyStreamArgs<T, R, W, S, O>): AsyncGenerator<QueryResult<T, R, W, S, O>, void, undefined>;
+    findFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
+    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    findFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
+    findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
     create(args: CreateArgs<T>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
     update(args: UpdateArgs<T>): Promise<T>;
     buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
+    private nestedCreate;
+    private nestedUpdate;
+    private runInImplicitTx;
+    private buildNestedCtx;
+    private makeTxProxy;
     delete(args: DeleteArgs<T>): Promise<T>;
     buildDelete(args: DeleteArgs<T>): DeferredQuery<T>;
     upsert(args: UpsertArgs<T>): Promise<T>;
@@ -502,6 +513,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Supports: has, hasEvery, hasSome, isEmpty.
      */
     private buildArrayFilterClauses;
+    /**
+     * Build SQL clause for full-text search using to_tsvector @@ to_tsquery.
+     * The config name is validated to prevent injection (only alphanumeric + underscore).
+     */
+    private buildTextSearchClause;
     /**
      * Get the Postgres array type for a column (used by UNNEST in createMany).
      * Uses pre-computed Map for O(1) lookup instead of linear scan.