@gesslar/toolkit 0.5.0 → 0.7.0

package/src/types/Glog.d.ts

@@ -1,92 +1,345 @@
 // Implementation: ../lib/Glog.js
 
 /**
- * Global logging utility with configurable log levels and prefixes.
- * Provides a flexible logging system that can be used as both a class and
- * a callable function, with support for log level filtering and custom
- * prefixes for better log organization.
+ * Color configuration object for log levels.
+ * Uses \@gesslar/colours format strings.
+ */
+export interface LoggerColours {
+  debug: [string, string, string, string, string]
+  info: string
+  warn: string
+  error: string
+  reset: string
+}
+
+/**
+ * Configuration options for Glog instance creation.
+ */
+export interface GlogOptions {
+  /** Logger name (appears in composed messages) */
+  name?: string
+  /** Debug level (0-5, alias for logLevel) */
+  debugLevel?: number
+  /** Log level (0-5) */
+  logLevel?: number
+  /** Message prefix */
+  prefix?: string
+  /** Custom colors configuration */
+  colors?: LoggerColours
+  /** Enable stack trace extraction */
+  stackTrace?: boolean
+  /** Environment type ('extension' for VSCode integration) */
+  env?: string
+}
+
+/**
+ * Enhanced global logging utility combining simple logging with advanced Logger features.
  *
- * The Glog class uses a proxy to enable both class-style and function-style
- * usage patterns, making it convenient for different coding preferences.
+ * Glog can be used in multiple ways:
+ * 1. Simple function call: `Glog(data)` or `Glog(2, "debug message")`
+ * 2. Configured instance: `new Glog(options)`
+ * 3. Fluent setup: `Glog.create().withName("App").withColors()`
+ * 4. Traditional logger: `logger.debug("message", level)`
  *
- * Log levels range from 0 (critical/always shown) to 5 (verbose debug).
- * Messages with levels higher than the configured threshold are filtered out.
+ * Features:
+ * - Log level filtering (0-5)
+ * - Custom prefixes for message organization
+ * - Color support via \@gesslar/colours
+ * - Traditional logger methods (debug, info, warn, error, success)
+ * - Template literal color formatting
+ * - VSCode extension integration
+ * - Static and instance usage patterns
  *
  * @example
  * ```typescript
  * import { Glog } from '@gesslar/toolkit'
  *
- * // Configure logging once at startup
+ * // Simple usage with static configuration
  * Glog.setLogLevel(3).setLogPrefix('[MyApp]')
+ * Glog(0, 'Critical error!')
+ * Glog(2, 'Debug info:', data)
  *
- * // Use as a function (most common)
- * Glog(0, 'Critical error - system failure!')  // Always shown
- * Glog(1, 'Warning: deprecated API used')      // Shown if level >= 1
- * Glog(2, 'Info: processing user request')     // Shown if level >= 2
- * Glog(3, 'Debug: cache hit for key:', key)    // Shown if level >= 3
- * Glog('Simple message')                       // Level 0 by default
+ * // Instance usage with configuration
+ * const logger = new Glog({ name: 'API', logLevel: 2 })
+ * logger.debug('Processing request', 1)
+ * logger.info('Request completed')
+ * logger.error('Request failed')
  *
- * // Method chaining for configuration
- * Glog.setLogLevel(2)
- *     .setLogPrefix('[API]')
+ * // Fluent instance creation
+ * const log = Glog.create()
+ *   .withName('Database')
+ *   .withLogLevel(3)
+ *   .withColors()
  *
- * // Different contexts can use different prefixes
- * const dbLogger = Glog.setLogPrefix('[DB]')
- * const apiLogger = Glog.setLogPrefix('[API]')
+ * // Color template literals
+ * logger.colorize`{success}Operation completed{/} in {bold}${time}ms{/}`
+ * logger.success('All tests passed!')
  * ```
- *
- * @remarks
- * The proxy implementation allows Glog to be called directly as a function
- * while still providing static methods for configuration. This makes it
- * extremely convenient for quick logging without ceremony.
  */
