@vantreeseba/drizzle-graphql 2.0.0 → 4.0.0

package/dist/index.d.cts

@@ -2,7 +2,8 @@ import { Table, Column, 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 } from 'graphql';
+import { GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLScalarType, GraphQLEnumType } from 'graphql';
+export { GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'graphql-scalars';
 
 type TableNamedRelations = {
     relation: Relation;
@@ -89,6 +90,23 @@ type RelationResolverFactory = (params: {
     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 } });
+ * });
+ * ```
+ *
+ * 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 drizzleExecutorKey: unique symbol;
 /**
  * Creates a RelationResolverFactory that generates field-level resolvers for each relation.
  * Each resolver:
@@ -97,9 +115,41 @@ type RelationResolverFactory = (params: {
  *   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.
  */
-declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>) => RelationResolverFactory;
+declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, filterCtx?: RelationFilterBase) => RelationResolverFactory;
 declare const extractOrderBy: <TTable extends Table, TArgs extends OrderByArgs<any> = OrderByArgs<TTable>>(table: TTable, orderArgs: TArgs) => SQL[];
-declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>) => SQL | undefined;
+/**
+ * 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
+ * relation keys can't appear in the input to begin with.
+ */
+interface RelationFilterContext {
+    /** Every table in the schema, keyed by its schema key. */
+    tables: Record<string, Table>;
+    /** Relations keyed by table schema key, then relation name. */
+    relationMap: Record<string, Record<string, TableNamedRelations>>;
+    /**
+     * Schema key of the table being filtered. Not always the same as the `tableName` label
+     * used in error messages (relation `where` callbacks pass the relation name there).
+     */
+    tableKey: string;
+    /** Shared counter making every subquery alias unique within one extraction. */
+    aliases?: {
+        n: number;
+    };
+}
+/**
+ * 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'>;
+declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>, relationCtx?: RelationFilterContext) => SQL | undefined;
+/**
+ * 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;
 
 type Relations<TTable extends string = string, TConfig extends Record<string, Relation> = Record<string, Relation>> = {
     table: {
@@ -144,6 +194,22 @@ type UpdateArgs<TTable extends Table> = Partial<{
     set: GetRemappedTableUpdateDataType<TTable>;
     where?: Filters<TTable>;
 }>;
+/**
+ * The `onConflict` argument of the generated upsert mutations.
+ *
+ * `target` and `where` exist on PostgreSQL and SQLite only: MySQL's
+ * `ON DUPLICATE KEY UPDATE` fires on whichever unique key was violated and takes no
+ * predicate, so neither field is generated there.
+ */
+type UpsertConflictArgs<TTable extends Table> = {
+    action?: 'UPDATE' | 'NOTHING';
+    target?: string[];
+    update?: string[];
+    where?: Filters<TTable>;
+};
+type UpsertArgs<TTable extends Table, isSingle extends boolean> = InsertArgs<TTable, isSingle> & {
+    onConflict?: UpsertConflictArgs<TTable>;
+};
 type DeleteArgs<TTable extends Table> = {
     where?: Filters<TTable>;
 };
@@ -153,9 +219,23 @@ type SelectResolver<TTable extends Table, TTables extends Record<string, Table>,
 type SelectSingleResolver<TTable extends Table, TTables extends Record<string, Table>, TRelations extends Record<string, Relation>> = (source: any, args: Partial<QueryArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<(keyof TRelations extends infer RelKey ? RelKey extends string ? GetRemappedTableDataType<TTable> & {
     [K in RelKey]: TRelations[K] extends One<string> ? GetRemappedTableDataType<ExtractTableByName<TTables, TRelations[K]['referencedTableName']> extends infer T ? T[keyof T] : never> | null : TRelations[K] extends Many<string> ? Array<GetRemappedTableDataType<ExtractTableByName<TTables, TRelations[K]['referencedTableName']> extends infer T ? T[keyof T] : never>> : never;
 } : GetRemappedTableDataType<TTable> : GetRemappedTableDataType<TTable>) | null>;
-type InsertResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, false>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? Array<GetRemappedTableDataType<TTable>> : MutationReturnlessResult>;
-type InsertArrResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `create<Table>Single`: one row in, one row (or `undefined`) out. */
+type InsertResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `create<Table>`: an array of rows in, an array of rows out. */
+type InsertArrResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, false>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? Array<GetRemappedTableDataType<TTable>> : MutationReturnlessResult>;
 type UpdateResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: UpdateArgs<TTable>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `upsert<Table>Single`. */
+type UpsertResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<UpsertArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `upsert<Table>`. */
+type UpsertArrResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<UpsertArgs<TTable, false>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? Array<GetRemappedTableDataType<TTable>> : MutationReturnlessResult>;
+/**
+ * Resolver for a table's generated aggregate query (`<plural>Aggregate`).
+ * Returns only the requested aggregations: `count` plus per-column `avg` / `sum`
+ * (numeric columns, as Float) and `min` / `max` (orderable columns, as the column's type).
+ */
+type AggregateResolver<TTable extends Table> = (source: any, args: {
+    where?: Filters<TTable>;
+}, context: any, info: GraphQLResolveInfo) => Promise<Record<string, any>>;
 type DeleteResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: DeleteArgs<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 ? {
@@ -173,6 +253,9 @@ type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations e
             where: {
                 type: TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never;
             };
+            distinct: {
+                type: GraphQLList<GraphQLNonNull<GraphQLEnumType>>;
+            };
         };
         resolve: SelectResolver<TSchemaTables[TName], TSchemaTables, ExtractTableRelations<TSchemaTables[TName], TSchemaRelations> extends infer R ? R[keyof R] : never>;
     } : never;
@@ -192,6 +275,16 @@ type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations e
         };
         resolve: SelectSingleResolver<TSchemaTables[TName], TSchemaTables, ExtractTableRelations<TSchemaTables[TName], TSchemaRelations> extends infer R ? R[keyof R] : never>;
     } : never;
+} & {
+    [TName in keyof TSchemaTables as TName extends string ? `${Uncapitalize<TName>}Aggregate` : never]: TName extends string ? {
+        type: GraphQLNonNull<TOutputs[`${Capitalize<TName>}Aggregate`] extends GraphQLObjectType ? TOutputs[`${Capitalize<TName>}Aggregate`] : GraphQLObjectType>;
+        args: {
+            where: {
+                type: TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never;
+            };
+        };
+        resolve: AggregateResolver<TSchemaTables[TName]>;
+    } : never;
 };
 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 ? {
@@ -213,6 +306,32 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
         };
         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`]>>>;
