npmpackage.info

Gathering detailed insights and metrics for @roundtreasury/prisma-extension-soft-delete

@roundtreasury/prisma-extension-soft-delete - 1.1.0 | npmpackage.info

@roundtreasury/prisma-extension-soft-delete

Prisma extension for adding soft delete to Prisma models, even when using nested queries

1.1.0

Apache-2.0

TypeScript

94.51 kB

Installations

npm install @roundtreasury/prisma-extension-soft-delete

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Node Version

22.9.0

NPM Version

10.8.3 Pull Requests

Open

0

Total

1

Closed

0

Merged

1

Issues

Open

0

Total

0

Closed

0

Releases

v1.1.0

Updated on May 15, 2025

v1.0.1

Updated on May 15, 2025

View All 2 releases

Languages

TypeScript

JavaScript

Shell

TypeScript (99.6%)

JavaScript (0.3%)

Shell (0.1%)

Developer

round-cash

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

GitHub Statistics

Apache-2.0 License

19 Commits

2 Branches

Updated on May 15, 2025

Maintainers

View All 1 Contributors

Package Meta Information

Latest Version

1.1.0

Package Id

@roundtreasury/prisma-extension-soft-delete@1.1.0

Unpacked Size

94.51 kB

Size

15.83 kB

File Count

NPM Version

10.8.3

Node Version

22.9.0

Published on

May 15, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Prisma Extension Soft Delete

Round Prisma extension for soft deleting records.

Soft deleting records is a common pattern in many applications. This library provides an extension for Prisma that allows you to soft delete records and exclude them from queries. It handles deleting records through relations and excluding soft deleted records when including relations or referencing them in where objects. It does this by using the prisma-extension-nested-operations library to handle nested relations.

Installation
Usage
- Extension Setup
- Prisma Schema Setup
Behaviour
LICENSE

Installation

This module is distributed via npm and should be installed as one of your project's dependencies:

npm install prisma-extension-soft-delete

@prisma/client is a peer dependency of this library, so you will need to install it if you haven't already:

npm install @prisma/client

Usage

Extension Setup

To add soft delete functionality to your Prisma client create the extension using the createSoftDeleteExtension function and pass it to client.$extends.

The createSoftDeleteExtension function takes a config object where you can define the models you want to use soft delete with.

1import { PrismaClient } from "@prisma/client";
2
3const client = new PrismaClient();
4
5const extendedClient = client.$extends(
6  createSoftDeleteExtension({
7    models: {
8      Comment: true,
9    },
10  })
11);

By default the extension will use a deleted field of type Boolean on the model. If you want to use a custom field name or value you can pass a config object for the model. For example to use a deletedAt field where the value is null by default and a DateTime when the record is deleted you would pass the following:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      Comment: {
5        field: "deletedAt",
6        createValue: (deleted) => {
7          if (deleted) return new Date();
8          return null;
9        },
10      },
11    },
12  })
13);

The field property is the name of the field to use for soft delete, and the createValue property is a function that takes a deleted argument and returns the value for whether the record is soft deleted or not. The createValue method must return a falsy value if the record is not deleted and a truthy value if it is deleted.

It is possible to setup soft delete for multiple models at once by passing a config for each model in the models object:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      Comment: true,
5      Post: true,
6    },
7  })
8);

To modify the default field and type for all models you can pass a defaultConfig:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      Comment: true,
5      Post: true,
6    },
7    defaultConfig: {
8      field: "deletedAt",
9      createValue: (deleted) => {
10        if (deleted) return new Date();
11        return null;
12      },
13    },
14  })
15);

When using the default config you can also override the default config for a specific model by passing a config object for that model:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      Comment: true,
5      Post: {
6        field: "deleted",
7        createValue: Boolean,
8      },
9    },
10    defaultConfig: {
11      field: "deletedAt",
12      createValue: (deleted) => {
13        if (deleted) return new Date();
14        return null;
15      },
16    },
17  })
18);

