@vantreeseba/drizzle-graphql 5.6.0 → 7.0.0

package/dist/index.d.cts

@@ -40,6 +40,63 @@ type ColumnTypeMapperInfo = {
  * the built-in detection.
  */
 type ColumnTypeMapper = (column: Column, info: ColumnTypeMapperInfo) => ScalarOverride | undefined;
+/** Everything an {@link EnumNameMapper} needs to name — or opt a column out of — a generated enum type. */
+type EnumNameInfo = {
+    /**
+     * The name the enum type was declared with (`pgEnum('status', …)`), shared by every column
+     * that uses it. `undefined` for an inline value list (`text({ enum: [...] })`,
+     * `mysqlEnum(...)`), which belongs to the one column that declares it.
+     */
+    enumName: string | undefined;
+    /** The Postgres schema the named enum was declared in, when it declares one. */
+    schema: string | undefined;
+    /** The table's key in the Drizzle schema object. */
+    tableName: string;
+    /** The column's property name on the table object. */
+    columnName: string;
+    /** The enum's values, in declaration order. */
+    values: readonly string[];
+};
+/**
+ * Names a generated GraphQL enum type. Return `undefined` to keep the default name. See
+ * `BuildSchemaConfig.enumNameMapper`.
+ */
+type EnumNameMapper = (info: EnumNameInfo) => string | undefined;
+/** Context handed to the documentation and deprecation hooks alongside the column itself. */
+type ColumnDocInfo = {
+    /** The table's key in the Drizzle schema object. */
+    tableName: string;
+    /** The column's property name on the table object. */
+    columnName: string;
+};
+/**
+ * Supplies the GraphQL `description` for a generated column field. See
+ * `BuildSchemaConfig.describeColumn`.
+ */
+type ColumnDescriber = (column: Column, info: ColumnDocInfo) => string | undefined;
+/**
+ * Supplies the GraphQL `deprecationReason` for a generated column field. See
+ * `BuildSchemaConfig.deprecateColumn`.
+ */
+type ColumnDeprecator = (column: Column, info: ColumnDocInfo) => string | undefined;
+/** Supplies the GraphQL `description` for a table's object type. See `BuildSchemaConfig.describeTable`. */
+type TableDescriber = (tableName: string) => string | undefined;
+/**
+ * Supplies the GraphQL `description` for a relation field. See
+ * `BuildSchemaConfig.describeRelation`.
+ */
+type RelationDescriber = (tableName: string, relationName: string) => string | undefined;
+/**
+ * The documentation hooks a build was configured with, resolved once and threaded through
+ * type generation. Every member is optional; a build with no hooks generates fields with no
+ * descriptions at all.
+ */
+type SchemaDocs = {
+    describeColumn?: ColumnDescriber;
+    describeTable?: TableDescriber;
+    describeRelation?: RelationDescriber;
+    deprecateColumn?: ColumnDeprecator;
+};
 
 type TableNamedRelations = {
     relation: Relation;
@@ -175,8 +232,14 @@ declare const drizzleExecutorKey: unique symbol;
  *   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>, filterCtx?: RelationFilterBase) => RelationResolverFactory;
+declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, nullOrdering: NullOrdering, filterCtx?: RelationFilterBase) => RelationResolverFactory;
 /**
  * Compiles an `orderBy` argument into ORDER BY expressions, highest priority first.
  *
@@ -218,6 +281,14 @@ interface RelationFilterContext {
  */
 type RelationFilterBase = Pick<RelationFilterContext, 'tables' | 'relationMap'>;
 declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>, relationCtx?: RelationFilterContext) => SQL | undefined;
+/**
+ * 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).
+ * - `nulls-smallest` — MySQL and SQLite: NULLs sort as the smallest values (first in ASC, last
+ *   in DESC).
+ * 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
@@ -580,6 +651,83 @@ type SchemaFeatures = {
      * @default false
      */
     upsert?: boolean;
