@vantreeseba/drizzle-graphql 7.9.1 → 8.0.0

package/dist/index.d.cts

@@ -1,11 +1,214 @@
-import { Column, Table, Relation, SQL, One, Many } from 'drizzle-orm';
+import { Column, Table, Relation, SQL, TablesRelationalConfig, One, Many } from 'drizzle-orm';
 import { MySqlDatabase } from 'drizzle-orm/mysql-core';
 import { PgAsyncDatabase } from 'drizzle-orm/pg-core';
 import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
-import { GraphQLScalarType, GraphQLOutputType, GraphQLInputType, GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLEnumType } from 'graphql';
+import { GraphQLError, GraphQLScalarType, GraphQLOutputType, GraphQLInputType, GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLEnumType } from 'graphql';
 import { ResolveTree } from 'graphql-parse-resolve-info';
 export { GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'graphql-scalars';
 
+/**
+ * The identity a generated field publishes about itself, under `extensions.drizzle`.
+ *
+ * Every field this library generates carries one, so a wrapper — `graphql-middleware`,
+ * envelop, `graphql-shield`, an audit log, a cache invalidator — can ask the schema what a
+ * field is instead of reverse-engineering its name. Names are configurable (`prefixes`,
+ * `suffixes`, `typeNameMapper`), so name parsing is ambiguous by construction; this is not.
+ *
+ * This shape is stable API: fields are only ever added to it, never removed or repurposed.
+ */
+/** What family of field this is. */
+type DrizzleFieldKind = 'query' | 'mutation' | 'relation' | 'aggregate' | 'type';
+/**
+ * What the field does. Arity is carried separately by `single`, so `select` covers both
+ * the list query and its `…Single` sibling rather than being spelled twice.
+ */
+type DrizzleFieldOperation = 'select' | 'insert' | 'update' | 'updateMany' | 'upsert' | 'delete' | 'restore' | 'aggregate' | 'groupBy' | 'relation' | 'relationAggregate';
+/** The argument holding the rows a field is about, when it has one. */
+type DrizzleTargetArg = 'where' | 'values' | 'updates';
+/** `extensions.drizzle` on a generated field. */
+type DrizzleFieldExtension = {
+    /** The Drizzle schema key of the table the field reads or writes. */
+    table: string;
+    kind: Exclude<DrizzleFieldKind, 'type'>;
+    operation: DrizzleFieldOperation;
+    /** Whether the field resolves to one row (or one aggregate) rather than a list. */
+    single: boolean;
+    /**
+     * Which argument names the rows: `where` for select/update/delete/aggregate, `values`
+     * for insert and upsert, `updates` for the batch update's per-entry `{ where, set }`.
+     * Absent when the field takes no such argument.
+     */
+    targetArg?: DrizzleTargetArg;
+    /**
+     * Primary-key property names of `table`, in schema order. Empty when the table declares
+     * no primary key. Carried here so {@link identifyRows} works from the field alone.
+     */
+    primaryKey: readonly string[];
+    /**
+     * For `operation: 'delete'` on a soft-deleting table that opted into `hardDelete`: the
+     * field takes a `hard` argument that issues a real `DELETE` rather than writing the marker.
+     * Absent everywhere else, so a wrapper can gate purging without parsing arguments.
+     */
+    hardDelete?: boolean;
+    /** For `kind: 'relation'` and `operation: 'relationAggregate'`: the relation's name. */
+    relation?: string;
+    /** For `kind: 'relation'` and `operation: 'relationAggregate'`: the table it hangs off. */
+    parentTable?: string;
+};
+/** `extensions.drizzle` on a generated object type. */
+type DrizzleTypeExtension = {
+    /** The Drizzle schema key this type was generated from. */
+    table: string;
+    kind: 'type';
+    /** Primary-key property names of `table`, in schema order. Empty when there is none. */
+    primaryKey: readonly string[];
+};
+type DrizzleExtension = DrizzleFieldExtension | DrizzleTypeExtension;
+/** Anything carrying GraphQL `extensions` — a field config, a field, or a named type. */
+type WithExtensions = {
+    extensions?: {
+        drizzle?: unknown;
+    } | null;
+} | null | undefined;
+/**
+ * Reads the `drizzle` extension off a field or type, typed. Returns `undefined` for
+ * anything this library did not generate, which is the check a wrapper wants before it
+ * treats a field as one of ours.
+ */
+declare const drizzleExtension: (target: WithExtensions) => DrizzleExtension | undefined;
+/** Narrows to the field form — object types carry `kind: 'type'` and no operation. */
+declare const isDrizzleFieldExtension: (value: DrizzleExtension | undefined) => value is DrizzleFieldExtension;
+/** The rows a field's arguments name. */
+type IdentifiedRows = {
+    /** The Drizzle schema key of the table being read or written. */
+    table: string;
+    /** Primary-key property names, in schema order. */
+    primaryKey: readonly string[];
+    /** One entry per identified row: the primary-key values, keyed by property name. */
+    rows: Record<string, unknown>[];
+    /**
+     * Whether `rows` is exactly the set the operation affects.
+     *
+     * `false` means the arguments do not pin the rows down — an insert whose key the
+     * database generates, a `where` that filters on something other than the primary key,
+     * a plural update with no filter at all, or a table with no primary key. `rows` is then
+     * a best-effort subset-free superset: every entry in it is a row the key values name,
+     * but other filters may narrow the real set further, and it may be empty.
+     */
+    complete: boolean;
+};
+/**
+ * The rows a generated field's arguments are about, as primary-key values.
+ *
+ * The row identity of a mutation lives in a different argument for every operation —
+ * `where` for update and delete, `values` for insert and upsert, a per-entry `where` inside
+ * `updates` for the batch update — and each of those has both a one-row and a many-row
+ * spelling. This reads whichever one applies:
+ *
+ * ```ts
+ * const field = info.parentType.getFields()[info.fieldName];
+ * const target = identifyRows(field, args);
+ * if (target?.complete) await invalidate(target.table, target.rows);
+ * ```
+ *
+ * Returns `undefined` for a field this library did not generate, or an object type. Check
+ * `complete` before treating `rows` as the affected set — see {@link IdentifiedRows}.
+ */
+declare const identifyRows: (field: WithExtensions, args: Record<string, unknown> | undefined) => IdentifiedRows | undefined;
+
+/**
+ * The classification of an error drizzle-graphql raised itself, published as
+ * `extensions.code`. A consumer maps these onto its own vocabulary; the prose is written for
+ * a client to read and may be reworded in any release, so it is not something to match on.
+ */
+type DrizzleErrorCode = 
+/** A `Single` write's `where` matched more than one row, so nothing was written. */
+'DRIZZLE_MULTI_ROW_MATCH'
+/** A write that refuses to run unbounded was given no `where`, or one matching every row. */
+ | 'DRIZZLE_WHERE_REQUIRED'
+/** The requested `limit` is above the maximum the field's limit policy allows. */
+ | 'DRIZZLE_LIMIT_EXCEEDED'
+/** A write's `values` / `set` carried nothing to write. */
+ | 'DRIZZLE_NO_VALUES'
+/** An insert reported no row back, so there is nothing to return or attach. */
+ | 'DRIZZLE_NO_ROW_RETURNED'
+/** The driver reported no row count for a returnless write. */
+ | 'DRIZZLE_ROW_COUNT_UNAVAILABLE'
+/** A nested write was passed to a field that cannot run one. */
+ | 'DRIZZLE_NESTED_WRITES_UNSUPPORTED'
+/** A nested `create` / `connect` / `disconnect` / `set` operand was not usable. */
+ | 'DRIZZLE_NESTED_WRITE_INVALID'
+/** A `groupBy` named no column, or one that cannot be grouped by. */
+ | 'DRIZZLE_INVALID_GROUP_BY'
+/** An `after` cursor did not decode, or was issued for a different ordering. */
+ | 'DRIZZLE_INVALID_CURSOR'
+/** A `where` key was not a filter of the table, or a relation was used as one. */
+ | 'DRIZZLE_INVALID_FILTER'
+/** A column's update operations input held none, or more than one. */
+ | 'DRIZZLE_INVALID_UPDATE_OPERATION'
+/** A configured `scope` hook returned something that is not a predicate. */
+ | 'DRIZZLE_INVALID_SCOPE'
+/** An `orderBy` named something that cannot be ordered by in this query. */
+ | 'DRIZZLE_INVALID_ORDER_BY'
+/** `distinct` was asked for where it cannot be applied. */
+ | 'DRIZZLE_INVALID_DISTINCT'
+/** An `onConflict` named a target or update column the upsert cannot use. */
+ | 'DRIZZLE_INVALID_ON_CONFLICT'
+/** The request's shared mutation transaction was rolled back, so this field never ran. */
+ | 'DRIZZLE_TRANSACTION_ABORTED';
+/**
+ * What an error was about, published as `extensions.drizzle` beside the code — the runtime
+ * half of the `extensions.drizzle` markers a generated field carries.
+ *
+ * `field` is the **generated** field name, which is why it is data rather than prose: a build
+ * that republishes these fields under other names (`RenameRootFields`, a stitched gateway, a
+ * hand-written façade) would otherwise be telling a client about a field it has never heard
+ * of. The name the client asked for is already in the error's `path`.
+ */
+type DrizzleErrorContext = {
+    /** The Drizzle schema key of the table the field reads or writes. */
+    table?: string;
+    operation?: DrizzleFieldOperation;
+    /** The generated field's own name, pre-rename. */
+    field?: string;
+    /** For a relation field: the relation's name. */
+    relation?: string;
+};
+/**
+ * A `GraphQLError` carrying its context as data. The message says what went wrong, in prose
+ * meant for a client; `extensions.code` classifies it and `extensions.drizzle` says which
+ * table, operation and generated field it came from.
+ */
+declare const drizzleError: (message: string, { code, ...context }: DrizzleErrorContext & {
+    code: DrizzleErrorCode;
+}) => GraphQLError;
+/**
+ * Default for `config.onError`: keeps drizzle-graphql's own errors, which are written for
+ * the client, and replaces driver/database errors with a generic message. Their text names
+ * tables, columns, constraints and offending values, none of which belongs in a response.
+ * The original is preserved on `originalError` for server-side logging.
+ */
+declare const defaultErrorMapper: (error: unknown) => unknown;
+
+/** {@link BuildSchemaConfig.limits} resolved for one table. `undefined` means no policy. */
+type ResolvedLimitPolicy = {
+    defaultLimit: number | undefined;
+    maxLimit: number | undefined;
+    clampToMax: boolean;
+};
+/**
+ * Looks up the limit policy for a table by its Drizzle schema key. Built once per schema by
+ * `buildSchema`; `undefined` for a table the caller left unbounded.
+ */
+type LimitPolicyFor = (tableName: string) => ResolvedLimitPolicy | undefined;
+/**
+ * {@link BuildSchemaConfig.defaults} resolved for one table: the `orderBy` a read falls back
+ * to when the request passes none, already in the shape the generated argument has.
+ * `undefined` means the table declares no default and keeps whatever order the database
+ * returns.
+ */
+type DefaultOrderByFor = (tableName: string) => Record<string, any> | undefined;
+
 /**
  * A scalar override for one column. A bare scalar applies to both directions; the object form
  * lets output (object type, aggregate min/max) and input (create/update inputs, filter operands)
@@ -171,6 +374,12 @@ type FilterColumnOperatorsCore<TColumn extends Column, TColType = GetColumnGqlDa
     isEmpty: boolean;
     isNull: boolean;
     isNotNull: boolean;
+    /**
+     * String columns: compares every operator in this object case-insensitively
+     * (`lower(column)` against `lower(operand)`). Applies to the operators beside it only —
+     * a nested `AND`/`OR`/`NOT` branch sets its own.
+     */
+    insensitive: boolean;
 }>;
 type FiltersCore<TTable extends Table> = Partial<{
     [Column in keyof TTable['_']['columns']]: FilterColumnOperatorsCore<TTable['_']['columns'][Column]>;
@@ -198,133 +407,55 @@ type OrderByArgs<TTable extends Table> = {
     };
 };
 
