feat: adds trash support to the count operation (#13304)

### What?

- Updated the `countOperation` to respect the `trash` argument.

### Why?

- Previously, `count` would incorrectly include trashed documents even
when `trash` was not specified.
- This change aligns `count` behavior with `find` and other operations,
providing accurate counts for normal and trashed documents.

### How?

- Applied `appendNonTrashedFilter` in `countOperation` to automatically
exclude soft-deleted docs when `trash: false` (default).
- Added `trash` argument support in Local API, REST API (`/count`
endpoints), and GraphQL (`count<Collection>` queries).

Author: PatrikKozak

packages/graphql/src/resolvers/collections/count.ts

@@ -9,6 +9,7 @@ export type Resolver = (
   args: {
     data: Record<string, unknown>
     locale?: string
+    trash?: boolean
     where?: Where
   },
   context: {
@@ -30,6 +31,7 @@ export function countResolver(collection: Collection): Resolver {
     const options = {
       collection,
       req: isolateObjectProperty(req, 'transactionID'),
+      trash: args.trash,
       where: args.where,
     }
 

packages/graphql/src/schema/initCollections.ts

@@ -239,6 +239,7 @@ export function initCollections({ config, graphqlResult }: InitCollectionsGraphQ
         }),
         args: {
           draft: { type: GraphQLBoolean },
+          trash: { type: GraphQLBoolean },
           where: { type: collection.graphQL.whereInputType },
           ...(config.localization
             ? {

packages/payload/src/collections/endpoints/count.ts

@@ -8,13 +8,15 @@ import { countOperation } from '../operations/count.js'
 
 export const countHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
-  const { where } = req.query as {
+  const { trash, where } = req.query as {
+    trash?: string
     where?: Where
   }
 
   const result = await countOperation({
     collection,
     req,
+    trash: trash === 'true',
     where,
   })
 

packages/payload/src/collections/operations/count.ts

@@ -7,6 +7,7 @@ import { executeAccess } from '../../auth/executeAccess.js'
 import { combineQueries } from '../../database/combineQueries.js'
 import { validateQueryPaths } from '../../database/queryValidation/validateQueryPaths.js'
 import { sanitizeWhereQuery } from '../../database/sanitizeWhereQuery.js'
+import { appendNonTrashedFilter } from '../../utilities/appendNonTrashedFilter.js'
 import { killTransaction } from '../../utilities/killTransaction.js'
 import { buildAfterOperation } from './utils.js'
 
@@ -15,6 +16,7 @@ export type Arguments = {
   disableErrors?: boolean
   overrideAccess?: boolean
   req?: PayloadRequest
+  trash?: boolean
   where?: Where
 }
 
@@ -47,6 +49,7 @@ export const countOperation = async <TSlug extends CollectionSlug>(
       disableErrors,
       overrideAccess,
       req,
+      trash = false,
       where,
     } = args
 
@@ -71,9 +74,16 @@ export const countOperation = async <TSlug extends CollectionSlug>(
 
     let result: { totalDocs: number }
 
-    const fullWhere = combineQueries(where!, accessResult!)
+    let fullWhere = combineQueries(where!, accessResult!)
     sanitizeWhereQuery({ fields: collectionConfig.flattenedFields, payload, where: fullWhere })
 
+    // Exclude trashed documents when trash: false
+    fullWhere = appendNonTrashedFilter({
+      enableTrash: collectionConfig.trash,
+      trash,
+      where: fullWhere,
+    })
+
     await validateQueryPaths({
       collectionConfig,
       overrideAccess: overrideAccess!,

packages/payload/src/collections/operations/local/count.ts

@@ -41,6 +41,15 @@ export type Options<TSlug extends CollectionSlug> = {
    * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
    */
   req?: Partial<PayloadRequest>
+  /**
+   * When set to `true`, the query will include both normal and trashed documents.
+   * To query only trashed documents, pass `trash: true` and combine with a `where` clause filtering by `deletedAt`.
+   * By default (`false`), the query will only include normal documents and exclude those with a `deletedAt` field.
+   *
+   * This argument has no effect unless `trash` is enabled on the collection.
+   * @default false
+   */
+  trash?: boolean
   /**
    * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
    */
@@ -55,7 +64,13 @@ export async function countLocal<TSlug extends CollectionSlug>(
   payload: Payload,
   options: Options<TSlug>,
 ): Promise<{ totalDocs: number }> {
-  const { collection: collectionSlug, disableErrors, overrideAccess = true, where } = options
+  const {
+    collection: collectionSlug,
+    disableErrors,
+    overrideAccess = true,
+    trash = false,
+    where,
+  } = options
 
   const collection = payload.collections[collectionSlug]
 
@@ -70,6 +85,7 @@ export async function countLocal<TSlug extends CollectionSlug>(
     disableErrors,
     overrideAccess,
     req: await createLocalReq(options as CreateLocalReqOptions, payload),
+    trash,
     where,
   })
 }

test/trash/int.spec.ts

@@ -709,6 +709,35 @@ describe('trash', () => {
         ).rejects.toThrow(/Cannot restore a version of a trashed document/i)
       })
     })
+
+    describe('count operation', () => {
+      it('should return total count of non-soft-deleted documents by default (trash: false)', async () => {
+        const result = await payload.count({
+          collection: postsSlug,
+        })
+
+        expect(result.totalDocs).toEqual(1) // Only postsDocOne
+      })
+
+      it('should return total count of all documents including soft-deleted when trash: true', async () => {
+        const result = await payload.count({
+          collection: postsSlug,
+          trash: true,
+        })
+
+        expect(result.totalDocs).toEqual(2)
+      })
+
+      it('should return count of only soft-deleted documents when where[deletedAt][exists]=true', async () => {
+        const result = await payload.count({
+          collection: postsSlug,
+          trash: true,
+          where: { deletedAt: { exists: true } },
+        })
+
+        expect(result.totalDocs).toEqual(1) // Only postsDocTwo
+      })
+    })
   })
 
   describe('REST API', () => {
@@ -1055,6 +1084,30 @@ describe('trash', () => {
         )
       })
     })
+
+    describe('count endpoint', () => {
+      it('should return count of non-soft-deleted docs by default (trash=false)', async () => {
+        const res = await restClient.GET(`/${postsSlug}/count`)
+        expect(res.status).toBe(200)
+        const data = await res.json()
+        expect(data.totalDocs).toEqual(1)
+      })
+
+      it('should return count of all docs including soft-deleted when trash=true', async () => {
+        const res = await restClient.GET(`/${postsSlug}/count?trash=true`)
+        expect(res.status).toBe(200)
+        const data = await res.json()
+        expect(data.totalDocs).toEqual(2)
+      })
+
+      it('should return count of only soft-deleted docs with trash=true & where[deletedAt][exists]=true', async () => {
+        const res = await restClient.GET(
+          `/${postsSlug}/count?trash=true&where[deletedAt][exists]=true`,
+        )
+        const data = await res.json()
+        expect(data.totalDocs).toEqual(1)
+      })
+    })
   })
 
   describe('GRAPHQL API', () => {
@@ -1632,5 +1685,52 @@ describe('trash', () => {
         )
       })
     })
+
+    describe('count query', () => {
+      it('should return count of non-soft-deleted documents by default (trash=false)', async () => {
+        const query = `
+          query {
+            countPosts {
+              totalDocs
+            }
+          }
+        `
+        const res = await restClient
+          .GRAPHQL_POST({ body: JSON.stringify({ query }) })
+          .then((r) => r.json())
+
+        expect(res.data.countPosts.totalDocs).toBe(1)
+      })
+
+      it('should return count of all documents including soft-deleted when trash=true', async () => {
+        const query = `
+          query {
+            countPosts(trash: true) {
+              totalDocs
+            }
+          }
+        `
+        const res = await restClient
+          .GRAPHQL_POST({ body: JSON.stringify({ query }) })
+          .then((r) => r.json())
+
+        expect(res.data.countPosts.totalDocs).toBe(2)
+      })
+
+      it('should return count of only soft-deleted docs with where[deletedAt][exists]=true', async () => {
+        const query = `
+          query {
+            countPosts(trash: true, where: { deletedAt: { exists: true } }) {
+              totalDocs
+            }
+          }
+        `
+        const res = await restClient
+          .GRAPHQL_POST({ body: JSON.stringify({ query }) })
+          .then((r) => r.json())
+
+        expect(res.data.countPosts.totalDocs).toBe(1)
+      })
+    })
   })
 })