@vantreeseba/drizzle-graphql 5.4.0 → 5.6.0

package/dist/index.d.cts

@@ -1,10 +1,46 @@
-import { Table, Column, Relation, SQL, One, Many } from 'drizzle-orm';
+import { Column, Table, Relation, SQL, 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 { GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLScalarType, GraphQLEnumType } from 'graphql';
+import { GraphQLScalarType, GraphQLOutputType, GraphQLInputType, GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLEnumType } from 'graphql';
 export { GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'graphql-scalars';
 
+/**
+ * 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)
+ * use different scalars — or override only one side, leaving the other on built-in detection.
+ */
+type ScalarOverride = GraphQLScalarType | {
+    output?: GraphQLScalarType;
+    input?: GraphQLScalarType;
+};
+/**
+ * Declarative per-table, per-column scalar overrides. Keys are the Drizzle schema keys —
+ * the table's key in the schema object and the column's property name (not the SQL names).
+ */
+type ScalarOverridesConfig = Record<string, Record<string, ScalarOverride>>;
+/** Context handed to {@link ColumnTypeMapper} alongside the column itself. */
+type ColumnTypeMapperInfo = {
+    /** The table's key in the Drizzle schema object. */
+    tableName: string;
+    /** The column's property name on the table object. */
+    columnName: string;
+    /**
+     * The GraphQL type built-in detection would use for output positions (without nullability
+     * wrapping). `undefined` when detection has no mapping for the column's data type — the
+     * mapper is then the only way to give the column a type.
+     */
+    defaultType: GraphQLOutputType | undefined;
+    /** The input-position counterpart of `defaultType`. */
+    defaultInputType: GraphQLInputType | undefined;
+};
+/**
+ * Rule-based scalar mapping, called once per column at build time. Return a scalar (or
+ * `{ output, input }` pair) to override the column's GraphQL type, or `undefined` to keep
+ * the built-in detection.
+ */
+type ColumnTypeMapper = (column: Column, info: ColumnTypeMapperInfo) => ScalarOverride | undefined;
+
 type TableNamedRelations = {
     relation: Relation;
     targetTableName: string;
@@ -693,6 +729,40 @@ type BuildSchemaConfig = {
      * queries are always generated, so `Query` is never empty.
      */
     features?: SchemaFeatures;
+    /**
+     * Automatic transactions for GraphQL documents that fire more than one mutation.
+     *
+     * `'none'` (default) — every root mutation field runs on its own connection, so a failure
+     * mid-document leaves the earlier mutations committed (today's behavior).
+     *
+     * `'auto'` — when a request's document selects more than one root mutation field, the
+     * library opens `db.transaction()` once for the whole request and runs every mutation
+     * field (and the reads nested under them) inside it. The transaction commits when the
+     * last mutation field completes and rolls back when any of them fails; mutation fields
+     * after a failure are not executed against the rolled-back transaction — they fail fast.
+     * The object form additionally sets the safety timeout (default 30000ms) after which an
+     * abandoned transaction — e.g. the host server stopped calling resolvers because of a
+     * non-null completion error — is rolled back instead of leaking a connection.
+     *
+     * Never nests: a caller-supplied executor on the GraphQL context under
+     * `drizzleExecutorKey` always wins, and the library opens nothing of its own.
+     *
+     * Requirements and caveats:
+     * - The driver must support `db.transaction()` (e.g. `neon-http` does not). For SQLite
+     *   only asynchronous drivers (libsql, better-sqlite3 is synchronous) can hold a
+     *   transaction open across resolvers; `buildSchema` throws for synchronous ones.
+     * - The GraphQL context value must be a fresh object per request (every mainstream
+     *   server does this) — it keys the per-request transaction state.
+     * - Documents that mix in mutation fields not generated by this build (consumer
+     *   extensions) are left alone: their completion cannot be tracked, so no transaction
+     *   is opened.
+     *
+     * @default 'none'
+     */
+    transactions?: 'auto' | 'none' | {
+        mode: 'auto';
+        timeoutMs?: number;
+    };
     /**
      * Optional mapper from table key to singular/plural name pair.
      * When provided for a table, overrides the default (table key) naming for GraphQL type names,
@@ -740,6 +810,56 @@ type BuildSchemaConfig = {
      * @default true
      */
     eagerLoadRelations?: boolean | ((tableName: string, relationName: string) => boolean);
+    /**
+     * Declarative per-table, per-column scalar overrides — replaces the GraphQL type built-in
+     * detection would pick for a column with the scalar you provide, everywhere that column's
+     * type surfaces: the object type, create/update inputs, filter operands (in a filter type
+     * named `${Scalar}Filter`), and aggregate min/max fields.
+     *
+     * Keys are the Drizzle schema keys: the table's key in your schema object and the column's
+     * property name. The value is either one scalar for both directions, or `{ output, input }`
+     * to type outputs and inputs differently (either side may be omitted to keep the default).
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   scalars: {
+     *     users: {
+     *       balance: GraphQLBigIntString,                      // both directions
+     *       settings: { output: PrettyJSON },                  // output only, input stays default
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * Validation and coercion become the scalar's job: for an overridden column the generated
+     * resolvers pass values through untouched — `parseValue`/`parseLiteral` results go to the
+     * database driver as-is, and raw driver values go to `serialize` as-is — so the scalar must
+     * accept what the driver produces and produce what the driver accepts.
+     *
+     * A declarative entry fully decides its column and wins over {@link mapColumnType}.
+     */
+    scalars?: ScalarOverridesConfig;
+    /**
+     * Rule-based scalar mapping, called once per column at build time — the tool for applying
+     * a convention across many columns (e.g. "every `numeric` column is `Money`") or for typing
+     * custom column types the built-in detection does not know.
+     *
+     * Return a scalar (or `{ output, input }` pair) to override the column, or `undefined` to
+     * keep the default. `info` carries the table/column schema keys and the types built-in
+     * detection would use (`defaultType` / `defaultInputType`), so rules can key off either the
+     * Drizzle column or the default GraphQL type.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   mapColumnType: (column, { columnName }) =>
+     *     column.columnType === 'PgNumeric' ? MoneyScalar : undefined,
+     * });
+     * ```
+     *
+     * Same semantics as {@link scalars} otherwise; a column matched by both is decided by
+     * `scalars` alone.
+     */
+    mapColumnType?: ColumnTypeMapper;
     /**
      * Called for every error thrown by a generated resolver, before it reaches the client.
      *
@@ -783,4 +903,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 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 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 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 };

package/dist/index.d.ts

@@ -1,10 +1,46 @@
-import { Table, Column, Relation, SQL, One, Many } from 'drizzle-orm';
+import { Column, Table, Relation, SQL, 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 { GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLScalarType, GraphQLEnumType } from 'graphql';
+import { GraphQLScalarType, GraphQLOutputType, GraphQLInputType, GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLEnumType } from 'graphql';
 export { GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'graphql-scalars';
 
+/**
+ * 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)
+ * use different scalars — or override only one side, leaving the other on built-in detection.
+ */
+type ScalarOverride = GraphQLScalarType | {
+    output?: GraphQLScalarType;
+    input?: GraphQLScalarType;
+};
+/**
+ * Declarative per-table, per-column scalar overrides. Keys are the Drizzle schema keys —
+ * the table's key in the schema object and the column's property name (not the SQL names).
+ */
+type ScalarOverridesConfig = Record<string, Record<string, ScalarOverride>>;
+/** Context handed to {@link ColumnTypeMapper} alongside the column itself. */
+type ColumnTypeMapperInfo = {
+    /** The table's key in the Drizzle schema object. */
+    tableName: string;
+    /** The column's property name on the table object. */
+    columnName: string;
+    /**
+     * The GraphQL type built-in detection would use for output positions (without nullability
+     * wrapping). `undefined` when detection has no mapping for the column's data type — the
+     * mapper is then the only way to give the column a type.
+     */
+    defaultType: GraphQLOutputType | undefined;
+    /** The input-position counterpart of `defaultType`. */
+    defaultInputType: GraphQLInputType | undefined;
+};
+/**
+ * Rule-based scalar mapping, called once per column at build time. Return a scalar (or
+ * `{ output, input }` pair) to override the column's GraphQL type, or `undefined` to keep
+ * the built-in detection.
+ */
+type ColumnTypeMapper = (column: Column, info: ColumnTypeMapperInfo) => ScalarOverride | undefined;
+
 type TableNamedRelations = {
     relation: Relation;
     targetTableName: string;
@@ -693,6 +729,40 @@ type BuildSchemaConfig = {
      * queries are always generated, so `Query` is never empty.
      */
     features?: SchemaFeatures;
+    /**
+     * Automatic transactions for GraphQL documents that fire more than one mutation.
+     *
+     * `'none'` (default) — every root mutation field runs on its own connection, so a failure
+     * mid-document leaves the earlier mutations committed (today's behavior).
+     *
+     * `'auto'` — when a request's document selects more than one root mutation field, the
+     * library opens `db.transaction()` once for the whole request and runs every mutation
+     * field (and the reads nested under them) inside it. The transaction commits when the
+     * last mutation field completes and rolls back when any of them fails; mutation fields
+     * after a failure are not executed against the rolled-back transaction — they fail fast.
+     * The object form additionally sets the safety timeout (default 30000ms) after which an
+     * abandoned transaction — e.g. the host server stopped calling resolvers because of a
+     * non-null completion error — is rolled back instead of leaking a connection.
+     *
+     * Never nests: a caller-supplied executor on the GraphQL context under
+     * `drizzleExecutorKey` always wins, and the library opens nothing of its own.
+     *
+     * Requirements and caveats:
+     * - The driver must support `db.transaction()` (e.g. `neon-http` does not). For SQLite
+     *   only asynchronous drivers (libsql, better-sqlite3 is synchronous) can hold a
+     *   transaction open across resolvers; `buildSchema` throws for synchronous ones.
+     * - The GraphQL context value must be a fresh object per request (every mainstream
+     *   server does this) — it keys the per-request transaction state.
+     * - Documents that mix in mutation fields not generated by this build (consumer
+     *   extensions) are left alone: their completion cannot be tracked, so no transaction
+     *   is opened.
+     *
+     * @default 'none'
+     */
+    transactions?: 'auto' | 'none' | {
+        mode: 'auto';
+        timeoutMs?: number;
+    };
     /**
      * Optional mapper from table key to singular/plural name pair.
      * When provided for a table, overrides the default (table key) naming for GraphQL type names,
@@ -740,6 +810,56 @@ type BuildSchemaConfig = {
      * @default true
      */
     eagerLoadRelations?: boolean | ((tableName: string, relationName: string) => boolean);
+    /**
+     * Declarative per-table, per-column scalar overrides — replaces the GraphQL type built-in
+     * detection would pick for a column with the scalar you provide, everywhere that column's
+     * type surfaces: the object type, create/update inputs, filter operands (in a filter type
+     * named `${Scalar}Filter`), and aggregate min/max fields.
+     *
+     * Keys are the Drizzle schema keys: the table's key in your schema object and the column's
+     * property name. The value is either one scalar for both directions, or `{ output, input }`
+     * to type outputs and inputs differently (either side may be omitted to keep the default).
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   scalars: {
+     *     users: {
+     *       balance: GraphQLBigIntString,                      // both directions
+     *       settings: { output: PrettyJSON },                  // output only, input stays default
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * Validation and coercion become the scalar's job: for an overridden column the generated
+     * resolvers pass values through untouched — `parseValue`/`parseLiteral` results go to the
+     * database driver as-is, and raw driver values go to `serialize` as-is — so the scalar must
+     * accept what the driver produces and produce what the driver accepts.
+     *
+     * A declarative entry fully decides its column and wins over {@link mapColumnType}.
+     */
+    scalars?: ScalarOverridesConfig;
+    /**
+     * Rule-based scalar mapping, called once per column at build time — the tool for applying
+     * a convention across many columns (e.g. "every `numeric` column is `Money`") or for typing
+     * custom column types the built-in detection does not know.
+     *
+     * Return a scalar (or `{ output, input }` pair) to override the column, or `undefined` to
+     * keep the default. `info` carries the table/column schema keys and the types built-in
+     * detection would use (`defaultType` / `defaultInputType`), so rules can key off either the
+     * Drizzle column or the default GraphQL type.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   mapColumnType: (column, { columnName }) =>
+     *     column.columnType === 'PgNumeric' ? MoneyScalar : undefined,
+     * });
+     * ```
+     *
+     * Same semantics as {@link scalars} otherwise; a column matched by both is decided by
+     * `scalars` alone.
+     */
+    mapColumnType?: ColumnTypeMapper;
     /**
      * Called for every error thrown by a generated resolver, before it reaches the client.
      *
@@ -783,4 +903,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 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 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 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 };