@vantreeseba/drizzle-graphql 15.1.1 → 15.1.3

package/dist/index.d.cts

@@ -385,7 +385,9 @@ type IdentifiedRows = {
    *
    * `false` means the arguments do not pin the rows down — an insert whose key the
    * database generates, a `where` that filters on something other than the primary key,
-   * a plural update with no filter at all, or a table with no primary key. `rows` is then
+   * a plural update with no filter at all, a table with no primary key, or an upsert whose
+   * `onConflict` conflicts on another unique key (the row updated is the one holding that
+   * key) or can skip a conflicting row (`action: NOTHING`, a `where` guard). `rows` is then
    * a best-effort subset-free superset: every entry in it is a row the key values name,
    * but other filters may narrow the real set further, and it may be empty.
    */
@@ -805,6 +807,14 @@ interface RelationFilterContext {
    * generate is an unknown filter key like any other.
    */
   uniqueKeys?: Record<string, UniqueKeyMap>;
+  /**
+   * The row policies of the request being compiled. A relation filter (and an ordering through
+   * a relation) reads the target table in a subquery, so it applies the target's `scope` and
+   * `softDelete` here — with the mode the relation field itself would default to — or a filter
+   * could match, and a sort could rank by, a row the relation hides. Absent for a scope's own
+   * filter object, which is the server's predicate and is compiled unscoped.
+   */
+  scope?: ScopeResolver;
 }
 /**
  * The build-scoped half of {@link RelationFilterContext}. Created once per generated schema and
@@ -922,6 +932,8 @@ type WriteHookFor = (tableName: string, operation: WriteOperation) => ResolvedWr
 type ScopeHook<TContext = any> = (context: TContext, table: any) => SQL | Record<string, any> | undefined | null;
 /** Build-time lookup: the scope configured for a table, if any. */
 type ScopeFor = (tableName: string) => ScopeHook | undefined;
+/** What a read over a soft-deleting table does with rows that are marked deleted. */
+type DeletedMode = 'EXCLUDE' | 'INCLUDE' | 'ONLY';
 /**
  * One table's soft-delete convention, resolved against the real column at build time.
  *
@@ -959,6 +971,22 @@ type SoftDeleteInfo = {
 };
 /** Build-time lookup: the soft-delete convention of a table, if it declares one. */
 type SoftDeleteFor = (tableName: string) => SoftDeleteInfo | undefined;
+/**
+ * The row policies of one request, bound to its context: the table's scope and its
+ * soft-delete convention, which both narrow the same `where`. `has` answers "does this table
+ * restrict anything at all", cheaply and without evaluating a hook; `on` compiles the
+ * predicate against a given table.
+ */
+type ScopeResolver = {
+  has: (tableName: string, mode?: DeletedMode) => boolean;
+  on: (tableName: string, table: Table, mode?: DeletedMode) => SQL | undefined;
+  /**
+   * The mode a relation field reading `tableName` defaults to — see
+   * {@link relationDeletedDefault}. Carried here because the eager (`with:`) path has the
+   * resolver but not the build-time soft-delete lookup.
+   */
+  relationDefault: (tableName: string, requiredToOne: boolean) => DeletedMode | undefined;
+};
 /** Produces one column's value from the GraphQL context. See `BuildSchemaConfig.contextValues`. */
 type ContextValueHook<TContext = any> = (context: TContext) => any;
 /** Build-time lookup: the context-derived columns of a table, keyed by column property name. */
@@ -1178,6 +1206,9 @@ type UpdateManyArgs<TTable extends Table> = {
  * `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.
+ *
+ * `target` may name a partial unique index; its predicate is repeated in the statement's
+ * `ON CONFLICT (…) WHERE …`, which is what lets the database match it.
  */
 type UpsertConflictArgs<TTable extends Table> = {
   action?: 'UPDATE' | 'NOTHING';
@@ -1604,7 +1635,9 @@ type SchemaFeatures = {
    * have — the guarantee is in the input type.
    *
    * Single-column constraints get no field (`eq` on the column already says it), and a
-   * constraint whose field name is taken by a column or a relation is skipped. The fields live
+   * constraint whose field name is taken by a column or a relation is skipped. So is a partial
+   * unique index (`uniqueIndex().on(…).where(…)`): it is unique only among the rows its
+   * predicate matches, so its columns do not name one row of the table. The fields live
    * on `<Type>Filters`, so they are accepted wherever a filter is: the `Single` reads and
    * writes they are meant for, but also list queries, relation filters and `onConflict.where`.
    *
@@ -2029,7 +2062,8 @@ type BuildSchemaConfig = {
    *   what an `after`-only page is ordered by. Changing a table's default changes what its
    *   existing cursors mean.
    * - Entries name column property names of that table; a direction alone is shorthand for
-   *   `{ direction }`. Unknown table or column names throw at build time.
+   *   `{ direction }`. Unknown table or column names throw at build time, and so does a
+   *   column hidden by `exclude.columns`: cursors carry the ordering values in readable form.
    * - Aggregates and `groupBy` take their own ordering and are unaffected.
    *
    * Off by default: a table with no entry keeps returning rows in whatever order the database
@@ -2058,6 +2092,10 @@ type BuildSchemaConfig = {
    *   only ever narrow the scope, never widen it.
    * - It applies to every path that reads the table: list and single queries, aggregates and
    *   `groupBy`, relation fields (batched and eager), relation aggregates, and cursor pages.
+   *   It also applies wherever another table's request reads this one in a subquery: a
+   *   relation filter (`some` / `none` / `every`, to-one, `.through()` — the junction's scope
+   *   included) can only match in-scope rows, and an `orderBy` through a to-one relation sorts
+   *   an out-of-scope target as `NULL`.
    * - It applies to every path that writes it: `update`, `updateMany`, `delete`, the
    *   conflict-update half of an upsert (PostgreSQL and SQLite), and the rows a nested
    *   `connect` / `disconnect` / `set` is allowed to reach. An out-of-scope row is simply not
@@ -2091,7 +2129,8 @@ type BuildSchemaConfig = {
    * - The column is removed from the generated insert and update inputs, so a client cannot
    *   send it at all — the schema itself documents that it is server-owned.
    * - Every insert stamps it, including the rows created by a nested `create`.
-   * - Updates never write it: an update cannot hand a row to another owner.
+   * - Updates never write it: an update cannot hand a row to another owner. That includes
+   *   the conflict branch of an upsert, whose `onConflict.update` does not offer it.
    * - Keyed by the Drizzle schema key, then by the column's property name (not its database
    *   name), the same keying {@link BuildSchemaConfig.exclude} uses.
    */
@@ -2121,7 +2160,8 @@ type BuildSchemaConfig = {
    * - Every generated read hides marked rows: list and single queries, aggregates, `groupBy`,
    *   relation fields on both the eager and the batched path, and relation aggregates. Each
    *   of those fields takes a `deleted: EXCLUDE | INCLUDE | ONLY` argument (default
-   *   `EXCLUDE`); `ONLY` is a trash view.
+   *   `EXCLUDE`); `ONLY` is a trash view. Relation filters and an `orderBy` through a to-one
+   *   relation see the rows the relation field would show, with the same default mode.
    * - Every generated write skips them too: an `update`, a `delete`, or a nested `connect`
    *   cannot reach a row that is already marked.
    * - The marker column is removed from the create and update inputs, so the only ways to set
@@ -2214,6 +2254,11 @@ type BuildSchemaConfig = {
    * deliberately all-or-nothing: a column you can filter on but not select is an oracle, since
    * `where: { keyHash: { eq: '…' } }` confirms a value without ever returning it.
    *
+   * One value stays readable: a row's `cursor` is base64url JSON of its ordering values, and the
+   * primary key is always among them, so excluding the primary key does not hide it from a
+   * client that decodes a cursor. Wrap cursors in your own opaque token if it must stay secret.
+   * A `defaults` ordering on an excluded column throws at build time for the same reason.
+   *
    * Excluding a `NOT NULL` column that has no default makes that table's inserts impossible to
    * satisfy — `buildSchema` warns on the console when it sees this, and still builds, since a
    * read-only table is a reasonable thing to want.
@@ -2620,6 +2665,11 @@ type SelectionOptions = {
   derivedTypeNameMapper?: DerivedTypeNameMapper;
   typeNamePrefix?: string;
   typeNameSuffix?: string;
+  /**
+   * The resolver's GraphQL context. The build's `scope` hooks are called with it, so a build
+   * that configures `scope` requires it — the helpers throw rather than read unscoped.
+   */
+  context?: any;
 };
 /**
  * Translates a GraphQL selection set into the relational query builder's `with` tree — the
@@ -2639,6 +2689,10 @@ type SelectionOptions = {
  * const row = await tx.query.Users.findFirst({ where: { id: { eq } }, with: withTree });
  * ```
  *
+ * Every nested entry carries the build's row policies — `scope`, `softDelete`, `limits` and
+ * `defaults.orderBy` — exactly as the generated `with:` clause does. The build is found
+ * through the resolve info; pass `context` when it configures `scope`.
+ *
  * Returns `undefined` when the selection asks for no relations, which is the value the
  * query builder wants for "no `with` clause".
  */
@@ -2660,6 +2714,11 @@ type ResolveSelectionOptions = SelectionOptions & {
   offset?: number;
   /** The generated `after` cursor argument, for keyset pagination. */
   after?: string;
+  /**
+   * The generated `deleted` argument, for a soft-deleting table. Defaults to `EXCLUDE`, as the
+   * generated field does.
+   */
+  deleted?: DeletedMode;
 };
 /**
  * Runs the read a generated select resolver would have run, against whichever executor is
@@ -2669,11 +2728,13 @@ type ResolveSelectionOptions = SelectionOptions & {
  * This is what an override usually wants after it has done its own work:
  *
  * ```ts
- * const rows = await resolveSelection(info, { db, table: 'Users', where, executor: tx });
+ * const rows = await resolveSelection(info, { db, table: 'Users', context, where, executor: tx });
  * ```
  *
  * Relation arguments and aggregate fields keep behaving as they do in the generated schema,
- * because it is the generated schema's own code path.
+ * because it is the generated schema's own code path. So do the build's row policies: the
+ * root table and every nested relation are scoped and soft-delete-filtered, and the limit
+ * policy and default ordering apply. Pass `context` when the build configures `scope`.
  */
 declare const resolveSelection: (info: GraphQLResolveInfo | ResolveTree, options: ResolveSelectionOptions) => Promise<any>;
 //#endregion

package/dist/index.d.ts

@@ -385,7 +385,9 @@ type IdentifiedRows = {
    *
    * `false` means the arguments do not pin the rows down — an insert whose key the
    * database generates, a `where` that filters on something other than the primary key,
-   * a plural update with no filter at all, or a table with no primary key. `rows` is then
+   * a plural update with no filter at all, a table with no primary key, or an upsert whose
+   * `onConflict` conflicts on another unique key (the row updated is the one holding that
+   * key) or can skip a conflicting row (`action: NOTHING`, a `where` guard). `rows` is then
    * a best-effort subset-free superset: every entry in it is a row the key values name,
    * but other filters may narrow the real set further, and it may be empty.
    */
@@ -805,6 +807,14 @@ interface RelationFilterContext {
    * generate is an unknown filter key like any other.
    */
   uniqueKeys?: Record<string, UniqueKeyMap>;
+  /**
+   * The row policies of the request being compiled. A relation filter (and an ordering through
+   * a relation) reads the target table in a subquery, so it applies the target's `scope` and
+   * `softDelete` here — with the mode the relation field itself would default to — or a filter
+   * could match, and a sort could rank by, a row the relation hides. Absent for a scope's own
+   * filter object, which is the server's predicate and is compiled unscoped.
+   */
+  scope?: ScopeResolver;
 }
 /**
  * The build-scoped half of {@link RelationFilterContext}. Created once per generated schema and
@@ -922,6 +932,8 @@ type WriteHookFor = (tableName: string, operation: WriteOperation) => ResolvedWr
 type ScopeHook<TContext = any> = (context: TContext, table: any) => SQL | Record<string, any> | undefined | null;
 /** Build-time lookup: the scope configured for a table, if any. */
 type ScopeFor = (tableName: string) => ScopeHook | undefined;
+/** What a read over a soft-deleting table does with rows that are marked deleted. */
+type DeletedMode = 'EXCLUDE' | 'INCLUDE' | 'ONLY';
 /**
  * One table's soft-delete convention, resolved against the real column at build time.
  *
@@ -959,6 +971,22 @@ type SoftDeleteInfo = {
 };
 /** Build-time lookup: the soft-delete convention of a table, if it declares one. */
 type SoftDeleteFor = (tableName: string) => SoftDeleteInfo | undefined;
+/**
+ * The row policies of one request, bound to its context: the table's scope and its
+ * soft-delete convention, which both narrow the same `where`. `has` answers "does this table
+ * restrict anything at all", cheaply and without evaluating a hook; `on` compiles the
+ * predicate against a given table.
+ */
+type ScopeResolver = {
+  has: (tableName: string, mode?: DeletedMode) => boolean;
+  on: (tableName: string, table: Table, mode?: DeletedMode) => SQL | undefined;
+  /**
+   * The mode a relation field reading `tableName` defaults to — see
+   * {@link relationDeletedDefault}. Carried here because the eager (`with:`) path has the
+   * resolver but not the build-time soft-delete lookup.
+   */
+  relationDefault: (tableName: string, requiredToOne: boolean) => DeletedMode | undefined;
+};
 /** Produces one column's value from the GraphQL context. See `BuildSchemaConfig.contextValues`. */
 type ContextValueHook<TContext = any> = (context: TContext) => any;
 /** Build-time lookup: the context-derived columns of a table, keyed by column property name. */
@@ -1178,6 +1206,9 @@ type UpdateManyArgs<TTable extends Table> = {
  * `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.
+ *
+ * `target` may name a partial unique index; its predicate is repeated in the statement's
+ * `ON CONFLICT (…) WHERE …`, which is what lets the database match it.
  */
 type UpsertConflictArgs<TTable extends Table> = {
   action?: 'UPDATE' | 'NOTHING';
@@ -1604,7 +1635,9 @@ type SchemaFeatures = {
    * have — the guarantee is in the input type.
    *
    * Single-column constraints get no field (`eq` on the column already says it), and a
-   * constraint whose field name is taken by a column or a relation is skipped. The fields live
+   * constraint whose field name is taken by a column or a relation is skipped. So is a partial
+   * unique index (`uniqueIndex().on(…).where(…)`): it is unique only among the rows its
+   * predicate matches, so its columns do not name one row of the table. The fields live
    * on `<Type>Filters`, so they are accepted wherever a filter is: the `Single` reads and
    * writes they are meant for, but also list queries, relation filters and `onConflict.where`.
    *
@@ -2029,7 +2062,8 @@ type BuildSchemaConfig = {
    *   what an `after`-only page is ordered by. Changing a table's default changes what its
    *   existing cursors mean.
    * - Entries name column property names of that table; a direction alone is shorthand for
-   *   `{ direction }`. Unknown table or column names throw at build time.
+   *   `{ direction }`. Unknown table or column names throw at build time, and so does a
+   *   column hidden by `exclude.columns`: cursors carry the ordering values in readable form.
    * - Aggregates and `groupBy` take their own ordering and are unaffected.
    *
    * Off by default: a table with no entry keeps returning rows in whatever order the database
@@ -2058,6 +2092,10 @@ type BuildSchemaConfig = {
    *   only ever narrow the scope, never widen it.
    * - It applies to every path that reads the table: list and single queries, aggregates and
    *   `groupBy`, relation fields (batched and eager), relation aggregates, and cursor pages.
+   *   It also applies wherever another table's request reads this one in a subquery: a
+   *   relation filter (`some` / `none` / `every`, to-one, `.through()` — the junction's scope
+   *   included) can only match in-scope rows, and an `orderBy` through a to-one relation sorts
+   *   an out-of-scope target as `NULL`.
    * - It applies to every path that writes it: `update`, `updateMany`, `delete`, the
    *   conflict-update half of an upsert (PostgreSQL and SQLite), and the rows a nested
    *   `connect` / `disconnect` / `set` is allowed to reach. An out-of-scope row is simply not
@@ -2091,7 +2129,8 @@ type BuildSchemaConfig = {
    * - The column is removed from the generated insert and update inputs, so a client cannot
    *   send it at all — the schema itself documents that it is server-owned.
    * - Every insert stamps it, including the rows created by a nested `create`.
-   * - Updates never write it: an update cannot hand a row to another owner.
+   * - Updates never write it: an update cannot hand a row to another owner. That includes
+   *   the conflict branch of an upsert, whose `onConflict.update` does not offer it.
    * - Keyed by the Drizzle schema key, then by the column's property name (not its database
    *   name), the same keying {@link BuildSchemaConfig.exclude} uses.
    */
@@ -2121,7 +2160,8 @@ type BuildSchemaConfig = {
    * - Every generated read hides marked rows: list and single queries, aggregates, `groupBy`,
    *   relation fields on both the eager and the batched path, and relation aggregates. Each
    *   of those fields takes a `deleted: EXCLUDE | INCLUDE | ONLY` argument (default
-   *   `EXCLUDE`); `ONLY` is a trash view.
+   *   `EXCLUDE`); `ONLY` is a trash view. Relation filters and an `orderBy` through a to-one
+   *   relation see the rows the relation field would show, with the same default mode.
    * - Every generated write skips them too: an `update`, a `delete`, or a nested `connect`
    *   cannot reach a row that is already marked.
    * - The marker column is removed from the create and update inputs, so the only ways to set
@@ -2214,6 +2254,11 @@ type BuildSchemaConfig = {
    * deliberately all-or-nothing: a column you can filter on but not select is an oracle, since
    * `where: { keyHash: { eq: '…' } }` confirms a value without ever returning it.
    *
+   * One value stays readable: a row's `cursor` is base64url JSON of its ordering values, and the
+   * primary key is always among them, so excluding the primary key does not hide it from a
+   * client that decodes a cursor. Wrap cursors in your own opaque token if it must stay secret.
+   * A `defaults` ordering on an excluded column throws at build time for the same reason.
+   *
    * Excluding a `NOT NULL` column that has no default makes that table's inserts impossible to
    * satisfy — `buildSchema` warns on the console when it sees this, and still builds, since a
    * read-only table is a reasonable thing to want.
@@ -2620,6 +2665,11 @@ type SelectionOptions = {
   derivedTypeNameMapper?: DerivedTypeNameMapper;
   typeNamePrefix?: string;
   typeNameSuffix?: string;
+  /**
+   * The resolver's GraphQL context. The build's `scope` hooks are called with it, so a build
+   * that configures `scope` requires it — the helpers throw rather than read unscoped.
+   */
+  context?: any;
 };
 /**
  * Translates a GraphQL selection set into the relational query builder's `with` tree — the
@@ -2639,6 +2689,10 @@ type SelectionOptions = {
  * const row = await tx.query.Users.findFirst({ where: { id: { eq } }, with: withTree });
  * ```
  *
+ * Every nested entry carries the build's row policies — `scope`, `softDelete`, `limits` and
+ * `defaults.orderBy` — exactly as the generated `with:` clause does. The build is found
+ * through the resolve info; pass `context` when it configures `scope`.
+ *
  * Returns `undefined` when the selection asks for no relations, which is the value the
  * query builder wants for "no `with` clause".
  */
@@ -2660,6 +2714,11 @@ type ResolveSelectionOptions = SelectionOptions & {
   offset?: number;
   /** The generated `after` cursor argument, for keyset pagination. */
   after?: string;
+  /**
+   * The generated `deleted` argument, for a soft-deleting table. Defaults to `EXCLUDE`, as the
+   * generated field does.
+   */
+  deleted?: DeletedMode;
 };
 /**
  * Runs the read a generated select resolver would have run, against whichever executor is
@@ -2669,11 +2728,13 @@ type ResolveSelectionOptions = SelectionOptions & {
  * This is what an override usually wants after it has done its own work:
  *
  * ```ts
- * const rows = await resolveSelection(info, { db, table: 'Users', where, executor: tx });
+ * const rows = await resolveSelection(info, { db, table: 'Users', context, where, executor: tx });
  * ```
  *
  * Relation arguments and aggregate fields keep behaving as they do in the generated schema,
- * because it is the generated schema's own code path.
+ * because it is the generated schema's own code path. So do the build's row policies: the
+ * root table and every nested relation are scoped and soft-delete-filtered, and the limit
+ * policy and default ordering apply. Pass `context` when the build configures `scope`.
  */
 declare const resolveSelection: (info: GraphQLResolveInfo | ResolveTree, options: ResolveSelectionOptions) => Promise<any>;
 //#endregion