+        args: {
+            values: {
+                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>>>;
+            };
+            onConflict: {
+                type: GraphQLInputObjectType;
+            };
+        };
+        resolve: UpsertArrResolver<TSchemaTables[TName], IsReturnless>;
+    } : 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`];
+        args: {
+            values: {
+                type: GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>;
+            };
+            onConflict: {
+                type: GraphQLInputObjectType;
+            };
+        };
+        resolve: UpsertResolver<TSchemaTables[TName], IsReturnless>;
+    } : 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`]>>>;
@@ -248,6 +367,8 @@ type GeneratedInputs<TSchema extends Record<string, Table>> = {
 };
 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>}Aggregate` : never]: GraphQLObjectType;
 } & (IsReturnless extends true ? {
     MutationReturn: GraphQLObjectType;
 } : {
@@ -272,6 +393,32 @@ type GeneratedData<TDatabase extends AnyDrizzleDB<any>> = {
     schema: GraphQLSchema;
     entities: GeneratedEntities<TDatabase>;
 };
+/**
+ * Per-feature switches for what `buildSchema` generates. Every flag defaults to `true`.
+ * See {@link BuildSchemaConfig.features}.
+ */
+type SchemaFeatures = {
+    /** `<plural>Aggregate` root queries and the aggregate output types. @default true */
+    aggregates?: boolean;
+    /** `<relation>Aggregate` fields on object types, for to-many relations. @default true */
+    relationAggregates?: boolean;
+    /** The `distinct` argument on list queries. @default true */
+    distinct?: boolean;
+    /** `create<Table>` / `create<Table>Single` mutations. @default true */
+    insert?: boolean;
+    /** `update<Table>` mutations. @default true */
+    update?: boolean;
+    /** `delete<Table>` mutations. @default true */
+    delete?: boolean;
+    /**
+     * `upsert<Table>` / `upsert<Table>Single` mutations — insert, or update the row that
+     * already holds the same unique key. Off unless asked for, so an existing schema does
+     * not grow new mutations on upgrade.
+     *
+     * @default false
+     */
+    upsert?: boolean;
+};
 type BuildSchemaConfig = {
     /**
      * Determines whether generated mutations will be passed to returned schema.
@@ -304,7 +451,7 @@ type BuildSchemaConfig = {
     /**
      * Customizes query name prefixes for generated GraphQL operations.
      *
-     * @default { insert: 'create', delete: 'delete', update: 'update' }
+     * @default { insert: 'create', delete: 'delete', update: 'update', upsert: 'upsert' }
      */
     prefixes?: {
         /** Prefix for insert mutations (e.g., 'users' -> 'createUsers') */
@@ -313,6 +460,8 @@ type BuildSchemaConfig = {
         delete?: string;
         /** Prefix for update mutations (e.g., 'users' -> 'updateUsers') */
         update?: string;
+        /** Prefix for upsert mutations (e.g., 'users' -> 'upsertUsers') */
+        upsert?: string;
     };
     /**
      * Customizes query name suffixes for generated GraphQL operations.
@@ -328,8 +477,40 @@ type BuildSchemaConfig = {
     /**
      * When true, insert mutations will use onConflictDoNothing() to silently
      * ignore duplicate key violations. Defaults to false (conflicts throw errors).
+     *
+     * PostgreSQL and SQLite only — MySQL's insert builder has no equivalent, so the flag is
+     * ignored there and conflicts keep throwing.
+     *
+     * @deprecated Build-wide and unconditional: a request cannot opt out of it, and a
+     * swallowed insert returns `null` with no indication why. Turn on `features.upsert` and
+     * pass `onConflict: { action: NOTHING }` per request instead. This flag keeps working
+     * until the next major.
      */
     conflictDoNothing?: boolean;
+    /**
+     * Turns individual generated features off.
+     *
+     * Every flag defaults to `true` except `upsert`, which is opt-in: a build with no
+     * `features` block generates exactly what it generated before this option existed.
+     * Turning one off removes both the schema surface it adds and the work behind it.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   features: {
+     *     aggregates: false,         // no `<plural>Aggregate` root queries
+     *     relationAggregates: false, // no `<relation>Aggregate` fields on object types
+     *     distinct: false,           // no `distinct` argument on list queries
+     *     delete: false,             // no delete mutations
+     *     upsert: true,              // opt in to `upsert<Table>` mutations
+     *   },
+     * });
+     * ```
+     *
+     * Turning off every mutation feature omits the `Mutation` type entirely, exactly as
+     * `mutations: false` does. Query-side features can all be off — the list and single
+     * queries are always generated, so `Query` is never empty.
+     */
+    features?: SchemaFeatures;
     /**
      * 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,
@@ -377,8 +558,40 @@ type BuildSchemaConfig = {
      * @default true
      */
     eagerLoadRelations?: boolean | ((tableName: string, relationName: string) => boolean);
