refactor: add int tests and refactor for reuse

Author: John Doe

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

@@ -0,0 +1,118 @@
+import process from 'node:process';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { installExitHandlers } from './exit-process.js';
+
+describe('installExitHandlers', () => {
+  const onError = vi.fn();
+  const onClose = 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, onClose })).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(onClose).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(onClose).not.toHaveBeenCalled();
+  });
+
+  it('should call onClose and exit with code 0 for SIGINT', () => {
+    expect(() => installExitHandlers({ onClose })).not.toThrow();
+
+    (process as any).emit('SIGINT');
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledWith(130, {
+      kind: 'signal',
+      signal: 'SIGINT',
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('should call onClose and exit with code 0 for SIGTERM', () => {
+    expect(() => installExitHandlers({ onClose })).not.toThrow();
+
+    (process as any).emit('SIGTERM');
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledWith(143, {
+      kind: 'signal',
+      signal: 'SIGTERM',
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('should call onClose and exit with code 0 for SIGQUIT', () => {
+    expect(() => installExitHandlers({ onClose })).not.toThrow();
+
+    (process as any).emit('SIGQUIT');
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledWith(131, {
+      kind: 'signal',
+      signal: 'SIGQUIT',
+    });
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it('should call onClose for normal exit', () => {
+    expect(() => installExitHandlers({ onClose })).not.toThrow();
+
+    (process as any).emit('exit');
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledWith(undefined, { kind: 'exit' });
+    expect(onError).not.toHaveBeenCalled();
+    expect(processExitSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -1,43 +1,88 @@
+import os from 'node:os';
 import process from 'node:process';
 
-/* eslint-disable  @typescript-eslint/no-magic-numbers */
-const SIGNALS = [
-  ['SIGINT', 130],
-  ['SIGTERM', 143],
-  ['SIGQUIT', 131],
-] as const;
-/* eslint-enable  @typescript-eslint/no-magic-numbers */
+const isWindows = os.platform() === 'win32';
 
+// 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;
+
+export const SIGNAL_EXIT_CODES = (): Record<SignalName, number> => {
+  const isWindowsRuntime = os.platform() === 'win32';
+  return {
+    SIGINT: isWindowsRuntime ? SIGINT_CODE : unixSignalExitCode(SIGINT_CODE),
+    SIGTERM: unixSignalExitCode(15),
+    SIGQUIT: unixSignalExitCode(3),
+  };
+};
+
+export const DEFAULT_FATAL_EXIT_CODE = 1;
+
+export type SignalName = 'SIGINT' | 'SIGTERM' | 'SIGQUIT';
 export type FatalKind = 'uncaughtException' | 'unhandledRejection';
-type ExitHandlerOptions =
-  | {
-      onClose?: () => void;
-      onFatal: (err: unknown, kind?: FatalKind) => void;
-    }
-  | {
-      onClose: () => void;
-      onFatal?: never;
-    };
-
-export function installExitHandlers(options: ExitHandlerOptions): void {
-  // Fatal errors
+
+export type CloseReason =
+  | { kind: 'signal'; signal: SignalName }
+  | { kind: 'fatal'; fatal: FatalKind }
+  | { kind: 'exit' };
+
+export type ExitHandlerOptions = {
+  onClose?: (code: number, reason: CloseReason) => void;
+  onError?: (err: unknown, kind: FatalKind) => void;
+  fatalExit?: boolean;
+  signalExit?: boolean;
+  fatalExitCode?: number;
+};
+
+export function installExitHandlers(options: ExitHandlerOptions = {}): void {
+  let closedReason: CloseReason | undefined;
+  const {
+    onClose,
+    onError,
+    fatalExit,
+    signalExit,
+    fatalExitCode = DEFAULT_FATAL_EXIT_CODE,
+  } = options;
+
+  const close = (code: number, reason: CloseReason) => {
+    if (closedReason) return;
+    closedReason = reason;
+    onClose?.(code, reason);
+  };
+
   process.on('uncaughtException', err => {
-    options.onFatal?.(err, 'uncaughtException');
+    onError?.(err, 'uncaughtException');
+    if (fatalExit)
+      close(fatalExitCode, {
+        kind: 'fatal',
+        fatal: 'uncaughtException',
+      });
   });
 
   process.on('unhandledRejection', reason => {
-    options.onFatal?.(reason, 'unhandledRejection');
+    onError?.(reason, 'unhandledRejection');
+    if (fatalExit)
+      close(fatalExitCode, {
+        kind: 'fatal',
+        fatal: 'unhandledRejection',
+      });
   });
 
-  // Graceful shutdown signals
-  SIGNALS.forEach(([signal]) => {
+  (['SIGINT', 'SIGTERM', 'SIGQUIT'] as const).forEach(signal => {
     process.on(signal, () => {
-      options.onClose?.();
+      close(SIGNAL_EXIT_CODES()[signal], { kind: 'signal', signal });
+      if (signalExit) {
+        process.exit(SIGNAL_EXIT_CODES()[signal]);
+      }
     });
   });
 
-  // Normal exit
-  process.on('exit', () => {
-    options.onClose?.();
+  process.on('exit', code => {
+    if (closedReason) return;
+    close(code, { kind: 'exit' });
   });
 }