Cascading Delete

Copy codenpm install @00akshatsinha00/convex-cascading-delete

Copy code// 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;

Copy code// 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
);

Copy code// 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 }
  }
});

Copy code// 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;
  }
});

Copy codeconst 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)
    }
  ]
});

Copy codeconst cd = new CascadingDelete(components.convexCascadingDelete, { rules });

Copy codeconst summary: DeletionSummary = await cd.deleteWithCascade(ctx, "users", userId);
// Returns: { users: 1, posts: 5, comments: 23 }

Copy codeconst 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

Copy codeawait cd.validateRules(ctx);
// Throws descriptive error if any index is missing or misconfigured

Copy codeexport 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
  }
});

Copy codeimport { makeBatchDeleteHandler } from "@00akshatsinha00/convex-cascading-delete";
import { components } from "./_generated/api";
import { internalMutation } from "./_generated/server";

export const _cascadeBatchHandler = makeBatchDeleteHandler(
  internalMutation,
  components.convexCascadingDelete
);

Copy codeimport { 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 (
    <div>
      <progress value={progress} max={100} />
      <p>{status.status}: {status.completedCount} / {status.totalTargetCount}</p>
      {status.status === "completed" && (
        <pre>{JSON.stringify(JSON.parse(status.completedSummary), null, 2)}</pre>
      )}
    </div>
  );
}

Copy codeimport type {
  CascadeRule,       // { to: string; via: string; field: string }
  CascadeConfig,     // { [sourceTable: string]: CascadeRule[] }
  DeletionSummary,   // { [tableName: string]: number }
  DeletionTarget,    // { table: string; id: string }
  BatchJobStatus,    // { status, totalTargetCount, completedCount, completedSummary, error? }
} from "@00akshatsinha00/convex-cascading-delete";

Copy code// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
  }),

  posts: defineTable({
    authorId: v.id("users"),
    title: v.string(),
    content: v.string(),
  }).index("byAuthorId", ["authorId"]),  // Required for cascade from users

  comments: defineTable({
    authorId: v.id("users"),
    postId: v.id("posts"),
    text: v.string(),
  })
    .index("byAuthorId", ["authorId"])   // For user → comments cascade
    .index("byPostId", ["postId"]),      // For post → comments cascade
});

Copy codeconst rules = defineCascadeRules({
  users: [
    { to: "posts", via: "byAuthorId", field: "authorId" },
    { to: "comments", via: "byAuthorId", field: "authorId" }
  ],
  posts: [
    { to: "comments", via: "byPostId", field: "postId" }
  ]
});

Copy codeconst rules = defineCascadeRules({
  organizations: [
    { to: "teams", via: "byOrganizationId", field: "organizationId" }
  ],
  teams: [
    { to: "members", via: "byTeamId", field: "teamId" },
    { to: "projects", via: "byTeamId", field: "teamId" }
  ],
  projects: [
    { to: "tasks", via: "byProjectId", field: "projectId" }
  ],
  tasks: [
    { to: "comments", via: "byTaskId", field: "taskId" }
  ]
});

// Deleting an organization cascades through 5 levels
const summary = await cd.deleteWithCascade(ctx, "organizations", orgId);
// Returns: { organizations: 1, teams: 5, members: 23, projects: 12, tasks: 67, comments: 234 }

Copy codeconst rules = defineCascadeRules({
  users: [
    { to: "posts", via: "byAuthorId", field: "authorId" },
    { to: "comments", via: "byAuthorId", field: "authorId" },
    { to: "likes", via: "byUserId", field: "userId" },
    { to: "follows", via: "byFollowerId", field: "followerId" }
  ]
});

Copy codeconst rules = defineCascadeRules({
  users: [
    { to: "friendships", via: "byUserId", field: "userId" }
  ],
  friendships: [
    { to: "users", via: "byFriendId", field: "friendId" }
  ]
});

// Safe - visited set prevents re-processing already-seen documents
const summary = await cd.deleteWithCascade(ctx, "users", userId);

Copy codeimport { mutation } from "./_generated/server";
import { cd } from "./cascading";