The config object also has a allowToOneUpdates option that can be used to allow updates to toOne relationships through nested updates. By default this is set to false and will throw an error if you try to update a toOne relationship through a nested update. If you want to allow this you can set allowToOneUpdates to true:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      Comment: {
5        field: "deleted",
6        createValue: Boolean,
7        allowToOneUpdates: true,
8      },
9    },
10  })
11);

For more information for why updating through toOne relationship is disabled by default see the Updating Records section.

Similarly to allowToOneUpdates there is an allowCompoundUniqueIndexWhere option that can be used to allow using where objects with compound unique index fields when using findUnique queries. By default this is set to false and will throw an error if you try to use a where with compound unique index fields. If you want to allow this you can set allowCompoundUniqueIndexWhere to true:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      Comment: {
5        field: "deleted",
6        createValue: Boolean,
7        allowCompoundUniqueIndexWhere: true,
8      },
9    },
10  })
11);

For more information for why updating through toOne relationship is disabled by default see the Excluding Soft Deleted Records in a findUnique Operation section.

To allow to one updates or compound unique index fields globally you can use the defaultConfig to do so:

1const extendedClient = client.$extends(
2  createSoftDeleteExtension({
3    models: {
4      User: true,
5      Comment: true,
6    },
7    defaultConfig: {
8      field: "deleted",
9      createValue: Boolean,
10      allowToOneUpdates: true,
11      allowCompoundUniqueIndexWhere: true,
12    },
13  })
14);

Prisma Schema Setup

The Prisma schema must be updated to include the soft delete field for each model you want to use soft delete with.

For models configured to use the default field and type you must add the deleted field to your Prisma schema manually. Using the Comment model configured in Extension Setup you would need add the following to the Prisma schema:

1model Comment {
2  deleted   Boolean  @default(false)
3  [other fields]
4}

If the Comment model was configured to use a deletedAt field where the value is null by default and a DateTime when the record is deleted you would need to add the following to your Prisma schema:

1model Comment {
2  deletedAt DateTime?
3  [other fields]
4}

Models configured to use soft delete that are related to other models through a toOne relationship must have this relationship defined as optional. This is because the extension will exclude soft deleted records when the relationship is included or selected. If the relationship is not optional the types for the relation will be incorrect and you may get runtime errors.

For example if you have an author relationship on the Comment model and the User model is configured to use soft delete you would need to change the relationship to be optional:

1model Comment {
2  authorId Int?
3  author   User?   @relation(fields: [authorId], references: [id])
4  [other fields]
5}

@unique fields on models that are configured to use soft deletes may cause problems due to the records not actually being deleted. If a record is soft deleted and then a new record is created with the same value for the unique field, the new record will not be created.

Behaviour

The main behaviour of the extension is to replace delete operations with update operations that set the soft delete field to the deleted value.

The extension also prevents accidentally fetching or updating soft deleted records by excluding soft deleted records from find queries, includes, selects and bulk updates. The extension does allow explicit queries for soft deleted records and allows updates through unique fields such is it's id. The reason it allows updates through unique fields is because soft deleted records can only be fetched explicitly so updates through a unique fields should be intentional.

Deleting Records

When deleting a record using the delete or deleteMany operations the extension will change the operation to an update operation and set the soft delete field to be the deleted value defined in the config for that model.

For example if the Comment model was configured to use the default deleted field of type Boolean the extension would change the delete operation to an update operation and set the deleted field to true.

Deleting a Single Record

When deleting a single record using the delete operation:

1await client.comment.delete({
2  where: {
3    id: 1,
4  },
5});

The extension would change the operation to:

1await client.comment.update({
2  where: {
3    id: 1,
4  },
5  data: {
6    deleted: true,
7  },
8});

Deleting Multiple Records

When deleting multiple records using the deleteMany operation:

1await client.comment.deleteMany({
2  where: {
3    id: {
4      in: [1, 2, 3],
5    },
6  },
7});

The extension would change the operation to:

1await client.comment.updateMany({
2  where: {
3    id: {
4      in: [1, 2, 3],
5    },
6  },
7  data: {
8    deleted: true,
9  },
10});

