@rawnodes/logger 2.5.0 → 2.6.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,35 @@ 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>;
+
+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 +356,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 +366,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 +378,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 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, registerShutdown, safeValidateConfig, 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,35 @@ 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>;
+
+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 +356,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 +366,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 +378,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 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, registerShutdown, safeValidateConfig, validateConfig };

package/dist/index.js

@@ -689,6 +689,7 @@ function createFormattedFilterStream(format, level, rules, store, destination) {
 }
 function createStreams(config, store) {
   const streams = [];
+  const transports = [];
   const consoleStream = createFormattedFilterStream(
     config.console.format,
     config.console.level,
@@ -736,6 +737,7 @@ function createStreams(config, store) {
   }
   for (const discordConfig of toArray(config.discord)) {
     const transport = new DiscordTransport(discordConfig);
+    transports.push(transport);
     const discordStream = createHttpTransportStream(transport, discordConfig.level, discordConfig.rules, store);
     streams.push({
       level: "trace",
@@ -744,6 +746,7 @@ function createStreams(config, store) {
   }
   for (const telegramConfig of toArray(config.telegram)) {
     const transport = new TelegramTransport(telegramConfig);
+    transports.push(transport);
     const telegramStream = createHttpTransportStream(transport, telegramConfig.level, telegramConfig.rules, store);
     streams.push({
       level: "trace",
@@ -752,13 +755,17 @@ function createStreams(config, store) {
   }
   for (const cloudwatchConfig of toArray(config.cloudwatch)) {
     const transport = new CloudWatchTransport(cloudwatchConfig, config.hostname);
+    transports.push(transport);
     const cwStream = createHttpTransportStream(transport, cloudwatchConfig.level, cloudwatchConfig.rules, store);
     streams.push({
       level: "trace",
       stream: cwStream
     });
   }
-  return pino__default.default.multistream(streams);
+  return {
+    destination: pino__default.default.multistream(streams),
+    transports
+  };
 }
 function toArray(value) {
   if (!value) return [];
@@ -843,14 +850,14 @@ function createState(config, store) {
     levelOverrides.set(key, rule);
   }
   const { contextIndex, complexRules } = buildIndexes(levelOverrides);
-  const streams = createStreams(config, loggerStore);
+  const { destination, transports } = createStreams(config, loggerStore);
   const options = {
     level: "trace",
     // Accept all, we filter in shouldLog()
     customLevels: CUSTOM_LEVELS,
     base: { hostname: config.hostname ?? os.hostname() }
   };
-  const pinoLogger = pino__default.default(options, streams);
+  const pinoLogger = pino__default.default(options, destination);
   let callerConfig;
   if (config.caller === true) {
     callerConfig = {};
@@ -864,7 +871,8 @@ function createState(config, store) {
     levelOverrides,
     contextIndex,
     complexRules,
-    callerConfig
+    callerConfig,
+    transports
   };
 }
 function rebuildIndexes(state) {
@@ -1010,6 +1018,10 @@ var CallerConfigSchema = zod.z.object({
   depth: zod.z.number().int().nonnegative().optional(),
   fullPath: zod.z.boolean().optional()
 });
+var AutoShutdownConfigSchema = zod.z.object({
+  timeout: zod.z.number().int().positive().optional(),
+  signals: zod.z.array(zod.z.string()).optional()
+});
 var LoggerConfigSchema = zod.z.object({
   level: LevelConfigSchema,
   console: ConsoleConfigSchema,
@@ -1018,7 +1030,8 @@ var LoggerConfigSchema = zod.z.object({
   telegram: zod.z.union([TelegramConfigSchema, zod.z.array(TelegramConfigSchema)]).optional(),
   cloudwatch: zod.z.union([CloudWatchConfigSchema, zod.z.array(CloudWatchConfigSchema)]).optional(),
   caller: zod.z.union([zod.z.boolean(), CallerConfigSchema]).optional(),
-  hostname: zod.z.string().optional()
+  hostname: zod.z.string().optional(),
+  autoShutdown: zod.z.union([zod.z.boolean(), AutoShutdownConfigSchema]).optional()
 });
 function validateConfig(config) {
   return LoggerConfigSchema.parse(config);
@@ -1087,6 +1100,53 @@ function formatCallerInfo(info) {
   return location;
 }
 
+// src/utils/shutdown.ts
+var DEFAULT_OPTIONS2 = {
+  timeout: 5e3,
+  exitCode: 0,
+  signals: ["SIGTERM", "SIGINT"]
+};
+var registered = false;
+function registerShutdown(logger, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS2, ...options };
+  const shutdown = async (signal) => {
+    if (signal) {
+      console.error(`[Logger] Received ${signal}, shutting down gracefully...`);
+    }
+    try {
+      if (opts.onShutdown) {
+        await opts.onShutdown();
+      }
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Shutdown timed out after ${opts.timeout}ms`));
+        }, opts.timeout);
+      });
+      await Promise.race([
+        logger.shutdown(),
+        timeoutPromise
+      ]);
+      if (signal) {
+        console.error("[Logger] Graceful shutdown completed");
+        process.exit(opts.exitCode);
+      }
+    } catch (error) {
+      console.error("[Logger] Shutdown error:", error instanceof Error ? error.message : error);
+      if (signal) {
+        process.exit(1);
+      }
+    }
+  };
+  if (!registered) {
+    for (const signal of opts.signals) {
+      process.on(signal, () => void shutdown(signal));
+    }
+    process.on("beforeExit", () => void shutdown());
+    registered = true;
+  }
+  return shutdown;
+}
+
 // src/logger.ts
 var Logger = class _Logger {
   constructor(state, context) {
@@ -1097,7 +1157,12 @@ var Logger = class _Logger {
   static create(config, store) {
     const validatedConfig = validateConfig(config);
     const state = createState(validatedConfig, store);
-    return new _Logger(state, "APP");
+    const logger = new _Logger(state, "APP");
+    if (validatedConfig.autoShutdown) {
+      const shutdownConfig = typeof validatedConfig.autoShutdown === "object" ? validatedConfig.autoShutdown : {};
+      registerShutdown(logger, shutdownConfig);
+    }
+    return logger;
   }
   for(context) {
     return new _Logger(this.state, context);
@@ -1139,6 +1204,15 @@ var Logger = class _Logger {
   getLevelOverrides() {
     return Array.from(this.state.levelOverrides.values());
   }
+  // Shutdown
+  /**
+   * Gracefully shutdown the logger, flushing all pending messages.
+   * Should be called before process exit to ensure no logs are lost.
+   */
+  async shutdown() {
+    const closePromises = this.state.transports.map((transport) => transport.close());
+    await Promise.all(closePromises);
+  }
   // Profiling
   profile(id, meta) {
     const existing = this.profileTimers.get(id);
@@ -1405,16 +1479,28 @@ function createMasker(options = {}) {
 }
 
 // src/formatters.ts
-function flattenObject(obj, prefix = "") {
+var MAX_FLATTEN_DEPTH = 10;
+var CIRCULAR_REF = "[Circular]";
+function flattenObject(obj, prefix = "", ancestors = /* @__PURE__ */ new WeakSet(), depth = 0) {
   const result = {};
+  if (depth > MAX_FLATTEN_DEPTH) {
+    result[prefix || "value"] = "[Max depth exceeded]";
+    return result;
+  }
+  ancestors.add(obj);
   for (const [key, value] of Object.entries(obj)) {
     const newKey = prefix ? `${prefix}.${key}` : key;
     if (value !== null && typeof value === "object" && !Array.isArray(value) && !(value instanceof Error)) {
-      Object.assign(result, flattenObject(value, newKey));
+      if (ancestors.has(value)) {
+        result[newKey] = CIRCULAR_REF;
+      } else {
+        Object.assign(result, flattenObject(value, newKey, ancestors, depth + 1));
+      }
     } else {
       result[newKey] = value;
     }
   }
+  ancestors.delete(obj);
   return result;
 }
 function formatLogfmtValue(value) {
@@ -1443,6 +1529,7 @@ function formatLogfmt(data) {
   return Object.entries(flattened).filter(([, value]) => value !== void 0 && value !== null).map(([key, value]) => `${key}=${formatLogfmtValue(value)}`).join(" ");
 }
 
+exports.AutoShutdownConfigSchema = AutoShutdownConfigSchema;
 exports.BaseHttpTransport = BaseHttpTransport;
 exports.CallerConfigSchema = CallerConfigSchema;
 exports.CloudWatchConfigSchema = CloudWatchConfigSchema;
@@ -1484,6 +1571,7 @@ exports.maskSecrets = maskSecrets;
 exports.matchesContext = matchesContext;
 exports.measureAsync = measureAsync;
 exports.measureSync = measureSync;
+exports.registerShutdown = registerShutdown;
 exports.safeValidateConfig = safeValidateConfig;
 exports.validateConfig = validateConfig;
 //# sourceMappingURL=index.js.map