@guisao-llc/gambit-cascade 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import type { ClientSession, Types } from "mongoose";
+/**
+ * @guisao-llc/gambit-cascade
+ *
+ * Cascading deletion, minus the deletions.
+ *
+ * Mongo has no foreign keys, so "deleting this takes its dependents with it" is
+ * application code in every app that needs it. One app here spreads roughly 700
+ * lines of that across eight files; another does the same job in schema hooks.
+ * What those have in common is not the deletions — those are entirely domain —
+ * but the small amount of machinery around them: an operation interface, and a
+ * runner that executes a list of them in order.
+ *
+ * That is all this package is. It never touches a collection itself.
+ */
+/**
+ * One step of a cascade: delete what this subject owns in one collection.
+ *
+ * Generic over its arguments, because cascades are not all keyed the same way.
+ * Deleting a person runs on `(id, session)`. Deleting a ROLE runs on the role's
+ * NAME, because the accounts holding it store a name string rather than a
+ * reference — and that difference had produced a second, near-identical copy of
+ * the runner before this was generalized.
+ *
+ * The default parameter keeps the common case free of type noise.
+ */
+export interface CascadeOperation<TArgs extends unknown[] = [Types.ObjectId, ClientSession]> {
+    execute(...args: TArgs): Promise<void>;
+}
+/**
+ * Runs operations in order, inside the caller's transaction.
+ *
+ * Order is the caller's to decide and it matters: a leaf that RESOLVES a
+ * reference — reading `person.accountId` before the account is deleted — has to
+ * run before whatever removes the document it reads from.
+ *
+ * ── Why there is no per-operation catch ──────────────────────────────────────
+ *
+ * Deliberately none, and this is the load-bearing decision in the file.
+ *
+ * A cascade runs inside `session.withTransaction(...)`, so a throw from any
+ * leaf must abort the whole thing. Catching and continuing would let a PARTIAL
+ * delete commit: rows orphaned against a parent that no longer exists, silently,
+ * with no error anywhere. That is strictly worse than the failure it would be
+ * hiding, because the failure is loud and the orphans are not.
+ *
+ * If a step is genuinely allowed to fail, it catches its own error and resolves.
+ * Making that the exception rather than the default keeps it a visible decision.
+ *
+ * Composable: this is itself a `CascadeOperation`, so cascades nest.
+ */
+export declare class SequentialCascade<TArgs extends unknown[] = [Types.ObjectId, ClientSession]> implements CascadeOperation<TArgs> {
+    private readonly operations;
+    constructor(operations: CascadeOperation<TArgs>[]);
+    execute(...args: TArgs): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAErD;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB,CAC/B,KAAK,SAAS,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,aAAa,CAAC;IAEzD,OAAO,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAiB,CAC5B,KAAK,SAAS,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,aAAa,CAAC,CACzD,YAAW,gBAAgB,CAAC,KAAK,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE;IAE5D,OAAO,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;CAK7C"}

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SequentialCascade = void 0;
+/**
+ * Runs operations in order, inside the caller's transaction.
+ *
+ * Order is the caller's to decide and it matters: a leaf that RESOLVES a
+ * reference — reading `person.accountId` before the account is deleted — has to
+ * run before whatever removes the document it reads from.
+ *
+ * ── Why there is no per-operation catch ──────────────────────────────────────
+ *
+ * Deliberately none, and this is the load-bearing decision in the file.
+ *
+ * A cascade runs inside `session.withTransaction(...)`, so a throw from any
+ * leaf must abort the whole thing. Catching and continuing would let a PARTIAL
+ * delete commit: rows orphaned against a parent that no longer exists, silently,
+ * with no error anywhere. That is strictly worse than the failure it would be
+ * hiding, because the failure is loud and the orphans are not.
+ *
+ * If a step is genuinely allowed to fail, it catches its own error and resolves.
+ * Making that the exception rather than the default keeps it a visible decision.
+ *
+ * Composable: this is itself a `CascadeOperation`, so cascades nest.
+ */
+class SequentialCascade {
+    constructor(operations) {
+        this.operations = operations;
+    }
+    async execute(...args) {
+        for (const op of this.operations) {
+            await op.execute(...args);
+        }
+    }
+}
+exports.SequentialCascade = SequentialCascade;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAkCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,iBAAiB;IAI5B,YAA6B,UAAqC;QAArC,eAAU,GAAV,UAAU,CAA2B;IAAG,CAAC;IAEtE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAW;QAC1B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACjC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;CACF;AAXD,8CAWC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@guisao-llc/gambit-cascade",
+  "version": "0.1.0",
+  "description": "Sequential cascading deletion for databases without foreign keys.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Guisao-LLC/Gambit.git",
+    "directory": "packages/gambit-cascade"
+  },
+  "homepage": "https://github.com/Guisao-LLC/Gambit/tree/main/packages/gambit-cascade",
+  "keywords": [
+    "mongodb",
+    "mongoose",
+    "cascade",
+    "delete",
+    "referential-integrity"
+  ],
+  "engines": {
+    "node": ">=20 <23"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm run build && npm test && node ../../scripts/prepublish-check.mjs"
+  },
+  "peerDependencies": {
+    "mongoose": ">=8"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}