---
name: bijection-cascading-delete
description: "Evaluate and integrate the Cascading Delete component with Bijection."
---

# Cascading Delete

A Bijection component for managing cascading deletes across related documents with atomic and batched deletion modes.

- Package: @bijectionhq/cascading-delete
- Category: Database & Backend
- Status: Reference
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/cascading-delete/tree/68b7f60fd6bc1b333d1a71f4093e2153e40992ee
- Upstream: https://github.com/akshatsinha0/convex-cascading-delete/tree/074bf116878e875b6f95b3e7c1b7e6abfea916b7
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/cascading-delete

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/cascading-delete.git
cd cascading-delete
git checkout 68b7f60fd6bc1b333d1a71f4093e2153e40992ee
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @00akshatsinha00/convex-cascading-delete. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Cascading Delete

## Instructions

Convex Cascading Delete lets you define declarative relationship rules between tables and then delete a root document with all its dependents automatically. It supports two deletion modes: inline (single atomic transaction) for small trees and batched (scheduled across multiple transactions) for large trees. The component works with existing schemas and indexes without requiring any schema migrations, and returns a per-table deletion summary for observability.

### Installation

```bash
npm install @00akshatsinha00/convex-cascading-delete
```

## Use cases

- Deleting a user account and automatically removing all their posts, comments, and other associated records without writing manual cleanup logic
- Removing an organization record and all nested teams, members, projects, and files where the total document count could exceed Convex transaction limits
- Enforcing referential integrity in a Convex app that lacks foreign key constraints at the database level
- Tracking progress of a large multi-batch deletion job in a React UI using the returned job ID and the useDeletionJobStatus hook
- Guarding critical mutations against accidental direct db.delete calls by wrapping the database context with the patchDb safety proxy

## How it works

You define cascade rules using `defineCascadeRules`, mapping source tables to target tables via existing index names and field names. These rules are passed to a `CascadingDelete` instance constructed with the component reference from `components.convexCascadingDelete`. The component validates that all referenced indexes exist at startup via `validateRules`, catching configuration errors before they surface at delete time.

For small to medium deletion trees, `deleteWithCascade` performs a depth-first post-order traversal, deleting children before parents, within a single Convex mutation transaction. A visited set prevents infinite loops in circular or diamond dependency graphs. For larger trees, `deleteWithCascadeBatched` first collects all deletion targets via a read-only traversal, deletes the first batch inline, then schedules remaining batches through the component's internal job system using a function reference you export via `makeBatchDeleteHandler`.

The batched mode requires you to export a `_cascadeBatchHandler` internal mutation created by `makeBatchDeleteHandler`, which the component's scheduler invokes with each batch of `{ table, id }` targets. This handler calls `ctx.db.delete` for each target and reports completion back to the component. Each batch runs as its own Convex transaction, so consistency is atomic per batch but eventual across batches.

A React hook, `useDeletionJobStatus`, accepts the `jobId` returned by `deleteWithCascadeBatched` and reactively subscribes to job state, exposing fields like `status`, `completedCount`, `totalTargetCount`, and a serialized `completedSummary` for rendering progress UI.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Cascading Delete is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%4000akshatsinha00%2Fconvex-cascading-delete)
- [GitHub repository](https://github.com/akshatsinha0/convex-cascading-delete)
- [Live demo](https://convex-cascading-delete.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/00akshatsinha00/convex-cascading-delete)
- [Convex documentation](https://docs.convex.dev)