-interface GlogInterface {
+declare class Glog {
+  /** Current static log level (0-5) */
+  static logLevel: number
+  /** Current static log prefix */
+  static logPrefix: string
+  /** Current static color configuration */
+  static colors: LoggerColours | null
+  /** Whether stack traces are enabled globally */
+  static stackTrace: boolean
+  /** Global logger name */
+  static name: string
+
+  /**
+   * Create a new Glog instance with optional configuration.
+   *
+   * @param options - Configuration options
+   */
+  constructor(options?: GlogOptions)
+
+  // === STATIC CONFIGURATION METHODS ===
+
+  /**
+   * Set the global log prefix for all messages.
+   *
+   * @param prefix - Prefix string to prepend to messages
+   * @returns The Glog class for chaining
+   */
+  static setLogPrefix(prefix: string): typeof Glog
+
+  /**
+   * Set the global log level threshold.
+   * Messages with levels higher than this are filtered out.
+   *
+   * @param level - Log level (0-5, automatically clamped)
+   * @returns The Glog class for chaining
+   */
+  static setLogLevel(level: number): typeof Glog
+
+  /**
+   * Set the global logger name.
+   *
+   * @param name - Logger name
+   * @returns The Glog class for chaining
+   */
+  static withName(name: string): typeof Glog
+
+  /**
+   * Configure global color settings.
+   *
+   * @param colors - Color configuration (defaults to loggerColours)
+   * @returns The Glog class for chaining
+   */
+  static withColors(colors?: LoggerColours): typeof Glog
+
+  /**
+   * Enable or disable global stack trace extraction.
+   *
+   * @param enabled - Whether to enable stack traces (default: true)
+   * @returns The Glog class for chaining
+   */
+  static withStackTrace(enabled?: boolean): typeof Glog
+
+  /**
+   * Create a new Glog instance (fluent factory method).
+   *
+   * @param options - Configuration options
+   * @returns New Glog instance
+   */
+  static create(options?: GlogOptions): Glog
+
+  /**
+   * Log a colorized message using template literals (static).
+   *
+   * @param strings - Template strings
+   * @param values - Template values
+   */
+  static colorize(strings: TemplateStringsArray, ...values: unknown[]): void
+
+  /**
+   * Log a success message with green color (static).
+   *
+   * @param message - Success message
+   * @param args - Additional arguments
+   */
+  static success(message: string, ...args: unknown[]): void
+
+  /**
+   * Set a color alias for convenient usage.
+   *
+   * @param alias - Alias name
+   * @param colorCode - Color code (e.g., "{F196}" or "{<B}")
+   * @returns The Glog class for chaining
+   */
+  static setAlias(alias: string, colorCode: string): typeof Glog
+
+  // === INSTANCE CONFIGURATION METHODS ===
+
+  /**
+   * Set instance options.
+   *
+   * @param options - Configuration options
+   * @returns This instance for chaining
+   */
+  setOptions(options: GlogOptions): this
+
+  /**
+   * Set instance logger name (fluent).
+   *
+   * @param name - Logger name
+   * @returns This instance for chaining
+   */
+  withName(name: string): this
+
   /**
-   * Sets the log prefix for all subsequent log messages.
-   * The prefix helps identify the source of log messages in complex
-   * applications with multiple components.
+   * Set instance log level (fluent).
    *
-   * @param prefix - The prefix string to prepend to log messages
-   * @returns Returns the Glog class for method chaining
+   * @param level - Log level (0-5)
+   * @returns This instance for chaining
    */
-  setLogPrefix(prefix: string): typeof Glog
+  withLogLevel(level: number): this
 
   /**
-   * Sets the minimum log level for messages to be displayed.
-   * Messages with a level higher than this threshold will be filtered out.
-   * Log levels range from 0 (critical) to 5 (verbose debug).
+   * Set instance prefix (fluent).
    *
-   * @param level - The minimum log level (0-5, clamped to range)
-   * @returns Returns the Glog class for method chaining
+   * @param prefix - Message prefix
+   * @returns This instance for chaining
    */
-  setLogLevel(level: number): typeof Glog
+  withPrefix(prefix: string): this
 
   /**
-   * Executes a log operation with the provided arguments.
-   * This method serves as the entry point for all logging operations.
+   * Configure instance colors (fluent).
+   *
+   * @param colors - Color configuration (defaults to loggerColours)
+   * @returns This instance for chaining
+   */
+  withColors(colors?: LoggerColours): this
+
+  /**
+   * Enable or disable instance stack trace extraction (fluent).
+   *
+   * @param enabled - Whether to enable stack traces (default: true)
+   * @returns This instance for chaining
+   */
+  withStackTrace(enabled?: boolean): this
+
+  // === INSTANCE PROPERTIES ===
+
+  /** Instance logger name */
+  get name(): string
+
+  /** Instance debug/log level */
+  get debugLevel(): number
+
+  /** Instance configuration options */
+  get options(): {
+    name: string
+    debugLevel: number
+    prefix: string
+    colors: LoggerColours | null
+    stackTrace: boolean
+  }
+
+  /** Access to colours template function */
+  get colours(): any
+
+  // === INSTANCE LOGGING METHODS ===
+
+  /**
+   * Log a debug message with optional level.
+   * Level 0 means debug OFF - use levels 1-4 for debug verbosity.
+   * Debug messages only show when logLevel > 0.
+   *
+   * @param message - Debug message
+   * @param level - Debug level (1-4, default: 1)
+   * @param arg - Additional arguments
+   * @throws {Error} If level < 1 (level 0 = debug OFF, not a valid debug level)
+   */
+  debug(message: string, level?: number, ...arg: unknown[]): void
+
+  /**
+   * Log an informational message.
+   *
+   * @param message - Info message
+   * @param arg - Additional arguments
+   */
+  info(message: string, ...arg: unknown[]): void
+
+  /**
+   * Log a warning message.
+   *
+   * @param message - Warning message
+   * @param arg - Additional arguments
+   */
+  warn(message: string, ...arg: unknown[]): void
+
+  /**
+   * Log an error message.
+   *
+   * @param message - Error message
+   * @param arg - Additional arguments
+   */
+  error(message: string, ...arg: unknown[]): void
+
+  /**
+   * Log a colorized message using template literals (instance).
+   *
+   * @param strings - Template strings
+   * @param values - Template values
+   */
+  colorize(strings: TemplateStringsArray, ...values: unknown[]): void
+
+  /**
+   * Log a success message with green color (instance).
+   *
+   * @param message - Success message
+   * @param args - Additional arguments
+   */
+  success(message: string, ...args: unknown[]): void
+
+  /**
+   * Execute instance logging (supports level filtering).
    *
    * @param args - Log level (optional) followed by message arguments
    */
-  execute(...args: any[]): void
+  execute(...args: unknown[]): void
+
+  /**
+   * Create a new debug function with tag extraction.
+   *
+   * @param tag - Tag name (will be replaced by extracted function info)
+   * @returns Bound debug function
+   */
+  newDebug(tag: string): (message: string, level: number, ...arg: unknown[]) => void
+
+  /**
+   * Extract file and function information from call stack.
+   * Simplified implementation returns "caller" by default.
+   *
+   * @returns Caller information string
+   */
+  extractFileFunction(): string
 }
 
 /**
- * Callable interface for the proxied Glog class.
- * Allows the class to be used as a function.
+ * Callable interface for the proxied Glog export.
+ * The default export is a Proxy that allows both class and function usage.
  */
 interface GlogCallable {
   /**
    * Log a message with optional level specification.
+   * First argument can be a number (level) or part of the message.
    *
    * @param args - Either (level: number, ...messages) or (...messages)
    */
-  (...args: any[]): void
+  (...args: unknown[]): void
 }
 
 /**
- * The Glog class with proxy functionality for callable behavior.
- * Can be used both as a static class and as a callable function.
+ * The Glog export: a Proxy combining class methods with callable behavior.
+ * Can be used as:
+ * - A function: `Glog(message)` or `Glog(level, message)`
+ * - A class: `new Glog(options)`
+ * - Static methods: `Glog.setLogLevel(3)`
  */
-declare const Glog: GlogInterface & GlogCallable
+declare const GlogExport: typeof Glog & GlogCallable
 
-export default Glog
+export default GlogExport

package/src/types/Sass.d.ts

@@ -21,4 +21,4 @@ export default class Sass extends Error {
 
   /** Factory method to create or enhance Sass instances */
   static new(message: string, error?: Error | Sass): Sass
-}
+}