+    /**
+     * Called for every error thrown by a generated resolver, before it reaches the client.
+     *
+     * Return an error to surface that one instead. Return nothing to fall through to the
+     * default handling, which makes this a pure logging hook:
+     *
+     * ```ts
+     * buildSchema(db, { onError: (error) => { logger.error(error) } })
+     * ```
+     *
+     * The default passes through errors drizzle-graphql raises itself (bad filter, missing
+     * values, invalid date, …) and replaces everything else — driver and database errors —
+     * with a generic `Internal server error`, keeping the original on `originalError` so it
+     * is still available to server-side logging. Database messages routinely name tables,
+     * columns, constraints and the values that violated them, which is not something a
+     * public API should hand back.
+     *
+     * To surface raw database errors instead (useful in development):
+     *
+     * ```ts
+     * buildSchema(db, { onError: (error) => error as Error })
+     * ```
+     */
+    onError?: (error: unknown) => unknown;
 };
 
+/**
+ * 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
+ * `GraphQLBigInt` is deliberately not used: it emits numbers for safe integers and strings
+ * for everything else, so a client cannot know which it will get.
+ */
+declare const GraphQLBigIntString: GraphQLScalarType<string, string>;
+
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>>(db: TDbClient, config?: BuildSchemaConfig) => GeneratedData<TDbClient>;
 
