@vantreeseba/drizzle-graphql 6.0.0 → 7.1.0

package/dist/index.d.cts

@@ -232,8 +232,25 @@ 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>, nullOrdering: NullOrdering, filterCtx?: RelationFilterBase, limits?: LimitPolicyFor) => RelationResolverFactory;
+/** {@link BuildSchemaConfig.limits} resolved for one table. `undefined` means no policy. */
+type ResolvedLimitPolicy = {
+    defaultLimit: number | undefined;
+    maxLimit: number | undefined;
+    clampToMax: boolean;
+};
+/**
+ * Looks up the limit policy for a table by its Drizzle schema key. Built once per schema by
+ * `buildSchema`; `undefined` for a table the caller left unbounded.
  */
-declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, filterCtx?: RelationFilterBase) => RelationResolverFactory;
+type LimitPolicyFor = (tableName: string) => ResolvedLimitPolicy | undefined;
 /**
  * Compiles an `orderBy` argument into ORDER BY expressions, highest priority first.
  *
@@ -275,6 +292,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
@@ -669,6 +694,51 @@ type SchemaFeatures = {
      * @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
@@ -701,6 +771,29 @@ type ComplexityConfig = {
      */
     aggregateCost?: number;
 };
+/**
+ * A limit policy: what a request without `limit` gets, and how large a `limit` may be.
+ * Every field is optional — an empty policy is the default unbounded behavior.
+ */
+type TableLimitPolicy = {
+    /** Applied when the client passes no `limit`. Capped by `maxLimit` when both are set. */
+    defaultLimit?: number;
+    /**
+     * The largest `limit` a client may ask for. Also bounds a request that passes no `limit` at
+     * all, since that means every row.
+     */
+    maxLimit?: number;
+    /**
+     * `false` (default) rejects a `limit` above `maxLimit` with a GraphQL error; `true` reduces
+     * it to `maxLimit` instead.
+     */
+    clampToMax?: boolean;
+};
+/** {@link BuildSchemaConfig.limits} — a global policy plus per-table overrides. */
+type LimitsConfig = TableLimitPolicy & {
+    /** Per-table overrides, keyed by the table's key in the Drizzle schema. */
+    tables?: Record<string, TableLimitPolicy>;
+};
 type BuildSchemaConfig = {
     /**
      * Determines whether generated mutations will be passed to returned schema.
@@ -852,6 +945,43 @@ type BuildSchemaConfig = {
         mode: 'auto';
         timeoutMs?: number;
     };
+    /**
+     * Bounds on the `limit` argument of list queries and to-many relation fields.
+     *
+     * Both knobs are off by default: without them a client can omit `limit` and pull a whole
+     * table, or pass `limit: 1000000` and do the same thing politely. Turning either on changes
+     * observable behavior for existing consumers, so nothing is applied unless asked for.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   limits: {
+     *     defaultLimit: 50,  // used when the client passes no `limit`
+     *     maxLimit: 500,     // anything above is rejected
+     *     tables: {
+     *       auditLog: { defaultLimit: 20, maxLimit: 100 },
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * - Applies to root list queries **and** to to-many relation fields — an unbounded relation
+     *   inside a bounded root is the same scan one level down. A relation field takes the policy
+     *   of the table it *targets*, so a table is bounded wherever it is reached from. Single-row
+     *   queries and aggregates take no `limit` and are unaffected.
+     * - A `limit` above `maxLimit` is rejected with a GraphQL error. Set `clampToMax: true` to
+     *   silently reduce it instead — honest paginating clients prefer the error, since a clamped
+     *   page looks like the end of the results.
+     * - `maxLimit` on its own also bounds the *omitted* case: no `limit` means every row, which
+     *   is above any maximum. `defaultLimit` is what a request without `limit` gets, capped by
+     *   `maxLimit` if both are set.
+     * - `tables` overrides per table, keyed by the Drizzle schema key. A table's entry replaces
+     *   the top-level value for whichever keys it sets.
+     * - Cursor pagination inherits the same policy — a keyset page needs a limit to be
+     *   meaningful, and `defaultLimit` is what makes `after`-only pagination well-formed.
+     * - The complexity hints price the *effective* limit, so cost estimation and enforcement
+     *   agree.
+     */
+    limits?: LimitsConfig;
     /**
      * 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,
@@ -1080,4 +1210,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 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 };
+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 LimitsConfig, 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 TableLimitPolicy, 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

@@ -232,8 +232,25 @@ 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>, nullOrdering: NullOrdering, filterCtx?: RelationFilterBase, limits?: LimitPolicyFor) => RelationResolverFactory;
+/** {@link BuildSchemaConfig.limits} resolved for one table. `undefined` means no policy. */
+type ResolvedLimitPolicy = {
+    defaultLimit: number | undefined;
+    maxLimit: number | undefined;
+    clampToMax: boolean;
+};
+/**
+ * Looks up the limit policy for a table by its Drizzle schema key. Built once per schema by
+ * `buildSchema`; `undefined` for a table the caller left unbounded.
  */
-declare const createRelationResolverFactory: (db: any, tables: Record<string, Table>, filterCtx?: RelationFilterBase) => RelationResolverFactory;
+type LimitPolicyFor = (tableName: string) => ResolvedLimitPolicy | undefined;
 /**
  * Compiles an `orderBy` argument into ORDER BY expressions, highest priority first.
  *
@@ -275,6 +292,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
@@ -669,6 +694,51 @@ type SchemaFeatures = {
      * @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
@@ -701,6 +771,29 @@ type ComplexityConfig = {
      */
     aggregateCost?: number;
 };