package/src/types/Schemer.d.ts

@@ -4,10 +4,10 @@ import type { ValidateFunction, ErrorObject } from 'ajv'
 
 /**
  * Schemer provides utilities for compiling and validating JSON schemas using AJV.
- * 
+ *
  * This class serves as a convenient wrapper around AJV (Another JSON Schema Validator)
  * with toolkit-specific enhancements for error reporting and schema compilation.
- * 
+ *
  * @example
  * ```typescript
  * // Create validator from schema object
@@ -19,19 +19,19 @@ import type { ValidateFunction, ErrorObject } from 'ajv'
  *   },
  *   required: ["name"]
  * })
- * 
+ *
  * // Validate data
  * const isValid = validator({ name: "John", age: 30 })
  * ```
- * 
+ *
  * @example
  * ```typescript
  * // Create validator from file
  * const file = new FileObject("schema.json")
  * const validator = await Schemer.fromFile(file)
  * ```
- * 
- * @example  
+ *
+ * @example
  * ```typescript
  * // Get raw AJV validator and format errors
  * const validate = Schemer.getValidator(schema)
@@ -45,14 +45,14 @@ import type { ValidateFunction, ErrorObject } from 'ajv'
 declare class Schemer {
   /**
    * Creates an AJV validator function from a schema file
-   * 
+   *
    * @param file - FileObject pointing to a JSON/YAML schema file
    * @param options - AJV configuration options
    * @returns Promise resolving to AJV validator function
-   * 
+   *
    * @throws {Sass} If file cannot be loaded or schema is invalid
    * @throws {Sass} If file is not a FileObject or options are invalid
-   * 
+   *
    * @example
    * ```typescript
    * const file = new FileObject("user-schema.json")
@@ -60,7 +60,7 @@ declare class Schemer {
    *   allErrors: true,
    *   verbose: true
    * })
-   * 
+   *
    * const isValid = validator({ name: "John", age: 30 })
    * if (!isValid) {
    *   console.log("Errors:", validator.errors)
@@ -68,20 +68,20 @@ declare class Schemer {
    * ```
    */
   static fromFile(
-    file: import('./FileObject.js').default, 
+    file: import('./FileObject.js').default,
     options?: object
   ): Promise<ValidateFunction>
 
   /**
    * Creates an AJV validator function from a schema object
-   * 
+   *
    * @param schemaData - JSON schema object to compile
-   * @param options - AJV configuration options  
+   * @param options - AJV configuration options
    * @returns Promise resolving to AJV validator function
-   * 
+   *
    * @throws {Sass} If schema data or options are not plain objects
    * @throws {Sass} If schema compilation fails
-   * 
+   *
    * @example
    * ```typescript
    * const validator = await Schemer.from({
@@ -91,11 +91,11 @@ declare class Schemer {
    *     email: { type: "string", format: "email" }
    *   },
    *   required: ["id", "email"]
-   * }, { 
+   * }, {
    *   formats: true,
-   *   allErrors: true 
+   *   allErrors: true
    * })
-   * 
+   *
    * const isValid = validator({ id: "123", email: "test@example.com" })
    * if (!isValid) {
    *   console.log("Errors:", validator.errors)
@@ -106,11 +106,11 @@ declare class Schemer {
 
   /**
    * Creates a raw AJV validator function from a schema object
-   * 
+   *
    * @param schema - The JSON schema to compile
    * @param options - AJV configuration options (defaults to {allErrors: true, verbose: true})
    * @returns AJV validator function with .errors property when validation fails
-   * 
+   *
    * @example
    * ```typescript
    * const validate = Schemer.getValidator({
@@ -118,13 +118,13 @@ declare class Schemer {
    *   minLength: 1,
    *   maxLength: 100
    * })
-   * 
+   *
    * const isValid = validate("Hello World")
    * if (!isValid) {
    *   console.log("Errors:", validate.errors)
    * }
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // Custom AJV options
@@ -136,21 +136,21 @@ declare class Schemer {
    * ```
    */
   static getValidator(
-    schema: object, 
+    schema: object,
     options?: { allErrors?: boolean; verbose?: boolean; [key: string]: unknown }
   ): ValidateFunction
 
   /**
    * Formats AJV validation errors into a human-readable report
-   * 
+   *
    * @param errors - Array of AJV error objects from failed validation
    * @returns Formatted error message with helpful details and suggestions
-   * 
+   *
    * @example
    * ```typescript
    * const validate = Schemer.getValidator(schema)
    * const isValid = validate(data)
-   * 
+   *
    * if (!isValid) {
    *   const report = Schemer.reportValidationErrors(validate.errors)
    *   console.error("Validation failed:")
@@ -161,14 +161,14 @@ declare class Schemer {
    *   //   ➜ Received value: "string"
    * }
    * ```
-   * 
+   *
    * @example
    * ```typescript
    * // The error report includes helpful details:
    * // - Property paths and error descriptions
    * // - Expected vs actual types
    * // - Missing required fields
-   * // - Pattern matching failures  
+   * // - Pattern matching failures
    * // - Closest matches for enum values
    * // - Unexpected additional properties
    * ```
@@ -176,4 +176,4 @@ declare class Schemer {
   static reportValidationErrors(errors: ErrorObject[] | null | undefined): string
 }
 
-export default Schemer
+export default Schemer

package/src/types/Tantrum.d.ts

@@ -5,17 +5,17 @@ import Sass from './Sass'
 
 /**
  * Custom aggregate error class that extends AggregateError.
- * 
+ *
  * Automatically wraps plain Error objects in Sass instances while preserving
  * existing Sass errors, providing consistent formatted reporting for
  * multiple error scenarios.
- * 
+ *
  * @example
  * ```typescript
  * // Collect multiple errors and throw as a bundle
  * const errors = [new Error("thing 1"), sassError, new Error("thing 3")]
  * throw Tantrum.new("Multiple validation failures", errors)
- * 
+ *
  * // Later, in error handling:
  * catch (error) {
  *   if (error instanceof Tantrum) {
@@ -28,7 +28,7 @@ export default class Tantrum extends AggregateError {
   /**
    * Creates a new Tantrum instance.
    * Plain Error objects are automatically wrapped in Sass instances.
-   * 
+   *
    * @param message - The aggregate error message describing the overall failure
    * @param errors - Array of errors to aggregate (mix of Error and Sass instances allowed)
    */