export const processUser = mutation({
  handler: async (ctx, args) => {
    // Replace ctx.db with a guarded version for this mutation
    const safeCtx = { ...ctx, db: cd.patchDb(ctx.db) };

    // All reads work normally
    const user = await safeCtx.db.get(args.userId);

    // Direct deletes are blocked - forces cascade usage
    // safeCtx.db.delete(args.userId)  --> throws Error

    // Must use cascade delete instead
    await cd.deleteWithCascade(ctx, "users", args.userId);
  }
});

┌─────────────────────────────────────────────────────────────────┐
│  YOUR APP                                                       │
│                                                                 │
│  ┌──────────────────────────────────┐                           │
│  │  Your Mutation                   │                           │
│  │                                  │                           │
│  │  const cd = new CascadingDelete( │                           │
│  │    components.convexCascadingDel,│                           │
│  │    { rules: cascadeRules }       │                           │
│  │  );                              │                           │
│  │                                  │  ctx.db (YOUR tables)     │
│  │  // Inline mode:                 │─────► .query(table)       │
│  │  cd.deleteWithCascade(ctx,       │       .withIndex(idx,...) │
│  │    "teams", teamId)              │       .collect()          │
│  │                                  │       .delete(id)         │
│  │  // Batched mode:                │                           │
│  │  cd.deleteWithCascadeBatched(ctx,│                           │
│  │    "teams", teamId, opts)        │                           │
│  │                                  │                           │
│  └──────────┬───────────────────────┘                           │
│             │                                                   │
│             │ ctx.runMutation(component.lib.createBatchJob, ...)│
│             │ ctx.runQuery(component.lib.getJobStatus, ...)     │
│             ▼                                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  COMPONENT (Isolated — own DB, own transactions)         │   │
│  │                                                          │   │
│  │  Table: deletionJobs                                     │   │
│  │    { status, targets, deleteHandle, batchSize, summary } │   │
│  │                                                          │   │
│  │  Functions:                                              │   │
│  │    createBatchJob(targets, handle, batchSize)            │   │
│  │    processNextBatch(jobId)                               │   │
│  │      ├─ scheduler.runAfter(0, deleteHandle, batch)     ──┼──►│
│  │      └─ scheduler.runAfter(200ms, self, jobId)           │   │
│  │    getJobStatus(jobId) → reactive query                  │   │
│  │    reportBatchComplete(jobId, summary)                   │   │
│  └──────────────────────────────────────────────────────────┘   │
│             │                                                   │
│             │ Function handle callback                          │
│             ▼                                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Your Batch Delete Handler (via makeBatchDeleteHandler)  │   │
│  │                                                          │   │
│  │  handler: async (ctx, { targets, jobId }) => {           │   │
│  │    for (t of targets) await ctx.db.delete(t.id);         │   │
│  │    await ctx.runMutation(component.reportBatchComplete,  │   │
│  │      { jobId, summary });                                │   │
│  │  }                                                       │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Copy codeimport { convexTest } from "convex-test";
import { register } from "@00akshatsinha00/convex-cascading-delete/test";
import schema from "./schema";

const modules = import.meta.glob("./convex/**/*.ts");

test("cascading delete works", async () => {
  const t = convexTest(schema, modules);
  register(t, "convexCascadingDelete");

  // ... your test code using the component
});

Copy code# Clone the repository
git clone https://github.com/akshatsinha0/convex-cascading-delete.git
cd convex-cascading-delete

# Install dependencies
npm install

# Start the dev server (backend + frontend + build watcher)
npm run dev

Copy codeawait cd.validateRules(ctx);
// Error: Cascade validation failed: Index "byAuthorId" with field "authorId"
// does not exist on table "posts". Define it in your schema.
// Source table: "users"

Copy codeconst status = await ctx.runQuery(
  components.convexCascadingDelete.lib.getJobStatus,
  { jobId }
);
console.log(status);
// { status: "processing", totalTargetCount: 500, completedCount: 200, ... }

Copy code// Instead of:
await cd.deleteWithCascade(ctx, "organizations", orgId);

// Use:
await cd.deleteWithCascadeBatched(ctx, "organizations", orgId, {
  batchHandlerRef: internal.cascading._cascadeBatchHandler,
  batchSize: 1000  // Reduce batch size if needed
});

Copy codeconst summary = await cd.deleteWithCascade(ctx, "users", userId as any);