+    /**
+     * Relation fields on `Create<Table>Input` and `Update<Table>Input`, so a parent row and
+     * the rows it is related to can be written in one mutation. Off unless asked for: it adds
+     * a field per writable relation to every create and update input.
+     *
+     * ```graphql
+     * createPostsSingle(values: {
+     *   title: "Hello"
+     *   author: { connect: { id: { eq: "a1" } } }
+     *   tags: { create: [{ name: "drizzle" }] }
+     * }) { id }
+     * ```
+     *
+     * Each relation field offers `create` and `connect`; the update input adds `disconnect`
+     * and, for a to-many relation, `set` (replace the whole set). `disconnect` and `set` are
+     * generated only when the foreign key is nullable — there is no way to detach a row whose
+     * key is NOT NULL — and many-to-many (`.through()`) relations are not written through at
+     * all. Nesting is one level deep: the row a nested `create` inserts takes columns only.
+     *
+     * The whole tree runs in one transaction (a savepoint when the request already carries
+     * one), and a column a relation fills in (`authorId`, when `author: { create: … }` is
+     * offered) becomes nullable on the create input, since the relation is the other way to
+     * supply it.
+     *
+     * PostgreSQL and SQLite only. MySQL cannot return the rows it just wrote, which is how a
+     * nested write learns the parent's key, so `buildSchema` rejects the flag there. On SQLite
+     * the driver must be asynchronous (libsql, D1, …): a synchronous one commits before an
+     * awaited statement runs, so `buildSchema` rejects the combination outright.
+     *
+     * @default false
+     */
+    nestedWrites?: boolean;
+    /**
+     * Operation inputs on the update `set`, so a column can be changed relative to its current
+     * value instead of only replaced.
+     *
+     * ```graphql
+     * updatePostsSingle(where: { id: { eq: "p1" } }, set: { views: { increment: 1 } }) { views }
+     * ```
+     *
+     * Every numeric column's field on `Update<Table>Input` becomes a `<Scalar>FieldUpdate`
+     * input carrying `set`, `increment`, `decrement`, `multiply` and `divide`; every array
+     * column's becomes a `<Scalar>ListFieldUpdate` carrying `set` and `push`. Exactly one
+     * operation per field, checked at resolve time. `set` is the explicit spelling of what the
+     * field did before, so `set: { views: 42 }` becomes `set: { views: { set: 42 } }`.
+     *
+     * The arithmetic happens in the database (`SET views = views + 1`), so a counter no longer
+     * needs a read-modify-write round trip and no longer loses concurrent updates. Rounding on
+     * an integer column, and division by zero, follow the database's own rules rather than
+     * being guarded here. Columns owned by a scalar override keep their plain type — an
+     * override owns what the column accepts.
+     *
+     * Off by default: it changes the type of every numeric and array field on every update
+     * input, which no existing document is written against.
+     *
+     * @default false
+     */
+    fieldUpdateOperations?: boolean;
+    /**
+     * `update<Table>Count` / `delete<Table>Count` mutations — the same write as the plural
+     * `update<Table>` / `delete<Table>`, returning the number of rows affected instead of the
+     * rows themselves.
+     *
+     * ```graphql
+     * deletePostsCount(where: { published: { eq: false } })   # Int!
+     * ```
+     *
+     * A mass update or delete otherwise has to `RETURNING *` every row it touched purely so
+     * the caller can count them, which crosses the driver and is serialized through GraphQL
+     * for nothing. Each mutation is generated only when its plural counterpart is
+     * (`features.update` / `features.delete`), and honours `features.requireWhere`.
+     *
+     * Off unless asked for, so an existing schema does not grow new mutations on upgrade.
+     *
+     * @default false
+     */
+    countMutations?: boolean;
     /**
      * Makes `where` non-null on the plural `update<Table>` / `delete<Table>` mutations, and
      * rejects a `where` that collapses to no filters (e.g. `where: {}`), so a schema can rule
@@ -884,6 +1032,94 @@ type BuildSchemaConfig = {
      * ```
      */
     onError?: (error: unknown) => unknown;