Deleting Through a relationship

When using a nested delete through a relationship the extension will change the nested delete operation to an update operation:

1await client.post.update({
2  where: {
3    id: 1,
4  },
5  data: {
6    comments: {
7      delete: {
8        where: {
9          id: 2,
10        },
11      },
12    },
13    author: {
14      delete: true,
15    },
16  },
17});

The extension would change the operation to:

1await client.post.update({
2  where: {
3    id: 1,
4  },
5  data: {
6    comments: {
7      update: {
8        where: {
9          id: 2,
10        },
11        data: {
12          deleted: true,
13        },
14      },
15    },
16    author: {
17      update: {
18        deleted: true,
19      },
20    },
21  },
22});

The same behaviour applies when using a nested deleteMany with a toMany relationship.

Hard Deletes

Hard deletes are not currently supported by this extension, when the extendedWhereUnique feature is supported it will be possible to explicitly hard delete a soft deleted record. In the meantime you can use the executeRaw operation to perform hard deletes.

Excluding Soft Deleted Records

When using the findUnique, findFirst and findMany operations the extension will modify the where object passed to exclude soft deleted records. It does this by adding an additional condition to the where object that excludes records where the soft delete field is set to the deleted value defined in the config for that model.

Excluding Soft Deleted Records in a `findFirst` Operation

When using a findFirst operation the extension will modify the where object to exclude soft deleted records, so for:

1await client.comment.findFirst({
2  where: {
3    id: 1,
4  },
5});

The extension would change the operation to:

1await client.comment.findFirst({
2  where: {
3    id: 1,
4    deleted: false,
5  },
6});

Excluding Soft Deleted Records in a `findMany` Operation

When using a findMany operation the extension will modify the where object to exclude soft deleted records, so for:

1await client.comment.findMany({
2  where: {
3    id: 1,
4  },
5});

The extension would change the operation to:

1await client.comment.findMany({
2  where: {
3    id: 1,
4    deleted: false,
5  },
6});

Excluding Soft Deleted Records in a `findUnique` Operation

When using a findUnique operation the extension will change the query to use findFirst so that it can modify the where object to exclude soft deleted records, so for:

1await client.comment.findUnique({
2  where: {
3    id: 1,
4  },
5});

The extension would change the operation to:

1await client.comment.findFirst({
2  where: {
3    id: 1,
4    deleted: false,
5  },
6});

When querying using a compound unique index in the where object the extension will throw an error by default. This is because it is not possible to use these types of where object with findFirst and it is not possible to exclude soft-deleted records when using findUnique. For example take the following query:

1await client.user.findUnique({
2  where: {
3    name_email: {
4      name: "foo",
5      email: "bar",
6    },
7  },
8});

Since the compound unique index @@unique([name, email]) is being queried through the name_email field of the where object the extension will throw to avoid accidentally returning a soft deleted record.

It is possible to override this behaviour by setting allowCompoundUniqueIndexWhere to true in the model config.

Updating Records

Updating records is split into three categories, updating a single record using a root operation, updating a single record through a relation and updating multiple records either through a root operation or a relation.

When updating a single record using a root operation such as update or upsert the extension will not modify the operation. This is because unless explicitly queried for soft deleted records should not be returned from queries, so if these operations are updating a soft deleted record it should be intentional.

When updating a single record through a relation the extension will throw an error by default. This is because it is not possible to filter out soft deleted records for nested toOne relations. For example take the following query:

1await client.post.update({
2  where: {
3    id: 1,
4  },
5  data: {
6    author: {
7      update: {
8        name: "foo",
9      },
10    },
11  },
12});

Since the author field is a toOne relation it does not support a where object. This means that if the author field is a soft deleted record it will be updated accidentally.

It is possible to override this behaviour by setting allowToOneUpdates to true in the extension config.

When updating multiple records using updateMany the extension will modify the where object passed to exclude soft deleted records. For example take the following query:

1await client.comment.updateMany({
2  where: {
3    id: 1,
4  },
5  data: {
6    content: "foo",
7  },
8});

