# 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.
## Upstream package documentation
Recorded 2026-10-23. This describes @00akshatsinha00/convex-cascading-delete; check the Bijection adaptation separately.
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.
### 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.
### Upstream README
# Convex Cascading Delete
A Convex component for managing cascading deletes across related documents. Configure relationships via existing indexes, then delete documents safely knowing all related records will be cleaned up automatically with clear consistency guarantees.
## Why Use This Component?
- **Works with existing schemas** - No migration to special schema definitions; uses your existing `defineTable` and indexes
- **Explicit configuration** - Clear, declarative rules for cascade relationships defined in one place
- **Two deletion modes** - Inline (atomic, single transaction) for small deletes, batched (scheduled) for large trees
- **Progress tracking** - React hook for real-time batch deletion progress with reactive updates
- **Safety guards** - Optional `patchDb` helper prevents accidental direct `db.delete` calls
- **Index validation** - Catch configuration errors at startup, not at delete time
- **Circular handling** - Automatically handles circular and diamond dependencies via visited set
- **Full observability** - Returns deletion summary with per-table document counts
- **Non-invasive** - Drop-in component that doesn't replace your schema builder or require code changes beyond deletion calls
## Pre-requisite: Convex
You'll need an existing Convex project to use this component. Convex is a hosted backend platform, including a database, serverless functions, and a bunch more you can learn about [here](https://docs.convex.dev/get-started).
Run `npm create convex` or follow any of the [Convex quickstarts](https://docs.convex.dev/home) to set one up.
## Installation
### Step 1: Install the package
```bash
npm install @00akshatsinha00/convex-cascading-delete
```
### Step 2: Add the component to your Convex app
```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import convexCascadingDelete from "@00akshatsinha00/convex-cascading-delete/convex.config";
const app = defineApp();
app.use(convexCascadingDelete);
export default app;
```
### Step 3: Configure cascade rules and instantiate
```ts
// convex/cascading.ts
import {
CascadingDelete,
defineCascadeRules,
makeBatchDeleteHandler
} from "@00akshatsinha00/convex-cascading-delete";
import { components } from "./_generated/api";
import { internalMutation } from "./_generated/server";
export const cascadeRules = defineCascadeRules({
users: [
{ to: "posts", via: "byAuthorId", field: "authorId" },
{ to: "comments", via: "byAuthorId", field: "authorId" }
],
posts: [
{ to: "comments", via: "byPostId", field: "postId" }
]
});
export const cd = new CascadingDelete(components.convexCascadingDelete, {
rules: cascadeRules
});
// Required for batched mode - exports an internal mutation that processes deletion batches
export const _cascadeBatchHandler = makeBatchDeleteHandler(
internalMutation,
components.convexCascadingDelete
);
```
## Quick Start
Use the configured `cd` instance in your mutations:
```ts
// convex/users.ts
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { cd } from "./cascading";
export const deleteUser = mutation({
args: { userId: v.id("users") },
handler: async (ctx, { userId }) => {
// Deletes user + all their posts + all comments on those posts
const summary = await cd.deleteWithCascade(ctx, "users", userId);
console.log("Deleted:", summary);
// Returns: { users: 1, posts: 5, comments: 23 }
}
});
```
For large deletion trees, use batched mode:
```ts
// convex/organizations.ts
import { mutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";
import { cd } from "./cascading";
export const deleteOrganization = mutation({
args: { orgId: v.id("organizations") },
handler: async (ctx, { orgId }) => {
const result = await cd.deleteWithCascadeBatched(
ctx,
"organizations",
orgId,
{
batchHandlerRef: internal.cascading._cascadeBatchHandler,
batchSize: 2000
}
);
// result.jobId can be used to track progress via useDeletionJobStatus hook
// result.initialSummary contains counts from the first inline batch
return result;
}
});
```
## API Reference
### `defineCascadeRules(config)`
Defines and validates cascade relationships between tables. Returns a frozen configuration object.
```ts
const rules = defineCascadeRules({
[sourceTable: string]: [
{
to: string, // Target table name to cascade to
via: string, // Index name on target table
field: string // Field in index used for equality matching (holds parent ID)
}
]
});
```
**Requirements:**
- The index specified by `via` must exist on the target table
- The index must include the field specified by `field`
- The `field` must contain IDs from the source table
**Validation performed:**
- All properties (`to`, `via`, `field`) must be present and be strings
- Duplicate rules (same `to:via:field` combination) are rejected
- Configuration must be a non-null object
### `CascadingDelete` Class
Main interface for deletion operations.
#### Constructor
```ts
const cd = new CascadingDelete(components.convexCascadingDelete, { rules });
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `component` | `ComponentApi` | Component reference from `components.convexCascadingDelete` |
| `options.rules` | `CascadeConfig` | Rules from `defineCascadeRules()` |
#### `deleteWithCascade(ctx, table, id)`
Deletes a document and all its cascading dependents in a single transaction. Uses depth-first post-order traversal (children deleted before parents) with a visited set for cycle detection.
```ts
const summary: DeletionSummary = await cd.deleteWithCascade(ctx, "users", userId);
// Returns: { users: 1, posts: 5, comments: 23 }
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `ctx` | `MutationCtx` | Convex mutation context |
| `table` | `string` | Source table name |
| `id` | `string` | Document ID to delete |
| **Returns** | `DeletionSummary` | Map of table names to deleted document counts |
**Best for:** Small to medium deletion trees (fewer than 4,000 documents)
**Consistency:** Fully atomic - all deletes succeed or all fail within a single Convex transaction
#### `deleteWithCascadeBatched(ctx, table, id, options)`
Deletes a document and its dependents across multiple batched transactions. Collects all targets first via read-only traversal, deletes the first batch inline, then schedules remaining batches via the component's job system.
```ts
const result = await cd.deleteWithCascadeBatched(
ctx,
"organizations",
orgId,
{
batchHandlerRef: internal.cascading._cascadeBatchHandler,
batchSize: 2000 // Optional, defaults to 2000
}
);
// Returns: { jobId: "j57a...", initialSummary: { organizations: 1, teams: 3 } }
// jobId is null if all targets fit in the first batch
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `ctx` | `MutationCtx` | Convex mutation context |
| `table` | `string` | Source table name |
| `id` | `string` | Document ID to delete |
| `options.batchHandlerRef` | `FunctionReference<"mutation">` | Reference to your exported batch handler (from `makeBatchDeleteHandler`) |
| `options.batchSize` | `number` (optional) | Documents per batch, defaults to 2000 |
| **Returns** | `{ jobId: string \| null, initialSummary: DeletionSummary }` | Job ID for tracking (null if all deleted inline) and first-batch summary |
**Best for:** Large deletion trees (any size)
**Consistency:** Per-batch atomic, inter-batch eventual. Each batch is a separate Convex transaction.
**Progress tracking:** Pass the returned `jobId` to the `useDeletionJobStatus` React hook
#### `validateRules(ctx)`
Validates that all configured indexes exist by probing each index with a test query. Should be called once during app initialization or in a dev-only check.
```ts
await cd.validateRules(ctx);
// Throws descriptive error if any index is missing or misconfigured
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `ctx` | `QueryCtx` | Convex query or mutation context |
#### `patchDb(db)`
Returns a proxied database writer that throws on direct `.delete()` calls, forcing all deletions to go through `deleteWithCascade`. Useful as a safety guard in critical mutations.
```ts
export const safeDeleteUser = mutation({
handler: async (ctx, args) => {
const safeDb = cd.patchDb(ctx.db);
// safeDb.delete(id) --> throws "Direct db.delete() is disabled"
// safeDb.query(...) --> works normally
// safeDb.insert(...) --> works normally
// safeDb.patch(...) --> works normally
}
});
```
### `makeBatchDeleteHandler(internalMutationBuilder, componentRef)`
Factory function that creates the app-side internal mutation for processing deletion batches. This function must be exported from your convex code so the component's scheduler can invoke it via a function handle.
```ts
import { makeBatchDeleteHandler } from "@00akshatsinha00/convex-cascading-delete";
import { components } from "./_generated/api";
import { internalMutation } from "./_generated/server";
export const _cascadeBatchHandler = makeBatchDeleteHandler(
internalMutation,
components.convexCascadingDelete
);
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `internalMutationBuilder` | `InternalMutation` | Your app's `internalMutation` builder from `_generated/server` |
| `componentRef` | `ComponentApi` | Component reference from `components.convexCascadingDelete` |
| **Returns** | `FunctionReference<"mutation">` | Internal mutation to pass as `batchHandlerRef` |
**How it works:** The returned mutation receives a batch of `{ table, id }` targets, deletes each one via `ctx.db.delete(id)`, then reports completion back to the component via `reportBatchComplete`. The component's scheduler calls this function handle with each batch.
### React Hook
#### `useDeletionJobStatus(api, jobId)`
Monitors batch deletion progress with reactive updates. Wraps the component's `getJobStatus` query.
```tsx
import { useDeletionJobStatus } from "@00akshatsinha00/convex-cascading-delete/react";
import { api } from "../convex/_generated/api";
function DeletionProgress({ jobId }: { jobId: string | null }) {
const status = useDeletionJobStatus(api, jobId);
if (!status) return null;
const progress = (status.completedCount / status.totalTargetCount) * 100;
return (