-/** Optional mapper from table key to singular/plural name pair. Return undefined to use default naming for a table. */
-type TypeNameMapper = (tableName: string) => {
-    singular: string;
-    plural: string;
-} | undefined;
 /**
- * Extracts the join column info from a drizzle-orm v1 Relation object.
- * Returns the JS property name of the local column on the parent table and the
- * Column object for the foreign column on the target table, or undefined if the
- * relation internals are not accessible.
- */
-declare const extractRelationJoinColumns: (relEntry: TableNamedRelations, parentTable: Table, targetTable: Table) => {
-    localColPropName: string;
-    foreignCol: Column;
-    foreignColPropName: string;
-} | undefined;
-type RelationResolverFactory = (params: {
-    tableName: string;
-    relationName: string;
-    relEntry: TableNamedRelations;
-    isOne: boolean;
-}) => GraphQLFieldResolver<any, any> | undefined;
-/**
- * Key on the GraphQL context object under which a caller can place a Drizzle transaction
- * (or any other executor: a pooled connection, a logging proxy). Every generated resolver
- * reads it at resolve time and runs its statements there instead of on the database the
- * schema was built from, which is what lets several mutations in one request share a
- * transaction and lets a query see that transaction's uncommitted rows:
- *
- * ```ts
- * await db.transaction(async (tx) => {
- *   await graphql({ schema, source, contextValue: { [drizzleExecutorKey]: tx } });
- * });
- * ```
+ * What a generated type is, so a name mapper can answer for one kind without matching on the
+ * spelling of the default name.
  *
- * Registered with `Symbol.for` so the ESM and CJS builds of this package agree on it when
- * both end up loaded in one process.
+ * - `object` — a table's row type, the one `typeNameMapper` already names
+ * - `filter` / `listRelationFilter` — `<Type>Filters` and the `some`/`none`/`every` wrapper
+ * - `orderBy` — `<Type>OrderBy`
+ * - `createInput` / `updateInput` / `updateManyInput` / `nestedWriteInput` / `fieldUpdateInput`
+ *   — the write inputs
+ * - `aggregate` — `<Type>Aggregate` and its per-operation children (`operation` names which)
+ * - `having` / `groupBy` / `groupKeys` — the group-by family
+ * - `onConflict` — the upsert's conflict input
+ * - `uniqueKey` — a compound unique constraint's key input
+ * - `columnEnum` — an enum naming a table's columns (`distinct`, conflict target, …)
+ * - `columnFilter` — a shared per-scalar filter (`StringFilter`, `IntFilter`, …), not per table
+ * - `shared` — everything else the build creates once (`OrderNulls`, `DeletedFilter`, …)
  */
