feat: add process exit handler

packages/utils/src/lib/exit-process.int.test.ts

@@ -0,0 +1,129 @@
+import process from 'node:process';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { SIGNAL_EXIT_CODES, installExitHandlers } from './exit-process.js';
+
+describe('installExitHandlers', () => {
+  const onError = vi.fn();
+  const onExit = vi.fn();
+  const processOnSpy = vi.spyOn(process, 'on');
+  const processExitSpy = vi.spyOn(process, 'exit').mockImplementation(vi.fn());
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    [
+      'uncaughtException',
+      'unhandledRejection',
+      'SIGINT',
+      'SIGTERM',
+      'SIGQUIT',
+      'exit',
+    ].forEach(event => {
+      process.removeAllListeners(event);
+    });
+  });
+
+  it('should install event listeners for all expected events', () => {
+    expect(() => installExitHandlers({ onError, onExit })).not.toThrow();
+
+    expect(processOnSpy).toHaveBeenCalledWith(
+      'uncaughtException',
+      expect.any(Function),
+    );
+    expect(processOnSpy).toHaveBeenCalledWith(
+      'unhandledRejection',
+      expect.any(Function),
+    );
+    expect(processOnSpy).toHaveBeenCalledWith('SIGINT', expect.any(Function));
+    expect(processOnSpy).toHaveBeenCalledWith('SIGTERM', expect.any(Function));
+    expect(processOnSpy).toHaveBeenCalledWith('SIGQUIT', expect.any(Function));
+    expect(processOnSpy).toHaveBeenCalledWith('exit', expect.any(Function));
+  });
+
+  it('should call onError with error and kind for uncaughtException', () => {
+    expect(() => installExitHandlers({ onError })).not.toThrow();
+
+    const testError = new Error('Test uncaught exception');
+
+    (process as any).emit('uncaughtException', testError);
+
+    expect(onError).toHaveBeenCalledWith(testError, 'uncaughtException');
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onExit).not.toHaveBeenCalled();
+  });
+
+  it('should call onError with reason and kind for unhandledRejection', () => {
+    expect(() => installExitHandlers({ onError })).not.toThrow();
+
+    const testReason = 'Test unhandled rejection';
+
+    (process as any).emit('unhandledRejection', testReason);
+
+    expect(onError).toHaveBeenCalledWith(testReason, 'unhandledRejection');
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onExit).not.toHaveBeenCalled();
+  });
+
+  it('should call onExit and exit with code 0 for SIGINT', () => {
+    expect(() => installExitHandlers({ onExit })).not.toThrow();
+
+    (process as any).emit('SIGINT');
+
+    expect(onExit).toHaveBeenCalledTimes(1);
+    expect(onExit).toHaveBeenCalledWith(SIGNAL_EXIT_CODES().SIGINT, {
+      kind: 'signal',
+      signal: 'SIGINT',
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('should call onExit and exit with code 0 for SIGTERM', () => {
+    expect(() => installExitHandlers({ onExit })).not.toThrow();
+
+    (process as any).emit('SIGTERM');
+
+    expect(onExit).toHaveBeenCalledTimes(1);
+    expect(onExit).toHaveBeenCalledWith(SIGNAL_EXIT_CODES().SIGTERM, {
+      kind: 'signal',
+      signal: 'SIGTERM',
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('should call onExit and exit with code 0 for SIGQUIT', () => {
+    expect(() => installExitHandlers({ onExit })).not.toThrow();
+
+    (process as any).emit('SIGQUIT');
+
+    expect(onExit).toHaveBeenCalledTimes(1);
+    expect(onExit).toHaveBeenCalledWith(SIGNAL_EXIT_CODES().SIGQUIT, {
+      kind: 'signal',
+      signal: 'SIGQUIT',
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('should call onExit for successful process termination with exit code 0', () => {
+    expect(() => installExitHandlers({ onExit })).not.toThrow();
+
+    (process as any).emit('exit', 0);
+
+    expect(onExit).toHaveBeenCalledTimes(1);
+    expect(onExit).toHaveBeenCalledWith(0, { kind: 'exit' });
+    expect(onError).not.toHaveBeenCalled();
+    expect(processExitSpy).not.toHaveBeenCalled();
+  });
+
+  it('should call onExit for failed process termination with exit code 1', () => {
+    expect(() => installExitHandlers({ onExit })).not.toThrow();
+
+    (process as any).emit('exit', 1);
+
+    expect(onExit).toHaveBeenCalledTimes(1);
+    expect(onExit).toHaveBeenCalledWith(1, { kind: 'exit' });
+    expect(onError).not.toHaveBeenCalled();
+    expect(processExitSpy).not.toHaveBeenCalled();
+  });
+});

packages/utils/src/lib/exit-process.ts

@@ -0,0 +1,96 @@
+import os from 'node:os';
+import process from 'node:process';
+
+// POSIX shells convention: exit status = 128 + signal number
+// https://www.gnu.org/software/bash/manual/html_node/Exit-Status.html#:~:text=When%20a%20command%20terminates%20on%20a%20fatal%20signal%20whose%20number%20is%20N%2C%20Bash%20uses%20the%20value%20128%2BN%20as%20the%20exit%20status.
+const UNIX_SIGNAL_EXIT_CODE_OFFSET = 128;
+const unixSignalExitCode = (signalNumber: number) =>
+  UNIX_SIGNAL_EXIT_CODE_OFFSET + signalNumber;
+
+const SIGINT_CODE = 2;
+const SIGTERM_CODE = 15;
+const SIGQUIT_CODE = 3;
+
+export const SIGNAL_EXIT_CODES = (): Record<SignalName, number> => {
+  const isWindowsRuntime = os.platform() === 'win32';
+  return {
+    SIGINT: isWindowsRuntime ? SIGINT_CODE : unixSignalExitCode(SIGINT_CODE),
+    SIGTERM: unixSignalExitCode(SIGTERM_CODE),
+    SIGQUIT: unixSignalExitCode(SIGQUIT_CODE),
+  };
+};
+
+export const DEFAULT_FATAL_EXIT_CODE = 1;
+
+export type SignalName = 'SIGINT' | 'SIGTERM' | 'SIGQUIT';
+export type FatalKind = 'uncaughtException' | 'unhandledRejection';
+
+export type CloseReason =
+  | { kind: 'signal'; signal: SignalName }
+  | { kind: 'fatal'; fatal: FatalKind }
+  | { kind: 'exit' };
+
+export type ExitHandlerOptions = {
+  onExit?: (code: number, reason: CloseReason) => void;
+  onError?: (err: unknown, kind: FatalKind) => void;
+  exitOnFatal?: boolean;
+  exitOnSignal?: boolean;
+  fatalExitCode?: number;
+};
+
+export function installExitHandlers(options: ExitHandlerOptions = {}): void {
+  // eslint-disable-next-line functional/no-let
+  let closedReason: CloseReason | undefined;
+  const {
+    onExit,
+    onError,
+    exitOnFatal,
+    exitOnSignal,
+    fatalExitCode = DEFAULT_FATAL_EXIT_CODE,
+  } = options;
+
+  const close = (code: number, reason: CloseReason) => {
+    if (closedReason) {
+      return;
+    }
+    closedReason = reason;
+    onExit?.(code, reason);
+  };
+
+  process.on('uncaughtException', err => {
+    onError?.(err, 'uncaughtException');
+    if (exitOnFatal) {
+      close(fatalExitCode, {
+        kind: 'fatal',
+        fatal: 'uncaughtException',
+      });
+    }
+  });
+
+  process.on('unhandledRejection', reason => {
+    onError?.(reason, 'unhandledRejection');
+    if (exitOnFatal) {
+      close(fatalExitCode, {
+        kind: 'fatal',
+        fatal: 'unhandledRejection',
+      });
+    }
+  });
+
+  (['SIGINT', 'SIGTERM', 'SIGQUIT'] as const).forEach(signal => {
+    process.on(signal, () => {
+      close(SIGNAL_EXIT_CODES()[signal], { kind: 'signal', signal });
+      if (exitOnSignal) {
+        // eslint-disable-next-line n/no-process-exit
+        process.exit(SIGNAL_EXIT_CODES()[signal]);
+      }
+    });
+  });
+
+  process.on('exit', code => {
+    if (closedReason) {
+      return;
+    }
+    close(code, { kind: 'exit' });
+  });
+}