@effectstream/log 0.100.22 → 0.100.23

package/package.json

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

package/src/mod.ts

@@ -11,6 +11,10 @@ export {
 } from "./const.ts";
 export { attachTransport } from "./tslog.ts";
 export { DefaultLogLevels } from "./tslog.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

@@ -0,0 +1,62 @@
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { log } from "./mod.ts";
+
+/**
+ * Install a process-wide `unhandledRejection` handler.
+ *
+ * By default the handler logs the error at ERROR and re-crashes the process
+ * via `process.exit(1)` — preserving the "let it crash" semantic that Node /
+ * Bun apply when no handler is registered. The point of installing this
+ * handler is *visibility*: without it, Bun crashes silently with no log line
+ * about what the rejection actually was.
+ *
+ * Pass `shouldSurvive` to opt specific errors out of the crash — useful for
+ * known-transient failures from external systems (e.g. a pg pool ECONNRESET
+ * from a serverless Postgres cold-start). Surviving errors are logged at
+ * WARN; non-surviving ones at ERROR before exit.
+ *
+ * Idempotent: only the first call in this module registers a listener.
+ */
+let unhandledRejectionLoggerInstalled = false;
+
+/**
+ * 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,
+  onFatal: (code: number) => void = (code) => process.exit(code),
+): (reason: unknown) => void {
+  return (reason: unknown) => {
+    const survive = shouldSurvive?.(reason) ?? false;
+    log.remote(
+      componentName,
+      ["unhandledRejection"],
+      survive ? SeverityNumber.WARN : SeverityNumber.ERROR,
+      (log) => log(reason),
+    );
+    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]);
+});