-declare const drizzleExecutorKey: unique symbol;
-/** The write a hook is attached to. `restore` only exists for a soft-deleting table. */
-type WriteOperation = 'insert' | 'update' | 'updateMany' | 'upsert' | 'delete' | 'restore';
-/** What a write hook is handed. See {@link BuildSchemaConfig.onWrite}. */
-type WriteHookPayload = {
-    /** Drizzle schema key of the table being written. */
-    table: string;
-    operation: WriteOperation;
-    /** `'before'` runs ahead of the statement, `'after'` once it has returned. */
-    position: 'before' | 'after';
-    /** Whether the field writes a single row (`createUsersSingle`) or a list. */
-    single: boolean;
-    /** The field's GraphQL arguments, exactly as the resolver received them. */
-    args: any;
+type GeneratedTypeKind = 'object' | 'filter' | 'listRelationFilter' | 'orderBy' | 'createInput' | 'updateInput' | 'updateManyInput' | 'nestedWriteInput' | 'fieldUpdateInput' | 'aggregate' | 'having' | 'groupBy' | 'groupKeys' | 'onConflict' | 'uniqueKey' | 'columnEnum' | 'columnFilter' | 'shared';
+/** What a name mapper is told about the type it is being asked to name. */
+interface GeneratedTypeInfo {
+    /** Which kind of generated type this is. */
+    kind: GeneratedTypeKind;
+    /** The name the library would use, before any prefix or suffix. */
+    defaultName: string;
+    /** The table key the type belongs to, where it belongs to one. */
+    table?: string;
     /**
-     * The rows the write produced, as the database returned them — before the output mapper,
-     * so values are database-shaped. Empty at the `before` position, and on MySQL, whose
-     * mutations return no rows.
+     * The narrower thing the type is for, where the kind alone does not say: the aggregate
+     * operation (`sum`, `avg`, …), the relation a nested-write input is for, the scalar a
+     * column filter covers, the columns of a unique key.
      */
-    rows: any[];
-    context: any;
-    info: any;
-    /** The executor the mutation itself ran on. Throwing from the hook rolls it back. */
-    tx: any;
-};
-type WriteHook = (payload: WriteHookPayload) => void | Promise<void>;
-type WriteHookPositions = {
-    before?: WriteHook;
-    after?: WriteHook;
-};
-type WriteHooks = WriteHook | WriteHookPositions;
-/** Resolved, per-field hooks: `undefined` when the table registered none. */
-type ResolvedWriteHooks = {
-    before?: WriteHook;
-    after?: WriteHook;
-};
-/** Build-time lookup of a table's hooks, installed on {@link TablePolicies}. */
-type WriteHookFor = (tableName: string, operation: WriteOperation) => ResolvedWriteHooks | undefined;
-/**
- * Creates a RelationResolverFactory that generates field-level resolvers for each relation.
- * Each resolver:
- *   1. Returns pre-fetched data if the parent resolver already included it (eager path, zero cost).
- *   2. When limit/offset args are present, falls back to a direct per-item query.
- *   3. Otherwise batches all sibling resolver calls within the same GraphQL execution tick
- *      into a single IN-clause query, eliminating N+1 database round-trips.
- *
- * `nullOrdering` is the dialect's native `ORDER BY` placement for `NULL` — the keyset
- * predicate behind a relation's `after` argument has to match it, or rows with a `NULL` in an
- * ordered column would be skipped instead of paged through. It has no sensible default, so
- * each dialect builder states it: `'nulls-largest'` for PostgreSQL, `'nulls-smallest'` for
- * MySQL and SQLite.
- */
-declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, nullOrdering: NullOrdering, filterCtx?: RelationFilterBase, limits?: LimitPolicyFor, policies?: TablePolicies) => RelationResolverFactory;
-/** {@link BuildSchemaConfig.limits} resolved for one table. `undefined` means no policy. */
-type ResolvedLimitPolicy = {
-    defaultLimit: number | undefined;
-    maxLimit: number | undefined;
-    clampToMax: boolean;
-};
-/**
- * Looks up the limit policy for a table by its Drizzle schema key. Built once per schema by
- * `buildSchema`; `undefined` for a table the caller left unbounded.
- */
-type LimitPolicyFor = (tableName: string) => ResolvedLimitPolicy | undefined;
+    operation?: string;
+}
 /**
- * {@link BuildSchemaConfig.defaults} resolved for one table: the `orderBy` a read falls back
- * to when the request passes none, already in the shape the generated argument has.
- * `undefined` means the table declares no default and keeps whatever order the database
- * returns.
+ * Renames a generated type. Return `undefined` — or the same name — to keep the default,
+ * which is what an unlisted kind should do; anything returned is used verbatim, without the
+ * build's prefix or suffix.
  */
-type DefaultOrderByFor = (tableName: string) => Record<string, any> | undefined;
-/**
- * Compiles an `orderBy` argument into ORDER BY expressions, highest priority first.
- *
- * A key naming one of the table's columns orders by that column. A key naming a to-one
- * relation takes the target table's own OrderBy input and orders by the related row's
- * column(s), compiled as a correlated scalar subquery — reusing the aliased-join machinery
- * the relation filters are built on — so it works identically on all three dialects and
- * inside the relational query builder's aliased CTEs. Priorities share one global space
- * across relation boundaries. Each entry may also carry `nulls: first | last`
- * (see {@link orderExpressions} for how MySQL emulates it).
- *
- * An entry may instead set `matchFilterOrder`, which sorts by the column's position in the
- * `inArray` list the same request's `where` gives it — `whereArgs` is that `where`.
- *
- * `ctx` supplies the tables and relation map that relation ordering needs; callers whose
- * inputs cannot contain relation keys may omit it.
- */
-declare const extractOrderBy: <TTable extends Table, TArgs extends OrderByArgs<any> = OrderByArgs<TTable>>(table: TTable, orderArgs: TArgs, ctx?: RelationFilterContext, whereArgs?: Record<string, any>) => SQL[];
+type DerivedTypeNameMapper = (info: GeneratedTypeInfo) => string | undefined;
+
+/** Optional mapper from table key to singular/plural name pair. Return undefined to use default naming for a table. */
+type TypeNameMapper = (tableName: string) => {
+    singular: string;
+    plural: string;
+} | undefined;
+
+/** A table's unique-key `where` fields: field name → the constraint's member property names. */
+type UniqueKeyMap = Record<string, readonly string[]>;
+
 /**
  * Everything `extractFilters` needs to turn a relation key in a `where` argument into a
  * correlated subquery. Omitted by callers that don't generate relation filters, in which case
@@ -344,13 +475,58 @@ interface RelationFilterContext {
     aliases?: {
         n: number;
     };
+    /**
+     * The compound-unique-key `where` fields of each table, keyed by table schema key. Only
+     * populated when `features.uniqueKeyFilters` generated them — a key field the build did not
+     * generate is an unknown filter key like any other.
+     */
+    uniqueKeys?: Record<string, UniqueKeyMap>;
 }
 /**
  * The build-scoped half of {@link RelationFilterContext}. Created once per generated schema and
  * handed to every resolver, which adds the table it is filtering.
  */
