@vantreeseba/drizzle-graphql 15.1.2 → 15.1.3

package/dist/index.d.cts

@@ -807,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
@@ -924,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.
  *
@@ -961,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. */
@@ -2036,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
@@ -2065,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
@@ -2129,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
@@ -2222,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.
@@ -2628,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
@@ -2647,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".
  */
@@ -2668,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
@@ -2677,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

@@ -807,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
@@ -924,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.
  *
@@ -961,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. */
@@ -2036,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
@@ -2065,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
@@ -2129,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
@@ -2222,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.
@@ -2628,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
@@ -2647,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".
  */
@@ -2668,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
@@ -2677,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