feat: adds trash support (soft deletes)

.github/workflows/main.yml

@@ -320,6 +320,7 @@ jobs:
           - plugin-nested-docs
           - plugin-seo
           - sort
+          - trash
           - versions
           - uploads
     env:
@@ -457,6 +458,7 @@ jobs:
           - plugin-nested-docs
           - plugin-seo
           - sort
+          - trash
           - versions
           - uploads
     env:

.vscode/launch.json

@@ -139,6 +139,13 @@
       "request": "launch",
       "type": "node-terminal"
     },
+    {
+      "command": "pnpm tsx --no-deprecation test/dev.ts trash",
+      "cwd": "${workspaceFolder}",
+      "name": "Run Dev Trash",
+      "request": "launch",
+      "type": "node-terminal"
+    },
     {
       "command": "pnpm tsx --no-deprecation test/dev.ts uploads",
       "cwd": "${workspaceFolder}",

docs/configuration/collections.mdx

@@ -79,6 +79,7 @@ The following options are available:
 | `lockDocuments`      | Enables or disables document locking. By default, document locking is enabled. Set to an object to configure, or set to `false` to disable locking. [More details](../admin/locked-documents).                                   |
 | `slug` \*            | Unique, URL-friendly string that will act as an identifier for this Collection.                                                                                                                                                  |
 | `timestamps`         | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps.                                                                                                                               |
+| `trash`              | A boolean to enable soft deletes for this collection. Defaults to `false`. [More details](../trash/overview).                                                                                                                    |
 | `typescript`         | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.                                                                                                              |
 | `upload`             | Specify options if you would like this Collection to support file uploads. For more, consult the [Uploads](../upload/overview) documentation.                                                                                    |
 | `versions`           | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#collection-config).                                                                                              |

docs/live-preview/server.mdx

@@ -51,6 +51,7 @@ export default async function Page() {
     collection: 'pages',
     id: '123',
     draft: true,
+    trash: true, // add this if trash is enabled in your collection and want to preview trashed documents
   })
 
   return (

docs/trash/overview.mdx

@@ -0,0 +1,199 @@
+---
+title: Trash
+label: Overview
+order: 10
+desc: Enable soft deletes for your collections to mark documents as deleted without permanently removing them.
+keywords: trash, soft delete, deletedAt, recovery, restore
+---
+
+Trash (also known as soft delete) allows documents to be marked as deleted without being permanently removed. When enabled on a collection, deleted documents will receive a `deletedAt` timestamp, making it possible to restore them later, view them in a dedicated Trash view, or permanently delete them.
+
+Soft delete is a safer way to manage content lifecycle, giving editors a chance to review and recover documents that may have been deleted by mistake.
+
+<Banner type="warning">
+  **Note:** The Trash feature is currently in beta and may be subject to change
+  in minor version updates.
+</Banner>
+
+## Collection Configuration
+
+To enable soft delete for a collection, set the `trash` property to `true`:
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const Posts: CollectionConfig = {
+  slug: 'posts',
+  trash: true,
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+    },
+    // other fields...
+  ],
+}
+```
+
+When enabled, Payload automatically injects a deletedAt field into the collection's schema. This timestamp is set when a document is soft-deleted, and cleared when the document is restored.
+
+## Admin Panel behavior
+
+Once `trash` is enabled, the Admin Panel provides a dedicated Trash view for each collection:
+
+- A new route is added at `/collections/:collectionSlug/trash`
+- The Trash view shows all documents that have a `deletedAt` timestamp
+
+From the Trash view, you can:
+
+- Use bulk actions to manage trashed documents:
+
+  - **Restore** to clear the `deletedAt` timestamp and return documents to their original state
+  - **Delete** to permanently remove selected documents
+  - **Empty Trash** to select and permanently delete all trashed documents at once
+
+- Enter each document's **edit view**, just like in the main list view. While in the edit view of a trashed document:
+  - All fields are in a **read-only** state
+  - All document actions (e.g. Save, Publish, Restore Version) are hidden or disabled
+  - Preserve access to the **API**, **Versions**, and **Preview** views
+
+When deleting a document from the main collection List View, Payload will soft-delete the document by default. A checkbox in the delete confirmation modal allows users to skip the trash and permanently delete instead.
+
+## API Support
+
+Soft deletes are fully supported across all Payload APIs: **Local**, **REST**, and **GraphQL**.
+
+The following operations respect and support the `trash` functionality:
+
+- `find`
+- `findByID`
+- `update`
+- `updateByID`
+- `delete`
+- `deleteByID`
+- `findVersions`
+- `findVersionByID`
+
+### Understanding `trash` Behavior
+
+Passing `trash: true` to these operations will **include soft-deleted documents** in the query results.
+
+To return _only_ soft-deleted documents, you must combine `trash: true` with a `where` clause that checks if `deletedAt` exists.
+
+### Examples
+
+#### Local API
+
+Return all documents including trashed:
+
+```ts
+const result = await payload.find({
+  collection: 'posts',
+  trash: true,
+})
+```
+
+Return only trashed documents:
+
+```ts
+const result = await payload.find({
+  collection: 'posts',
+  trash: true,
+  where: {
+    deletedAt: {
+      exists: true,
+    },
+  },
+})
+```
+
+Return only non-trashed documents:
+
+```ts
+const result = await payload.find({
+  collection: 'posts',
+  trash: false,
+})
+```
+
+#### REST
+
+Return **all** documents including trashed:
+
+```http
+GET /api/posts?trash=true
+```
+
+Return **only trashed** documents:
+
+```http
+GET /api/posts?trash=true&where[deletedAt][exists]=true
+```
+
+Return only non-trashed documents:
+
+```http
+GET /api/posts?trash=false
+```
+
+#### GraphQL
+
+Return all documents including trashed:
+
+```ts
+query {
+  Posts(trash: true) {
+    docs {
+      id
+      deletedAt
+    }
+  }
+}
+```
+
+Return only trashed documents:
+
+```ts
+query {
+  Posts(
+    trash: true
+    where: { deletedAt: { exists: true } }
+  ) {
+    docs {
+      id
+      deletedAt
+    }
+  }
+}
+```
+
+Return only non-trashed documents:
+
+```ts
+query {
+  Posts(trash: false) {
+    docs {
+      id
+      deletedAt
+    }
+  }
+}
+```
+
+## Access Control
+
+All trash-related actions (delete, permanent delete) respect the `delete` access control defined in your collection config.
+
+This means:
+
+- If a user is denied delete access, they cannot soft delete or permanently delete documents
+
+## Versions and Trash
+
+When a document is soft-deleted:
+
+- It can no longer have a version **restored** until it is first restored from trash
+- Attempting to restore a version while the document is in trash will result in an error
+- This ensures consistency between the current document state and its version history
+
+However, versions are still fully **visible and accessible** from the **edit view** of a trashed document. You can view the full version history, but must restore the document itself before restoring any individual version.

packages/drizzle/src/queries/sanitizeQueryValue.ts

@@ -112,9 +112,14 @@ export const sanitizeQueryValue = ({
 
   if (field.type === 'date' && operator !== 'exists') {
     if (typeof val === 'string') {
-      formattedValue = new Date(val).toISOString()
-      if (Number.isNaN(Date.parse(formattedValue))) {
-        return { operator, value: undefined }
+      if (val === 'null' || val === '') {
+        formattedValue = null
+      } else {
+        const date = new Date(val)
+        if (Number.isNaN(date.getTime())) {
+          return { operator, value: undefined }
+        }
+        formattedValue = date.toISOString()
       }
     } else if (typeof val === 'number') {
       formattedValue = new Date(val).toISOString()

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

@@ -11,6 +11,7 @@ export type Resolver<TSlug extends CollectionSlug> = (
     fallbackLocale?: string
     id: number | string
     locale?: string
+    trash?: boolean
   },
   context: {
     req: PayloadRequest
@@ -49,6 +50,7 @@ export function getDeleteResolver<TSlug extends CollectionSlug>(
       collection,
       depth: 0,
       req: isolateObjectProperty(req, 'transactionID'),
+      trash: args.trash,
     }
 
     const result = await deleteByIDOperation(options)

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

@@ -15,6 +15,7 @@ export type Resolver = (
     page?: number
     pagination?: boolean
     sort?: string
+    trash?: boolean
     where?: Where
   },
   context: {
@@ -57,6 +58,7 @@ export function findResolver(collection: Collection): Resolver {
       pagination: args.pagination,
       req,
       sort: args.sort,
+      trash: args.trash,
       where: args.where,
     }
 

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

@@ -11,6 +11,7 @@ export type Resolver<TData> = (
     fallbackLocale?: string
     id: string
     locale?: string
+    trash?: boolean
   },
   context: {
     req: PayloadRequest
@@ -50,6 +51,7 @@ export function findByIDResolver<TSlug extends CollectionSlug>(
       depth: 0,
       draft: args.draft,
       req: isolateObjectProperty(req, 'transactionID'),
+      trash: args.trash,
     }
 
     const result = await findByIDOperation(options)

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

@@ -10,6 +10,7 @@ export type Resolver<T extends TypeWithID = any> = (
     fallbackLocale?: string
     id: number | string
     locale?: string
+    trash?: boolean
   },
   context: {
     req: PayloadRequest
@@ -33,6 +34,7 @@ export function findVersionByIDResolver(collection: Collection): Resolver {
       collection,
       depth: 0,
       req: isolateObjectProperty(req, 'transactionID'),
+      trash: args.trash,
     }
 
     const result = await findVersionByIDOperation(options)

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

@@ -14,6 +14,7 @@ export type Resolver = (
     page?: number
     pagination?: boolean
     sort?: string
+    trash?: boolean
     where: Where
   },
   context: {
@@ -54,6 +55,7 @@ export function findVersionsResolver(collection: Collection): Resolver {
       pagination: args.pagination,
       req: isolateObjectProperty(req, 'transactionID'),
       sort: args.sort,
+      trash: args.trash,
       where: args.where,
     }
 

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

@@ -13,6 +13,7 @@ export type Resolver<TSlug extends CollectionSlug> = (
     fallbackLocale?: string
     id: number | string
     locale?: string
+    trash?: boolean
   },
   context: {
     req: PayloadRequest
@@ -54,6 +55,7 @@ export function updateResolver<TSlug extends CollectionSlug>(
       depth: 0,
       draft: args.draft,
       req: isolateObjectProperty(req, 'transactionID'),
+      trash: args.trash,
     }
 
     const result = await updateByIDOperation<TSlug>(options)