-type RelationFilterBase = Pick<RelationFilterContext, 'tables' | 'relationMap'>;
+type RelationFilterBase = Pick<RelationFilterContext, 'tables' | 'relationMap' | 'uniqueKeys'>;
 declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>, relationCtx?: RelationFilterContext) => SQL | undefined;
+
+/** The write a hook is attached to. `restore` only exists for a soft-deleting table. */
+type WriteOperation = 'insert' | 'update' | 'updateMany' | 'upsert' | 'delete' | 'restore';
+/** What a write hook is handed. See {@link BuildSchemaConfig.onWrite}. */
+type WriteHookPayload = {
+    /** Drizzle schema key of the table being written. */
+    table: string;
+    operation: WriteOperation;
+    /** `'before'` runs ahead of the statement, `'after'` once it has returned. */
+    position: 'before' | 'after';
+    /** Whether the field writes a single row (`createUsersSingle`) or a list. */
+    single: boolean;
+    /** The field's GraphQL arguments, exactly as the resolver received them. */
+    args: any;
+    /**
+     * The rows the write produced, as the database returned them — before the output mapper,
+     * so values are database-shaped. Empty at the `before` position, and on MySQL, whose
+     * mutations return no rows.
+     */
+    rows: any[];
+    context: any;
+    info: any;
+    /** The executor the mutation itself ran on. Throwing from the hook rolls it back. */
+    tx: any;
+};
+type WriteHook = (payload: WriteHookPayload) => void | Promise<void>;
+type WriteHookPositions = {
+    before?: WriteHook;
+    after?: WriteHook;
+};
+type WriteHooks = WriteHook | WriteHookPositions;
+/** Resolved, per-field hooks: `undefined` when the table registered none. */
+type ResolvedWriteHooks = {
+    before?: WriteHook;
+    after?: WriteHook;
+};
+/** Build-time lookup of a table's hooks, installed on {@link TablePolicies}. */
+type WriteHookFor = (tableName: string, operation: WriteOperation) => ResolvedWriteHooks | undefined;
+
 /**
  * A table's row-level scope: the predicate every generated read, update and delete on that
  * table is narrowed by. See `BuildSchemaConfig.scope`.
@@ -368,10 +544,11 @@ type ScopeFor = (tableName: string) => ScopeHook | undefined;
 /**
  * One table's soft-delete convention, resolved against the real column at build time.
  *
- * `nullable` picks the shape of the predicate. A nullable column marks a row deleted by
- * holding a value at all (`deletedAt IS NOT NULL`), which is the common timestamp form; a
- * non-nullable one marks it by holding `marker` (`isDeleted = true`), so the column has to
- * have a constant that means "deleted" and another that means "not deleted".
+ * `marker` picks the shape of the predicate. When the config names a constant that means
+ * deleted, the predicate compares against it (`isDeleted = true`); otherwise the column marks
+ * a row deleted by holding a value at all (`deletedAt IS NOT NULL`), the common timestamp
+ * form. A NOT NULL column has no "absent" state, so it must have a marker; a nullable one
+ * takes the NULL-means-alive reading only when no marker was configured.
  */
 type SoftDeleteInfo = {
     /** Property name of the column on the drizzle table — also the key on an aliased proxy. */
@@ -382,8 +559,22 @@ type SoftDeleteInfo = {
     writeDeleted: () => any;
     /** Written by the restore mutation. */
     writeRestored: any;
-    /** Non-nullable form only: the constant that means "this row is deleted". */
+    /**
+     * The constant that means "this row is deleted", when the config named one. Required on a
+     * NOT NULL column; optional on a nullable one, which otherwise reads NULL as alive.
+     */
     marker?: any;
+    /**
+     * Which reads hide marked rows by default — `'all'` (the table's own fields and every
+     * relation pointing at it) or `'root'` (its own fields only). See
+     * {@link relationDeletedDefault}.
+     */
+    scope: 'root' | 'all';
+    /**
+     * Whether the delete mutations take a `hard` argument that issues a real `DELETE`. Off
+     * unless the table opts in, so the generated schema says which tables can be purged.
+     */
+    hardDelete: boolean;
 };
 /** Build-time lookup: the soft-delete convention of a table, if it declares one. */
 type SoftDeleteFor = (tableName: string) => SoftDeleteInfo | undefined;
@@ -409,6 +600,26 @@ type TablePolicies = {
     /** See `BuildSchemaConfig.defaults`. */
     defaultOrderBy?: DefaultOrderByFor;
 };
+
+/**
+ * Compiles an `orderBy` argument into ORDER BY expressions, highest priority first.
+ *
+ * A key naming one of the table's columns orders by that column. A key naming a to-one
+ * relation takes the target table's own OrderBy input and orders by the related row's
+ * column(s), compiled as a correlated scalar subquery — reusing the aliased-join machinery
+ * the relation filters are built on — so it works identically on all three dialects and
+ * inside the relational query builder's aliased CTEs. Priorities share one global space
+ * across relation boundaries. Each entry may also carry `nulls: first | last`
+ * (see {@link orderExpressions} for how MySQL emulates it).
+ *
+ * An entry may instead set `matchFilterOrder`, which sorts by the column's position in the
+ * `inArray` list the same request's `where` gives it — `whereArgs` is that `where`.
+ *
+ * `ctx` supplies the tables and relation map that relation ordering needs; callers whose
+ * inputs cannot contain relation keys may omit it.
+ */
+declare const extractOrderBy: <TTable extends Table, TArgs extends OrderByArgs<any> = OrderByArgs<TTable>>(table: TTable, orderArgs: TArgs, ctx?: RelationFilterContext, whereArgs?: Record<string, any>) => SQL[];
+
 /**
  * Where a dialect's default sort places NULLs relative to non-NULL values:
  * - `nulls-largest` — PostgreSQL: NULLs sort as the largest values (last in ASC, first in DESC).
@@ -417,13 +628,58 @@ type TablePolicies = {
  * The keyset predicate has to agree with the dialect's ORDER BY, so each builder passes its own.
  */
 type NullOrdering = 'nulls-largest' | 'nulls-smallest';
+
 /**
- * Default for `config.onError`: keeps drizzle-graphql's own errors, which are written for
- * the client, and replaces driver/database errors with a generic message. Their text names
- * tables, columns, constraints and offending values, none of which belongs in a response.
- * The original is preserved on `originalError` for server-side logging.
+ * Key on the GraphQL context object under which a caller can place a Drizzle transaction
+ * (or any other executor: a pooled connection, a logging proxy). Every generated resolver
+ * reads it at resolve time and runs its statements there instead of on the database the
+ * schema was built from, which is what lets several mutations in one request share a
+ * transaction and lets a query see that transaction's uncommitted rows:
+ *
+ * ```ts
+ * await db.transaction(async (tx) => {
+ *   await graphql({ schema, source, contextValue: { [drizzleExecutorKey]: tx } });
+ * });
+ * ```
+ *
+ * Registered with `Symbol.for` so the ESM and CJS builds of this package agree on it when
+ * both end up loaded in one process.
  */
-declare const defaultErrorMapper: (error: unknown) => unknown;
+declare const drizzleExecutorKey: unique symbol;
+
+/**
+ * Extracts the join column info from a drizzle-orm v1 Relation object.
+ * Returns the JS property name of the local column on the parent table and the
+ * Column object for the foreign column on the target table, or undefined if the
+ * relation internals are not accessible.
+ */
+declare const extractRelationJoinColumns: (relEntry: TableNamedRelations, parentTable: Table, targetTable: Table) => {
+    localColPropName: string;
+    foreignCol: Column;
+    foreignColPropName: string;
+} | undefined;
+type RelationResolverFactory = (params: {
+    tableName: string;
+    relationName: string;
+    relEntry: TableNamedRelations;
+    isOne: boolean;
+}) => GraphQLFieldResolver<any, any> | undefined;
+
+/**
+ * Creates a RelationResolverFactory that generates field-level resolvers for each relation.
+ * Each resolver:
+ *   1. Returns pre-fetched data if the parent resolver already included it (eager path, zero cost).
+ *   2. When limit/offset args are present, falls back to a direct per-item query.
+ *   3. Otherwise batches all sibling resolver calls within the same GraphQL execution tick
+ *      into a single IN-clause query, eliminating N+1 database round-trips.
+ *
+ * `nullOrdering` is the dialect's native `ORDER BY` placement for `NULL` — the keyset
+ * predicate behind a relation's `after` argument has to match it, or rows with a `NULL` in an
+ * ordered column would be skipped instead of paged through. It has no sensible default, so
+ * each dialect builder states it: `'nulls-largest'` for PostgreSQL, `'nulls-smallest'` for
+ * MySQL and SQLite.
+ */
+declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, nullOrdering: NullOrdering, filterCtx?: RelationFilterBase, limits?: LimitPolicyFor, policies?: TablePolicies) => RelationResolverFactory;
 
 type Relations<TTable extends string = string, TConfig extends Record<string, Relation> = Record<string, Relation>> = {
     table: {
@@ -435,7 +691,19 @@ type Relations<TTable extends string = string, TConfig extends Record<string, Re
 };
 
 type AnyDrizzleDB<TSchema extends Record<string, any>> = PgAsyncDatabase<any, TSchema> | BaseSQLiteDatabase<any, any, TSchema> | MySqlDatabase<any, any, TSchema>;
-type ExtractTables<TSchema extends Record<string, Table | unknown>> = {
+/**
+ * The tables a database handle knows about, keyed by their schema key.
+ *
+ * Two shapes reach this type, because drizzle-orm v1 changed what a database's generic slot
+ * holds. SQLite and MySQL handles still carry the schema module itself, so the tables are
+ * picked out of it directly. PostgreSQL handles carry only the relations config built by
+ * `buildRelations` — a `Record<string, { table; name; relations }>` — so the tables are read
+ * off its `table` members instead. Without the second branch every PG-derived type collapses
+ * to `never`.
+ */
+type ExtractTables<TSchema extends Record<string, Table | unknown>> = TSchema extends TablesRelationalConfig ? {
+    [K in keyof TSchema]: TSchema[K]['table'] extends infer TTable extends Table ? TTable : never;
+} : {
     [K in keyof TSchema as TSchema[K] extends Table ? K : never]: TSchema[K] extends Table ? TSchema[K] : never;
 };
 type ExtractRelations<TSchema extends Record<string, Table | unknown>> = {
@@ -550,7 +818,7 @@ type DeleteResolver<TTable extends Table, IsReturnless extends boolean> = (sourc
 type DeleteSingleResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: DeleteSingleArgs<TTable>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
 type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations extends Record<string, Relations>, TInputs extends Record<string, GraphQLInputObjectType>, TOutputs extends Record<string, GraphQLObjectType>> = {
     [TName in keyof TSchemaTables as TName extends string ? `${Uncapitalize<TName>}` : never]: TName extends string ? {
-        type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[`${Capitalize<TName>}SelectItem`]>>>;
+        type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[Capitalize<TName>]>>>;
         args: {
             offset: {
                 type: GraphQLScalarType<number, number>;
@@ -572,7 +840,7 @@ type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations e
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `${Uncapitalize<TName>}Single` : never]: TName extends string ? {
-        type: TOutputs[`${Capitalize<TName>}SelectItem`];
+        type: TOutputs[Capitalize<TName>];
         args: {
             offset: {
                 type: GraphQLScalarType<number, number>;
@@ -599,30 +867,30 @@ type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations e
 };
 type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends Record<string, GraphQLInputObjectType>, TOutputs extends Record<string, GraphQLObjectType>, IsReturnless extends boolean> = {
     [TName in keyof TSchemaTables as TName extends string ? `create${Capitalize<TName>}` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[`${Capitalize<TName>}Item`]>>>;
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[Capitalize<TName>]>>>;
         args: {
             values: {
-                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>>>;
+                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`Create${Capitalize<TName>}Input`]>>>;
             };
         };
         resolve: InsertArrResolver<TSchemaTables[TName], IsReturnless>;
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `create${Capitalize<TName>}Single` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[`${Capitalize<TName>}Item`];
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[Capitalize<TName>];
         args: {
             values: {
-                type: GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>;
+                type: GraphQLNonNull<TInputs[`Create${Capitalize<TName>}Input`]>;
             };
         };
         resolve: InsertResolver<TSchemaTables[TName], IsReturnless>;
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `upsert${Capitalize<TName>}` : never]?: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[`${Capitalize<TName>}Item`]>>>;
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[Capitalize<TName>]>>>;
         args: {
             values: {
-                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>>>;
+                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`Create${Capitalize<TName>}Input`]>>>;
             };
             onConflict: {
                 type: GraphQLInputObjectType;
@@ -632,10 +900,10 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `upsert${Capitalize<TName>}Single` : never]?: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[`${Capitalize<TName>}Item`];
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[Capitalize<TName>];
         args: {
             values: {
-                type: GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>;
+                type: GraphQLNonNull<TInputs[`Create${Capitalize<TName>}Input`]>;
             };
             onConflict: {
                 type: GraphQLInputObjectType;
@@ -645,10 +913,10 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `update${Capitalize<TName>}` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[`${Capitalize<TName>}Item`]>>>;
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[Capitalize<TName>]>>>;
         args: {
             set: {
-                type: GraphQLNonNull<TInputs[`${Capitalize<TName>}UpdateInput`]>;
+                type: GraphQLNonNull<TInputs[`Update${Capitalize<TName>}Input`]>;
             };
             where: {
                 type: TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never;
@@ -658,20 +926,20 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `update${Capitalize<TName>}Many` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<TOutputs[`${Capitalize<TName>}Item`]>>;
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<TOutputs[Capitalize<TName>]>>;
         args: {
             updates: {
-                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`${Capitalize<TName>}UpdateManyInput`]>>>;
+                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`Update${Capitalize<TName>}ManyInput`]>>>;
             };
         };
         resolve: UpdateManyResolver<TSchemaTables[TName], IsReturnless>;
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `update${Capitalize<TName>}Single` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[`${Capitalize<TName>}Item`];
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[Capitalize<TName>];
         args: {
             set: {
-                type: GraphQLNonNull<TInputs[`${Capitalize<TName>}UpdateInput`]>;
+                type: GraphQLNonNull<TInputs[`Update${Capitalize<TName>}Input`]>;
             };
             where: {
                 type: GraphQLNonNull<TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never>;
@@ -681,7 +949,7 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `delete${Capitalize<TName>}` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[`${Capitalize<TName>}Item`]>>>;
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : GraphQLNonNull<GraphQLList<GraphQLNonNull<TOutputs[Capitalize<TName>]>>>;
         args: {
             where: {
                 type: TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never;
@@ -691,7 +959,7 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
     } : never;
 } & {
     [TName in keyof TSchemaTables as TName extends string ? `delete${Capitalize<TName>}Single` : never]: TName extends string ? {
-        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[`${Capitalize<TName>}Item`];
+        type: IsReturnless extends true ? TOutputs['MutationReturn'] extends GraphQLObjectType ? TOutputs['MutationReturn'] : never : TOutputs[Capitalize<TName>];
         args: {
             where: {
                 type: GraphQLNonNull<TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never>;
@@ -700,25 +968,42 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
         resolve: DeleteSingleResolver<TSchemaTables[TName], IsReturnless>;
     } : never;
 };
+/**
+ * Keys of `entities.inputs`, which is keyed by generated GraphQL input type name.
+ *
+ * The write inputs are named from the configured `prefixes`, so these keys describe a build
+ * that uses the defaults (`insert: 'create'`, `update: 'update'`); a build that overrides a
+ * prefix produces correspondingly different keys. Inputs that only exist when a feature is
+ * enabled — `${Table}OnConflict` for upsert, `${Table}Having` for group-by — are not listed,
+ * since whether they were generated is a runtime decision.
+ */
 type GeneratedInputs<TSchema extends Record<string, Table>> = {
-    [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}InsertInput` : never]: GraphQLInputObjectType;
+    [TName in keyof TSchema as TName extends string ? `Create${Capitalize<TName>}Input` : never]: GraphQLInputObjectType;
 } & {
-    [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}UpdateInput` : never]: GraphQLInputObjectType;
+    [TName in keyof TSchema as TName extends string ? `Update${Capitalize<TName>}Input` : never]: GraphQLInputObjectType;
 } & {
-    [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}UpdateManyInput` : never]: GraphQLInputObjectType;
+    [TName in keyof TSchema as TName extends string ? `Update${Capitalize<TName>}ManyInput` : never]: GraphQLInputObjectType;
 } & {
     [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}OrderBy` : never]: GraphQLInputObjectType;
 } & {
     [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}Filters` : never]: GraphQLInputObjectType;
 };
+/**
+ * Keys of `entities.types`, which is keyed by generated GraphQL type name.
+ *
+ * This build emits ONE object type per table (`Users`) used for both selects and mutation
+ * returns — upstream drizzle-graphql emitted two (`UsersSelectItem` / `UsersItem`), and this
+ * type kept those names long after the generator stopped producing them. MySQL still has a
+ * shared `MutationReturn` instead of per-table return types, because its writes return no rows.
+ */
 type GeneratedOutputs<TSchema extends Record<string, Table>, IsReturnless extends boolean> = {
-    [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}SelectItem` : never]: GraphQLObjectType;
+    [TName in keyof TSchema as TName extends string ? Capitalize<TName> : never]: GraphQLObjectType;
 } & {
     [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}Aggregate` : never]: GraphQLObjectType;
 } & (IsReturnless extends true ? {
     MutationReturn: GraphQLObjectType;
 } : {
-    [TName in keyof TSchema as TName extends string ? `${Capitalize<TName>}Item` : never]: GraphQLObjectType;
+    [TName in keyof TSchema as TName extends string ? Capitalize<TName> : never]: GraphQLObjectType;
 });
 type GeneratedEntities<TDatabase extends AnyDrizzleDB<TSchema>, TSchema extends Record<string, unknown> = TDatabase extends AnyDrizzleDB<infer ISchema> ? ISchema : never, TSchemaTables extends ExtractTables<TSchema> = ExtractTables<TSchema>, TSchemaRelations extends ExtractRelations<TSchema> = ExtractRelations<TSchema>, TInputs extends GeneratedInputs<TSchemaTables> = GeneratedInputs<TSchemaTables>, TOutputs extends GeneratedOutputs<TSchemaTables, TDatabase extends MySqlDatabase<any, any, any, any> ? true : false> = GeneratedOutputs<TSchemaTables, TDatabase extends MySqlDatabase<any, any, any, any> ? true : false>> = {
     queries: QueriesCore<TSchemaTables, TSchemaRelations, TInputs, TOutputs>;
@@ -750,7 +1035,8 @@ type GeneratedData<TDatabase extends AnyDrizzleDB<any>> = {
 type FeatureSwitch = boolean | ((tableName: string) => boolean);
 /**
  * Per-feature switches for what `buildSchema` generates. Every flag defaults to `true` except
- * `upsert`, `nestedWrites`, `fieldUpdateOperations`, `countMutations` and `requireWhere`.
+ * `upsert`, `nestedWrites`, `fieldUpdateOperations`, `countMutations`, `requireWhere` and
+ * `uniqueKeyFilters`.
  * Each one takes a boolean or a per-table predicate, apart from `nestedWrites`, which is
  * build-wide.
  * See {@link BuildSchemaConfig.features}.
@@ -885,6 +1171,29 @@ type SchemaFeatures = {
      * @default false
      */
     requireWhere?: FeatureSwitch;
+    /**
+     * One `where` field per compound unique constraint, so a lookup by a natural key names the
+     * key instead of restating its columns:
+     *
+     * ```graphql
+     * stockSingle(where: { itemId_locationId: { itemId: "i1", locationId: "l1" } }) { quantity }
+     * ```
+     *
+     * The field is named after its member columns and every member is non-null, so a half-
+     * supplied key fails query validation rather than becoming a broader filter that returns
+     * whichever row happens to come first. It compiles to the same equalities the columns would
+     * have — the guarantee is in the input type.
+     *
+     * Single-column constraints get no field (`eq` on the column already says it), and a
+     * constraint whose field name is taken by a column or a relation is skipped. The fields live
+     * on `<Type>Filters`, so they are accepted wherever a filter is: the `Single` reads and
+     * writes they are meant for, but also list queries, relation filters and `onConflict.where`.
+     *
+     * Off unless asked for: it adds an input type per compound constraint.
+     *
+     * @default false
+     */
+    uniqueKeyFilters?: FeatureSwitch;
 };
 /**
  * Per-field cost hints for `graphql-query-complexity` (or any estimator that reads
@@ -995,6 +1304,33 @@ type SoftDeleteColumn = string | {
      * for a NOT NULL boolean; required for any other NOT NULL column.
      */
     restoredValue?: any;
+    /**
+     * Which generated reads hide marked rows by default.
+     *
+     * - `'all'` (the default) — the table's own query fields and every relation field that
+     *   points at it. A *required* to-one relation is the one exception: hiding the row
+     *   there can only produce "Cannot return null for non-nullable field", never a usable
+     *   result, so it reads `INCLUDE` unless the request says otherwise.
+     * - `'root'` — only the table's own query fields. Relation fields read marked rows,
+     *   which is what "retired, not erased" usually means: keep the row off the pickers and
+     *   the lists, keep rendering it on the historical rows that reference it.
+     *
+     * The `deleted` argument is generated either way, so either default can be overridden
+     * per request.
+     */
+    scope?: 'root' | 'all';
+    /**
+     * Whether the table's delete mutations accept `hard: Boolean = false`, which issues a
+     * real `DELETE` instead of writing the marker — emptying the trash, reclaiming a unique
+     * key, clearing a table. Opt-in per table, and the argument is only generated when it is
+     * on, so the schema itself says which tables can be purged.
+     *
+     * A hard delete reads at `INCLUDE`: it reaches already-marked rows, which is the case it
+     * mostly exists for. A `scope` still confines it, exactly as it confines every other write.
+     *
+     * @default false
+     */
+    hardDelete?: boolean;
 };
 
 /**
@@ -1466,6 +1802,58 @@ type BuildSchemaConfig = {
         singular: string;
         plural: string;
     } | undefined);
+    /**
+     * Renames the types generated *around* a table — the filter, the write inputs, the
+     * order-by, the aggregate family, the group-by types, the conflict input, the shared scalar
+     * filters. `typeNameMapper` names a table's object type and its root fields; those derived
+     * names follow from it by a fixed rule, and this is the hook that overrides the rule.
+     *
+     * Asked once per generated type, with the kind, the name the library would use, and the
+     * table it belongs to where it belongs to one. Return `undefined` — or the same name — to
+     * keep the default, so a mapper that answers for one kind leaves everything else alone:
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   derivedTypeNameMapper: ({ kind, table, operation, defaultName }) =>
+     *     kind === 'aggregate' && operation ? `${table}Aggregate${operation}` : undefined,
+     * });
+     * ```
+     *
+     * A returned name is used verbatim — {@link BuildSchemaConfig.typeNamePrefix} and
+     * {@link BuildSchemaConfig.typeNameSuffix} do not wrap it, since the more specific of the
+     * two knobs wins.
+     *
+     * The point of it is stitching: a schema merged with a second generator over the same
+     * tables collides on the derived names constantly, because both derive them from the model
+     * name by the same obvious rule. Renaming them here means the collision never exists, rather
+     * than being papered over by a `RenameTypes` transform on the way out.
+     */
+    derivedTypeNameMapper?: DerivedTypeNameMapper;
+    /**
+     * Prepended to every generated type name — object types, filters, write inputs, the
+     * aggregate family, the shared scalar filters, everything — that
+     * {@link BuildSchemaConfig.derivedTypeNameMapper} did not answer for. The one-line way to
+     * make a whole subschema collision-free before stitching it:
+     *
+     * ```ts
+     * buildSchema(db, { typeNamePrefix: 'Db' });
+     * // type DbUsers, input DbUsersFilters, input DbStringFilter, enum DbOrderNulls, …
+     * ```
+     *
+     * Custom scalars, database enum types and `PgGeometryObject` keep their own names: their
+     * definition does not vary between builds, so a gateway merges them rather than colliding
+     * on them. Field and argument names are untouched too — only type names move, so a client's
+     * queries are unaffected apart from the names it spells in variable declarations.
+     *
+     * Must be a valid GraphQL name start (`/^[_A-Za-z][_0-9A-Za-z]*$/`); anything else throws.
+     */
+    typeNamePrefix?: string;
+    /**
+     * Appended to every generated type name that {@link BuildSchemaConfig.derivedTypeNameMapper}
+     * did not answer for. The counterpart of {@link BuildSchemaConfig.typeNamePrefix}; both may
+     * be given at once.
+     */
+    typeNameSuffix?: string;
     /**
      * Controls whether a relation is eagerly pre-fetched via Drizzle's `with:` clause
      * when its parent is loaded through a generated query or mutation.
@@ -1682,110 +2070,6 @@ declare const singularizeMapper: (tableName: string) => {
     plural: string;
 };
 
-/**
- * The identity a generated field publishes about itself, under `extensions.drizzle`.
- *
- * Every field this library generates carries one, so a wrapper — `graphql-middleware`,
- * envelop, `graphql-shield`, an audit log, a cache invalidator — can ask the schema what a
- * field is instead of reverse-engineering its name. Names are configurable (`prefixes`,
- * `suffixes`, `typeNameMapper`), so name parsing is ambiguous by construction; this is not.
- *
- * This shape is stable API: fields are only ever added to it, never removed or repurposed.
- */
-/** What family of field this is. */
-type DrizzleFieldKind = 'query' | 'mutation' | 'relation' | 'aggregate' | 'type';
-/**
- * What the field does. Arity is carried separately by `single`, so `select` covers both
- * the list query and its `…Single` sibling rather than being spelled twice.
- */
-type DrizzleFieldOperation = 'select' | 'insert' | 'update' | 'updateMany' | 'upsert' | 'delete' | 'restore' | 'aggregate' | 'groupBy' | 'relation' | 'relationAggregate';
-/** The argument holding the rows a field is about, when it has one. */
-type DrizzleTargetArg = 'where' | 'values' | 'updates';
-/** `extensions.drizzle` on a generated field. */
-type DrizzleFieldExtension = {
-    /** The Drizzle schema key of the table the field reads or writes. */
-    table: string;
-    kind: Exclude<DrizzleFieldKind, 'type'>;
-    operation: DrizzleFieldOperation;
-    /** Whether the field resolves to one row (or one aggregate) rather than a list. */
-    single: boolean;
-    /**
-     * Which argument names the rows: `where` for select/update/delete/aggregate, `values`
-     * for insert and upsert, `updates` for the batch update's per-entry `{ where, set }`.
-     * Absent when the field takes no such argument.
-     */
-    targetArg?: DrizzleTargetArg;
-    /**
-     * Primary-key property names of `table`, in schema order. Empty when the table declares
-     * no primary key. Carried here so {@link identifyRows} works from the field alone.
-     */
-    primaryKey: readonly string[];
-    /** For `kind: 'relation'` and `operation: 'relationAggregate'`: the relation's name. */
-    relation?: string;
-    /** For `kind: 'relation'` and `operation: 'relationAggregate'`: the table it hangs off. */
-    parentTable?: string;
-};
-/** `extensions.drizzle` on a generated object type. */
-type DrizzleTypeExtension = {
-    /** The Drizzle schema key this type was generated from. */
-    table: string;
-    kind: 'type';
-    /** Primary-key property names of `table`, in schema order. Empty when there is none. */
-    primaryKey: readonly string[];
-};
-type DrizzleExtension = DrizzleFieldExtension | DrizzleTypeExtension;
-/** Anything carrying GraphQL `extensions` — a field config, a field, or a named type. */
-type WithExtensions = {
-    extensions?: {
-        drizzle?: unknown;
-    } | null;
-} | null | undefined;
-/**
- * Reads the `drizzle` extension off a field or type, typed. Returns `undefined` for
- * anything this library did not generate, which is the check a wrapper wants before it
- * treats a field as one of ours.
- */
-declare const drizzleExtension: (target: WithExtensions) => DrizzleExtension | undefined;
-/** Narrows to the field form — object types carry `kind: 'type'` and no operation. */
-declare const isDrizzleFieldExtension: (value: DrizzleExtension | undefined) => value is DrizzleFieldExtension;
-/** The rows a field's arguments name. */
-type IdentifiedRows = {
-    /** The Drizzle schema key of the table being read or written. */
-    table: string;
-    /** Primary-key property names, in schema order. */
-    primaryKey: readonly string[];
-    /** One entry per identified row: the primary-key values, keyed by property name. */
-    rows: Record<string, unknown>[];
-    /**
-     * Whether `rows` is exactly the set the operation affects.
-     *
-     * `false` means the arguments do not pin the rows down — an insert whose key the
-     * database generates, a `where` that filters on something other than the primary key,
-     * a plural update with no filter at all, or a table with no primary key. `rows` is then
-     * a best-effort subset-free superset: every entry in it is a row the key values name,
-     * but other filters may narrow the real set further, and it may be empty.
-     */
-    complete: boolean;
-};
-/**
- * The rows a generated field's arguments are about, as primary-key values.
- *
- * The row identity of a mutation lives in a different argument for every operation —
- * `where` for update and delete, `values` for insert and upsert, a per-entry `where` inside
- * `updates` for the batch update — and each of those has both a one-row and a many-row
- * spelling. This reads whichever one applies:
- *
- * ```ts
- * const field = info.parentType.getFields()[info.fieldName];
- * const target = identifyRows(field, args);
- * if (target?.complete) await invalidate(target.table, target.rows);
- * ```
- *
- * Returns `undefined` for a field this library did not generate, or an object type. Check
- * `complete` before treating `rows` as the affected set — see {@link IdentifiedRows}.
- */
-declare const identifyRows: (field: WithExtensions, args: Record<string, unknown> | undefined) => IdentifiedRows | undefined;
-
 /**
  * A 64-bit integer. Always transported as a decimal string, in both directions, so no value
  * is ever silently rounded by JSON's double-precision numbers. `graphql-scalars`' own
@@ -1813,6 +2097,14 @@ type SelectionOptions = {
      * pass the same mapper here or nothing will match.
      */
     typeNameMapper?: TypeNameMapper;
+    /**
+     * The `derivedTypeNameMapper` / `typeNamePrefix` / `typeNameSuffix` the schema was built
+     * with, when any were configured. Same reason as `typeNameMapper`: the translation matches
+     * selections against the names the build actually published.
+     */
+    derivedTypeNameMapper?: DerivedTypeNameMapper;
+    typeNamePrefix?: string;
+    typeNameSuffix?: string;
 };
 /**
  * Translates a GraphQL selection set into the relational query builder's `with` tree — the
@@ -1872,4 +2164,4 @@ declare const resolveSelection: (info: GraphQLResolveInfo | ResolveTree, options
 
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>>(db: TDbClient, config?: BuildSchemaConfig) => GeneratedData<TDbClient>;
 
-export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type ContextValuesConfig, type DefaultOrderByEntry, type DefaultsConfig, type DeleteResolver, type DeleteSingleResolver, type DrizzleExtension, type DrizzleFieldExtension, type DrizzleFieldKind, type DrizzleFieldOperation, type DrizzleTargetArg, type DrizzleTypeExtension, type EnumNameInfo, type EnumNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type FeatureSwitch, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, GraphQLDecimalString, type IdentifiedRows, type InsertArrResolver, type InsertResolver, type LimitsConfig, type MutationReturnlessResult, type MutationsCore, type OnWriteConfig, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ResolveSelectionOptions, type RowScope, type RowScopeFilter, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaExclusions, type SchemaFeatures, type ScopeConfig, type SelectResolver, type SelectSingleResolver, type SelectionOptions, type SoftDeleteColumn, type SoftDeleteConfig, type TableDefaults, type TableDescriber, type TableLimitPolicy, type TableNamedRelations, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, type WriteHook, type WriteHookPayload, type WriteHookPositions, type WriteHooks, type WriteOperation, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, drizzleExtension, extractFilters, extractOrderBy, extractRelationJoinColumns, identifyRows, isDrizzleFieldExtension, resolveSelection, selectionToWith, singularizeMapper };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type ContextValuesConfig, type DefaultOrderByEntry, type DefaultsConfig, type DeleteResolver, type DeleteSingleResolver, type DrizzleErrorCode, type DrizzleErrorContext, type DrizzleExtension, type DrizzleFieldExtension, type DrizzleFieldKind, type DrizzleFieldOperation, type DrizzleTargetArg, type DrizzleTypeExtension, type EnumNameInfo, type EnumNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type FeatureSwitch, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, GraphQLDecimalString, type IdentifiedRows, type InsertArrResolver, type InsertResolver, type LimitsConfig, type MutationReturnlessResult, type MutationsCore, type OnWriteConfig, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ResolveSelectionOptions, type RowScope, type RowScopeFilter, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaExclusions, type SchemaFeatures, type ScopeConfig, type SelectResolver, type SelectSingleResolver, type SelectionOptions, type SoftDeleteColumn, type SoftDeleteConfig, type TableDefaults, type TableDescriber, type TableLimitPolicy, type TableNamedRelations, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, type WriteHook, type WriteHookPayload, type WriteHookPositions, type WriteHooks, type WriteOperation, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleError, drizzleExecutorKey, drizzleExtension, extractFilters, extractOrderBy, extractRelationJoinColumns, identifyRows, isDrizzleFieldExtension, resolveSelection, selectionToWith, singularizeMapper };