-export { type AnyDrizzleDB, type BuildSchemaConfig, type DeleteResolver, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationResolverFactory, type SelectResolver, type SelectSingleResolver, type TableNamedRelations, type UpdateResolver, buildSchema, createRelationResolverFactory, extractFilters, extractOrderBy, extractRelationJoinColumns };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type DeleteResolver, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationResolverFactory, type SchemaFeatures, type SelectResolver, type SelectSingleResolver, type TableNamedRelations, type UpdateResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, extractFilters, extractOrderBy, extractRelationJoinColumns };

package/dist/index.d.ts

@@ -2,7 +2,8 @@ import { Table, Column, 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 } from 'graphql';
+import { GraphQLFieldResolver, GraphQLResolveInfo, GraphQLSchema, GraphQLInputObjectType, GraphQLObjectType, GraphQLNonNull, GraphQLList, GraphQLScalarType, GraphQLEnumType } from 'graphql';
+export { GraphQLDate, GraphQLDateTime, GraphQLJSON, GraphQLUUID } from 'graphql-scalars';
 
 type TableNamedRelations = {
     relation: Relation;
@@ -89,6 +90,23 @@ type RelationResolverFactory = (params: {
     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 } });
+ * });
+ * ```
+ *
+ * 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 drizzleExecutorKey: unique symbol;
 /**
  * Creates a RelationResolverFactory that generates field-level resolvers for each relation.
  * Each resolver:
@@ -97,9 +115,41 @@ type RelationResolverFactory = (params: {
  *   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.
  */
-declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>) => RelationResolverFactory;
+declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, filterCtx?: RelationFilterBase) => RelationResolverFactory;
 declare const extractOrderBy: <TTable extends Table, TArgs extends OrderByArgs<any> = OrderByArgs<TTable>>(table: TTable, orderArgs: TArgs) => SQL[];
-declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>) => SQL | undefined;
+/**
+ * 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
+ * relation keys can't appear in the input to begin with.
+ */
+interface RelationFilterContext {
+    /** Every table in the schema, keyed by its schema key. */
+    tables: Record<string, Table>;
+    /** Relations keyed by table schema key, then relation name. */
+    relationMap: Record<string, Record<string, TableNamedRelations>>;
+    /**
+     * Schema key of the table being filtered. Not always the same as the `tableName` label
+     * used in error messages (relation `where` callbacks pass the relation name there).
+     */
+    tableKey: string;
+    /** Shared counter making every subquery alias unique within one extraction. */
+    aliases?: {
+        n: number;
+    };
+}
+/**
+ * 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'>;
+declare const extractFilters: <TTable extends Table>(table: TTable, tableName: string, filters: Filters<TTable>, relationCtx?: RelationFilterContext) => SQL | undefined;
+/**
+ * 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;
 
 type Relations<TTable extends string = string, TConfig extends Record<string, Relation> = Record<string, Relation>> = {
     table: {
@@ -144,6 +194,22 @@ type UpdateArgs<TTable extends Table> = Partial<{
     set: GetRemappedTableUpdateDataType<TTable>;
     where?: Filters<TTable>;
 }>;
+/**
+ * The `onConflict` argument of the generated upsert mutations.
+ *
+ * `target` and `where` exist on PostgreSQL and SQLite only: MySQL's
+ * `ON DUPLICATE KEY UPDATE` fires on whichever unique key was violated and takes no
+ * predicate, so neither field is generated there.
+ */
+type UpsertConflictArgs<TTable extends Table> = {
+    action?: 'UPDATE' | 'NOTHING';
+    target?: string[];
+    update?: string[];
+    where?: Filters<TTable>;
+};
+type UpsertArgs<TTable extends Table, isSingle extends boolean> = InsertArgs<TTable, isSingle> & {
+    onConflict?: UpsertConflictArgs<TTable>;
+};
 type DeleteArgs<TTable extends Table> = {
     where?: Filters<TTable>;
 };
@@ -153,9 +219,23 @@ type SelectResolver<TTable extends Table, TTables extends Record<string, Table>,
 type SelectSingleResolver<TTable extends Table, TTables extends Record<string, Table>, TRelations extends Record<string, Relation>> = (source: any, args: Partial<QueryArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<(keyof TRelations extends infer RelKey ? RelKey extends string ? GetRemappedTableDataType<TTable> & {
     [K in RelKey]: TRelations[K] extends One<string> ? GetRemappedTableDataType<ExtractTableByName<TTables, TRelations[K]['referencedTableName']> extends infer T ? T[keyof T] : never> | null : TRelations[K] extends Many<string> ? Array<GetRemappedTableDataType<ExtractTableByName<TTables, TRelations[K]['referencedTableName']> extends infer T ? T[keyof T] : never>> : never;
 } : GetRemappedTableDataType<TTable> : GetRemappedTableDataType<TTable>) | null>;
-type InsertResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, false>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? Array<GetRemappedTableDataType<TTable>> : MutationReturnlessResult>;
-type InsertArrResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `create<Table>Single`: one row in, one row (or `undefined`) out. */
+type InsertResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `create<Table>`: an array of rows in, an array of rows out. */
+type InsertArrResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<InsertArgs<TTable, false>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? Array<GetRemappedTableDataType<TTable>> : MutationReturnlessResult>;
 type UpdateResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: UpdateArgs<TTable>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `upsert<Table>Single`. */
+type UpsertResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<UpsertArgs<TTable, true>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? GetRemappedTableDataType<TTable> | undefined : MutationReturnlessResult>;
+/** Resolver for `upsert<Table>`. */
+type UpsertArrResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: Partial<UpsertArgs<TTable, false>>, context: any, info: GraphQLResolveInfo) => Promise<IsReturnless extends false ? Array<GetRemappedTableDataType<TTable>> : MutationReturnlessResult>;
+/**
+ * Resolver for a table's generated aggregate query (`<plural>Aggregate`).
+ * Returns only the requested aggregations: `count` plus per-column `avg` / `sum`
+ * (numeric columns, as Float) and `min` / `max` (orderable columns, as the column's type).
+ */
+type AggregateResolver<TTable extends Table> = (source: any, args: {
+    where?: Filters<TTable>;
+}, context: any, info: GraphQLResolveInfo) => Promise<Record<string, any>>;
 type DeleteResolver<TTable extends Table, IsReturnless extends boolean> = (source: any, args: DeleteArgs<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 ? {
@@ -173,6 +253,9 @@ type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations e
             where: {
                 type: TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never;
             };
+            distinct: {
+                type: GraphQLList<GraphQLNonNull<GraphQLEnumType>>;
+            };
         };
         resolve: SelectResolver<TSchemaTables[TName], TSchemaTables, ExtractTableRelations<TSchemaTables[TName], TSchemaRelations> extends infer R ? R[keyof R] : never>;
     } : never;
@@ -192,6 +275,16 @@ type QueriesCore<TSchemaTables extends Record<string, Table>, TSchemaRelations e
         };
         resolve: SelectSingleResolver<TSchemaTables[TName], TSchemaTables, ExtractTableRelations<TSchemaTables[TName], TSchemaRelations> extends infer R ? R[keyof R] : never>;
     } : never;
+} & {
+    [TName in keyof TSchemaTables as TName extends string ? `${Uncapitalize<TName>}Aggregate` : never]: TName extends string ? {
+        type: GraphQLNonNull<TOutputs[`${Capitalize<TName>}Aggregate`] extends GraphQLObjectType ? TOutputs[`${Capitalize<TName>}Aggregate`] : GraphQLObjectType>;
+        args: {
+            where: {
+                type: TInputs[`${Capitalize<TName>}Filters`] extends GraphQLInputObjectType ? TInputs[`${Capitalize<TName>}Filters`] : never;
+            };
+        };
+        resolve: AggregateResolver<TSchemaTables[TName]>;
+    } : never;
 };
 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 ? {
@@ -213,6 +306,32 @@ type MutationsCore<TSchemaTables extends Record<string, Table>, TInputs extends
         };
         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`]>>>;
