@decaf-ts/logging 0.2.3 → 0.3.2

package/LICENSE.md

@@ -1,157 +1,21 @@
-# GNU LESSER GENERAL PUBLIC LICENSE
-
-Version 3, 29 June 2007
-
-Copyright (C) 2025 Tiago Venceslau
-<https:/github.com/TiagoVenceslau>
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-This version of the GNU Lesser General Public License incorporates the
-terms and conditions of version 3 of the GNU General Public License,
-supplemented by the additional permissions listed below.
-
-## 0. Additional Definitions.
-
-As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the
-GNU General Public License.
-
-"The Library" refers to a covered work governed by this License, other
-than an Application or a Combined Work as defined below.
-
-An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-A "Combined Work" is a work produced by combining or linking an
-Application with the Library. The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-## 1. Exception to Section 3 of the GNU GPL.
-
-You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-## 2. Conveying Modified Versions.
-
-If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
--   a) under this License, provided that you make a good faith effort
-    to ensure that, in the event an Application does not supply the
-    function or data, the facility still operates, and performs
-    whatever part of its purpose remains meaningful, or
--   b) under the GNU GPL, with none of the additional permissions of
-    this License applicable to that copy.
-
-## 3. Object Code Incorporating Material from Library Header Files.
-
-The object code form of an Application may incorporate material from a
-header file that is part of the Library. You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
--   a) Give prominent notice with each copy of the object code that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the object code with a copy of the GNU GPL and this
-    license document.
-
-## 4. Combined Works.
-
-You may convey a Combined Work under terms of your choice that, taken
-together, effectively do not restrict modification of the portions of
-the Library contained in the Combined Work and reverse engineering for
-debugging such modifications, if you also do each of the following:
-
--   a) Give prominent notice with each copy of the Combined Work that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the Combined Work with a copy of the GNU GPL and this
-    license document.
--   c) For a Combined Work that displays copyright notices during
-    execution, include the copyright notice for the Library among
-    these notices, as well as a reference directing the user to the
-    copies of the GNU GPL and this license document.
--   d) Do one of the following:
-    -   0) Convey the Minimal Corresponding Source under the terms of
-           this License, and the Corresponding Application Code in a form
-           suitable for, and under terms that permit, the user to
-           recombine or relink the Application with a modified version of
-           the Linked Version to produce a modified Combined Work, in the
-           manner specified by section 6 of the GNU GPL for conveying
-           Corresponding Source.
-    -   1) Use a suitable shared library mechanism for linking with
-           the Library. A suitable mechanism is one that (a) uses at run
-           time a copy of the Library already present on the user's
-           computer system, and (b) will operate properly with a modified
-           version of the Library that is interface-compatible with the
-           Linked Version.
--   e) Provide Installation Information, but only if you would
-    otherwise be required to provide such information under section 6
-    of the GNU GPL, and only to the extent that such information is
-    necessary to install and execute a modified version of the
-    Combined Work produced by recombining or relinking the Application
-    with a modified version of the Linked Version. (If you use option
-    4d0, the Installation Information must accompany the Minimal
-    Corresponding Source and Corresponding Application Code. If you
-    use option 4d1, you must provide the Installation Information in
-    the manner specified by section 6 of the GNU GPL for conveying
-    Corresponding Source.)
-
-## 5. Combined Libraries.
-
-You may place library facilities that are a work based on the Library
-side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
--   a) Accompany the combined library with a copy of the same work
-    based on the Library, uncombined with any other library
-    facilities, conveyed under the terms of this License.
--   b) Give prominent notice with the combined library that part of it
-    is a work based on the Library, and explaining where to find the
-    accompanying uncombined form of the same work.
-
-## 6. Revised Versions of the GNU Lesser General Public License.
-
-The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Library
-as you received it specifies that a certain numbered version of the
-GNU Lesser General Public License "or any later version" applies to
-it, you have the option of following the terms and conditions either
-of that published version or of any later version published by the
-Free Software Foundation. If the Library as you received it does not
-specify a version number of the GNU Lesser General Public License, you
-may choose any version of the GNU Lesser General Public License ever
-published by the Free Software Foundation.
-
-If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+# MIT License
+
+Copyright (c) 2025 Tiago Venceslau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,8 +2,7 @@
 
 ## Decaf's Logging
 
