@rawnodes/logger 2.5.0 → 2.7.0

package/README.md

@@ -414,6 +414,68 @@ logger.for('payments').error('Payment failed');
 logger.for('auth').error('Login failed');
 ```
 
+## Graceful Shutdown
+
+External transports (Discord, Telegram, CloudWatch) buffer messages before sending. To ensure no logs are lost on process exit, use graceful shutdown.
+
+### Automatic (Recommended)
+
+Enable `autoShutdown` in config to automatically handle SIGTERM/SIGINT:
+
+```typescript
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  cloudwatch: { /* ... */ },
+  autoShutdown: true,  // Auto-register shutdown handlers
+});
+
+// Or with options:
+const logger = Logger.create({
+  level: 'info',
+  console: { format: 'plain' },
+  cloudwatch: { /* ... */ },
+  autoShutdown: {
+    timeout: 10000,              // Max wait time (default: 5000ms)
+    signals: ['SIGTERM'],        // Signals to handle (default: ['SIGTERM', 'SIGINT'])
+  },
+});
+```
+
+### Manual
+
+For more control, use `registerShutdown` or call `shutdown()` directly:
+
+```typescript
+import { Logger, registerShutdown } from '@rawnodes/logger';
+
+const logger = Logger.create(config);
+
+// Option 1: Register handlers manually
+registerShutdown(logger, {
+  timeout: 10000,
+  onShutdown: async () => {
+    console.log('Flushing logs...');
+  },
+});
+
+// Option 2: Call shutdown directly (e.g., in your own signal handler)
+process.on('SIGTERM', async () => {
+  await logger.shutdown();  // Flush all buffered messages
+  process.exit(0);
+});
+```
+
+### In Tests
+
+For tests, call `shutdown()` in `afterAll` to flush pending logs:
+
+```typescript
+afterAll(async () => {
+  await logger.shutdown();
+});
+```
+
 ## Singleton Pattern
 
 For app-wide logging:

package/dist/index.d.mts

@@ -100,6 +100,12 @@ interface CallerInfo {
     column?: number;
     function?: string;
 }
+interface AutoShutdownConfig {
+    /** Timeout in ms before forcing exit (default: 5000) */
+    timeout?: number;
+    /** Custom signals to handle (default: ['SIGTERM', 'SIGINT']) */
+    signals?: NodeJS.Signals[];
+}
 interface LoggerConfig {
     level: LevelConfig;
     console: ConsoleConfig;
@@ -111,6 +117,8 @@ interface LoggerConfig {
     caller?: boolean | CallerConfig;
     /** Hostname to include in all log entries. Defaults to os.hostname() if not specified */
     hostname?: string;
+    /** Auto-register graceful shutdown handlers. Pass true for defaults or config object */
+    autoShutdown?: boolean | AutoShutdownConfig;
 }
 type LoggerContext = Record<string, unknown>;
 type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
@@ -141,6 +149,11 @@ declare class Logger<TContext extends LoggerContext = LoggerContext> {
     removeLevelOverride(match: LevelOverrideMatch<TContext>): boolean;
     clearLevelOverrides(): void;
     getLevelOverrides(): LevelOverride<TContext>[];
+    /**
+     * Gracefully shutdown the logger, flushing all pending messages.
+     * Should be called before process exit to ensure no logs are lost.
+     */
+    shutdown(): Promise<void>;
     profile(id: string, meta?: object): void;
     error(errorOrMessage: Error | string, messageOrMeta?: string | Meta, meta?: Meta): void;
     warn(message: string, meta?: Meta): void;
@@ -165,10 +178,6 @@ interface SingletonLogger<TContext extends LoggerContext> {
 }
 declare function createSingletonLogger<TContext extends LoggerContext = LoggerContext>(): SingletonLogger<TContext>;
 
-declare function matchesContext(storeContext: LoggerContext | undefined, loggerContext: string | undefined, match: Record<string, unknown> & {
-    context?: string;
-}): boolean;
-
 interface BufferedMessage {
     level: LogLevel;
     message: string;
@@ -216,6 +225,10 @@ declare abstract class BaseHttpTransport extends EventEmitter {
     protected abstract sendBatch(messages: BufferedMessage[]): Promise<void>;
 }
 
+declare function matchesContext(storeContext: LoggerContext | undefined, loggerContext: string | undefined, match: Record<string, unknown> & {
+    context?: string;
+}): boolean;
+
 declare class DiscordTransport extends BaseHttpTransport {
     private config;
     constructor(config: DiscordConfig);
@@ -295,7 +308,83 @@ declare function createMasker(options?: MaskSecretsOptions): (obj: unknown) => u
 declare function getCallerInfo(config: CallerConfig, additionalOffset?: number): CallerInfo | undefined;
 declare function formatCallerInfo(info: CallerInfo): string;
 
-declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+interface GracefulShutdownOptions {
+    /** Timeout in ms before forcing exit (default: 5000) */
+    timeout?: number;
+    /** Exit code on successful shutdown (default: 0) */
+    exitCode?: number;
+    /** Custom signals to handle (default: ['SIGTERM', 'SIGINT']) */
+    signals?: NodeJS.Signals[];
+    /** Called before shutdown starts */
+    onShutdown?: () => void | Promise<void>;
+}
+/**
+ * Register graceful shutdown handlers for the logger.
+ * Ensures all buffered logs are flushed before process exit.
+ *
+ * @example
+ * ```typescript
+ * const logger = Logger.create(config);
+ * registerShutdown(logger);
+ *
+ * // Or with options:
+ * registerShutdown(logger, {
+ *   timeout: 10000,
+ *   onShutdown: () => console.log('Shutting down...'),
+ * });
+ * ```
+ */
+declare function registerShutdown<TContext extends LoggerContext>(logger: Logger<TContext>, options?: GracefulShutdownOptions): () => Promise<void>;
+
+/**
+ * HTTP error data extracted from axios/fetch errors
+ */
+interface HttpErrorData {
+    /** HTTP status code (e.g., 400, 500) */
+    status?: number;
+    /** HTTP status text (e.g., "Bad Request") */
+    statusText?: string;
+    /** Response body data */
+    responseData?: unknown;
+    /** Request URL */
+    url?: string;
+    /** HTTP method (GET, POST, etc.) */
+    method?: string;
+    /** Error code (e.g., ECONNREFUSED, ETIMEDOUT) */
+    code?: string;
+}
+/**
+ * Serialized error data for logging
+ */
+interface SerializedError {
+    /** Error message */
+    errorMessage: string;
+    /** Stack trace */
+    stack?: string;
+    /** HTTP-specific data if present */
+    http?: HttpErrorData;
+    /** Error code for non-HTTP errors */
+    code?: string;
+    /** Error name/type */
+    errorName?: string;
+}
+/**
+ * Serializes an Error object for logging, extracting HTTP-specific data
+ * from axios/fetch errors while preserving standard error properties.
+ *
+ * @example
+ * // Axios error
+ * try {
+ *   await axios.get('/api/data');
+ * } catch (error) {
+ *   const serialized = serializeError(error);
+ *   // serialized.http.status = 400
+ *   // serialized.http.responseData = { error: "invalid input" }
+ * }
+ */
+declare function serializeError(error: unknown): SerializedError;
+
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string, ancestors?: WeakSet<object>, depth?: number): Record<string, unknown>;
 declare function formatLogfmtValue(value: unknown): string;
 declare function formatLogfmt(data: Record<string, unknown>): string;
 
@@ -315,6 +404,7 @@ declare const CloudWatchConfigSchema: z.ZodType<CloudWatchConfig>;
 declare const LevelConfigObjectSchema: z.ZodType<LevelConfigObject>;
 declare const LevelConfigSchema: z.ZodType<LevelConfig>;
 declare const CallerConfigSchema: z.ZodType<CallerConfig>;
+declare const AutoShutdownConfigSchema: z.ZodType<AutoShutdownConfig>;
 declare const LoggerConfigSchema: z.ZodObject<{
     level: z.ZodType<LevelConfig, unknown, z.core.$ZodTypeInternals<LevelConfig, unknown>>;
     console: z.ZodType<ConsoleConfig, unknown, z.core.$ZodTypeInternals<ConsoleConfig, unknown>>;
@@ -324,6 +414,7 @@ declare const LoggerConfigSchema: z.ZodObject<{
     cloudwatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>, z.ZodArray<z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>>]>>;
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
+    autoShutdown: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<AutoShutdownConfig, unknown, z.core.$ZodTypeInternals<AutoShutdownConfig, unknown>>]>>;
 }, z.core.$strip>;
 declare function validateConfig(config: unknown): z.infer<typeof LoggerConfigSchema>;
 declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
@@ -335,6 +426,7 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[] | undefined;
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
+    autoShutdown?: boolean | AutoShutdownConfig | undefined;
 }>;
 
-export { BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, safeValidateConfig, validateConfig };
+export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };

package/dist/index.d.ts

@@ -100,6 +100,12 @@ interface CallerInfo {
     column?: number;
     function?: string;
 }
+interface AutoShutdownConfig {
+    /** Timeout in ms before forcing exit (default: 5000) */
+    timeout?: number;
+    /** Custom signals to handle (default: ['SIGTERM', 'SIGINT']) */
+    signals?: NodeJS.Signals[];
+}
 interface LoggerConfig {
     level: LevelConfig;
     console: ConsoleConfig;
@@ -111,6 +117,8 @@ interface LoggerConfig {
     caller?: boolean | CallerConfig;
     /** Hostname to include in all log entries. Defaults to os.hostname() if not specified */
     hostname?: string;
+    /** Auto-register graceful shutdown handlers. Pass true for defaults or config object */
+    autoShutdown?: boolean | AutoShutdownConfig;
 }
 type LoggerContext = Record<string, unknown>;
 type LevelOverrideMatch<TContext extends LoggerContext> = Partial<TContext> & {
@@ -141,6 +149,11 @@ declare class Logger<TContext extends LoggerContext = LoggerContext> {
     removeLevelOverride(match: LevelOverrideMatch<TContext>): boolean;
     clearLevelOverrides(): void;
     getLevelOverrides(): LevelOverride<TContext>[];
+    /**
+     * Gracefully shutdown the logger, flushing all pending messages.
+     * Should be called before process exit to ensure no logs are lost.
+     */
+    shutdown(): Promise<void>;
     profile(id: string, meta?: object): void;
     error(errorOrMessage: Error | string, messageOrMeta?: string | Meta, meta?: Meta): void;
     warn(message: string, meta?: Meta): void;
@@ -165,10 +178,6 @@ interface SingletonLogger<TContext extends LoggerContext> {
 }
 declare function createSingletonLogger<TContext extends LoggerContext = LoggerContext>(): SingletonLogger<TContext>;
 
-declare function matchesContext(storeContext: LoggerContext | undefined, loggerContext: string | undefined, match: Record<string, unknown> & {
-    context?: string;
-}): boolean;
-
 interface BufferedMessage {
     level: LogLevel;
     message: string;
@@ -216,6 +225,10 @@ declare abstract class BaseHttpTransport extends EventEmitter {
     protected abstract sendBatch(messages: BufferedMessage[]): Promise<void>;
 }
 
+declare function matchesContext(storeContext: LoggerContext | undefined, loggerContext: string | undefined, match: Record<string, unknown> & {
+    context?: string;
+}): boolean;
+
 declare class DiscordTransport extends BaseHttpTransport {
     private config;
     constructor(config: DiscordConfig);
@@ -295,7 +308,83 @@ declare function createMasker(options?: MaskSecretsOptions): (obj: unknown) => u
 declare function getCallerInfo(config: CallerConfig, additionalOffset?: number): CallerInfo | undefined;
 declare function formatCallerInfo(info: CallerInfo): string;
 
-declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+interface GracefulShutdownOptions {
+    /** Timeout in ms before forcing exit (default: 5000) */
+    timeout?: number;
+    /** Exit code on successful shutdown (default: 0) */
+    exitCode?: number;
+    /** Custom signals to handle (default: ['SIGTERM', 'SIGINT']) */
+    signals?: NodeJS.Signals[];
+    /** Called before shutdown starts */
+    onShutdown?: () => void | Promise<void>;
+}
+/**
+ * Register graceful shutdown handlers for the logger.
+ * Ensures all buffered logs are flushed before process exit.
+ *
+ * @example
+ * ```typescript
+ * const logger = Logger.create(config);
+ * registerShutdown(logger);
+ *
+ * // Or with options:
+ * registerShutdown(logger, {
+ *   timeout: 10000,
+ *   onShutdown: () => console.log('Shutting down...'),
+ * });
+ * ```
+ */
+declare function registerShutdown<TContext extends LoggerContext>(logger: Logger<TContext>, options?: GracefulShutdownOptions): () => Promise<void>;
+
+/**
+ * HTTP error data extracted from axios/fetch errors
+ */
+interface HttpErrorData {
+    /** HTTP status code (e.g., 400, 500) */
+    status?: number;
+    /** HTTP status text (e.g., "Bad Request") */
+    statusText?: string;
+    /** Response body data */
+    responseData?: unknown;
+    /** Request URL */
+    url?: string;
+    /** HTTP method (GET, POST, etc.) */
+    method?: string;
+    /** Error code (e.g., ECONNREFUSED, ETIMEDOUT) */
+    code?: string;
+}
+/**
+ * Serialized error data for logging
+ */
+interface SerializedError {
+    /** Error message */
+    errorMessage: string;
+    /** Stack trace */
+    stack?: string;
+    /** HTTP-specific data if present */
+    http?: HttpErrorData;
+    /** Error code for non-HTTP errors */
+    code?: string;
+    /** Error name/type */
+    errorName?: string;
+}
+/**
+ * Serializes an Error object for logging, extracting HTTP-specific data
+ * from axios/fetch errors while preserving standard error properties.
+ *
+ * @example
+ * // Axios error
+ * try {
+ *   await axios.get('/api/data');
+ * } catch (error) {
+ *   const serialized = serializeError(error);
+ *   // serialized.http.status = 400
+ *   // serialized.http.responseData = { error: "invalid input" }
+ * }
+ */
+declare function serializeError(error: unknown): SerializedError;
+
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string, ancestors?: WeakSet<object>, depth?: number): Record<string, unknown>;
 declare function formatLogfmtValue(value: unknown): string;
 declare function formatLogfmt(data: Record<string, unknown>): string;
 
@@ -315,6 +404,7 @@ declare const CloudWatchConfigSchema: z.ZodType<CloudWatchConfig>;
 declare const LevelConfigObjectSchema: z.ZodType<LevelConfigObject>;
 declare const LevelConfigSchema: z.ZodType<LevelConfig>;
 declare const CallerConfigSchema: z.ZodType<CallerConfig>;
+declare const AutoShutdownConfigSchema: z.ZodType<AutoShutdownConfig>;
 declare const LoggerConfigSchema: z.ZodObject<{
     level: z.ZodType<LevelConfig, unknown, z.core.$ZodTypeInternals<LevelConfig, unknown>>;
     console: z.ZodType<ConsoleConfig, unknown, z.core.$ZodTypeInternals<ConsoleConfig, unknown>>;
@@ -324,6 +414,7 @@ declare const LoggerConfigSchema: z.ZodObject<{
     cloudwatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>, z.ZodArray<z.ZodType<CloudWatchConfig, unknown, z.core.$ZodTypeInternals<CloudWatchConfig, unknown>>>]>>;
     caller: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<CallerConfig, unknown, z.core.$ZodTypeInternals<CallerConfig, unknown>>]>>;
     hostname: z.ZodOptional<z.ZodString>;
+    autoShutdown: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodType<AutoShutdownConfig, unknown, z.core.$ZodTypeInternals<AutoShutdownConfig, unknown>>]>>;
 }, z.core.$strip>;
 declare function validateConfig(config: unknown): z.infer<typeof LoggerConfigSchema>;
 declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
@@ -335,6 +426,7 @@ declare function safeValidateConfig(config: unknown): z.ZodSafeParseResult<{
     cloudwatch?: CloudWatchConfig | CloudWatchConfig[] | undefined;
     caller?: boolean | CallerConfig | undefined;
     hostname?: string | undefined;
+    autoShutdown?: boolean | AutoShutdownConfig | undefined;
 }>;
 
-export { BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, safeValidateConfig, validateConfig };
+export { type AutoShutdownConfig, AutoShutdownConfigSchema, BaseHttpTransport, type BaseHttpTransportOptions, type BufferOptions, type BufferedMessage, type CallerConfig, CallerConfigSchema, type CallerInfo, type CloudWatchConfig, CloudWatchConfigSchema, CloudWatchTransport, type ConsoleConfig, ConsoleConfigSchema, type DiscordConfig, DiscordConfigSchema, DiscordTransport, type FileConfig, FileConfigSchema, type GracefulShutdownOptions, type HttpErrorData, type HttpTransportBaseConfig, HttpTransportBaseConfigSchema, LOG_LEVELS, type LevelConfig, type LevelConfigObject, LevelConfigObjectSchema, LevelConfigSchema, type LevelOverride, type LevelOverrideMatch, type LevelRule, LevelRuleSchema, type LogFormat, LogFormatSchema, type LogLevel, LogLevelSchema, type LogStreamName, LogStreamNameSchema, type LogStreamPattern, type LogStreamPatternConfig, LogStreamPatternConfigSchema, LogStreamPatternSchema, type LogStreamTemplateConfig, LogStreamTemplateConfigSchema, Logger, type LoggerConfig, LoggerConfigSchema, type LoggerContext, LoggerStore, type MaskSecretsOptions, MessageBuffer, type Meta, type RequestIdOptions, type SerializedError, type SingletonLogger, type TelegramConfig, TelegramConfigSchema, TelegramTransport, type TimingResult, assertLogLevel, createMasker, createSingletonLogger, extractRequestId, flattenObject, formatCallerInfo, formatLogfmt, formatLogfmtValue, generateRequestId, getCallerInfo, getOrGenerateRequestId, isValidLogLevel, maskSecrets, matchesContext, measureAsync, measureSync, registerShutdown, safeValidateConfig, serializeError, validateConfig };