+        args: {
+            values: {
+                type: GraphQLNonNull<GraphQLList<GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>>>;
+            };
+            onConflict: {
+                type: GraphQLInputObjectType;
+            };
+        };
+        resolve: UpsertArrResolver<TSchemaTables[TName], IsReturnless>;
+    } : 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`];
+        args: {
+            values: {
+                type: GraphQLNonNull<TInputs[`${Capitalize<TName>}InsertInput`]>;
+            };
+            onConflict: {
+                type: GraphQLInputObjectType;
+            };
+        };
+        resolve: UpsertResolver<TSchemaTables[TName], IsReturnless>;
+    } : 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`]>>>;
@@ -248,6 +367,8 @@ type GeneratedInputs<TSchema extends Record<string, Table>> = {
 };
 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>}Aggregate` : never]: GraphQLObjectType;
 } & (IsReturnless extends true ? {
     MutationReturn: GraphQLObjectType;
 } : {
@@ -272,6 +393,32 @@ type GeneratedData<TDatabase extends AnyDrizzleDB<any>> = {
     schema: GraphQLSchema;
     entities: GeneratedEntities<TDatabase>;
 };
+/**
+ * Per-feature switches for what `buildSchema` generates. Every flag defaults to `true`.
+ * See {@link BuildSchemaConfig.features}.
+ */
+type SchemaFeatures = {
+    /** `<plural>Aggregate` root queries and the aggregate output types. @default true */
+    aggregates?: boolean;
+    /** `<relation>Aggregate` fields on object types, for to-many relations. @default true */
+    relationAggregates?: boolean;
+    /** The `distinct` argument on list queries. @default true */
+    distinct?: boolean;
+    /** `create<Table>` / `create<Table>Single` mutations. @default true */
+    insert?: boolean;
+    /** `update<Table>` mutations. @default true */
+    update?: boolean;
+    /** `delete<Table>` mutations. @default true */
+    delete?: boolean;
+    /**
+     * `upsert<Table>` / `upsert<Table>Single` mutations — insert, or update the row that
+     * already holds the same unique key. Off unless asked for, so an existing schema does
+     * not grow new mutations on upgrade.
+     *
+     * @default false
+     */
+    upsert?: boolean;
+};
 type BuildSchemaConfig = {
     /**
      * Determines whether generated mutations will be passed to returned schema.
@@ -304,7 +451,7 @@ type BuildSchemaConfig = {
     /**
      * Customizes query name prefixes for generated GraphQL operations.
      *
-     * @default { insert: 'create', delete: 'delete', update: 'update' }
+     * @default { insert: 'create', delete: 'delete', update: 'update', upsert: 'upsert' }
      */
     prefixes?: {
         /** Prefix for insert mutations (e.g., 'users' -> 'createUsers') */
@@ -313,6 +460,8 @@ type BuildSchemaConfig = {
         delete?: string;
         /** Prefix for update mutations (e.g., 'users' -> 'updateUsers') */
         update?: string;
+        /** Prefix for upsert mutations (e.g., 'users' -> 'upsertUsers') */
+        upsert?: string;
     };
     /**
      * Customizes query name suffixes for generated GraphQL operations.
@@ -328,8 +477,40 @@ type BuildSchemaConfig = {
     /**
      * When true, insert mutations will use onConflictDoNothing() to silently
      * ignore duplicate key violations. Defaults to false (conflicts throw errors).
+     *
+     * PostgreSQL and SQLite only — MySQL's insert builder has no equivalent, so the flag is
+     * ignored there and conflicts keep throwing.
+     *
+     * @deprecated Build-wide and unconditional: a request cannot opt out of it, and a
+     * swallowed insert returns `null` with no indication why. Turn on `features.upsert` and
+     * pass `onConflict: { action: NOTHING }` per request instead. This flag keeps working
+     * until the next major.
      */
     conflictDoNothing?: boolean;
+    /**
+     * Turns individual generated features off.
+     *
+     * Every flag defaults to `true` except `upsert`, which is opt-in: a build with no
+     * `features` block generates exactly what it generated before this option existed.
+     * Turning one off removes both the schema surface it adds and the work behind it.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   features: {
+     *     aggregates: false,         // no `<plural>Aggregate` root queries
+     *     relationAggregates: false, // no `<relation>Aggregate` fields on object types
+     *     distinct: false,           // no `distinct` argument on list queries
+     *     delete: false,             // no delete mutations
+     *     upsert: true,              // opt in to `upsert<Table>` mutations
+     *   },
+     * });
+     * ```
+     *
+     * Turning off every mutation feature omits the `Mutation` type entirely, exactly as
+     * `mutations: false` does. Query-side features can all be off — the list and single
+     * queries are always generated, so `Query` is never empty.
+     */
+    features?: SchemaFeatures;
     /**
      * 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,
@@ -377,8 +558,40 @@ type BuildSchemaConfig = {
      * @default true
      */
     eagerLoadRelations?: boolean | ((tableName: string, relationName: string) => boolean);
