@qianxude/logger 0.1.4

package/README.md

@@ -0,0 +1,352 @@
+# @qianxude/logger
+
+Production-ready pino-based logger implementations for the qianxude stack.
+
+## Installation
+
+```bash
+bun add @qianxude/logger
+```
+
+## Overview
+
+This package provides:
+
+1. **Factory functions** to create raw pino loggers configured for common use cases
+2. **PinoLogger class** that wraps pino and implements the stack-standard `Logger` interface from `@qianxude/shared`
+
+## Quick Start
+
+### Pretty Console Logger (Development)
+
+```typescript
+import { createPrettyPino, PinoLogger } from '@qianxude/logger';
+
+// Create a raw pino logger with pretty output
+const rawPino = createPrettyPino({
+  level: 'debug',
+  colorize: true,
+});
+
+// Wrap it as a stack-standard Logger
+const logger = new PinoLogger(rawPino, { service: 'my-app' });
+
+logger.info('Application started');
+logger.debug({ userId: 123 }, 'User logged in');
+logger.error({ err: new Error('Oops') }, 'Something went wrong');
+```
+
+### Duo-Target Logger (Production)
+
+Outputs to both console (pretty) and file (with rotation):
+
+```typescript
+import { createDuoTargetPino, PinoLogger } from '@qianxude/logger';
+
+const rawPino = createDuoTargetPino({
+  level: 'info',
+  file: './logs/app.log',
+  frequency: 'daily',      // Rotate daily
+  limit: { count: 7 },     // Keep 7 days of logs
+});
+
+const logger = new PinoLogger(rawPino);
+logger.info('Application started');
+```
+
+### File-Only Logger
+
+```typescript
+import { createRollFilePino, PinoLogger } from '@qianxude/logger';
+
+const rawPino = createRollFilePino({
+  level: 'info',
+  file: './logs/app.log',
+  size: '10m',             // Rotate at 10MB
+  limit: { count: 5 },     // Keep 5 rotated files
+});
+
+const logger = new PinoLogger(rawPino);
+```
+
+## Logger Interface
+
+`PinoLogger` implements the `Logger` interface from `@qianxude/shared`:
+
+```typescript
+interface Logger {
+  // Log methods
+  log(level: LogLevel, message: string, ctx?: Context): void;
+  fatal(message: string, ctx?: Context): void;
+  error(message: string, ctx?: Context): void;
+  warn(message: string, ctx?: Context): void;
+  info(message: string, ctx?: Context): void;
+  debug(message: string, ctx?: Context): void;
+  trace(message: string, ctx?: Context): void;
+
+  // Context management
+  get ctx(): Context;
+  attach(key: string, value: any): void;
+  attach(ctx: Context): void;
+  detach(ctx: Context): void;
+  spawn(ctx?: Context): this;
+}
+```
+
+### Context Management
+
+```typescript
+// Attach context
+logger.attach('userId', 123);
+logger.attach({ requestId: 'abc-123', method: 'GET' });
+
+// Create child logger with extended context
+const childLogger = logger.spawn({ operation: 'query' });
+childLogger.info('Executing query'); // Includes userId, requestId, method, operation
+
+// Detach context
+logger.detach({ userId: undefined });
+```
+
+### Log Levels
+
+- `trace` (10) - Ultra-verbose tracing
+- `debug` (20) - Debugging information
+- `info` (30) - General information (default)
+- `warn` (40) - Warnings
+- `error` (50) - Errors
+- `fatal` (60) - Critical errors
+
+## Factory Functions
+
+### createPrettyPino(options)
+
+Creates a pino logger with pretty console output.
+
+```typescript
+interface PrettyPinoOptions {
+  level?: LogLevel;        // Default: 'info'
+  colorize?: boolean;      // Default: true
+  translateTime?: string;  // Default: 'SYS:standard'
+  prettyOptions?: pino.PrettyOptions;
+}
+```
+
+### createDuoTargetPino(options)
+
+Creates a pino logger that outputs to both console (pretty) and file (with rotation).
+
+```typescript
+interface DuoTargetPinoOptions {
+  level?: LogLevel;        // Default: 'info'
+  file: string;            // Required: log file path
+  frequency?: 'daily' | 'hourly' | number;  // Time-based rotation
+  size?: string | number;  // Size-based rotation (e.g., '10m')
+  mkdir?: boolean;         // Create parent dirs (default: true)
+  symlink?: boolean;       // Create symlink to current log (default: true)
+  limit?: { count: number }; // Number of rotated files to keep
+  colorize?: boolean;      // Console colorize (default: true)
+  translateTime?: string;  // Default: 'SYS:standard'
+}
+```
+
+### createRollFilePino(options)
+
+Creates a pino logger that outputs only to file (with rotation).
+
+```typescript
+interface RotationOptions {
+  level?: LogLevel;
+  file: string;            // Required
+  frequency?: 'daily' | 'hourly' | number;
+  size?: string | number;
+  mkdir?: boolean;
+  symlink?: boolean;
+  limit?: { count: number };
+}
+```
+
+### createPino(options)
+
+Creates a basic pino logger with custom options.
+
+```typescript
+const logger = createPino({
+  level: 'debug',
+  base: { service: 'my-service' },
+});
+```
+
+## Environment Variables
+
+The logger package supports configuration via environment variables. Use the parsing functions to convert environment variables into logger options.
+
+### Required vs Optional
+
+| Variable | Required For | Optional For | Default |
+|----------|--------------|--------------|---------|
+| `LOG_FILE` | `parsePinoRollOptionsEnv`, `parseDuoTargetPinoOptionsEnv` | `parsePrettyPinoOptionsEnv` | - |
+| `LOG_LEVEL` | - | All functions | `'info'` |
+| `LOG_COLORIZE` | - | All functions | `true` |
+| `LOG_TRANSLATE_TIME` | - | All functions | `'SYS:standard'` |
+| `LOG_FILE_SIZE` | - | File logging | - |
+| `LOG_FILE_FREQUENCY` | - | File logging | - |
+| `LOG_FILE_EXTENSION` | - | File logging | - |
+| `LOG_FILE_SYMLINK` | - | File logging | `true` |
+| `LOG_FILE_LIMIT_COUNT` | - | File logging | - |
+| `LOG_FILE_DATE_FORMAT` | - | File logging | - |
+| `LOG_FILE_MKDIR` | - | File logging | `true` |
+
+**Important**: `LOG_FILE` is the only required environment variable, and it's only required for file-based logging functions (`parsePinoRollOptionsEnv` and `parseDuoTargetPinoOptionsEnv`).
+
+### Available Environment Variables
+
+#### Common/Pretty Options (All Optional)
+
+| Variable | Description | Example Values |
+|----------|-------------|----------------|
+| `LOG_LEVEL` | Minimum log level | `fatal`, `error`, `warn`, `info`, `debug`, `trace` |
+| `LOG_COLORIZE` | Enable colorized output | `true`, `false` |
+| `LOG_TRANSLATE_TIME` | Time format string | `SYS:standard`, `SYS:iso` |
+
+#### File Roll Options
+
+| Variable | Description | Required | Example Values |
+|----------|-------------|----------|----------------|
+| `LOG_FILE` | Log file path | **Yes** (for file logging) | `./logs/app.log` |
+| `LOG_FILE_SIZE` | Max file size | No | `10m`, `100k`, `1g`, or number (MB) |
+| `LOG_FILE_FREQUENCY` | Rotation frequency | No | `daily`, `hourly`, or number (ms) |
+| `LOG_FILE_EXTENSION` | File extension to append | No | `.log` |
+| `LOG_FILE_SYMLINK` | Create symlink to current log | No | `true`, `false` |
+| `LOG_FILE_LIMIT_COUNT` | Number of rotated files to keep | No | `7` |
+| `LOG_FILE_DATE_FORMAT` | Date format for filename | No | `yyyy-MM-dd` |
+| `LOG_FILE_MKDIR` | Create parent directories | No | `true`, `false` |
+
+### Usage Examples
+
+#### Parse Pretty Logger Options
+
+```typescript
+import { parsePrettyPinoOptionsEnv, createPrettyPino } from '@qianxude/logger';
+
+// Parse from process.env
+const options = parsePrettyPinoOptionsEnv();
+
+// Or pass a custom env object
+const options = parsePrettyPinoOptionsEnv({
+  LOG_LEVEL: 'debug',
+  LOG_COLORIZE: 'true',
+});
+
+const logger = createPrettyPino(options);
+```
+
+#### Parse File Roll Options
+
+```typescript
+import { parsePinoRollOptionsEnv, createRollFilePino } from '@qianxude/logger';
+
+const options = parsePinoRollOptionsEnv({
+  LOG_FILE: './logs/app.log',
+  LOG_FILE_FREQUENCY: 'daily',
+  LOG_FILE_LIMIT_COUNT: '7',
+});
+
+if (options.file) {
+  const logger = createRollFilePino({ level: 'info', ...options });
+}
+```
+
+#### Parse Duo-Target Options
+
+```typescript
+import { parseDuoTargetPinoOptionsEnv, createDuoTargetPino } from '@qianxude/logger';
+
+const options = parseDuoTargetPinoOptionsEnv(process.env);
+
+if (options.file) {
+  const logger = createDuoTargetPino(options);
+}
+```
+
+### Environment Variable Constants
+
+Use the exported `LOG_ENV_VARS` constant for type-safe env var names:
+
+```typescript
+import { LOG_ENV_VARS } from '@qianxude/logger';
+
+console.log(LOG_ENV_VARS.LOG_LEVEL);     // 'LOG_LEVEL'
+console.log(LOG_ENV_VARS.LOG_FILE);      // 'LOG_FILE'
+```
+
+### Error Handling
+
+The parsing functions throw descriptive errors for invalid values:
+
+```typescript
+import { parsePrettyPinoOptionsEnv } from '@qianxude/logger';
+
+try {
+  parsePrettyPinoOptionsEnv({ LOG_LEVEL: 'verbose' });
+} catch (err) {
+  // Error: Invalid LOG_LEVEL value 'verbose'. Must be one of: fatal, error, warn, info, debug, trace.
+}
+```
+
+### Graceful Error Handling with `noThrow`
+
+When you want to handle missing required env vars gracefully without exceptions, use the `noThrow` option:
+
+```typescript
+import { parsePinoRollOptionsEnv, createRollFilePino } from '@qianxude/logger';
+
+const options = parsePinoRollOptionsEnv(process.env, { noThrow: true });
+
+if (options._invalid) {
+  console.warn('File logging disabled:', options._invalidVars?.join(', '));
+  // Fall back to console-only logging
+} else {
+  const logger = createRollFilePino({ level: 'info', ...options });
+}
+```
+
+This is useful when file logging is optional and you want to check at runtime whether it's available.
+
+```typescript
+import { parseDuoTargetPinoOptionsEnv, createDuoTargetPino, createPrettyPino } from '@qianxude/logger';
+
+const options = parseDuoTargetPinoOptionsEnv(process.env, { noThrow: true });
+
+// Use duo-target if LOG_FILE is set, otherwise fall back to pretty console
+const logger = options._invalid
+  ? createPrettyPino({ level: 'info' })
+  : createDuoTargetPino(options);
+```
+
+## Integration with @qianxude/shared
+
+Use with the shared logger:
+
+```typescript
+import { logger } from '@qianxude/shared';
+import { createDuoTargetPino, PinoLogger } from '@qianxude/logger';
+
+// At app startup, configure the shared logger
+const pinoLogger = new PinoLogger(createDuoTargetPino({
+  level: 'info',
+  file: './logs/app.log',
+  frequency: 'daily',
+}));
+
+// Use configureLogger to set the delegate
+import { configureLogger } from '@qianxude/shared';
+configureLogger(logger, pinoLogger);
+
+// Now all packages using the shared logger will use pino
+logger.info('Application initialized');
+```
+
+## License
+
+MIT