The extension would change the operation to:

1await client.comment.updateMany({
2  where: {
3    id: 1,
4    deleted: false,
5  },
6  data: {
7    content: "foo",
8  },
9});

This also works when a toMany relation is updated:

1await client.post.update({
2  where: {
3    id: 1,
4  },
5  data: {
6    comments: {
7      updateMany: {
8        where: {
9          id: 1,
10        },
11        data: {
12          content: "foo",
13        },
14      },
15    },
16  },
17});

The extension would change the operation to:

1await client.post.update({
2  where: {
3    id: 1,
4  },
5  data: {
6    comments: {
7      updateMany: {
8        where: {
9          id: 1,
10          deleted: false,
11        },
12        data: {
13          content: "foo",
14        },
15      },
16    },
17  },
18});

Explicitly Updating Many Soft Deleted Records

When using the updateMany operation it is possible to explicitly update many soft deleted records by setting the deleted field to the deleted value defined in the config for that model. An example that would update soft deleted records would be:

1await client.comment.updateMany({
2  where: {
3    content: "foo",
4    deleted: true,
5  },
6  data: {
7    content: "bar",
8  },
9});

Where objects

When using a where query it is possible to reference models configured to use soft deletes. In this case the extension will modify the where object to exclude soft deleted records from the query, so for:

1await client.post.findMany({
2  where: {
3    id: 1,
4    comments: {
5      some: {
6        content: "foo",
7      },
8    },
9  },
10});

The extension would change the operation to:

1await client.post.findMany({
2  where: {
3    id: 1,
4    comments: {
5      some: {
6        content: "foo",
7        deleted: false,
8      },
9    },
10  },
11});

This also works when the where object includes logical operators:

1await client.post.findMany({
2  where: {
3    id: 1,
4    OR: [
5      {
6        comments: {
7          some: {
8            author: {
9              name: "Jack",
10            },
11          },
12        },
13      },
14      {
15        comments: {
16          none: {
17            author: {
18              name: "Jill",
19            },
20          },
21        },
22      },
23    ],
24  },
25});

The extension would change the operation to:

1await client.post.findMany({
2  where: {
3    id: 1,
4    OR: [
5      {
6        comments: {
7          some: {
8            deleted: false,
9            author: {
10              name: "Jack",
11            },
12          },
13        },
14      },
15      {
16        comments: {
17          none: {
18            deleted: false,
19            author: {
20              name: "Jill",
21            },
22          },
23        },
24      },
25    ],
26  },
27});

When using the every modifier the extension will modify the where object to exclude soft deleted records from the query in a different way, so for:

1await client.post.findMany({
2  where: {
3    id: 1,
4    comments: {
5      every: {
6        content: "foo",
7      },
8    },
9  },
10});

The extension would change the operation to:

1await client.post.findMany({
2  where: {
3    id: 1,
4    comments: {
5      every: {
6        OR: [{ deleted: { not: false } }, { content: "foo" }],
7      },
8    },
9  },
10});

This is because if the same logic that is used for some and none were to be used with every then the query would fail for cases where there are deleted models.

The deleted case uses the not operator to ensure that the query works for custom fields and types. For example if the field was configured to be deletedAt where the type is DateTime when deleted and null when not deleted then the query would be:

1await client.post.findMany({
2  where: {
3    id: 1,
4    comments: {
5      every: {
6        OR: [{ deletedAt: { not: null } }, { content: "foo" }],
7      },
8    },
9  },
10});

Explicitly Querying Soft Deleted Records

It is possible to explicitly query soft deleted records by setting the configured field in the where object. For example the following will include deleted records in the results:

1await client.comment.findMany({
2  where: {
3    deleted: true,
4  },
5});

It is also possible to explicitly query soft deleted records through relationships in the where object. For example the following will also not be modified:

1await client.post.findMany({
2  where: {
3    comments: {
4      some: {
5        deleted: true,
6      },
7    },
8  },
9});

Including or Selecting Soft Deleted Records

