soft-delete

Soft delete

Never lose your Payload documents again, soft delete is here to save the day.

soft-delete.mp4

Compatibility table

Payload version	Soft delete version
v3.23.0 or earlier	Incompatible
v3.24.0 or later	v1.x

Quick start

1. Install the plugin:

pnpm add @payload-bites/soft-delete

2. Add the plugin to your payload.config.ts:

// ...
import { softDeletePlugin } from "@payload-bites/soft-delete";

export default buildConfig({
  // ...
  plugins: [
    // ...
    softDeletePlugin({
      collections: {
        posts: {},
        "posts-with-drafts": {
          // ...
          enableRestore: false,
          enableHardDelete: false,
          softDeleteAccess: (args) => args.req.user.role === "admin",
        },
      },
    }),
  ],
});

Defaults

For defaults, refer to defaults.ts.

Options

For options, refer to types.ts.

Querying

You can retrieve active or soft deleted documents by checking for the existence of the deletedAt field.

Local API

const result = await payload.find({
  collection: "posts",
  where: {
    deletedAt: {
      exists: false,
    },
  },
});

REST API

import { stringify } from "qs-esm";
import type { Where } from "payload";

const query: Where = {
  deletedAt: {
    exists: false,
  },
};

const getPosts = async () => {
  const stringifiedQuery = stringify(
    {
      where: query,
    },
    { addQueryPrefix: true },
  );

  const response = await fetch(
    `http://localhost:3000/api/posts${stringifiedQuery}`,
  );
};

GraphQL API

query {
  Posts(where: { deletedAt: { exists: false } }) {
    docs {
      title
    }
  }
}

Caveats

• It is currently not possible to soft delete a draft document that has invalid fields (e.g. required) unless the document has a previously valid published version or you resolve the invalid fields.

Roadmap

• Add modal to hard delete.
• Enable/disable restore functionality per collection.
• Enable/disable hard delete functionality per collection.
• Schedule automatic deletion after certain number of days.
• Documentation (including API examples).
• Translations.