+    /**
+     * Called for every error thrown by a generated resolver, before it reaches the client.
+     *
+     * Return an error to surface that one instead. Return nothing to fall through to the
+     * default handling, which makes this a pure logging hook:
+     *
+     * ```ts
+     * buildSchema(db, { onError: (error) => { logger.error(error) } })
+     * ```
+     *
+     * The default passes through errors drizzle-graphql raises itself (bad filter, missing
+     * values, invalid date, …) and replaces everything else — driver and database errors —
+     * with a generic `Internal server error`, keeping the original on `originalError` so it
+     * is still available to server-side logging. Database messages routinely name tables,
+     * columns, constraints and the values that violated them, which is not something a
+     * public API should hand back.
+     *
+     * To surface raw database errors instead (useful in development):
+     *
+     * ```ts
+     * buildSchema(db, { onError: (error) => error as Error })
+     * ```
+     */
+    onError?: (error: unknown) => unknown;
 };
 
+/**
+ * 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
+ * `GraphQLBigInt` is deliberately not used: it emits numbers for safe integers and strings
+ * for everything else, so a client cannot know which it will get.
+ */
+declare const GraphQLBigIntString: GraphQLScalarType<string, string>;
+
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>>(db: TDbClient, config?: BuildSchemaConfig) => GeneratedData<TDbClient>;
 
-export { type AnyDrizzleDB, type BuildSchemaConfig, type DeleteResolver, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationResolverFactory, type SelectResolver, type SelectSingleResolver, type TableNamedRelations, type UpdateResolver, buildSchema, createRelationResolverFactory, extractFilters, extractOrderBy, extractRelationJoinColumns };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type DeleteResolver, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, GraphQLBigIntString, type InsertArrResolver, type InsertResolver, type MutationReturnlessResult, type MutationsCore, type QueriesCore, type RelationResolverFactory, type SchemaFeatures, type SelectResolver, type SelectSingleResolver, type TableNamedRelations, type UpdateResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleExecutorKey, extractFilters, extractOrderBy, extractRelationJoinColumns };