+    /**
+     * Supplies the GraphQL `description` for a column, everywhere that column becomes a field:
+     * the object type, the create/update inputs, the filter input, and the aggregate
+     * `min`/`max`/`group` fields.
+     *
+     * Nothing is generated by default. The library used to emit the column's own type name
+     * ("DateTime", "JSON") as its description, which documented nothing a reader could not see
+     * from the type — that is gone, and this hook is what puts real prose in its place. Drizzle
+     * carries no column-comment metadata to read, so the text has to come from here.
+     *
+     * ```ts
+     * const columnDocs = { Users: { email: 'Primary contact address. Unique, case-insensitive.' } };
+     *
+     * buildSchema(db, {
+     *   describeColumn: (_column, { tableName, columnName }) => columnDocs[tableName]?.[columnName],
+     * });
+     * ```
+     *
+     * `tableName` and `columnName` are the Drizzle schema keys. Return `undefined` to leave the
+     * field undocumented.
+     */
+    describeColumn?: ColumnDescriber;
+    /**
+     * Supplies the GraphQL `description` for a table's object type.
+     *
+     * ```ts
+     * buildSchema(db, { describeTable: (tableName) => tableDocs[tableName] });
+     * ```
+     */
+    describeTable?: TableDescriber;
+    /**
+     * Supplies the GraphQL `description` for a relation field on a table's object type.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   describeRelation: (tableName, relationName) =>
+     *     tableName === 'Users' && relationName === 'posts' ? 'Posts this user authored.' : undefined,
+     * });
+     * ```
+     *
+     * The generated `<relation>Aggregate` companion fields are not covered — they are derived
+     * fields rather than the relation itself.
+     */
+    describeRelation?: RelationDescriber;
+    /**
+     * Supplies the GraphQL `deprecationReason` for a column, marking it `@deprecated` on the
+     * object type and on the create/update inputs.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   deprecateColumn: (_column, { columnName }) =>
+     *     columnName === 'legacyFlag' ? 'Use `status` instead.' : undefined,
+     * });
+     * ```
+     *
+     * A required input field cannot be deprecated — GraphQL rejects the schema, since a client
+     * has no way to stop sending it — so the reason is dropped on non-null input fields and
+     * kept everywhere else. Filter and orderBy fields are never deprecated either: filtering on
+     * a deprecated column is how a caller finds the rows that still use it.
+     */
+    deprecateColumn?: ColumnDeprecator;
+    /**
+     * Names the GraphQL enum types generated for enum columns.
+     *
+     * By default a column declared with a named `pgEnum` gets one shared type named after the
+     * enum (`pgEnum('status', …)` → `StatusEnum`), reused by every column declared with that
+     * same `pgEnum` — the database column is the same type, so a client variable typed
+     * `StatusEnum!` is passable to any of them. A column with an inline value list
+     * (`text({ enum: [...] })`, `mysqlEnum(...)`) keeps a per-column type named for its table
+     * and column (`UsersRoleTextEnum`), because its values are shared with nothing.
+     *
+     * This hook overrides the name either way — for lining the schema up with another schema it
+     * is stitched into, or for opting a specific column back into a type of its own:
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   enumNameMapper: (info) => (info.enumName === 'status' ? 'PublicationStatus' : undefined),
+     * });
+     * ```
+     *
+     * Two columns the mapper sends to the same name share one type when their values match —
+     * the way to unify inline enums declared separately that mean the same thing. Sending two
+     * *different* value lists to one name throws at build time rather than producing an
+     * invalid schema.
+     *
+     * Return `undefined` to keep the default name.
+     */
+    enumNameMapper?: EnumNameMapper;
 };
 
 /**
@@ -903,4 +1139,4 @@ declare const GraphQLDecimalString: GraphQLScalarType<string, string>;
 
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>>(db: TDbClient, config?: BuildSchemaConfig) => GeneratedData<TDbClient>;
 
-export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type DeleteResolver, type DeleteSingleResolver, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, GraphQLDecimalString, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationResolverFactory, type ScalarOverride, type ScalarOverridesConfig, type SchemaFeatures, type SelectResolver, type SelectSingleResolver, type TableNamedRelations, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, extractFilters, extractOrderBy, extractRelationJoinColumns };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type DeleteResolver, type DeleteSingleResolver, type EnumNameInfo, type EnumNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, GraphQLDecimalString, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaFeatures, type SelectResolver, type SelectSingleResolver, type TableDescriber, type TableNamedRelations, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, extractFilters, extractOrderBy, extractRelationJoinColumns };

package/dist/index.d.ts

@@ -40,6 +40,63 @@ type ColumnTypeMapperInfo = {
  * the built-in detection.
  */
 type ColumnTypeMapper = (column: Column, info: ColumnTypeMapperInfo) => ScalarOverride | undefined;
