lifecycleion 0.0.1

package/dist/lib/process-signal-manager.d.ts

@@ -0,0 +1,305 @@
+/**
+ * The shutdown signal types that can trigger the shutdown callback
+ */
+type ShutdownSignal = 'SIGINT' | 'SIGTERM' | 'SIGTRAP';
+/**
+ * Status information about what the manager is attached to
+ */
+interface ProcessSignalManagerStatus {
+    /**
+     * Whether the manager is currently attached to signals and keypresses
+     */
+    isAttached: boolean;
+    /**
+     * Which handlers are registered
+     */
+    handlers: {
+        /**
+         * Whether a shutdown handler is registered
+         */
+        shutdown: boolean;
+        /**
+         * Whether a reload handler is registered
+         */
+        reload: boolean;
+        /**
+         * Whether an info handler is registered
+         */
+        info: boolean;
+        /**
+         * Whether a debug handler is registered
+         */
+        debug: boolean;
+    };
+    /**
+     * What events are currently being listened for (only populated when isListening is true)
+     */
+    listeningFor: {
+        /**
+         * Listening for shutdown signals (SIGINT, SIGTERM, SIGTRAP)
+         */
+        shutdownSignals: boolean;
+        /**
+         * Listening for reload signal (SIGHUP)
+         */
+        reloadSignal: boolean;
+        /**
+         * Listening for info signal (SIGUSR1)
+         */
+        infoSignal: boolean;
+        /**
+         * Listening for debug signal (SIGUSR2)
+         */
+        debugSignal: boolean;
+        /**
+         * Listening for keypresses (Ctrl+C, Escape, R, I, D)
+         */
+        keypresses: boolean;
+    };
+}
+/**
+ * Configuration options for ProcessSignalManager
+ */
+interface ProcessSignalManagerOptions {
+    /**
+     * Optional callback invoked when a shutdown signal is received.
+     *
+     * Triggered by:
+     * - Process signals: SIGINT, SIGTERM, SIGTRAP
+     * - Keyboard: Ctrl+C, Escape
+     */
+    onShutdownRequested?: (method: ShutdownSignal) => void | Promise<void>;
+    /**
+     * Optional callback invoked when reload is requested.
+     *
+     * Triggered by:
+     * - Process signal: SIGHUP
+     * - Keyboard: R key press (case-insensitive)
+     */
+    onReloadRequested?: () => void | Promise<unknown>;
+    /**
+     * Optional callback invoked when info/stats are requested.
+     *
+     * Triggered by:
+     * - Process signal: SIGUSR1
+     * - Keyboard: I key press (case-insensitive)
+     *
+     * Common uses: Print stats, health check, show metrics
+     */
+    onInfoRequested?: () => void | Promise<unknown>;
+    /**
+     * Optional callback invoked when debug mode is toggled or verbose info is requested.
+     *
+     * Triggered by:
+     * - Process signal: SIGUSR2
+     * - Keyboard: D key press (case-insensitive)
+     *
+     * Common uses: Toggle debug mode, dump full state, enable verbose logging
+     */
+    onDebugRequested?: () => void | Promise<unknown>;
+    /**
+     * Custom name for the shutdown callback used in error reporting.
+     * @default 'onShutdownRequested'
+     */
+    shutdownCallbackName?: string;
+    /**
+     * Custom name for the reload callback used in error reporting.
+     * @default 'onReloadRequested'
+     */
+    reloadCallbackName?: string;
+    /**
+     * Custom name for the info callback used in error reporting.
+     * @default 'onInfoRequested'
+     */
+    infoCallbackName?: string;
+    /**
+     * Custom name for the debug callback used in error reporting.
+     * @default 'onDebugRequested'
+     */
+    debugCallbackName?: string;
+    /**
+     * Throttle interval in milliseconds for keyboard events (leading-edge rate limiting).
+     * Allows an action to trigger at most once per interval. First press fires immediately,
+     * subsequent presses within the window are ignored.
+     * This prevents accidental double-triggers while allowing predictable repeated actions.
+     *
+     * Note: This only affects keyboard events, not process signals.
+     * Process signals are never throttled as they may come from external sources
+     * that expect immediate handling.
+     *
+     * @default 200 (200ms throttle, allowing 5 triggers per second maximum)
+     * @example 300 // Custom 300ms throttle (3.33 triggers per second max)
+     * @example 0 // Disable throttling entirely
+     */
+    keypressThrottleMS?: number;
+}
+/**
+ * Manages process signals and keyboard events for graceful shutdown, reload, and info/debug functionality.
+ *
+ * Handles:
+ * - Shutdown signals: SIGINT, SIGTERM, SIGTRAP
+ * - Reload signal: SIGHUP
+ * - Info signal: SIGUSR1
+ * - Debug signal: SIGUSR2
+ * - Keyboard shortcuts: Ctrl+C, Escape (shutdown), R (reload), I (info), D (debug)
+ *   All letter keys are case-insensitive
+ *
+ * All callbacks are executed safely with automatic error handling.
+ */
+declare class ProcessSignalManager {
+    private readonly instanceID;
+    private onShutdownRequested?;
+    private onReloadRequested?;
+    private onInfoRequested?;
+    private onDebugRequested?;
+    private shutdownCallbackName;
+    private reloadCallbackName;
+    private infoCallbackName;
+    private debugCallbackName;
+    private shutdownSignalListeners?;
+    private reloadSignalListener?;
+    private infoSignalListener?;
+    private debugSignalListener?;
+    private keypressHandler?;
+    private _isAttached;
+    private keypressThrottleMS;
+    private lastActionTimes;
+    constructor(options: ProcessSignalManagerOptions);
+    /**
+     * Check if the manager is currently attached to signals and keypresses.
+     */
+    get isAttached(): boolean;
+    /**
+     * Get detailed status information about what the manager is attached to.
+     *
+     * @returns Status object with handler registration and attachment state
+     */
+    getStatus(): ProcessSignalManagerStatus;
+    /**
+     * Attach signal handlers and start listening for process signals and keyboard events.
+     * Idempotent - calling multiple times has no effect.
+     */
+    attach(): void;
+    /**
+     * Detach signal handlers and stop listening for process signals and keyboard events.
+     * Cleans up all event listeners and restores stdin to normal mode.
+     *
+     * Idempotent - calling multiple times has no effect.
+     */
+    detach(): void;
+    /**
+     * Manually trigger a shutdown event
+     * if the manager is attached and a shutdown handler is registered
+     *
+     * @param method - The shutdown method (SIGINT, SIGTERM, or SIGTRAP) that will be passed to the shutdown callback
+     * @param shouldBypassAttachCheck - If true, triggers the callback even when not attached (useful for testing)
+     */
+    triggerShutdown(method: ShutdownSignal, shouldBypassAttachCheck?: boolean): void;
+    /**
+     * Manually trigger a reload event
+     * if the manager is attached and a reload handler is registered
+     *
+     * @param shouldBypassAttachCheck - If true, triggers the callback even when not attached (useful for testing)
+     */
+    triggerReload(shouldBypassAttachCheck?: boolean): void;
+    /**
+     * Manually trigger an info event
+     * if the manager is attached and an info handler is registered
+     *
+     * @param shouldBypassAttachCheck - If true, triggers the callback even when not attached (useful for testing)
+     */
+    triggerInfo(shouldBypassAttachCheck?: boolean): void;
+    /**
+     * Manually trigger a debug event
+     * if the manager is attached and a debug handler is registered
+     *
+     * @param shouldBypassAttachCheck - If true, triggers the callback even when not attached (useful for testing)
+     */
+    triggerDebug(shouldBypassAttachCheck?: boolean): void;
+    /**
+     * Check if an action should be throttled based on the last time it was successfully triggered.
+     * Uses leading-edge throttle: first press fires immediately, subsequent presses within the
+     * throttle window are ignored. Only updates timestamp when action is allowed (not throttled).
+     *
+     * This is the standard pattern for keyboard shortcuts and prevents accidental double-triggers
+     * while allowing predictable repeated actions at a maximum rate.
+     *
+     * @param action - The action type to check throttling for
+     * @returns true if the action should be throttled (ignored), false otherwise
+     */
+    private shouldThrottle;
+    /**
+     * Register handlers for all shutdown signals (SIGINT, SIGTERM, SIGTRAP) if callback is provided.
+     * Each signal will trigger the shutdown callback with the appropriate method.
+     */
+    private listenForShutdownSignals;
+    /**
+     * Remove handlers for all shutdown signals if they were registered.
+     * Uses the same function references to ensure proper cleanup.
+     */
+    private stopListeningForShutdownSignals;
+    /**
+     * Register handler for SIGHUP signal if reload callback is provided.
+     * SIGHUP is commonly used to trigger configuration reloads.
+     */
+    private listenForReloadSignal;
+    /**
+     * Remove handler for SIGHUP signal.
+     * Uses the same function reference to ensure proper cleanup.
+     */
+    private stopListeningForReloadSignal;
+    /**
+     * Register handler for SIGUSR1 signal if info callback is provided.
+     * SIGUSR1 is commonly used for printing stats, health checks, etc.
+     */
+    private listenForInfoSignal;
+    /**
+     * Remove handler for SIGUSR1 signal.
+     * Uses the same function reference to ensure proper cleanup.
+     */
+    private stopListeningForInfoSignal;
+    /**
+     * Register handler for SIGUSR2 signal if debug callback is provided.
+     * SIGUSR2 is commonly used for toggling debug mode, dumping state, etc.
+     */
+    private listenForDebugSignal;
+    /**
+     * Remove handler for SIGUSR2 signal.
+     * Uses the same function reference to ensure proper cleanup.
+     */
+    private stopListeningForDebugSignal;
+    /**
+     * Enable keyboard event listening if stdin is a TTY.
+     * Sets stdin to raw mode and listens for Ctrl+C, Escape, R, I, and D keypresses.
+     *
+     * Note: Letter keys are case-insensitive (R/r, I/i, D/d all work).
+     *
+     * Uses add-then-check pattern to prevent race conditions:
+     * 1. Add ourselves to attachedInstances first
+     * 2. Check if we're the first (size === 1) to enable raw mode
+     * This ensures no gap where another instance could read stale state.
+     */
+    private listenForKeyPresses;
+    /**
+     * Helper to clean up keypress handler registration on error.
+     * Removes handler, clears instance from shared state, and restores raw mode if needed.
+     *
+     * @param shared - The shared state object
+     * @param didAttemptRawModeEnable - If true, we attempted to enable raw mode (even if ownership wasn't recorded).
+     *   This handles the edge case where setRawMode(true) throws after actually enabling raw mode.
+     */
+    private cleanupKeypressHandler;
+    /**
+     * Restore stdin to normal mode and clean up keypress listener.
+     * Uses remove-then-check pattern (mirror of add-then-check in attach):
+     * 1. Remove ourselves from attachedInstances first
+     * 2. Check if we're the last (size === 0) to disable raw mode and pause stdin
+     *
+     * Note: Can be called even if keypressHandler is undefined (e.g., during error recovery).
+     * In that case, we still update shared state and attempt terminal restoration if we
+     * were the recorded raw mode owner.
+     */
+    private restoreStdin;
+}
+
+export { ProcessSignalManager, type ProcessSignalManagerOptions, type ProcessSignalManagerStatus, type ShutdownSignal };