@gesslar/toolkit 1.5.0 → 1.6.0

package/src/types/Glog.d.ts

@@ -1,345 +0,0 @@
-// Implementation: ../lib/Glog.js
-
-/**
- * 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.
- *
- * 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)`
- *
- * 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'
- *
- * // Simple usage with static configuration
- * Glog.setLogLevel(3).setLogPrefix('[MyApp]')
- * Glog(0, 'Critical error!')
- * Glog(2, 'Debug info:', data)
- *
- * // 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')
- *
- * // Fluent instance creation
- * const log = Glog.create()
- *   .withName('Database')
- *   .withLogLevel(3)
- *   .withColors()
- *
- * // Color template literals
- * logger.colorize`{success}Operation completed{/} in {bold}${time}ms{/}`
- * logger.success('All tests passed!')
- * ```
- */
-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
-
-  /**
-   * Set instance log level (fluent).
-   *
-   * @param level - Log level (0-5)
-   * @returns This instance for chaining
-   */
-  withLogLevel(level: number): this
-
-  /**
-   * Set instance prefix (fluent).
-   *
-   * @param prefix - Message prefix
-   * @returns This instance for chaining
-   */
-  withPrefix(prefix: string): this
-
-  /**
-   * 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: 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 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: unknown[]): void
-}
-
-/**
- * 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 GlogExport: typeof Glog & GlogCallable
-
-export default GlogExport

package/src/types/Sass.d.ts

@@ -1,24 +0,0 @@
-// Implementation: ../lib/Sass.js
-// Type definitions for Sass error class
-
-/**
- * Custom error class for toolkit errors.
- */
-export default class Sass extends Error {
-  constructor(message: string, ...arg: Array<any>)
-
-  /** Array of trace messages */
-  readonly trace: Array<string>
-
-  /** Add a trace message and return this instance for chaining */
-  addTrace(message: string): this
-
-  /** Report the error to the terminal */
-  report(nerdMode?: boolean): void
-
-  /** Create a Sass from an existing Error object */
-  static from(error: Error, message: string): Sass
-
-  /** Factory method to create or enhance Sass instances */
-  static new(message: string, error?: Error | Sass): Sass
-}

package/src/types/Schemer.d.ts

@@ -1,179 +0,0 @@
-// Implementation: ../lib/Schemer.js
-
-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
- * const validator = await Schemer.from({
- *   type: "object",
- *   properties: {
- *     name: { type: "string" },
- *     age: { type: "number", minimum: 0 }
- *   },
- *   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
- * ```typescript
- * // Get raw AJV validator and format errors
- * const validate = Schemer.getValidator(schema)
- * const isValid = validate(data)
- * if (!isValid) {
- *   const errorReport = Schemer.reportValidationErrors(validate.errors)
- *   console.error("Validation failed:", errorReport)
- * }
- * ```
- */
-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")
-   * const validator = await Schemer.fromFile(file, {
-   *   allErrors: true,
-   *   verbose: true
-   * })
-   *
-   * const isValid = validator({ name: "John", age: 30 })
-   * if (!isValid) {
-   *   console.log("Errors:", validator.errors)
-   * }
-   * ```
-   */
-  static fromFile(
-    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
-   * @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({
-   *   type: "object",
-   *   properties: {
-   *     id: { type: "string", format: "uuid" },
-   *     email: { type: "string", format: "email" }
-   *   },
-   *   required: ["id", "email"]
-   * }, {
-   *   formats: true,
-   *   allErrors: true
-   * })
-   *
-   * const isValid = validator({ id: "123", email: "test@example.com" })
-   * if (!isValid) {
-   *   console.log("Errors:", validator.errors)
-   * }
-   * ```
-   */
-  static from(schemaData?: object, options?: object): Promise<ValidateFunction>
-
-  /**
-   * 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({
-   *   type: "string",
-   *   minLength: 1,
-   *   maxLength: 100
-   * })
-   *
-   * const isValid = validate("Hello World")
-   * if (!isValid) {
-   *   console.log("Errors:", validate.errors)
-   * }
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // Custom AJV options
-   * const validate = Schemer.getValidator(schema, {
-   *   allErrors: false,
-   *   verbose: false,
-   *   strict: true
-   * })
-   * ```
-   */
-  static getValidator(
-    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:")
-   *   console.error(report)
-   *   // Output:
-   *   // - "(root)" must be object
-   *   //   ➜ Expected type: object
-   *   //   ➜ 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
-   * // - Closest matches for enum values
-   * // - Unexpected additional properties
-   * ```
-   */
-  static reportValidationErrors(errors: ErrorObject[] | null | undefined): string
-}
-
-export default Schemer

package/src/types/Tantrum.d.ts

@@ -1,81 +0,0 @@
-// Implementation: ../lib/Tantrum.js
-// Type definitions for Tantrum aggregate error class
-
-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) {
- *     error.report() // Reports all errors with Sass formatting
- *   }
- * }
- * ```
- */
-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)
-   */
-  constructor(message: string, errors?: Array<Error | Sass>)
-
-  /** Name of the error class */
-  readonly name: 'Tantrum'
-
-  /** Array of aggregated errors (all wrapped as Sass instances) */
-  readonly errors: Array<Sass>
-
-  /**
-   * 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 {
-   *   throw Tantrum.new("Batch failed", [error1, error2])
-   * } catch (tantrum) {
-   *   tantrum.report() // User-friendly output
-   *   tantrum.report(true) // Includes full stack traces
-   * }
-   * ```
-   */
-  report(nerdMode?: boolean): void
-
-  /**
-   * 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
-   * ])
-   * ```
-   */
-  static new(message: string, errors?: Array<Error | Sass>): Tantrum
-}

package/src/types/Term.d.ts

@@ -1,16 +0,0 @@
-// Implementation: ../lib/Term.js
-// Type definitions for Term utility class
-
-export default class Term {
-  static log(...arg: Array<unknown>): void
-  static info(...arg: Array<unknown>): void
-  static warn(...arg: Array<unknown>): void
-  static error(...arg: Array<unknown>): void
-  static debug(...arg: Array<unknown>): void
-  static status(args: string | Array<string | [string, string]>, options?: { silent?: boolean }): void
-  static terminalMessage(argList: string | Array<string | [string, string] | [string, string, string]>): string
-  static terminalBracket(parts: [string, string, [string, string]?]): string
-  static resetTerminal(): Promise<void>
-  static clearLines(num: number): Promise<void>
-  static directWrite(output: string): Promise<void>
-}