+/** Everything an {@link EnumNameMapper} needs to name — or opt a column out of — a generated enum type. */
+type EnumNameInfo = {
+    /**
+     * The name the enum type was declared with (`pgEnum('status', …)`), shared by every column
+     * that uses it. `undefined` for an inline value list (`text({ enum: [...] })`,
+     * `mysqlEnum(...)`), which belongs to the one column that declares it.
+     */
+    enumName: string | undefined;
+    /** The Postgres schema the named enum was declared in, when it declares one. */
+    schema: string | undefined;
+    /** The table's key in the Drizzle schema object. */
+    tableName: string;
+    /** The column's property name on the table object. */
+    columnName: string;
+    /** The enum's values, in declaration order. */
+    values: readonly string[];
+};
+/**
+ * Names a generated GraphQL enum type. Return `undefined` to keep the default name. See
+ * `BuildSchemaConfig.enumNameMapper`.
+ */
+type EnumNameMapper = (info: EnumNameInfo) => string | undefined;
+/** Context handed to the documentation and deprecation hooks alongside the column itself. */
+type ColumnDocInfo = {
+    /** The table's key in the Drizzle schema object. */
+    tableName: string;
+    /** The column's property name on the table object. */
+    columnName: string;
+};
+/**
+ * Supplies the GraphQL `description` for a generated column field. See
+ * `BuildSchemaConfig.describeColumn`.
+ */
+type ColumnDescriber = (column: Column, info: ColumnDocInfo) => string | undefined;
+/**
+ * Supplies the GraphQL `deprecationReason` for a generated column field. See
+ * `BuildSchemaConfig.deprecateColumn`.
+ */
+type ColumnDeprecator = (column: Column, info: ColumnDocInfo) => string | undefined;
+/** Supplies the GraphQL `description` for a table's object type. See `BuildSchemaConfig.describeTable`. */
+type TableDescriber = (tableName: string) => string | undefined;
+/**
+ * Supplies the GraphQL `description` for a relation field. See
+ * `BuildSchemaConfig.describeRelation`.
+ */
+type RelationDescriber = (tableName: string, relationName: string) => string | undefined;
+/**
+ * The documentation hooks a build was configured with, resolved once and threaded through
+ * type generation. Every member is optional; a build with no hooks generates fields with no
+ * descriptions at all.
+ */
+type SchemaDocs = {
+    describeColumn?: ColumnDescriber;
+    describeTable?: TableDescriber;
+    describeRelation?: RelationDescriber;
+    deprecateColumn?: ColumnDeprecator;
+};
 
 type TableNamedRelations = {
     relation: Relation;
@@ -175,8 +232,14 @@ declare const drizzleExecutorKey: unique symbol;
  *   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>, filterCtx?: RelationFilterBase) => RelationResolverFactory;
+declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, nullOrdering: NullOrdering, filterCtx?: RelationFilterBase) => RelationResolverFactory;
 /**
  * Compiles an `orderBy` argument into ORDER BY expressions, highest priority first.
  *
@@ -218,6 +281,14 @@ interface RelationFilterContext {
  */
 type RelationFilterBase = Pick<RelationFilterContext, 'tables' | 'relationMap'>;
 declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>, relationCtx?: RelationFilterContext) => SQL | undefined;
+/**
+ * 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).
+ * - `nulls-smallest` — MySQL and SQLite: NULLs sort as the smallest values (first in ASC, last
+ *   in DESC).
+ * 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
@@ -580,6 +651,83 @@ type SchemaFeatures = {
      * @default false
      */
     upsert?: boolean;