@@ -44,9 +44,9 @@ export default class Tantrum extends AggregateError {
    * Reports all aggregated errors to the terminal with formatted output.
    * Shows a header with error count, then delegates to each Sass instance
    * for individual error reporting.
-   * 
+   *
    * @param nerdMode - Whether to include detailed stack traces in output
-   * 
+   *
    * @example
    * ```typescript
    * try {
@@ -62,20 +62,20 @@ export default class Tantrum extends AggregateError {
   /**
    * Factory method to create a Tantrum instance.
    * Follows the same pattern as Sass.new() for consistency.
-   * 
+   *
    * @param message - The aggregate error message
    * @param errors - Array of errors to aggregate
    * @returns New Tantrum instance with all errors wrapped as Sass
-   * 
+   *
    * @example
    * ```typescript
    * // Typical usage pattern
    * throw Tantrum.new("Someone ate all my Runts!", [
    *   emptyRuntsBoxError,
-   *   emptyRuntsBoxError, 
+   *   emptyRuntsBoxError,
    *   emptyRuntsBoxError
    * ])
    * ```
    */
   static new(message: string, errors?: Array<Error | Sass>): Tantrum
-}
+}

package/src/types/Term.d.ts

@@ -13,4 +13,4 @@ export default class Term {
   static resetTerminal(): Promise<void>
   static clearLines(num: number): Promise<void>
   static directWrite(output: string): Promise<void>
-}
+}