-Wimple winston like wrapper for decaf usage
-
+A comprehensive, flexible, and type-safe logging library for TypeScript applications that provides hierarchical context-aware logging, configurable styling, multiple output formats, and method decorators. It offers a lightweight built-in logger and seamless Winston integration, enabling developers to easily add structured logging with different verbosity levels to their applications.
 
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/logging.svg?style=plastic)
@@ -37,6 +36,83 @@ Documentation available [here](https://decaf-ts.github.io/logging/)
 
 ### Description
 
+Decaf's Logging is a powerful TypeScript logging library designed to provide flexible, context-aware logging capabilities for applications of any size. The library is built with a focus on type safety, configurability, and ease of use.
+
+#### Core Architecture
+
+The library follows a modular architecture with several key components:
+
+1. **Logging System**:
+   - `Logging`: A static class that serves as the central entry point for the logging system. It manages global configuration, provides factory methods for creating loggers, and offers static logging methods.
+   - `MiniLogger`: A lightweight logger implementation that provides the core logging functionality with support for different log levels, context-aware logging, and customizable formatting.
+   - `Logger` interface: Defines the standard methods that all logger implementations must provide, ensuring consistency across different logger types.
+
+2. **Configuration System**:
+   - `LoggingConfig`: Defines configuration options for the logging system, including log level, verbosity, styling, timestamp format, and more.
+   - `DefaultLoggingConfig`: Provides sensible default settings that can be overridden as needed.
+
+3. **Log Levels**:
+   - `LogLevel` enum: Defines standard log levels (error, info, verbose, debug, silly) for categorizing log messages.
+   - `NumericLogLevels`: Maps log levels to numeric values for comparison and filtering.
+
+4. **Styling System**:
+   - `Theme` interface: Defines a comprehensive theming system for styling log output with colors and formatting.
+   - `DefaultTheme`: Provides a default color scheme for log output.
+   - `LoggingMode` enum: Supports different output formats (RAW, JSON) for log messages.
+
+5. **Decorator System**:
+   - Method decorators (`@log`, `@debug`, `@info`, `@verbose`, `@silly`): Allow for easy integration of logging into class methods with options for benchmarking and verbosity control.
+
+6. **Winston Integration**:
+   - `WinstonLogger`: Extends the core logging functionality to leverage the Winston logging library.
+   - `WinstonFactory`: A factory function for creating Winston-based loggers.
+
+#### Key Features
+
+1. **Hierarchical Context-Aware Logging**:
+   The library allows creating loggers for specific classes and methods, maintaining a hierarchy of contexts. This makes it easy to trace log messages back to their source and filter logs by context.
+
+2. **Configurable Styling**:
+   Extensive support for styling log output with colors and formatting, with a theme system that allows customizing the appearance of different log components.
+
+3. **Multiple Output Formats**:
+   Support for both human-readable (RAW) and machine-parseable (JSON) output formats.
+
+4. **Method Decorators**:
+   Easy-to-use decorators for adding logging to class methods, with support for benchmarking execution time.
+
+5. **Verbosity Control**:
+   Fine-grained control over log verbosity, allowing developers to adjust the detail level of logs without changing code.
+
+6. **Type Safety**:
+   Comprehensive TypeScript type definitions ensure type safety and enable IDE autocompletion.
+
+7. **Winston Integration**:
+   Seamless integration with the popular Winston logging library, providing access to its advanced features while maintaining the same interface.
+
+8. **Error Handling**:
+   Special support for logging errors with stack traces for better debugging.
+
+#### Usage Patterns
+
+The library supports several usage patterns:
+
+1. **Global Logging**:
+   Using the static `Logging` class methods for simple, application-wide logging.
+
+2. **Class-Specific Logging**:
+   Creating loggers for specific classes to provide context for log messages.
+
+3. **Method-Specific Logging**:
+   Creating child loggers for specific methods to further refine the context.
+
+4. **Decorator-Based Logging**:
+   Using method decorators to automatically log method calls and execution times.
+
+5. **Winston-Based Logging**:
+   Leveraging Winston's advanced features while maintaining the same interface.
+
+This flexible design makes the library suitable for a wide range of applications, from simple scripts to complex enterprise systems.
 
 
 ### How to Use
@@ -44,7 +120,292 @@ Documentation available [here](https://decaf-ts.github.io/logging/)
 - [Initial Setup](./tutorials/For%20Developers.md#_initial-setup_)
 - [Installation](./tutorials/For%20Developers.md#installation)
 
+## Basic Usage
+
+### Global Logging
+
+The simplest way to use the library is through the static `Logging` class:
+
+```typescript
+import { Logging, LogLevel } from 'decaf-logging';
+
+// Configure global logging settings
+Logging.setConfig({
+  level: LogLevel.debug,
+  style: true,
+  timestamp: true
+});
+
+// Log messages at different levels
+Logging.info('Application started');
+Logging.debug('Debug information');
+Logging.error('An error occurred');
+Logging.verbose('Detailed information', 1); // With verbosity level
+```
+
+### Class-Specific Logging
+
+For more context-aware logging, create loggers for specific classes:
+
+```typescript
+import { Logging, Logger } from 'decaf-logging';
+
+class UserService {
+  private logger: Logger;
+
+  constructor() {
+    // Create a logger for this class
+    this.logger = Logging.for(UserService);
+    // Or with string name: Logging.for('UserService');
+  }
+
+  getUser(id: string) {
+    this.logger.info(`Getting user with ID: ${id}`);
+    // ... implementation
+    this.logger.debug('User retrieved successfully');
+  }
+
+  updateUser(id: string, data: any) {
+    try {
+      this.logger.info(`Updating user with ID: ${id}`);
+      // ... implementation
+      this.logger.debug('User updated successfully');
+    } catch (error) {
+      this.logger.error(error); // Logs error with stack trace
+    }
+  }
+}
+```
+
+### Method-Specific Logging
+
+Create child loggers for specific methods to further refine the context:
+
+```typescript
+import { Logging, Logger } from 'decaf-logging';
 
+class DataProcessor {
+  private logger: Logger;
+
+  constructor() {
+    this.logger = Logging.for(DataProcessor);
+  }
+
+  processData(data: any[]) {
+    // Create a method-specific logger
+    const methodLogger = this.logger.for('processData');
+
+    methodLogger.info(`Processing ${data.length} items`);
+
+    // With custom configuration
+    const verboseLogger = methodLogger.for('details', { verbose: 2 });
+    verboseLogger.verbose('Starting detailed processing', 1);
+
+    // ... implementation
+  }
+}
+```
+
+### Using Decorators
+
+Decorators provide an easy way to add logging to class methods:
+
+```typescript
+import { debug, info, log, LogLevel, verbose } from 'decaf-logging';
+
+class PaymentProcessor {
+  // Basic logging with info level
+  @info()
+  processPayment(amount: number, userId: string) {
+    // Method implementation
+    return true;
+  }
+
+  // Debug level logging with benchmarking
+  @debug(true)
+  validatePayment(paymentData: any) {
+    // Method implementation
+    return true;
+  }
+
+  // Verbose logging with custom verbosity
+  @verbose(2)
+  recordTransaction(transactionData: any) {
+    // Method implementation
+  }
+
+  // Custom log level with benchmarking and verbosity
+  @log(LogLevel.error, true, 1)
+  handleFailure(error: Error) {
+    // Method implementation
+  }
+}
+```
+
+### Winston Integration
+
+To use Winston for logging:
+
+```typescript
+import { Logging, LogLevel } from 'decaf-logging';
+import { WinstonFactory } from 'decaf-logging/winston';
+import winston from 'winston';
+
+// Configure Winston transports
+const transports = [
+  new winston.transports.Console(),
+  new winston.transports.File({ filename: 'app.log' })
+];
+
+// Set Winston as the logger factory
+Logging.setFactory(WinstonFactory);
+
+// Configure global logging
+Logging.setConfig({
+  level: LogLevel.info,
+  timestamp: true,
+  timestampFormat: 'YYYY-MM-DD HH:mm:ss'
+});
+
+// Create a Winston logger for a class
+const logger = Logging.for('MyService');
+logger.info('Service initialized');
+```
+
+## Advanced Usage
+
+### Custom Styling
+
+Configure custom styling for log output:
+
+```typescript
+import { Logging, LogLevel, Theme } from 'decaf-logging';
+
+// Define a custom theme
+const customTheme: Theme = {
+  class: {
+    fg: 35, // Magenta
+  },
+  id: {
+    fg: 36, // Cyan
+  },
+  stack: {},
+  timestamp: {
+    fg: 90, // Gray
+  },
+  message: {
+    error: {
+      fg: 31, // Red
+      style: ['bold'],
+    },
+  },
+  method: {},
+  logLevel: {
+    error: {
+      fg: 31, // Red
+      style: ['bold'],
+    },
+    info: {
+      fg: 32, // Green
+    },
+    verbose: {
+      fg: 34, // Blue
+    },
+    debug: {
+      fg: 33, // Yellow
+    },
+  },
+};
+
+// Apply the custom theme
+Logging.setConfig({
+  style: true,
+  theme: customTheme
+});
+```
+
+### Correlation IDs
+
+Track related log messages with correlation IDs:
+
+```typescript
+import { Logging } from 'decaf-logging';
+
+function processRequest(requestId: string, data: any) {
+  // Create a logger with correlation ID
+  const logger = Logging.for('RequestProcessor', { 
+    correlationId: requestId 
+  });
+
+  logger.info('Processing request');
+
+  // All log messages from this logger will include the correlation ID
+  processRequestData(data, logger);
+
+  logger.info('Request processing completed');
+}
+
+function processRequestData(data: any, logger: Logger) {
+  // Child loggers inherit the correlation ID
+  const dataLogger = logger.for('DataProcessor');
+  dataLogger.debug('Processing data');
+  // ...
+}
+```
+
+### JSON Output Mode
+
+For machine-readable logs:
+
+```typescript
+import { Logging, LoggingMode } from 'decaf-logging';
+
+// Configure for JSON output
+Logging.setConfig({
+  mode: LoggingMode.JSON,
+  timestamp: true
+});
+
+Logging.info('This will be output in JSON format');
+```
+
+### Custom Logger Factory
+
+Create a custom logger implementation:
+
+```typescript
+import { Logger, LoggerFactory, Logging, MiniLogger } from 'decaf-logging';
+
+// Custom logger that adds prefix to all messages
+class PrefixedLogger extends MiniLogger {
+  constructor(context: string, prefix: string, conf?: Partial<LoggingConfig>) {
+    super(context, conf);
+    this.prefix = prefix;
+  }
+
+  private prefix: string;
+
+  protected override createLog(level: LogLevel, message: StringLike | Error, stack?: string): string {
+    const msg = typeof message === 'string' ? message : message.message;
+    const prefixedMsg = `${this.prefix}: ${msg}`;
+    return super.createLog(level, prefixedMsg, stack);
+  }
+}
+
+// Custom factory function
+const PrefixedLoggerFactory: LoggerFactory = (
+  context: string,
+  conf?: Partial<LoggingConfig>,
+  ...args: any[]
+) => new PrefixedLogger(context, args[0] || '[APP]', conf);
+
+// Set the custom factory
+Logging.setFactory(PrefixedLoggerFactory);
+
+// Create a logger with the custom factory
+const logger = Logging.for('MyClass', undefined, '[CUSTOM]');
+logger.info('Hello world'); // Outputs: "[CUSTOM]: Hello world"
+```
 
 
 ### Related