@crewhaus/abort-controller 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@crewhaus/abort-controller",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Parent/child abort tree with WeakRef cascade for cooperative cancellation",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/abort-controller"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/abort-controller#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import { createAbortTree } from "./index";
+
+describe("createAbortTree — basics", () => {
+  test("root has an unsignalled signal", () => {
+    const root = createAbortTree();
+    expect(root.signal.aborted).toBe(false);
+  });
+
+  test("aborting root signals its signal", () => {
+    const root = createAbortTree();
+    root.abort();
+    expect(root.signal.aborted).toBe(true);
+  });
+
+  test("abort reason propagates", () => {
+    const root = createAbortTree();
+    root.abort(new Error("test reason"));
+    expect((root.signal.reason as Error).message).toBe("test reason");
+  });
+});
+
+describe("parent → child cascade", () => {
+  test("parent abort cascades to child", () => {
+    const root = createAbortTree();
+    const child = root.child();
+    expect(child.signal.aborted).toBe(false);
+    root.abort();
+    expect(child.signal.aborted).toBe(true);
+  });
+
+  test("parent abort cascades to grandchild", () => {
+    const root = createAbortTree();
+    const child = root.child();
+    const grandchild = child.child();
+    root.abort();
+    expect(child.signal.aborted).toBe(true);
+    expect(grandchild.signal.aborted).toBe(true);
+  });
+
+  test("siblings are independent", () => {
+    const root = createAbortTree();
+    const a = root.child();
+    const b = root.child();
+    a.abort();
+    expect(a.signal.aborted).toBe(true);
+    expect(b.signal.aborted).toBe(false);
+    expect(root.signal.aborted).toBe(false);
+  });
+
+  test("child abort does NOT propagate to parent", () => {
+    const root = createAbortTree();
+    const child = root.child();
+    child.abort();
+    expect(child.signal.aborted).toBe(true);
+    expect(root.signal.aborted).toBe(false);
+  });
+
+  test("child constructed from already-aborted parent is born aborted", () => {
+    const root = createAbortTree();
+    root.abort();
+    const child = root.child();
+    expect(child.signal.aborted).toBe(true);
+  });
+
+  test("createAbortTree(parent) — external parent signal", () => {
+    const ctl = new AbortController();
+    const tree = createAbortTree(ctl.signal);
+    expect(tree.signal.aborted).toBe(false);
+    ctl.abort();
+    expect(tree.signal.aborted).toBe(true);
+  });
+});
+
+// T3: Integration — abort the parent and observe a real Bun.spawn'd child
+// process exit (SIGTERM cascade via { signal }).
+describe("T3 — child-process SIGTERM on parent abort", () => {
+  test("Bun.spawn(['sleep', '30'], { signal: child.signal }) exits when parent aborts", async () => {
+    const root = createAbortTree();
+    const child = root.child();
+
+    const proc = Bun.spawn(["sleep", "30"], {
+      signal: child.signal,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const start = Date.now();
+    // Abort 100 ms in to make sure the spawn has time to start.
+    setTimeout(() => root.abort(), 100);
+
+    const exitCode = await proc.exited;
+    const elapsedMs = Date.now() - start;
+
+    expect(elapsedMs).toBeLessThan(2_000); // sleep 30 — would have run for 30 s without abort
+    expect(child.signal.aborted).toBe(true);
+    // Bun's signal-driven exit yields a non-zero exit code (typically null/143).
+    // We just assert the process ended early.
+    expect(exitCode).not.toBe(0);
+  });
+});

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Catalog R1 `abort-controller` — parent/child cancellation tree.
+ *
+ * Semantics:
+ *   - Parent abort cascades to all children (recursively).
+ *   - Sibling abort does NOT propagate.
+ *   - Child abort does NOT propagate up to the parent.
+ *   - If `parent` is already aborted at construction time, the child is born aborted.
+ *
+ * Memory: parent → child propagation goes through WeakRefs so an abandoned
+ * child doesn't pin the parent, and a finalized child's listener is removed
+ * from the parent on its own abort. Mirrors the proven pattern in
+ * `claude-code/utils/abortController.ts`.
+ *
+ * Listener limit: Node's default of 10 trips a warning when a busy turn fans
+ * out into many tool calls; we raise it to 50 per signal.
+ */
+import { setMaxListeners } from "node:events";
+
+const MAX_LISTENERS_PER_SIGNAL = 50;
+
+export type AbortTree = {
+  readonly signal: AbortSignal;
+  abort(reason?: unknown): void;
+  child(): AbortTree;
+};
+
+/**
+ * Build an `AbortTree` rooted at the given parent (or no parent for a fresh
+ * root). The returned tree's `child()` produces children whose `signal`
+ * fires when this tree's `signal` fires.
+ */
+export function createAbortTree(parent?: AbortSignal): AbortTree {
+  const controller = new AbortController();
+  setMaxListeners(MAX_LISTENERS_PER_SIGNAL, controller.signal);
+
+  if (parent !== undefined) {
+    if (parent.aborted) {
+      controller.abort(parent.reason);
+    } else {
+      attachParent(parent, controller);
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    abort(reason?: unknown) {
+      controller.abort(reason);
+    },
+    child() {
+      return createAbortTree(controller.signal);
+    },
+  };
+}
+
+/**
+ * Wire `parent` so its abort propagates to `childCtl`. Uses WeakRefs both ways
+ * so neither the parent nor the listener pins the other.
+ */
+function attachParent(parent: AbortSignal, childCtl: AbortController): void {
+  const weakChild = new WeakRef(childCtl);
+
+  function onParentAbort(this: AbortSignal): void {
+    const ctl = weakChild.deref();
+    if (ctl !== undefined && !ctl.signal.aborted) {
+      ctl.abort(this.reason);
+    }
+  }
+
+  parent.addEventListener("abort", onParentAbort, { once: true });
+
+  // When the child aborts on its own, drop the parent listener so the parent
+  // doesn't accumulate dead listeners across many children.
+  childCtl.signal.addEventListener(
+    "abort",
+    () => {
+      parent.removeEventListener("abort", onParentAbort);
+    },
+    { once: true },
+  );
+}