+    /**
+     * Relation fields on `Create<Table>Input` and `Update<Table>Input`, so a parent row and
+     * the rows it is related to can be written in one mutation. Off unless asked for: it adds
+     * a field per writable relation to every create and update input.
+     *
+     * ```graphql
+     * createPostsSingle(values: {
+     *   title: "Hello"
+     *   author: { connect: { id: { eq: "a1" } } }
+     *   tags: { create: [{ name: "drizzle" }] }
+     * }) { id }
+     * ```
+     *
+     * Each relation field offers `create` and `connect`; the update input adds `disconnect`
+     * and, for a to-many relation, `set` (replace the whole set). `disconnect` and `set` are
+     * generated only when the foreign key is nullable — there is no way to detach a row whose
+     * key is NOT NULL — and many-to-many (`.through()`) relations are not written through at
+     * all. Nesting is one level deep: the row a nested `create` inserts takes columns only.
+     *
+     * The whole tree runs in one transaction (a savepoint when the request already carries
+     * one), and a column a relation fills in (`authorId`, when `author: { create: … }` is
+     * offered) becomes nullable on the create input, since the relation is the other way to
+     * supply it.
+     *
+     * PostgreSQL and SQLite only. MySQL cannot return the rows it just wrote, which is how a
+     * nested write learns the parent's key, so `buildSchema` rejects the flag there. On SQLite
+     * the driver must be asynchronous (libsql, D1, …): a synchronous one commits before an
+     * awaited statement runs, so `buildSchema` rejects the combination outright.
+     *
+     * @default false
+     */
+    nestedWrites?: boolean;
+    /**
+     * Operation inputs on the update `set`, so a column can be changed relative to its current
+     * value instead of only replaced.
+     *
+     * ```graphql
+     * updatePostsSingle(where: { id: { eq: "p1" } }, set: { views: { increment: 1 } }) { views }
+     * ```
+     *
+     * Every numeric column's field on `Update<Table>Input` becomes a `<Scalar>FieldUpdate`
+     * input carrying `set`, `increment`, `decrement`, `multiply` and `divide`; every array
+     * column's becomes a `<Scalar>ListFieldUpdate` carrying `set` and `push`. Exactly one
+     * operation per field, checked at resolve time. `set` is the explicit spelling of what the
+     * field did before, so `set: { views: 42 }` becomes `set: { views: { set: 42 } }`.
+     *
+     * The arithmetic happens in the database (`SET views = views + 1`), so a counter no longer
+     * needs a read-modify-write round trip and no longer loses concurrent updates. Rounding on
+     * an integer column, and division by zero, follow the database's own rules rather than
+     * being guarded here. Columns owned by a scalar override keep their plain type — an
+     * override owns what the column accepts.
+     *
+     * Off by default: it changes the type of every numeric and array field on every update
+     * input, which no existing document is written against.
+     *
+     * @default false
+     */
+    fieldUpdateOperations?: boolean;
+    /**
+     * `update<Table>Count` / `delete<Table>Count` mutations — the same write as the plural
+     * `update<Table>` / `delete<Table>`, returning the number of rows affected instead of the
+     * rows themselves.
+     *
+     * ```graphql
+     * deletePostsCount(where: { published: { eq: false } })   # Int!
+     * ```
+     *
+     * A mass update or delete otherwise has to `RETURNING *` every row it touched purely so
+     * the caller can count them, which crosses the driver and is serialized through GraphQL
+     * for nothing. Each mutation is generated only when its plural counterpart is
+     * (`features.update` / `features.delete`), and honours `features.requireWhere`.
+     *
+     * Off unless asked for, so an existing schema does not grow new mutations on upgrade.
+     *
+     * @default false
+     */
+    countMutations?: boolean;
     /**
      * Makes `where` non-null on the plural `update<Table>` / `delete<Table>` mutations, and
      * rejects a `where` that collapses to no filters (e.g. `where: {}`), so a schema can rule
@@ -884,6 +1032,94 @@ type BuildSchemaConfig = {
      * ```
      */
     onError?: (error: unknown) => unknown;
