@effectstream/log 0.100.20 → 0.100.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/log",
-  "version": "0.100.20",
+  "version": "0.100.21",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -13,7 +13,7 @@
   },
   "exports": "./src/mod.ts",
   "dependencies": {
-    "@effectstream/utils": "0.100.20",
+    "@effectstream/utils": "0.100.21",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "0.56.0",
     "@opentelemetry/exporter-logs-otlp-http": "0.56.0",

package/src/mod.ts

@@ -11,7 +11,10 @@ export {
 } from "./const.ts";
 export { attachTransport } from "./tslog.ts";
 export { DefaultLogLevels } from "./tslog.ts";
-export { installUnhandledRejectionLogger } from "./process-handlers.ts";
+export {
+  buildUnhandledRejectionHandler,
+  installUnhandledRejectionLogger,
+} from "./process-handlers.ts";
 
 // re-exporting this
 // so that we don't need to re-import opentelemetry in every component

package/src/process-handlers.ts

@@ -19,13 +19,25 @@ import { log } from "./mod.ts";
  */
 let unhandledRejectionLoggerInstalled = false;
 
-export function installUnhandledRejectionLogger(
+/**
+ * Build the `unhandledRejection` handler in isolation from `process.on`.
+ *
+ * The fatal-exit step is injected (`onFatal`, defaulting to `process.exit`) so
+ * the decision — *does this rejection crash the process or survive?* — can be
+ * exercised in a test without actually killing the test runner. This is the
+ * unit-level guard for the zombie failure mode: anything that is **not**
+ * classified survivable (e.g. a generic error escaping the effection root)
+ * must hit `onFatal`, never just log-and-continue.
+ *
+ * @returns the number of `onFatal` calls would-be (for the install path this is
+ * ignored; tests inspect their injected spy).
+ */
+export function buildUnhandledRejectionHandler(
   componentName: string,
   shouldSurvive?: (reason: unknown) => boolean,
-): void {
-  if (unhandledRejectionLoggerInstalled) return;
-  unhandledRejectionLoggerInstalled = true;
-  process.on("unhandledRejection", (reason: unknown) => {
+  onFatal: (code: number) => void = (code) => process.exit(code),
+): (reason: unknown) => void {
+  return (reason: unknown) => {
     const survive = shouldSurvive?.(reason) ?? false;
     log.remote(
       componentName,
@@ -33,6 +45,18 @@ export function installUnhandledRejectionLogger(
       survive ? SeverityNumber.WARN : SeverityNumber.ERROR,
       (log) => log(reason),
     );
-    if (!survive) process.exit(1);
-  });
+    if (!survive) onFatal(1);
+  };
+}
+
+export function installUnhandledRejectionLogger(
+  componentName: string,
+  shouldSurvive?: (reason: unknown) => boolean,
+): void {
+  if (unhandledRejectionLoggerInstalled) return;
+  unhandledRejectionLoggerInstalled = true;
+  process.on(
+    "unhandledRejection",
+    buildUnhandledRejectionHandler(componentName, shouldSurvive),
+  );
 }

package/test/process-handlers.test.ts

@@ -0,0 +1,65 @@
+// Guards the zombie failure mode: the `unhandledRejection` handler must crash
+// the process for anything it cannot prove survivable. The `survive` handler
+// (logs WARN, no exit) is the dangerous branch — if a rejection that escapes
+// the effection root were mis-classified as survivable, the whole effection
+// tree would be halted while the process stayed alive. These tests pin the
+// decision boundary using an injected `onFatal` spy instead of `process.exit`.
+
+import { test, expect } from "bun:test";
+import { buildUnhandledRejectionHandler } from "../src/mod.ts";
+
+const fatalSpy = () => {
+  const calls: number[] = [];
+  return { fn: (code: number) => calls.push(code), calls };
+};
+
+test("no shouldSurvive predicate => every rejection is fatal", () => {
+  const { fn, calls } = fatalSpy();
+  const handle = buildUnhandledRejectionHandler("test-component", undefined, fn);
+
+  handle(new Error("effection root died"));
+
+  expect(calls).toEqual([1]);
+});
+
+test("shouldSurvive=false => fatal (process exits)", () => {
+  const { fn, calls } = fatalSpy();
+  const handle = buildUnhandledRejectionHandler(
+    "test-component",
+    () => false,
+    fn,
+  );
+
+  handle(new Error("real logic bug"));
+
+  expect(calls).toEqual([1]);
+});
+
+test("shouldSurvive=true => survives (no exit)", () => {
+  const { fn, calls } = fatalSpy();
+  const handle = buildUnhandledRejectionHandler(
+    "test-component",
+    () => true,
+    fn,
+  );
+
+  handle({ code: "ECONNRESET", message: "transient pg blip" });
+
+  expect(calls).toEqual([]);
+});
+
+test("predicate decides per-rejection: only the survivable one is spared", () => {
+  const { fn, calls } = fatalSpy();
+  // Survive only objects carrying a `transient` marker; anything else is fatal.
+  const handle = buildUnhandledRejectionHandler(
+    "test-component",
+    (reason) => Boolean((reason as { transient?: boolean })?.transient),
+    fn,
+  );
+
+  handle({ transient: true }); // survivable -> no exit
+  expect(calls).toEqual([]);
+
+  handle(new Error("generic")); // not survivable -> exit
+  expect(calls).toEqual([1]);
+});