+/**
+ * A limit policy: what a request without `limit` gets, and how large a `limit` may be.
+ * Every field is optional — an empty policy is the default unbounded behavior.
+ */
+type TableLimitPolicy = {
+    /** Applied when the client passes no `limit`. Capped by `maxLimit` when both are set. */
+    defaultLimit?: number;
+    /**
+     * The largest `limit` a client may ask for. Also bounds a request that passes no `limit` at
+     * all, since that means every row.
+     */
+    maxLimit?: number;
+    /**
+     * `false` (default) rejects a `limit` above `maxLimit` with a GraphQL error; `true` reduces
+     * it to `maxLimit` instead.
+     */
+    clampToMax?: boolean;
+};
+/** {@link BuildSchemaConfig.limits} — a global policy plus per-table overrides. */
+type LimitsConfig = TableLimitPolicy & {
+    /** Per-table overrides, keyed by the table's key in the Drizzle schema. */
+    tables?: Record<string, TableLimitPolicy>;
+};
 type BuildSchemaConfig = {
     /**
      * Determines whether generated mutations will be passed to returned schema.
@@ -852,6 +945,43 @@ type BuildSchemaConfig = {
         mode: 'auto';
         timeoutMs?: number;
     };
+    /**
+     * Bounds on the `limit` argument of list queries and to-many relation fields.
+     *
+     * Both knobs are off by default: without them a client can omit `limit` and pull a whole
+     * table, or pass `limit: 1000000` and do the same thing politely. Turning either on changes
+     * observable behavior for existing consumers, so nothing is applied unless asked for.
+     *
+     * ```ts
+     * buildSchema(db, {
+     *   limits: {
+     *     defaultLimit: 50,  // used when the client passes no `limit`
+     *     maxLimit: 500,     // anything above is rejected
+     *     tables: {
+     *       auditLog: { defaultLimit: 20, maxLimit: 100 },
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * - Applies to root list queries **and** to to-many relation fields — an unbounded relation
+     *   inside a bounded root is the same scan one level down. A relation field takes the policy
+     *   of the table it *targets*, so a table is bounded wherever it is reached from. Single-row
+     *   queries and aggregates take no `limit` and are unaffected.
+     * - A `limit` above `maxLimit` is rejected with a GraphQL error. Set `clampToMax: true` to
+     *   silently reduce it instead — honest paginating clients prefer the error, since a clamped
+     *   page looks like the end of the results.
+     * - `maxLimit` on its own also bounds the *omitted* case: no `limit` means every row, which
+     *   is above any maximum. `defaultLimit` is what a request without `limit` gets, capped by
+     *   `maxLimit` if both are set.
+     * - `tables` overrides per table, keyed by the Drizzle schema key. A table's entry replaces
+     *   the top-level value for whichever keys it sets.
+     * - Cursor pagination inherits the same policy — a keyset page needs a limit to be
+     *   meaningful, and `defaultLimit` is what makes `after`-only pagination well-formed.
+     * - The complexity hints price the *effective* limit, so cost estimation and enforcement
+     *   agree.
+     */
+    limits?: LimitsConfig;
     /**
      * 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,
@@ -1080,4 +1210,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 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 };
+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 LimitsConfig, 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 TableLimitPolicy, 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 };