package/dist/env.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Environment variable parsing for logger options.
+ *
+ * This module provides conventions and parsing functions for configuring
+ * logger options via environment variables.
+ */
+import type { PrettyPinoOptions, DuoTargetPinoOptions } from './pino-factory.js';
+import type { PinoRollOptions } from './types/index.js';
+/**
+ * Options for environment variable parsing functions.
+ */
+export interface ParseEnvOptions {
+    /**
+     * If true, don't throw errors for missing required env vars.
+     * Instead, return partial options with `_invalid` metadata.
+     * @default false
+     */
+    noThrow?: boolean;
+}
+/**
+ * Metadata properties added to parsed options when `noThrow=true`
+ * and required env vars are missing or invalid.
+ */
+export interface ParseEnvMeta {
+    /**
+     * True if any required env var is missing or invalid.
+     */
+    _invalid?: boolean;
+    /**
+     * List of required env var names that are missing or invalid.
+     */
+    _invalidVars?: string[];
+}
+/**
+ * Result type for `parsePinoRollOptionsEnv` with `noThrow=true`.
+ */
+export type ParsedPinoRollOptions = Partial<PinoRollOptions> & ParseEnvMeta;
+/**
+ * Result type for `parseDuoTargetPinoOptionsEnv` with `noThrow=true`.
+ */
+export type ParsedDuoTargetPinoOptions = Partial<DuoTargetPinoOptions> & ParseEnvMeta;
+/**
+ * Environment variable names for logger configuration.
+ */
+export declare const LOG_ENV_VARS: {
+    readonly LOG_LEVEL: "LOG_LEVEL";
+    readonly LOG_COLORIZE: "LOG_COLORIZE";
+    readonly LOG_TRANSLATE_TIME: "LOG_TRANSLATE_TIME";
+    readonly LOG_FILE: "LOG_FILE";
+    readonly LOG_FILE_SIZE: "LOG_FILE_SIZE";
+    readonly LOG_FILE_FREQUENCY: "LOG_FILE_FREQUENCY";
+    readonly LOG_FILE_EXTENSION: "LOG_FILE_EXTENSION";
+    readonly LOG_FILE_SYMLINK: "LOG_FILE_SYMLINK";
+    readonly LOG_FILE_LIMIT_COUNT: "LOG_FILE_LIMIT_COUNT";
+    readonly LOG_FILE_DATE_FORMAT: "LOG_FILE_DATE_FORMAT";
+    readonly LOG_FILE_MKDIR: "LOG_FILE_MKDIR";
+};
+/**
+ * Parse PrettyPinoOptions from environment variables.
+ *
+ * All environment variables are optional.
+ *
+ * ## Optional Environment Variables
+ *
+ * - `LOG_LEVEL`: Log level ('fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'), default: 'info'
+ * - `LOG_COLORIZE`: Enable colorized output ('true' | 'false'), default: true
+ * - `LOG_TRANSLATE_TIME`: Time format string, default: 'SYS:standard'
+ *
+ * @param env - Environment variables object (defaults to process.env)
+ * @returns Partial PrettyPinoOptions parsed from environment
+ * @throws Error if any environment variable value is invalid
+ *
+ * @example
+ * ```ts
+ * const options = parsePrettyPinoOptionsEnv(process.env);
+ * const logger = createPrettyPino(options);
+ * ```
+ */
+export declare function parsePrettyPinoOptionsEnv(env?: NodeJS.ProcessEnv): Partial<PrettyPinoOptions>;
+/**
+ * Parse PinoRollOptions from environment variables.
+ *
+ * ## Required Environment Variables
+ *
+ * - `LOG_FILE`: Log file path. **Required** for file-based logging.
+ *
+ * ## Optional Environment Variables
+ *
+ * - `LOG_FILE_SIZE`: Max file size ('10m', '100k', '1g', or number in MB)
+ * - `LOG_FILE_FREQUENCY`: Rotation frequency ('daily', 'hourly', or number in ms)
+ * - `LOG_FILE_EXTENSION`: File extension to append
+ * - `LOG_FILE_SYMLINK`: Create symlink to current log ('true' | 'false'), default: true
+ * - `LOG_FILE_LIMIT_COUNT`: Number of rotated files to keep
+ * - `LOG_FILE_DATE_FORMAT`: Date format for filename (date-fns format)
+ * - `LOG_FILE_MKDIR`: Create parent directories ('true' | 'false'), default: true
+ *
+ * @param env - Environment variables object (defaults to process.env)
+ * @returns Partial PinoRollOptions parsed from environment
+ * @throws Error if LOG_FILE is missing/empty (when noThrow=false) or any env var value is invalid
+ *
+ * @example
+ * ```ts
+ * // Default: throws if LOG_FILE is missing
+ * const options = parsePinoRollOptionsEnv(process.env);
+ * if (options.file) {
+ *   const logger = createRollFilePino({ level: 'info', ...options });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With noThrow: returns partial options with metadata instead of throwing
+ * const options = parsePinoRollOptionsEnv(process.env, { noThrow: true });
+ * if (options._invalid) {
+ *   console.log('Missing required env vars:', options._invalidVars);
+ * } else {
+ *   const logger = createRollFilePino({ level: 'info', ...options });
+ * }
+ * ```
+ */
+export declare function parsePinoRollOptionsEnv(env?: NodeJS.ProcessEnv): Partial<PinoRollOptions>;
+export declare function parsePinoRollOptionsEnv(env: NodeJS.ProcessEnv | undefined, options: ParseEnvOptions): ParsedPinoRollOptions;
+/**
+ * Parse DuoTargetPinoOptions from environment variables.
+ *
+ * Combines both pretty options and roll options from environment.
+ *
+ * ## Required Environment Variables
+ *
+ * - `LOG_FILE`: Log file path. **Required** for duo-target logging (file output).
+ *
+ * ## Optional Environment Variables
+ *
+ * ### Common/Pretty Options
+ * - `LOG_LEVEL`: Log level ('fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'), default: 'info'
+ * - `LOG_COLORIZE`: Enable colorized output ('true' | 'false'), default: true
+ * - `LOG_TRANSLATE_TIME`: Time format string, default: 'SYS:standard'
+ *
+ * ### File Roll Options
+ * - `LOG_FILE_SIZE`: Max file size ('10m', '100k', '1g', or number in MB)
+ * - `LOG_FILE_FREQUENCY`: Rotation frequency ('daily', 'hourly', or number in ms)
+ * - `LOG_FILE_EXTENSION`: File extension to append
+ * - `LOG_FILE_SYMLINK`: Create symlink to current log ('true' | 'false'), default: true
+ * - `LOG_FILE_LIMIT_COUNT`: Number of rotated files to keep
+ * - `LOG_FILE_DATE_FORMAT`: Date format for filename (date-fns format)
+ * - `LOG_FILE_MKDIR`: Create parent directories ('true' | 'false'), default: true
+ *
+ * @param env - Environment variables object (defaults to process.env)
+ * @returns Partial DuoTargetPinoOptions parsed from environment
+ * @throws Error if LOG_FILE is missing/empty (when noThrow=false) or any env var value is invalid
+ *
+ * @example
+ * ```ts
+ * // Default: throws if LOG_FILE is missing
+ * const options = parseDuoTargetPinoOptionsEnv(process.env);
+ * if (options.file) {
+ *   const logger = createDuoTargetPino(options);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With noThrow: returns partial options with metadata instead of throwing
+ * const options = parseDuoTargetPinoOptionsEnv(process.env, { noThrow: true });
+ * if (options._invalid) {
+ *   console.log('Missing required env vars:', options._invalidVars);
+ * } else {
+ *   const logger = createDuoTargetPino(options);
+ * }
+ * ```
+ */
+export declare function parseDuoTargetPinoOptionsEnv(env?: NodeJS.ProcessEnv): Partial<DuoTargetPinoOptions>;
+export declare function parseDuoTargetPinoOptionsEnv(env: NodeJS.ProcessEnv | undefined, options: ParseEnvOptions): ParsedDuoTargetPinoOptions;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,GAAG,YAAY,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC,GAAG,YAAY,CAAC;AAEtF;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;CAef,CAAC;AAuHX;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAkB5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAC3F,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,eAAe,GACvB,qBAAqB,CAAC;AAiEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACrG,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,eAAe,GACvB,0BAA0B,CAAC"}