When using include or select the extension will modify the include and select objects passed to exclude soft deleted records.

Including or Selecting toMany Relations

When using include or select on a toMany relationship the extension will modify the where object to exclude soft deleted records from the query, so for:

1await client.post.findMany({
2  where: {
3    id: 1,
4  },
5  include: {
6    comments: true,
7  },
8});

If the Comment model was configured to be soft deleted the extension would modify the include action where object to exclude soft deleted records, so the query would be:

1await client.post.findMany({
2  where: {
3    id: 1,
4  },
5  include: {
6    comments: {
7      where: {
8        deleted: false,
9      },
10    },
11  },
12});

The same applies for select:

1await client.post.findMany({
2  where: {
3    id: 1,
4  },
5  select: {
6    comments: true,
7  },
8});

This also works for nested includes and selects:

1await client.user.findMany({
2  where: {
3    id: 1,
4  },
5  include: {
6    posts: {
7      select: {
8        comments: {
9          where: {
10            content: "foo",
11          },
12        },
13      },
14    },
15  },
16});

The extension would modify the query to:

1await client.user.findMany({
2  where: {
3    id: 1,
4  },
5  include: {
6    posts: {
7      select: {
8        comments: {
9          where: {
10            deleted: false,
11            content: "foo",
12          },
13        },
14      },
15    },
16  },
17});

Including or Selecting toOne Relations

Records included through a toOne relation are also excluded, however there is no way to explicitly include them. For example the following query:

1await client.post.findFirst({
2  where: {
3    id: 1,
4  },
5  include: {
6    author: true,
7  },
8});

The extension would not modify the query since toOne relations do not support where clauses. Instead the extension will manually filter results based on the configured deleted field.

So if the author of the Post was soft deleted the extension would filter the results and remove the author from the results:

1{
2  id: 1,
3  title: "foo",
4  author: null
5}

When selecting specific fields on a toOne relation the extension will manually add the configured deleted field to the select object, filter the results and finally strip the deleted field from the results before returning them.

For example the following query would behave that way:

1await client.post.findMany({
2  where: {
3    id: 1,
4  },
5  select: {
6    author: {
7      select: {
8        name: true,
9      },
10    },
11  },
12});

Explicitly Including Soft Deleted Records in toMany Relations

It is possible to explicitly include soft deleted records in toMany relations by adding the configured deleted field to the where object. For example the following will include deleted records in the results:

1await client.post.findMany({
2  where: {
3    id: 1,
4  },
5  include: {
6    comments: {
7      where: {
8        deleted: true,
9      },
10    },
11  },
12});

LICENSE

Apache 2.0

No vulnerabilities found.

No security vulnerabilities found.

@roundtreasury/prisma-extension-soft-delete

Installations

Developer Guide

Yes

CommonJS

22.9.0

10.8.3

Pull Requests

0

1

0

1

Issues

0

0

0

Releases

Languages

Developer

round-cash

Download Statistics

GitHub Statistics

Maintainers

Package Meta Information

Total Downloads

NaN

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

Peer Dependencies

Dev Dependencies

Prisma Extension Soft Delete

Table of Contents

Installation

Usage

Extension Setup

Prisma Schema Setup

Behaviour

Deleting Records

Deleting a Single Record

Deleting Multiple Records

Deleting Through a relationship

Hard Deletes

Excluding Soft Deleted Records

Excluding Soft Deleted Records in a findFirst Operation

Excluding Soft Deleted Records in a findMany Operation

Excluding Soft Deleted Records in a findUnique Operation

Updating Records

Explicitly Updating Many Soft Deleted Records

Where objects

Explicitly Querying Soft Deleted Records

Including or Selecting Soft Deleted Records

Including or Selecting toMany Relations

Including or Selecting toOne Relations

Explicitly Including Soft Deleted Records in toMany Relations

LICENSE

Excluding Soft Deleted Records in a `findFirst` Operation

Excluding Soft Deleted Records in a `findMany` Operation

Excluding Soft Deleted Records in a `findUnique` Operation