service-keepalive 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Supported HTTP methods for keep-alive pings.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * Strategy for calculating delays between retry attempts.
+ */
+type RetryStrategy = 'exponential' | 'linear' | 'fixed';
+/**
+ * Logging verbosity levels.
+ */
+type LogLevel = 'quiet' | 'normal' | 'verbose';
+/**
+ * Custom logger interface.
+ */
+interface LoggerInterface {
+    info(message: string, ...args: unknown[]): void;
+    success(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Result of an individual HTTP ping execution.
+ */
+interface PingResult {
+    /** Identifier of the service pinged */
+    serviceName: string;
+    /** Target URL */
+    url: string;
+    /** HTTP method used */
+    method: HttpMethod;
+    /** HTTP response status code (0 if network error / timeout) */
+    status: number;
+    /** HTTP response status text */
+    statusText: string;
+    /** Whether the ping was deemed successful */
+    ok: boolean;
+    /** Round-trip duration in milliseconds */
+    durationMs: number;
+    /** Which attempt number succeeded or failed (1-indexed) */
+    attempt: number;
+    /** ISO timestamp when the ping was executed */
+    timestamp: Date;
+    /** Error message if request failed */
+    error?: string;
+    /** Sanitized response headers if available and requested */
+    headers?: Record<string, string>;
+}
+/**
+ * Information passed during a retry event.
+ */
+interface RetryInfo {
+    serviceName: string;
+    url: string;
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+    error: string;
+}
+/**
+ * Configuration options for an individual KeepAlive target.
+ */
+interface KeepAliveConfig {
+    /** Target service URL to ping (must be a valid http or https URL) */
+    url: string;
+    /** Optional friendly name for the service (defaults to URL hostname) */
+    name?: string;
+    /** Interval between consecutive pings (e.g. '10m', '30s', '1h', or number in ms). Default: '10m' */
+    interval?: string | number;
+    /** Request timeout duration (e.g. '30s', '10s', or number in ms). Default: '30s' */
+    timeout?: string | number;
+    /** HTTP method to use. Default: 'GET' */
+    method?: HttpMethod;
+    /** Custom request headers */
+    headers?: Record<string, string>;
+    /** Optional request body payload (for POST/PUT requests) */
+    body?: string | null;
+    /** Number of retry attempts on failure. Default: 3 */
+    retries?: number;
+    /** Base delay between retries (e.g. '5s', '1000ms'). Default: '5s' */
+    retryDelay?: string | number;
+    /** Backoff strategy for retries. Default: 'exponential' */
+    retryStrategy?: RetryStrategy;
+    /** Whether to add random jitter to retry delays. Default: true */
+    retryJitter?: boolean;
+    /** Maximum upper bound for retry delay. Default: '60s' */
+    maxRetryDelay?: string | number;
+    /**
+     * Status code(s) considered successful.
+     * Can be an array of status codes or a predicate function.
+     * Default: any 2xx status (200-299)
+     */
+    expectedStatusCodes?: number[] | ((status: number) => boolean);
+    /** Custom logger or false to disable logging. Default: built-in console logger */
+    logger?: LoggerInterface | false;
+    /** Output verbosity level. Default: 'normal' */
+    logLevel?: LogLevel;
+    /** Whether the underlying timer should not prevent the Node process from exiting. Default: false */
+    unrefTimer?: boolean;
+}
+/**
+ * Configuration options for managing multiple services.
+ */
+interface MultiKeepAliveConfig {
+    /** List of service configurations to keep alive */
+    services: KeepAliveConfig[];
+    /** Default options applied to all services unless explicitly overridden */
+    defaults?: Partial<KeepAliveConfig>;
+    /** Global logger or false */
+    logger?: LoggerInterface | false;
+    /** Global log level */
+    logLevel?: LogLevel;
+}
+/**
+ * Resolved internal configuration with guaranteed types and parsed milliseconds.
+ */
+interface ResolvedServiceConfig {
+    name: string;
+    url: string;
+    intervalMs: number;
+    timeoutMs: number;
+    method: HttpMethod;
+    headers: Record<string, string>;
+    body: string | null;
+    retries: number;
+    retryDelayMs: number;
+    retryStrategy: RetryStrategy;
+    retryJitter: boolean;
+    maxRetryDelayMs: number;
+    expectedStatusCodes: number[] | ((status: number) => boolean);
+    logger: LoggerInterface | null;
+    logLevel: LogLevel;
+    unrefTimer: boolean;
+}
+/**
+ * CLI Options parsed from command line flags.
+ */
+interface CliOptions {
+    url?: string;
+    interval?: string;
+    timeout?: string;
+    method?: string;
+    retries?: string | number;
+    retryDelay?: string;
+    headers?: string[];
+    config?: string;
+    quiet?: boolean;
+    verbose?: boolean;
+    once?: boolean;
+    help?: boolean;
+    version?: boolean;
+}
+/**
+ * Events emitted by the KeepAlive instance.
+ */
+interface KeepAliveEvents {
+    start: (serviceName: string) => void;
+    stop: (serviceName: string) => void;
+    ping: (info: {
+        name: string;
+        url: string;
+        attempt: number;
+    }) => void;
+    success: (result: PingResult) => void;
+    failure: (result: PingResult) => void;
+    retry: (info: RetryInfo) => void;
+    error: (error: Error, serviceName: string) => void;
+}
+
+declare class KeepAlive extends EventEmitter {
+    private config;
+    private running;
+    private timer;
+    private inFlightAbortController;
+    private logger;
+    constructor(options: KeepAliveConfig);
+    private resolveConfig;
+    /**
+     * Returns whether the keep-alive scheduler is actively running.
+     */
+    isRunning(): boolean;
+    /**
+     * Returns the resolved service configuration.
+     */
+    getConfig(): Readonly<ResolvedServiceConfig>;
+    /**
+     * Starts the keep-alive scheduler.
+     * Performs an immediate ping, then continues at the configured interval.
+     */
+    start(): this;
+    /**
+     * Stops the keep-alive scheduler and aborts any active requests or wait timers.
+     */
+    stop(): Promise<void>;
+    /**
+     * Executes a single ping cycle with retries without starting the recurring scheduler.
+     */
+    pingOnce(): Promise<PingResult>;
+    /**
+     * Core scheduling loop. Executes a ping cycle, then schedules the next interval.
+     */
+    private runPingLoop;
+    /**
+     * Executes the ping request, retrying on failure up to configured retry attempts.
+     */
+    private executePingWithRetries;
+    on<K extends keyof KeepAliveEvents>(event: K, listener: KeepAliveEvents[K]): this;
+    once<K extends keyof KeepAliveEvents>(event: K, listener: KeepAliveEvents[K]): this;
+    off<K extends keyof KeepAliveEvents>(event: K, listener: KeepAliveEvents[K]): this;
+    emit<K extends keyof KeepAliveEvents>(event: K, ...args: Parameters<KeepAliveEvents[K]>): boolean;
+}
+
+declare class MultiKeepAlive extends EventEmitter {
+    private services;
+    private serviceMap;
+    private logger;
+    constructor(options: MultiKeepAliveConfig);
+    private forwardEvents;
+    /**
+     * Starts all configured services.
+     */
+    start(): this;
+    /**
+     * Stops all running services.
+     */
+    stop(): Promise<void>;
+    /**
+     * Pings all services once in parallel and returns their results.
+     */
+    pingOnce(): Promise<PingResult[]>;
+    /**
+     * Returns whether any of the services are currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Returns the list of all registered KeepAlive instances.
+     */
+    getServices(): KeepAlive[];
+    /**
+     * Returns a specific KeepAlive instance by service name.
+     */
+    getService(name: string): KeepAlive | undefined;
+    on<K extends keyof KeepAliveEvents>(event: K, listener: KeepAliveEvents[K]): this;
+    once<K extends keyof KeepAliveEvents>(event: K, listener: KeepAliveEvents[K]): this;
+    off<K extends keyof KeepAliveEvents>(event: K, listener: KeepAliveEvents[K]): this;
+    emit<K extends keyof KeepAliveEvents>(event: K, ...args: Parameters<KeepAliveEvents[K]>): boolean;
+}
+
+interface ExecutePingOptions {
+    serviceName: string;
+    url: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    body?: string | null;
+    timeoutMs: number;
+    attempt?: number;
+    expectedStatusCodes?: number[] | ((status: number) => boolean);
+    externalSignal?: AbortSignal;
+}
+/**
+ * Checks whether an HTTP status code is considered successful.
+ */
+declare function isStatusSuccessful(status: number, expected?: number[] | ((status: number) => boolean)): boolean;
+/**
+ * Executes a single HTTP ping request with timeout and cancellation protection.
+ */
+declare function executePing(options: ExecutePingOptions): Promise<PingResult>;
+
+/**
+ * Parses a human-readable duration string or millisecond number into milliseconds.
+ *
+ * Supported formats:
+ * - Number: `5000` (treated as 5000ms)
+ * - String: `'10s'`, `'30s'`, `'1m'`, `'5m'`, `'10m'`, `'1h'`, `'500ms'`, `'1m30s'`
+ *
+ * @throws {TypeError | RangeError} If the duration is invalid, zero, or negative.
+ */
+declare function parseDuration(value: string | number, fieldName?: string): number;
+/**
+ * Formats a duration in milliseconds into a concise human-readable string.
+ *
+ * Examples:
+ * - `142` -> `'142ms'`
+ * - `5000` -> `'5s'`
+ * - `60000` -> `'1m'`
+ * - `90000` -> `'1m 30s'`
+ * - `3600000` -> `'1h'`
+ */
+declare function formatDuration(ms: number): string;
+
+interface BackoffOptions {
+    attempt: number;
+    baseDelayMs: number;
+    strategy?: RetryStrategy;
+    maxDelayMs?: number;
+    jitter?: boolean;
+}
+/**
+ * Calculates the backoff delay in milliseconds for a given attempt.
+ *
+ * @param options Calculation parameters
+ * @returns Delay in milliseconds
+ */
+declare function calculateBackoff(options: BackoffOptions): number;
+/**
+ * Asynchronously sleeps for the given duration, cancellable via AbortSignal.
+ *
+ * @param ms Duration in milliseconds
+ * @param signal Optional AbortSignal to cancel waiting
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+/**
+ * Returns a shallow copy of headers with sensitive values masked.
+ */
+declare function redactHeaders(headers?: Record<string, string> | null): Record<string, string>;
+/**
+ * Masks sensitive query parameters in a URL string for safe logging.
+ */
+declare function redactUrl(urlStr: string): string;
+
+declare function formatTimestamp(date?: Date): string;
+declare class Logger implements LoggerInterface {
+    private logLevel;
+    private prefix?;
+    constructor(options?: {
+        logLevel?: LogLevel;
+        prefix?: string;
+    });
+    setLevel(level: LogLevel): void;
+    setPrefix(prefix: string | undefined): void;
+    private shouldLog;
+    private formatLine;
+    info(message: string, ...args: unknown[]): void;
+    success(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    retry(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+
+interface LoadedConfig {
+    services: KeepAliveConfig[];
+    defaults?: Partial<KeepAliveConfig>;
+    logLevel?: LogLevel;
+}
+/**
+ * Parses header strings in "Key: Value" or "Key=Value" format.
+ */
+declare function parseHeaderPairs(headers: string[] | undefined): Record<string, string>;
+/**
+ * Loads configuration from a file path.
+ */
+declare function loadConfigFile(customPath?: string): Promise<LoadedConfig | null>;
+/**
+ * Normalizes raw config object into LoadedConfig format.
+ */
+declare function normalizeRawConfig(raw: unknown): LoadedConfig;
+/**
+ * Reads environment variables into a partial KeepAliveConfig.
+ */
+declare function loadEnvConfig(): Partial<KeepAliveConfig>;
+/**
+ * Resolves complete runtime configuration from CLI flags, config file, and env variables.
+ */
+declare function resolveRuntimeConfig(cliOptions: CliOptions): Promise<MultiKeepAliveConfig | KeepAliveConfig>;
+
+declare function parseArgs(argv: string[]): CliOptions;
+declare function printHelp(): void;
+declare function runCli(argv?: string[]): Promise<number>;
+
+export { type BackoffOptions, type CliOptions, type ExecutePingOptions, type HttpMethod, KeepAlive, type KeepAliveConfig, type KeepAliveEvents, type LoadedConfig, type LogLevel, Logger, type LoggerInterface, MultiKeepAlive, type MultiKeepAliveConfig, type PingResult, type ResolvedServiceConfig, type RetryInfo, type RetryStrategy, calculateBackoff, executePing, formatDuration, formatTimestamp, isStatusSuccessful, loadConfigFile, loadEnvConfig, normalizeRawConfig, parseArgs, parseDuration, parseHeaderPairs, printHelp, redactHeaders, redactUrl, resolveRuntimeConfig, runCli, sleep };