+    /**
+     * Supplies the GraphQL `description` for a column, everywhere that column becomes a field:
+     * the object type, the create/update inputs, the filter input, and the aggregate
+     * `min`/`max`/`group` fields.
+     *
+     * Nothing is generated by default. The library used to emit the column's own type name
+     * ("DateTime", "JSON") as its description, which documented nothing a reader could not see
+     * from the type — that is gone, and this hook is what puts real prose in its place. Drizzle
+     * carries no column-comment metadata to read, so the text has to come from here.
+     *
+     * ```ts
+     * const columnDocs = { Users: { email: 'Primary contact address. Unique, case-insensitive.' } };
+     *
+     * buildSchema(db, {
+     *   describeColumn: (_column, { tableName, columnName }) => columnDocs[tableName]?.[columnName],
+     * });
+     * ```
+     *
+     * `tableName` and `columnName` are the Drizzle schema keys. Return `undefined` to leave the
+     * field undocumented.
+     */
+    describeColumn?: ColumnDescriber;
+    /**
+     * Supplies the GraphQL `description` for a table's object type.
+     *
+     * ```ts
+     * buildSchema(db, { describeTable: (tableName) => tableDocs[tableName] });
+     * ```
+     */
+    describeTable?: TableDescriber;
+    /**
+     * Supplies the GraphQL `description` for a relation field on a table's object type.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   describeRelation: (tableName, relationName) =>
+     *     tableName === 'Users' && relationName === 'posts' ? 'Posts this user authored.' : undefined,
+     * });
+     * ```
+     *
+     * The generated `<relation>Aggregate` companion fields are not covered — they are derived
+     * fields rather than the relation itself.
+     */
+    describeRelation?: RelationDescriber;
+    /**
+     * Supplies the GraphQL `deprecationReason` for a column, marking it `@deprecated` on the
+     * object type and on the create/update inputs.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   deprecateColumn: (_column, { columnName }) =>
+     *     columnName === 'legacyFlag' ? 'Use `status` instead.' : undefined,
+     * });
+     * ```
+     *
+     * A required input field cannot be deprecated — GraphQL rejects the schema, since a client
+     * has no way to stop sending it — so the reason is dropped on non-null input fields and
+     * kept everywhere else. Filter and orderBy fields are never deprecated either: filtering on
+     * a deprecated column is how a caller finds the rows that still use it.
+     */
+    deprecateColumn?: ColumnDeprecator;
+    /**
+     * Names the GraphQL enum types generated for enum columns.
+     *
+     * By default a column declared with a named `pgEnum` gets one shared type named after the
+     * enum (`pgEnum('status', …)` → `StatusEnum`), reused by every column declared with that
+     * same `pgEnum` — the database column is the same type, so a client variable typed
+     * `StatusEnum!` is passable to any of them. A column with an inline value list
+     * (`text({ enum: [...] })`, `mysqlEnum(...)`) keeps a per-column type named for its table
+     * and column (`UsersRoleTextEnum`), because its values are shared with nothing.
+     *
+     * This hook overrides the name either way — for lining the schema up with another schema it
+     * is stitched into, or for opting a specific column back into a type of its own:
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   enumNameMapper: (info) => (info.enumName === 'status' ? 'PublicationStatus' : undefined),
+     * });
+     * ```
+     *
+     * Two columns the mapper sends to the same name share one type when their values match —
+     * the way to unify inline enums declared separately that mean the same thing. Sending two
+     * *different* value lists to one name throws at build time rather than producing an
+     * invalid schema.
+     *
+     * Return `undefined` to keep the default name.
+     */
+    enumNameMapper?: EnumNameMapper;
 };
 
 /**
@@ -903,4 +1139,4 @@ declare const GraphQLDecimalString: GraphQLScalarType<string, string>;
 
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>>(db: TDbClient, config?: BuildSchemaConfig) => GeneratedData<TDbClient>;
 
-export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type DeleteResolver, type DeleteSingleResolver, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, GraphQLDecimalString, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationResolverFactory, type ScalarOverride, type ScalarOverridesConfig, type SchemaFeatures, type SelectResolver, type SelectSingleResolver, type TableNamedRelations, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, extractFilters, extractOrderBy, extractRelationJoinColumns };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type DeleteResolver, type DeleteSingleResolver, type EnumNameInfo, type EnumNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, GraphQLDecimalString, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaFeatures, type SelectResolver, type SelectSingleResolver, type TableDescriber, type TableNamedRelations, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, extractFilters, extractOrderBy, extractRelationJoinColumns };