feat!: move deleted filter to top-level query argument (#479)

* feat!: move deleted filter to top-level query argument

Soft-deleted rows are no longer part of Where inputs. List, aggregate,
singular, and reverse-relation queries on deletable entities take
`deleted: Boolean = false` instead. Skip the cascade-deletion OR in
permission EXISTS when the query does not include deleted rows.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(release): use conventionalcommits preset for commit analyzer

The angular preset does not parse feat! breaking-change notation, so
semantic-release skipped the commit on next. Align commit-analyzer with
release-notes-generator and add an explicit breaking release rule.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nicola-smartive

.releaserc

@@ -10,11 +10,15 @@
     [
       "@semantic-release/commit-analyzer",
       {
-        "preset": "angular",
+        "preset": "conventionalcommits",
         "releaseRules": [
           {
             "type": "break",
             "release": "major"
+          },
+          {
+            "breaking": true,
+            "release": "major"
           }
         ]
       }

docs/docs/10-migration-guides.md

@@ -1,5 +1,32 @@
 # Migration Guides
 
+## Upgrading to the next major version
+
+### `deleted` is a top-level argument, not a `where` filter
+
+The `deleted` field is no longer part of the auto-generated `Where` input. Instead, queries that operate on deletable entities expose a top-level `deleted: Boolean = false` argument. This applies to plural list queries, aggregate queries, singular `entity(where: …)` queries and reverse-relation list fields.
+
+Semantics of the new argument:
+
+- omitted or `deleted: false` (default): only non-deleted entries.
+- `deleted: true`: only deleted entries (requires `DELETE` permission).
+- `deleted: null`: both deleted and non-deleted entries (requires `DELETE` permission).
+
+Update affected queries:
+
+```diff
+- posts(where: { author: { id: "..." }, deleted: [true] }) { id }
++ posts(where: { author: { id: "..." } }, deleted: true) { id }
+
+- invoices_AGGREGATE(where: { deleted: [false] }) { COUNT }
++ invoices_AGGREGATE(deleted: false) { COUNT }
+
+- posts(where: { deleted: [true, false] }) { id }
++ posts(where: {}, deleted: null) { id }
+```
+
+Permission `WHERE` rules can no longer filter on `deleted` via the generated permission `Where` types. The hard-coded `deleted = false` join used by permission chains is unchanged.
+
 ## Upgrading to v19.0.0
 
 ### Configuration changes

docs/docs/2-models.md

@@ -145,7 +145,7 @@ This exposes:
 
 ```graphql
 query {
-  invoices_AGGREGATE(where: { deleted: [false] }) {
+  invoices_AGGREGATE(deleted: false) {
     COUNT
     amount_SUM
   }

src/models/models.ts

@@ -174,7 +174,6 @@ export class Models {
                 type: 'Boolean',
                 nonNull: true,
                 defaultValue: false,
-                filterable: { default: false },
                 generated: true,
                 ...(typeof entity.deletable === 'object' && entity.deletable.deleted),
               } satisfies BooleanFieldDefinition,

src/permissions/check.ts

@@ -38,6 +38,7 @@ export const applyPermissions = (
   query: Knex.QueryBuilder,
   action: PermissionAction,
   verifiedPermissionStack?: PermissionStack,
+  includesDeletedRows?: boolean,
 ): boolean | PermissionStack => {
   const permissionStack = getPermissionStack(ctx, type, action);
 
@@ -79,7 +80,7 @@ export const applyPermissions = (
               subQuery,
               links,
               ctx.knex.raw(`"${tableAlias}".id`),
-              ['READ', 'RESTORE'].includes(action) ? tableAlias : undefined,
+              ['READ', 'RESTORE'].includes(action) && includesDeletedRows ? tableAlias : undefined,
             ),
           ),
     ),

src/resolvers/arguments.ts

@@ -25,6 +25,7 @@ export type NormalizedArguments = {
   orderBy?: OrderBy[];
   where?: Where;
   search?: string;
+  deleted?: boolean | null;
   mine?: boolean;
   language?: string;
 };

src/resolvers/filters.ts

@@ -21,6 +21,9 @@ export type FilterNode = {
   tableAlias: string;
 };
 
+/** True when the query may return soft-deleted rows (`deleted: true` or `deleted: null`). */
+export const includesDeletedRows = (deleted: boolean | null | undefined) => deleted === true || deleted === null;
+
 export const applyFilters = async (node: FieldResolverNode, query: Knex.QueryBuilder, joins: Joins) => {
   const normalizedArguments = normalizeArguments(node);
   // No need for default order by in aggregates
@@ -33,7 +36,7 @@ export const applyFilters = async (node: FieldResolverNode, query: Knex.QueryBui
       }
     }
   }
-  const { limit, offset, orderBy, where, search } = normalizedArguments;
+  const { limit, offset, orderBy, where, search, deleted } = normalizedArguments;
 
   await node.ctx.queryHook?.({ model: node.model, query, args: normalizedArguments, ctx: node.ctx });
 
@@ -58,30 +61,44 @@ export const applyFilters = async (node: FieldResolverNode, query: Knex.QueryBui
   }
 
   const ops: QueryBuilderOps = [];
+  applyDeletedFilter(node, deleted, ops);
   applyWhere(node, where, ops, joins);
   void apply(query, ops);
 
   if (search) {
     void applySearch(node, search, query);
   }
 
-  return { paginated: normalizedArguments.limit !== undefined || normalizedArguments.offset !== undefined };
+  return {
+    paginated: normalizedArguments.limit !== undefined || normalizedArguments.offset !== undefined,
+    includesDeletedRows: includesDeletedRows(deleted),
+  };
 };
 
-const applyWhere = (node: FilterNode, where: Where | undefined, ops: QueryBuilderOps, joins: Joins) => {
-  if (node.model.deletable) {
-    if (!where) {
-      where = {};
-    }
-    if (where.deleted && (!Array.isArray(where.deleted) || where.deleted.some((v) => v))) {
-      if (!getPermissionStack(node.ctx, node.model.name, 'DELETE')) {
-        throw new ForbiddenError('You cannot access deleted entries.');
-      }
-    } else {
-      where.deleted = false;
-    }
+const applyDeletedFilter = (node: FilterNode, deleted: boolean | null | undefined, ops: QueryBuilderOps) => {
+  if (!node.model.deletable) {
+    return;
+  }
+  const effective = deleted === undefined ? false : deleted;
+  if (effective !== false && !getPermissionStack(node.ctx, node.model.name, 'DELETE')) {
+    throw new ForbiddenError('You cannot access deleted entries.');
   }
+  if (effective === null) {
+    return;
+  }
+  const column = getColumn(node, 'deleted');
+  ops.push((query) => query.where({ [column]: effective }));
+};
+
+const applyNestedDeletedDefault = (node: FilterNode, ops: QueryBuilderOps) => {
+  if (!node.model.deletable) {
+    return;
+  }
+  const column = getColumn(node, 'deleted');
+  ops.push((query) => query.where({ [column]: false }));
+};
 
+const applyWhere = (node: FilterNode, where: Where | undefined, ops: QueryBuilderOps, joins: Joins) => {
   if (!where) {
     return;
   }
@@ -139,6 +156,7 @@ const applyWhere = (node: FilterNode, where: Where | undefined, ops: QueryBuilde
         };
         const subOps: QueryBuilderOps = [];
         const subJoins: Joins = [];
+        applyNestedDeletedDefault(subWhereNode, subOps);
         applyWhere(subWhereNode, value as Where, subOps, subJoins);
 
         // TODO: make this work with subtypes
@@ -200,6 +218,7 @@ const applyWhere = (node: FilterNode, where: Where | undefined, ops: QueryBuilde
         tableAlias,
       };
       addJoin(joins, node.tableAlias, subNode.model.name, subNode.tableAlias, relation.field.foreignKey, 'id');
+      applyNestedDeletedDefault(subNode, ops);
       applyWhere(subNode, value as Where, ops, joins);
       continue;
     }

src/resolvers/resolver.ts

@@ -83,7 +83,7 @@ const buildQuery = async (
 ): Promise<{ query: Knex.QueryBuilder; verifiedPermissionStacks: VerifiedPermissionStacks; paginated: boolean }> => {
   const query = node.ctx.knex.fromRaw(`"${node.rootModel.name}" as "${node.ctx.aliases.getShort(node.resultAlias)}"`);
   const joins: Joins = [];
-  const { paginated } = await applyFilters(node, query, joins);
+  const { paginated, includesDeletedRows } = await applyFilters(node, query, joins);
   applySelects(node, query, joins);
   applyJoins(node.ctx.aliases, query, joins);
 
@@ -101,6 +101,7 @@ const buildQuery = async (
       query,
       'READ',
       parentVerifiedPermissionStacks?.[alias.split('__').slice(0, -1).join('__')],
+      includesDeletedRows,
     );
 
     if (typeof verifiedPermissionStack !== 'boolean') {

src/schema/generate.ts

@@ -42,6 +42,9 @@ const pickWhereVariant = (targetModel: EntityModel, exemptedFieldName?: string):
   };
 };
 
+const deletedArg = (model: EntityModel): Field[] =>
+  model.deletable ? [{ name: 'deleted', type: 'Boolean', defaultValue: false }] : [];
+
 const buildWhereFields = (
   model: EntityModel,
   { isSubWhere = false, exemptedFieldName }: { isSubWhere?: boolean; exemptedFieldName?: string } = {},
@@ -147,6 +150,7 @@ export const generateDefinitions = ({
                     type: variant.typeName,
                     nonNull: variant.nonNull,
                   },
+                  ...deletedArg(targetModel),
                   ...(targetModel.fields.some(({ searchable }) => searchable) ? [{ name: 'search', type: 'String' }] : []),
                   ...(targetModel.fields.some(({ orderable }) => orderable)
                     ? [{ name: 'orderBy', type: `${targetModel.name}OrderBy`, list: true }]
@@ -266,16 +270,17 @@ export const generateDefinitions = ({
       },
       ...entities
         .filter(({ queriable }) => queriable)
-        .map(({ name }) => ({
-          name: typeToField(name),
-          type: name,
+        .map((model) => ({
+          name: typeToField(model.name),
+          type: model.name,
           nonNull: true,
           args: [
             {
               name: 'where',
-              type: `${name}WhereLookup`,
+              type: `${model.name}WhereLookup`,
               nonNull: true,
             },
+            ...deletedArg(model),
           ],
         })),
       ...entities
@@ -291,6 +296,7 @@ export const generateDefinitions = ({
               type: `${model.name}Where`,
               nonNull: hasAnyMandatoryFilterableField(model),
             },
+            ...deletedArg(model),
             ...(model.fields.some(({ searchable }) => searchable) ? [{ name: 'search', type: 'String' }] : []),
             ...(model.fields.some(({ orderable }) => orderable)
               ? [{ name: 'orderBy', type: `${model.name}OrderBy`, list: true }]
@@ -312,6 +318,7 @@ export const generateDefinitions = ({
               type: `${model.name}Where`,
               nonNull: hasAnyMandatoryFilterableField(model),
             },
+            ...deletedArg(model),
             ...(model.fields.some(({ searchable }) => searchable) ? [{ name: 'search', type: 'String' }] : []),
           ],
         })),

tests/api/delete.spec.ts

@@ -16,7 +16,7 @@ describe('delete', () => {
       expect(
         await request(gql`
           query GetAnotherObject {
-            anotherObjects(where: { id: "${ANOTHER_ID}", deleted: true }) {
+            anotherObjects(where: { id: "${ANOTHER_ID}" }, deleted: true) {
               id
               deleted
             }