@vantreeseba/drizzle-graphql 5.6.0 → 6.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;
@@ -580,6 +637,38 @@ 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;
     /**
      * 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 +973,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 +1080,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;
@@ -580,6 +637,38 @@ 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;
     /**
      * 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 +973,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 +1080,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 };