@qlover/scripts-context 1.0.0 → 1.1.2

package/dist/index.js

@@ -2818,9 +2818,116 @@ var LogEvent = class {
     this.context = context;
     this.timestamp = Date.now();
   }
+  /**
+   * Timestamp when the log event was created
+   *
+   * Automatically set to the current time in milliseconds since the Unix epoch
+   * when the event is constructed. This ensures accurate timing information
+   * for each log entry.
+   *
+   * @example
+   * ```typescript
+   * const event = new LogEvent('info', ['message'], 'app');
+   * console.log(new Date(event.timestamp).toISOString());
+   * // Output: "2024-03-21T14:30:45.123Z"
+   * ```
+   */
   timestamp;
 };
 var LogContext = class {
+  /**
+   * Creates a new LogContext instance
+   *
+   * @param value - Optional context value of type Value
+   *
+   * The value parameter is marked as optional to support:
+   * - Empty contexts (no value provided)
+   * - Explicitly undefined values
+   * - Nullable types (Value | null)
+   *
+   * The value is stored as a public property to allow:
+   * - Direct access in formatters and handlers
+   * - Type-safe value extraction
+   * - Optional chaining support
+   *
+   * @example Basic construction
+   * ```typescript
+   * // With value
+   * const context = new LogContext({ userId: 123 });
+   * console.log(context.value?.userId); // 123
+   *
+   * // Empty context
+   * const empty = new LogContext();
+   * console.log(empty.value); // undefined
+   * ```
+   *
+   * @example Type-safe construction
+   * ```typescript
+   * interface UserContext {
+   *   id: number;
+   *   name: string;
+   *   role?: string;
+   * }
+   *
+   * const context = new LogContext<UserContext>({
+   *   id: 123,
+   *   name: 'John',
+   *   role: 'admin'  // Optional property
+   * });
+   *
+   * // Type-safe access
+   * const userId = context.value?.id;  // number | undefined
+   * const role = context.value?.role;  // string | undefined
+   * ```
+   *
+   * @example Nullable context
+   * ```typescript
+   * type NullableContext = {
+   *   sessionId: string;
+   * } | null;
+   *
+   * // With value
+   * const active = new LogContext<NullableContext>({
+   *   sessionId: 'sess-123'
+   * });
+   *
+   * // With null
+   * const inactive = new LogContext<NullableContext>(null);
+   *
+   * // Type-safe null handling
+   * console.log(active.value?.sessionId);    // 'sess-123'
+   * console.log(inactive.value?.sessionId);  // undefined
+   * ```
+   *
+   * @example Context in logging
+   * ```typescript
+   * interface RequestContext {
+   *   path: string;
+   *   method: string;
+   *   duration: number;
+   * }
+   *
+   * const context = new LogContext<RequestContext>({
+   *   path: '/api/users',
+   *   method: 'GET',
+   *   duration: 150
+   * });
+   *
+   * // Using context in log messages
+   * logger.info('Request completed', context);
+   *
+   * // Accessing context in formatters
+   * class RequestFormatter implements FormatterInterface<RequestContext> {
+   *   format(event: LogEvent<RequestContext>): string[] {
+   *     const ctx = event.context?.value;
+   *     return [
+   *       ctx ? `${ctx.method} ${ctx.path} (${ctx.duration}ms)` : 'Unknown',
+   *       ...event.args
+   *     ];
+   *   }
+   * }
+   * ```
+   */
   constructor(value) {
     this.value = value;
   }
@@ -3113,23 +3220,189 @@ var Logger = class {
   }
 };
 var ConsoleHandler = class {
+  /**
+   * Creates a new ConsoleHandler instance
+   *
+   * @param formatter - Optional formatter for customizing log message format
+   *                   If not provided, raw log messages will be output
+   *
+   * @example Without formatter
+   * ```typescript
+   * const handler = new ConsoleHandler();
+   * // Output: Raw message without formatting
+   * ```
+   *
+   * @example With timestamp formatter
+   * ```typescript
+   * const handler = new ConsoleHandler(
+   *   new TimestampFormatter({
+   *     locale: 'zh-CN',
+   *     prefixTemplate: '[{formattedTimestamp}] {level}:'
+   *   })
+   * );
+   * // Output: [2024-03-21 14:30:45] INFO: Message
+   * ```
+   *
+   * @example With JSON formatter
+   * ```typescript
+   * const handler = new ConsoleHandler(
+   *   new JSONFormatter({
+   *     pretty: true,
+   *     fields: ['timestamp', 'level', 'message']
+   *   })
+   * );
+   * // Output: {
+   * //   "timestamp": "2024-03-21T14:30:45.000Z",
+   * //   "level": "INFO",
+   * //   "message": "Application started"
+   * // }
+   * ```
+   */
   constructor(formatter = null) {
     this.formatter = formatter;
   }
   /**
-   * Set formatter
+   * Sets or updates the formatter for this handler
    *
-   * @override
-   * @param formatter
+   * This method allows dynamic updating of the formatter after handler creation.
+   * It's useful when you need to change the formatting style without creating
+   * a new handler instance.
+   *
+   * @override Implementation of HandlerInterface
+   * @param formatter - The formatter instance to use for formatting log messages
+   *
+   * @example Changing formatter at runtime
+   * ```typescript
+   * const handler = new ConsoleHandler();
+   * const logger = new Logger({ handlers: [handler] });
+   *
+   * // Initially no formatting
+   * logger.info('Plain message');
+   * // Output: Plain message
+   *
+   * // Switch to timestamp formatting
+   * handler.setFormatter(new TimestampFormatter());
+   * logger.info('Formatted message');
+   * // Output: [2024-03-21 14:30:45 INFO] Formatted message
+   *
+   * // Switch to JSON formatting
+   * handler.setFormatter(new JSONFormatter());
+   * logger.info('JSON message');
+   * // Output: {"timestamp":"2024-03-21T14:30:45.000Z","level":"INFO","message":"JSON message"}
+   * ```
+   *
+   * @example Conditional formatting
+   * ```typescript
+   * const handler = new ConsoleHandler();
+   * const logger = new Logger({ handlers: [handler] });
+   *
+   * if (process.env.NODE_ENV === 'development') {
+   *   // Use pretty formatting in development
+   *   handler.setFormatter(new TimestampFormatter({
+   *     prefixTemplate: '[{formattedTimestamp}] {level}:'
+   *   }));
+   * } else {
+   *   // Use JSON formatting in production
+   *   handler.setFormatter(new JSONFormatter({
+   *     fields: ['timestamp', 'level', 'message', 'metadata']
+   *   }));
+   * }
+   * ```
    */
   setFormatter(formatter) {
     this.formatter = formatter;
   }
   /**
-   * Append log event
+   * Processes and outputs a log event to the console
    *
-   * @override
-   * @param event
+   * This method:
+   * 1. Extracts level and arguments from the event
+   * 2. Applies formatting if a formatter is set
+   * 3. Selects appropriate console method based on level
+   * 4. Outputs the formatted message to the console
+   *
+   * @override Implementation of HandlerInterface
+   * @param event - The log event to process and output
+   *
+   * @example Basic event handling
+   * ```typescript
+   * const handler = new ConsoleHandler();
+   *
+   * // Simple message
+   * handler.append({
+   *   level: 'info',
+   *   args: ['Application started'],
+   *   timestamp: Date.now(),
+   *   loggerName: 'app'
+   * });
+   * // Console output: Application started
+   *
+   * // Message with context
+   * handler.append({
+   *   level: 'error',
+   *   args: [
+   *     'Database connection failed',
+   *     { host: 'localhost', port: 5432, error: 'Connection refused' }
+   *   ],
+   *   timestamp: Date.now(),
+   *   loggerName: 'db'
+   * });
+   * // Console output: Database connection failed { host: 'localhost', ... }
+   * ```
+   *
+   * @example Formatted event handling
+   * ```typescript
+   * const handler = new ConsoleHandler(
+   *   new TimestampFormatter({
+   *     prefixTemplate: '[{formattedTimestamp}] {level}:'
+   *   })
+   * );
+   *
+   * handler.append({
+   *   level: 'warn',
+   *   args: ['High memory usage', { usage: '85%' }],
+   *   timestamp: Date.now(),
+   *   loggerName: 'system'
+   * });
+   * // Console output: [2024-03-21 14:30:45] WARN: High memory usage { usage: '85%' }
+   * ```
+   *
+   * @example Level-specific console methods
+   * ```typescript
+   * const handler = new ConsoleHandler();
+   *
+   * // Uses console.error()
+   * handler.append({
+   *   level: 'error',
+   *   args: ['Critical error'],
+   *   timestamp: Date.now(),
+   *   loggerName: 'app'
+   * });
+   *
+   * // Uses console.warn()
+   * handler.append({
+   *   level: 'warn',
+   *   args: ['Deprecated feature used'],
+   *   timestamp: Date.now(),
+   *   loggerName: 'app'
+   * });
+   *
+   * // Uses console.debug()
+   * handler.append({
+   *   level: 'debug',
+   *   args: ['Processing request'],
+   *   timestamp: Date.now(),
+   *   loggerName: 'app'
+   * });
+   *
+   * // Unknown level falls back to console.log()
+   * handler.append({
+   *   level: 'custom',
+   *   args: ['Custom message'],
+   *   timestamp: Date.now(),
+   *   loggerName: 'app'
+   * });
+   * ```
    */
   append(event) {
     const { level, args } = event;
@@ -3145,12 +3418,87 @@ var defaultLocaleOptions = {
   timeZone: "UTC"
 };
 var TimestampFormatter = class {
+  /**
+   * Creates a new TimestampFormatter instance
+   *
+   * @param options - Configuration options for the formatter
+   *
+   * @example
+   * ```typescript
+   * const formatter = new TimestampFormatter({
+   *   locale: 'zh-CN',
+   *   prefixTemplate: '[{formattedTimestamp}] {level}:'
+   * });
+   * ```
+   */
   constructor(options = {}) {
     this.options = options;
   }
+  /**
+   * Replaces template variables in the prefix string with actual values
+   *
+   * This internal method handles the variable substitution in prefix templates,
+   * replacing placeholders like {timestamp} with their corresponding values.
+   *
+   * @param template - The template string containing variables in curly braces
+   * @param vars - Object containing variable names and their values
+   * @returns The template string with all variables replaced
+   *
+   * @example Internal usage
+   * ```typescript
+   * const vars = {
+   *   timestamp: '1679395845000',
+   *   level: 'INFO',
+   *   formattedTimestamp: '2024-03-21 14:30:45'
+   * };
+   *
+   * // Template: "[{formattedTimestamp}] {level}"
+   * // Result:  "[2024-03-21 14:30:45] INFO"
+   * const result = this.replacePrefix(template, vars);
+   * ```
+   *
+   * @protected
+   */
   replacePrefix(template, vars) {
     return template.replace(/\{([^{}]+)\}/g, (match, p1) => vars[p1] || match);
   }
+  /**
+   * Formats a log event by adding a timestamp prefix
+   *
+   * This method implements the FormatterInterface.format method. It:
+   * 1. Extracts format type from context (if provided)
+   * 2. Formats the timestamp according to locale and options
+   * 3. Builds the prefix using the template
+   * 4. Returns the formatted log entry
+   *
+   * @param event - The log event to format
+   * @param event.timestamp - Event timestamp in milliseconds
+   * @param event.level - Log level (e.g., INFO, ERROR)
+   * @param event.args - Original log message arguments
+   * @param event.context - Optional context with format customization
+   * @param event.loggerName - Name of the logger instance
+   *
+   * @returns Array containing the formatted prefix followed by original arguments
+   *
+   * @example Internal processing
+   * ```typescript
+   * // Input event:
+   * {
+   *   timestamp: 1679395845000,
+   *   level: 'INFO',
+   *   args: ['User logged in', { userId: 123 }],
+   *   context: { formatType: 'datetime' },
+   *   loggerName: 'UserService'
+   * }
+   *
+   * // Output array:
+   * [
+   *   '[2024-03-21 14:30:45 INFO]',
+   *   'User logged in',
+   *   { userId: 123 }
+   * ]
+   * ```
+   */
   format({ timestamp, level, args, context, loggerName }) {
     const {
       locale = "zh-CN",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qlover/scripts-context",
   "description": "A scripts context for frontwork",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "type": "module",
   "private": false,
   "homepage": "https://github.com/qlover/fe-base/tree/master/packages/scripts-context#readme",
@@ -45,15 +45,15 @@
     "@types/shelljs": "^0.8.15",
     "lodash": "^4.17.21",
     "@qlover/env-loader": "0.3.0",
-    "@qlover/logger": "0.1.1"
+    "@qlover/logger": "0.2.0"
   },
   "dependencies": {
-    "@qlover/fe-corekit": "^1.4.1",
+    "@qlover/fe-corekit": "^2.1.0",
     "chalk": "^5.3.0",
     "cosmiconfig": "^9.0.0"
   },
   "scripts": {
     "build": "tsup",
-    "build:docs": "fe-code2md --removePrefix -p ./src -g ./docs --formatOutput prettier"
+    "build:docs": "fe-code2md -p src -g docs --formatOutput prettier --removePrefix"
   }
 }