@vantreeseba/drizzle-graphql 13.1.1 → 14.0.0

package/dist/index.d.cts

@@ -811,17 +811,50 @@ declare const extractFilters: <TTable extends Table>(table: TTable, tableName: s
 //#region src/util/builders/common/write-hooks.d.ts
 /** The write a hook is attached to. `restore` only exists for a soft-deleting table. */
 type WriteOperation = 'insert' | 'update' | 'updateMany' | 'upsert' | 'delete' | 'restore';
+/** Which input of a relation field a nested write came from. */
+type NestedWriteOp = 'create' | 'connect' | 'disconnect' | 'set';
+/**
+ * Where a nested write came from: set on the payload of a hook that fires for a row a nested
+ * `create` / `connect` / `disconnect` / `set` wrote, and absent at the mutation field's own
+ * table. See {@link WriteHookPayload.nested}.
+ */
+type NestedWriteOrigin = {
+  /** Drizzle schema key of the table whose input carried the relation field. */
+  parentTable: string;
+  /** The relation field the write went through, as named on the parent table. */
+  relation: string;
+  /** The relation field's input that produced this statement. */
+  op: NestedWriteOp;
+};
 /** What a write hook is handed. See {@link BuildSchemaConfig.onWrite}. */
 type WriteHookPayload = {
   /** Drizzle schema key of the table being written. */
   table: string;
+  /**
+   * What happened to `table`. A nested write reports what its statement did to *that* table:
+   * `insert` for a nested `create`, `update` for a `connect` / `disconnect` / `set` that
+   * changes the foreign key on the target, and `insert` / `delete` on the junction table for
+   * a many-to-many link / unlink.
+   */
   operation: WriteOperation;
   /** `'before'` runs ahead of the statement, `'after'` once it has returned. */
   position: 'before' | 'after';
-  /** Whether the field writes a single row (`createUsersSingle`) or a list. */
+  /**
+   * Whether the field writes a single row (`createUsersSingle`) or a list. For a nested
+   * write, whether the relation it went through is a to-one.
+   */
   single: boolean;
-  /** The field's GraphQL arguments, exactly as the resolver received them. */
+  /**
+   * The field's GraphQL arguments, exactly as the resolver received them — for a nested
+   * write, the arguments of the root mutation field it is part of.
+   */
   args: any;
+  /**
+   * Set when the rows were written by a nested write under another table's mutation, and
+   * `undefined` for the mutation field's own table. A hook that only cares about root writes
+   * skips the rest with `if (payload.nested) return;`.
+   */
+  nested?: NestedWriteOrigin;
   /**
    * The rows the write produced, as the database returned them — before the output mapper,
    * so values are database-shaped. Empty at the `before` position, and on MySQL, whose
@@ -831,6 +864,9 @@ type WriteHookPayload = {
    * nested write needed), **and** every column the hook names in `columns`. A column the
    * client did not select and the hook did not name is absent. The count mutations select
    * nothing, so there a row holds the named columns, or the primary key when none are named.
+   *
+   * A nested write has no selection of its own, so its rows hold the table's primary key and
+   * the join column(s) the write changed, plus the hook's `columns`.
    */
   rows: any[];
   context: any;
@@ -1449,8 +1485,8 @@ type SchemaFeatures = {
    * columns only.
    *
    * A many-to-many (`.through()`) relation is written as junction rows: `connect` on the
-   * create input, and `connect` / `disconnect` / `set` on the update input, all
-   * unconditional, since unlinking deletes a junction row rather than nulling a column.
+   * create input, and `connect` / `disconnect` / `set` on the update input, whatever the
+   * columns' nullability, since unlinking deletes a junction row rather than nulling a column.
    * It offers no `create` — inserting a row and linking it are two writes to two tables —
    * and `set: []` clears the relation.
    *
@@ -1459,6 +1495,21 @@ type SchemaFeatures = {
    * offered) becomes nullable on the create input, since the relation is the other way to
    * supply it.
    *
+   * A nested write follows the rules of the table it writes:
+   *
+   * - **`features`** — each input is generated only when that table has the write it needs:
+   *   `create` needs the target's `insert` (plus its `update` on a to-one whose nullable key
+   *   lives on the target, since attaching detaches the previous row); a `connect` /
+   *   `disconnect` / `set` that moves the target's foreign key needs its `update`; a
+   *   parent-side `connect` / `disconnect` needs nothing of the target. Many-to-many inputs
+   *   need the junction's `insert` (`connect`), `delete` (`disconnect`) or both (`set`), and
+   *   an excluded junction removes them. What is left out is noted on the console, and a
+   *   relation left with no input loses its field.
+   * - **`onWrite`** — the hooks of the table a nested statement writes fire on the same `tx`,
+   *   with `payload.nested` set. See {@link BuildSchemaConfig.onWrite}.
+   * - **`scope`** and **`contextValues`** — `connect` / `disconnect` / `set` reach only
+   *   in-scope rows, and a nested `create` is stamped like any insert.
+   *
    * 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
@@ -2122,8 +2173,16 @@ type BuildSchemaConfig = {
    *   is unchanged. An unknown column, or `columns` with no `after` hook, fails the build; on
    *   a top-level registration a named column must exist on every table. MySQL returns no
    *   rows, so `columns` has no effect there.
-   * - The hook fires for the **mutation field's own table**. Rows a nested write creates in
-   *   another table do not fire that table's hook.
+   * - **With `nestedWrites`, a nested statement fires the hooks of the table it writes**, on
+   *   the same `tx`, once per relation input and operation (not per row): `insert` for a
+   *   nested `create`; `update` for a `connect` / `disconnect` / `set` that moves the
+   *   target's foreign key; `insert` / `delete` on the junction table for a many-to-many
+   *   link / unlink (`set` is both). A parent-side `connect` / `disconnect` writes only the
+   *   parent's own row, so only the parent's hook sees it. `payload.nested` is
+   *   `{ parentTable, relation, op }` there and `undefined` at the mutation field's own
+   *   table — `if (payload.nested) return;` keeps a hook to root writes. A nested
+   *   statement's `rows` hold the table's primary key and the join column(s) it changed, plus
+   *   the hook's `columns`. A throw rolls the whole tree back, parent row included.
    *
    * Off by default, and a build without it opens exactly the transactions it did before.
    */
@@ -2593,5 +2652,5 @@ declare const resolveSelection: (info: GraphQLResolveInfo | ResolveTree, options
 //#region src/index.d.ts
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>, TConfig extends BuildSchemaConfig = BuildSchemaConfig>(db: TDbClient, config?: TConfig) => GeneratedData<TDbClient, NamingOf<TConfig>>;
 //#endregion
-export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type ContextValuesConfig, type DefaultOrderByEntry, type DefaultsConfig, type DeleteResolver, type DeleteSingleResolver, type DerivedTypeNameMapper, type DrizzleErrorCode, type DrizzleErrorContext, type DrizzleExtension, type DrizzleFieldExtension, type DrizzleFieldKind, type DrizzleFieldOperation, type DrizzleTargetArg, type DrizzleTypeExtension, type EnumNameInfo, type EnumNameMapper, type EnumValueNameInfo, type EnumValueNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type FeatureSwitch, type FieldsByTypeName, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, type GeneratedTypeInfo, type GeneratedTypeKind, GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLDecimalString, GraphQLJSON, GraphQLUUID, type IdentifiedRows, type InsertArrResolver, type InsertResolver, type LimitsConfig, type MutationReturnlessResult, type MutationsCore, type NamingOf, type OnWriteConfig, type ParseResolveInfoOptions, type Pluralize, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ResolveSelectionOptions, type ResolveTree, type RowScope, type RowScopeFilter, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaExclusions, type SchemaFeatures, type ScopeConfig, type SelectResolver, type SelectSingleResolver, type SelectionOptions, type Singularize, type SoftDeleteColumn, type SoftDeleteConfig, type TableDefaults, type TableDescriber, type TableLimitPolicy, type TableNamedRelations, type TypeNameMapper, type TypeNaming, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, type WriteHook, type WriteHookPayload, type WriteHookPositions, type WriteHooks, type WriteOperation, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleError, drizzleExecutorKey, drizzleExtension, extractFilters, extractOrderBy, extractRelationJoinColumns, identifyRows, isDrizzleFieldExtension, parseResolveInfo, resolveSelection, selectionToWith, singularizeMapper };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type ContextValuesConfig, type DefaultOrderByEntry, type DefaultsConfig, type DeleteResolver, type DeleteSingleResolver, type DerivedTypeNameMapper, type DrizzleErrorCode, type DrizzleErrorContext, type DrizzleExtension, type DrizzleFieldExtension, type DrizzleFieldKind, type DrizzleFieldOperation, type DrizzleTargetArg, type DrizzleTypeExtension, type EnumNameInfo, type EnumNameMapper, type EnumValueNameInfo, type EnumValueNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type FeatureSwitch, type FieldsByTypeName, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, type GeneratedTypeInfo, type GeneratedTypeKind, GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLDecimalString, GraphQLJSON, GraphQLUUID, type IdentifiedRows, type InsertArrResolver, type InsertResolver, type LimitsConfig, type MutationReturnlessResult, type MutationsCore, type NamingOf, type NestedWriteOp, type NestedWriteOrigin, type OnWriteConfig, type ParseResolveInfoOptions, type Pluralize, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ResolveSelectionOptions, type ResolveTree, type RowScope, type RowScopeFilter, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaExclusions, type SchemaFeatures, type ScopeConfig, type SelectResolver, type SelectSingleResolver, type SelectionOptions, type Singularize, type SoftDeleteColumn, type SoftDeleteConfig, type TableDefaults, type TableDescriber, type TableLimitPolicy, type TableNamedRelations, type TypeNameMapper, type TypeNaming, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, type WriteHook, type WriteHookPayload, type WriteHookPositions, type WriteHooks, type WriteOperation, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleError, drizzleExecutorKey, drizzleExtension, extractFilters, extractOrderBy, extractRelationJoinColumns, identifyRows, isDrizzleFieldExtension, parseResolveInfo, resolveSelection, selectionToWith, singularizeMapper };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -811,17 +811,50 @@ declare const extractFilters: <TTable extends Table>(table: TTable, tableName: s
 //#region src/util/builders/common/write-hooks.d.ts
 /** The write a hook is attached to. `restore` only exists for a soft-deleting table. */
 type WriteOperation = 'insert' | 'update' | 'updateMany' | 'upsert' | 'delete' | 'restore';
+/** Which input of a relation field a nested write came from. */
+type NestedWriteOp = 'create' | 'connect' | 'disconnect' | 'set';
+/**
+ * Where a nested write came from: set on the payload of a hook that fires for a row a nested
+ * `create` / `connect` / `disconnect` / `set` wrote, and absent at the mutation field's own
+ * table. See {@link WriteHookPayload.nested}.
+ */
+type NestedWriteOrigin = {
+  /** Drizzle schema key of the table whose input carried the relation field. */
+  parentTable: string;
+  /** The relation field the write went through, as named on the parent table. */
+  relation: string;
+  /** The relation field's input that produced this statement. */
+  op: NestedWriteOp;
+};
 /** What a write hook is handed. See {@link BuildSchemaConfig.onWrite}. */
 type WriteHookPayload = {
   /** Drizzle schema key of the table being written. */
   table: string;
+  /**
+   * What happened to `table`. A nested write reports what its statement did to *that* table:
+   * `insert` for a nested `create`, `update` for a `connect` / `disconnect` / `set` that
+   * changes the foreign key on the target, and `insert` / `delete` on the junction table for
+   * a many-to-many link / unlink.
+   */
   operation: WriteOperation;
   /** `'before'` runs ahead of the statement, `'after'` once it has returned. */
   position: 'before' | 'after';
-  /** Whether the field writes a single row (`createUsersSingle`) or a list. */
+  /**
+   * Whether the field writes a single row (`createUsersSingle`) or a list. For a nested
+   * write, whether the relation it went through is a to-one.
+   */
   single: boolean;
-  /** The field's GraphQL arguments, exactly as the resolver received them. */
+  /**
+   * The field's GraphQL arguments, exactly as the resolver received them — for a nested
+   * write, the arguments of the root mutation field it is part of.
+   */
   args: any;
+  /**
+   * Set when the rows were written by a nested write under another table's mutation, and
+   * `undefined` for the mutation field's own table. A hook that only cares about root writes
+   * skips the rest with `if (payload.nested) return;`.
+   */
+  nested?: NestedWriteOrigin;
   /**
    * The rows the write produced, as the database returned them — before the output mapper,
    * so values are database-shaped. Empty at the `before` position, and on MySQL, whose
@@ -831,6 +864,9 @@ type WriteHookPayload = {
    * nested write needed), **and** every column the hook names in `columns`. A column the
    * client did not select and the hook did not name is absent. The count mutations select
    * nothing, so there a row holds the named columns, or the primary key when none are named.
+   *
+   * A nested write has no selection of its own, so its rows hold the table's primary key and
+   * the join column(s) the write changed, plus the hook's `columns`.
    */
   rows: any[];
   context: any;
@@ -1449,8 +1485,8 @@ type SchemaFeatures = {
    * columns only.
    *
    * A many-to-many (`.through()`) relation is written as junction rows: `connect` on the
-   * create input, and `connect` / `disconnect` / `set` on the update input, all
-   * unconditional, since unlinking deletes a junction row rather than nulling a column.
+   * create input, and `connect` / `disconnect` / `set` on the update input, whatever the
+   * columns' nullability, since unlinking deletes a junction row rather than nulling a column.
    * It offers no `create` — inserting a row and linking it are two writes to two tables —
    * and `set: []` clears the relation.
    *
@@ -1459,6 +1495,21 @@ type SchemaFeatures = {
    * offered) becomes nullable on the create input, since the relation is the other way to
    * supply it.
    *
+   * A nested write follows the rules of the table it writes:
+   *
+   * - **`features`** — each input is generated only when that table has the write it needs:
+   *   `create` needs the target's `insert` (plus its `update` on a to-one whose nullable key
+   *   lives on the target, since attaching detaches the previous row); a `connect` /
+   *   `disconnect` / `set` that moves the target's foreign key needs its `update`; a
+   *   parent-side `connect` / `disconnect` needs nothing of the target. Many-to-many inputs
+   *   need the junction's `insert` (`connect`), `delete` (`disconnect`) or both (`set`), and
+   *   an excluded junction removes them. What is left out is noted on the console, and a
+   *   relation left with no input loses its field.
+   * - **`onWrite`** — the hooks of the table a nested statement writes fire on the same `tx`,
+   *   with `payload.nested` set. See {@link BuildSchemaConfig.onWrite}.
+   * - **`scope`** and **`contextValues`** — `connect` / `disconnect` / `set` reach only
+   *   in-scope rows, and a nested `create` is stamped like any insert.
+   *
    * 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
@@ -2122,8 +2173,16 @@ type BuildSchemaConfig = {
    *   is unchanged. An unknown column, or `columns` with no `after` hook, fails the build; on
    *   a top-level registration a named column must exist on every table. MySQL returns no
    *   rows, so `columns` has no effect there.
-   * - The hook fires for the **mutation field's own table**. Rows a nested write creates in
-   *   another table do not fire that table's hook.
+   * - **With `nestedWrites`, a nested statement fires the hooks of the table it writes**, on
+   *   the same `tx`, once per relation input and operation (not per row): `insert` for a
+   *   nested `create`; `update` for a `connect` / `disconnect` / `set` that moves the
+   *   target's foreign key; `insert` / `delete` on the junction table for a many-to-many
+   *   link / unlink (`set` is both). A parent-side `connect` / `disconnect` writes only the
+   *   parent's own row, so only the parent's hook sees it. `payload.nested` is
+   *   `{ parentTable, relation, op }` there and `undefined` at the mutation field's own
+   *   table — `if (payload.nested) return;` keeps a hook to root writes. A nested
+   *   statement's `rows` hold the table's primary key and the join column(s) it changed, plus
+   *   the hook's `columns`. A throw rolls the whole tree back, parent row included.
    *
    * Off by default, and a build without it opens exactly the transactions it did before.
    */
@@ -2593,5 +2652,5 @@ declare const resolveSelection: (info: GraphQLResolveInfo | ResolveTree, options
 //#region src/index.d.ts
 declare const buildSchema: <TDbClient extends AnyDrizzleDB<any>, TConfig extends BuildSchemaConfig = BuildSchemaConfig>(db: TDbClient, config?: TConfig) => GeneratedData<TDbClient, NamingOf<TConfig>>;
 //#endregion
-export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type ContextValuesConfig, type DefaultOrderByEntry, type DefaultsConfig, type DeleteResolver, type DeleteSingleResolver, type DerivedTypeNameMapper, type DrizzleErrorCode, type DrizzleErrorContext, type DrizzleExtension, type DrizzleFieldExtension, type DrizzleFieldKind, type DrizzleFieldOperation, type DrizzleTargetArg, type DrizzleTypeExtension, type EnumNameInfo, type EnumNameMapper, type EnumValueNameInfo, type EnumValueNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type FeatureSwitch, type FieldsByTypeName, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, type GeneratedTypeInfo, type GeneratedTypeKind, GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLDecimalString, GraphQLJSON, GraphQLUUID, type IdentifiedRows, type InsertArrResolver, type InsertResolver, type LimitsConfig, type MutationReturnlessResult, type MutationsCore, type NamingOf, type OnWriteConfig, type ParseResolveInfoOptions, type Pluralize, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ResolveSelectionOptions, type ResolveTree, type RowScope, type RowScopeFilter, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaExclusions, type SchemaFeatures, type ScopeConfig, type SelectResolver, type SelectSingleResolver, type SelectionOptions, type Singularize, type SoftDeleteColumn, type SoftDeleteConfig, type TableDefaults, type TableDescriber, type TableLimitPolicy, type TableNamedRelations, type TypeNameMapper, type TypeNaming, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, type WriteHook, type WriteHookPayload, type WriteHookPositions, type WriteHooks, type WriteOperation, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleError, drizzleExecutorKey, drizzleExtension, extractFilters, extractOrderBy, extractRelationJoinColumns, identifyRows, isDrizzleFieldExtension, parseResolveInfo, resolveSelection, selectionToWith, singularizeMapper };
+export { type AggregateResolver, type AnyDrizzleDB, type BuildSchemaConfig, type ColumnDeprecator, type ColumnDescriber, type ColumnDocInfo, type ColumnTypeMapper, type ColumnTypeMapperInfo, type ComplexityConfig, type ContextValuesConfig, type DefaultOrderByEntry, type DefaultsConfig, type DeleteResolver, type DeleteSingleResolver, type DerivedTypeNameMapper, type DrizzleErrorCode, type DrizzleErrorContext, type DrizzleExtension, type DrizzleFieldExtension, type DrizzleFieldKind, type DrizzleFieldOperation, type DrizzleTargetArg, type DrizzleTypeExtension, type EnumNameInfo, type EnumNameMapper, type EnumValueNameInfo, type EnumValueNameMapper, type ExtractRelations, type ExtractTableByName, type ExtractTableRelations, type ExtractTables, type FeatureSwitch, type FieldsByTypeName, type GeneratedData, type GeneratedEntities, type GeneratedInputs, type GeneratedOutputs, type GeneratedTypeInfo, type GeneratedTypeKind, GraphQLBigIntString, GraphQLDate, GraphQLDateTime, GraphQLDecimalString, GraphQLJSON, GraphQLUUID, type IdentifiedRows, type InsertArrResolver, type InsertResolver, type LimitsConfig, type MutationReturnlessResult, type MutationsCore, type NamingOf, type NestedWriteOp, type NestedWriteOrigin, type OnWriteConfig, type ParseResolveInfoOptions, type Pluralize, type QueriesCore, type RelationDescriber, type RelationResolverFactory, type ResolveSelectionOptions, type ResolveTree, type RowScope, type RowScopeFilter, type ScalarOverride, type ScalarOverridesConfig, type SchemaDocs, type SchemaExclusions, type SchemaFeatures, type ScopeConfig, type SelectResolver, type SelectSingleResolver, type SelectionOptions, type Singularize, type SoftDeleteColumn, type SoftDeleteConfig, type TableDefaults, type TableDescriber, type TableLimitPolicy, type TableNamedRelations, type TypeNameMapper, type TypeNaming, type UpdateManyArgs, type UpdateManyEntry, type UpdateManyResolver, type UpdateResolver, type UpdateSingleResolver, type UpsertArgs, type UpsertArrResolver, type UpsertConflictArgs, type UpsertResolver, type WriteHook, type WriteHookPayload, type WriteHookPositions, type WriteHooks, type WriteOperation, buildSchema, createRelationResolverFactory, defaultErrorMapper, drizzleError, drizzleExecutorKey, drizzleExtension, extractFilters, extractOrderBy, extractRelationJoinColumns, identifyRows, isDrizzleFieldExtension, parseResolveInfo, resolveSelection, selectionToWith, singularizeMapper };
 //# sourceMappingURL=index.d.ts.map