alepha/logger.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core0 from "alepha";
import { Alepha, KIND, LogLevel, LoggerInterface, Static } from "alepha";
import * as typebox0 from "typebox";

//#region src/providers/LogDestinationProvider.d.ts
declare abstract class LogDestinationProvider {
  abstract write(message: string, entry: LogEntry): void;
}
//#endregion
//#region src/providers/LogFormatterProvider.d.ts
declare abstract class LogFormatterProvider {
  abstract format(entry: LogEntry): string;
}
//#endregion
//#region src/services/Logger.d.ts
declare class Logger implements LoggerInterface {
  protected readonly alepha: Alepha;
  protected readonly formatter: LogFormatterProvider;
  protected readonly destination: LogDestinationProvider;
  protected readonly levels: Record<string, number>;
  protected readonly service: string;
  protected readonly module: string;
  protected readonly app?: string;
  protected appLogLevel: string;
  protected logLevel: LogLevel;
  constructor(service: string, module: string);
  get context(): string | undefined;
  get level(): string;
  parseLevel(level: string, app: string): LogLevel;
  private matchesPattern;
  asLogLevel(something: string): LogLevel;
  error(message: string, data?: unknown): void;
  warn(message: string, data?: unknown): void;
  info(message: string, data?: unknown): void;
  debug(message: string, data?: unknown): void;
  trace(message: string, data?: unknown): void;
  protected log(level: LogLevel, message: string, data?: unknown): void;
}
interface LogEntry {
  level: LogLevel;
  message: string;
  service: string;
  module: string;
  context?: string;
  data?: object | Error | string;
  app?: string;
  timestamp: Date;
}
//#endregion
//#region src/descriptors/$logger.d.ts
/**
 * Create a logger.
 *
 * `name` is optional, by default it will use the name of the service.
 *
 * @example
 * ```ts
 * import { $logger } from "alepha";
 *
 * class MyService {
 * 	log = $logger();
 *
 *   constructor() {
 *     this.log.info("Service initialized");
 *     // print something like '[23:45:53.326] INFO <app.MyService>: Service initialized'
 *   }
 * }
 * ```
 */
declare const $logger: {
  (options?: LoggerDescriptorOptions): Logger;
  [KIND]: typeof Logger;
};
interface LoggerDescriptorOptions {
  name?: string;
}
//#endregion
//#region src/providers/ConsoleColorProvider.d.ts
declare class ConsoleColorProvider {
  static readonly COLORS: {
    reset: string;
    grey: string;
    red: string;
    orange: string;
    green: string;
    blue: string;
    white: string;
    cyan: string;
    darkGrey: string;
    silent: string;
    error: string;
    warn: string;
    info: string;
    debug: string;
    trace: string;
  };
  protected readonly env: {
    NO_COLOR?: string | undefined;
    FORCE_COLOR?: string | undefined;
  };
  protected readonly alepha: Alepha;
  protected enabled: boolean;
  constructor();
  isEnabled(): boolean;
  colorize(color: keyof typeof ConsoleColorProvider.COLORS, text: string, reset?: string): string;
}
//#endregion
//#region src/providers/ConsoleDestinationProvider.d.ts
declare class ConsoleDestinationProvider extends LogDestinationProvider {
  write(message: string): void;
}
//#endregion
//#region src/providers/JsonFormatterProvider.d.ts
declare class JsonFormatterProvider extends LogFormatterProvider {
  format(entry: LogEntry): string;
  protected formatJsonError(error: Error): object;
}
//#endregion
//#region src/providers/MemoryDestinationProvider.d.ts
declare class MemoryDestinationProvider extends LogDestinationProvider {
  protected entries: Array<LogEntry & {
    formatted: string;
  }>;
  readonly options: {
    maxEntries: number;
  };
  write(formatted: string, entry: LogEntry): void;
  get logs(): (LogEntry & {
    formatted: string;
  })[];
  clear(): void;
}
//#endregion
//#region src/providers/SimpleFormatterProvider.d.ts
declare class SimpleFormatterProvider extends LogFormatterProvider {
  protected color: ConsoleColorProvider;
  protected alepha: Alepha;
  format(entry: LogEntry): string;
  formatTimestamp(d: Date): string;
  protected pad2: (n: number) => string;
  protected pad3: (n: number) => string;
  protected formatError(error: Error): string;
}
//#endregion
//#region src/index.d.ts
/**
 * Minimalist logger module for Alepha.
 *
 * It offers a global logger interface (info, warn, ...) via the `$logger` descriptor.
 *
 * ```ts
 * import { $logger } from "alepha/logger";
 *
 * class App {
 *   log = $logger();
 * }
 * ```
 *
 * ### Formatting and Destinations
 *
 * `AlephaLogger` is **extensible**, destinations and formatters can be added or replaced.
 *
 * Default log destinations are:
 * - ConsoleDestinationProvider: logs to the console.
 * - MemoryDestinationProvider: stores logs in memory for later retrieval.
 *
 * Default log formatters are:
 * - JsonFormatterProvider: formats logs as JSON.
 * - SimpleFormatterProvider: formats logs as simple text (with colors when possible).
 * - RawFormatterProvider: formats logs as raw text without any formatting.
 *
 * ### Event Emission
 *
 * The logger emits 'log' events that can be listened to by external code, allowing for custom log processing and destinations.
 *
 * ```ts
 * class CustomDestination {
 *   onLog = $hook({
 *     on: "log",
 *     handler: (ev) => {
 *       // ev.message (formatted message)
 *       // ev.entry (level, raw message, ...)
 *     }
 *   });
 * }
 * ```
 *
 * ### Log Level
 *
 * You can configure the log level and format via environment variables:
 *
 * - `LOG_LEVEL`: Sets the default log level for the application.
 * - `LOG_FORMAT`: Sets the default log format for the application.
 *
 * ```bash
 * LOG_LEVEL=debug LOG_FORMAT=json node src/index.ts
 * ```
 *
 * Log level is also available in the state as `logLevel`, which can be used to dynamically change the log level at runtime.
 * ```ts
 * alepha.state.set("logLevel", "debug");
 * ```
 *
 * Log level is $module aware, meaning you can set different log levels for different modules.
 *
 * **Module-specific configuration:**
 * - `LOG_LEVEL=my.module.name:debug,info` - debug for `my.module.name` (and submodules), info for others
 * - `LOG_LEVEL=alepha:trace,my.app:error,info` - trace for alepha modules, error for my.app modules, info for others
 *
 * **Wildcard patterns (NEW):**
 * - `LOG_LEVEL=alepha.*:debug,info` - debug for all alepha submodules
 * - `LOG_LEVEL=*.test:silent,*.core:trace,info` - silent for test modules, trace for core modules
 *
 * **Robust parsing:**
 * - Empty parts are gracefully skipped: `LOG_LEVEL=",,debug,,"` works fine
 * - Better error messages: "Invalid log level 'bad' for module pattern 'alepha'"
 */
declare const AlephaLogger: _alepha_core0.Service<_alepha_core0.Module>;
declare const envSchema: _alepha_core0.TObject<{
  /**
   * Default log level for the application.
   *
   * Default by environment:
   * - dev = info
   * - prod = info
   * - test = error
   *
   * Levels are: "trace" | "debug" | "info" | "warn" | "error" | "silent"
   *
   * Level can be set for a specific module:
   *
   * @example
   * LOG_LEVEL=my.module.name:debug,info # Set debug level for my.module.name and info for all other modules
   * LOG_LEVEL=alepha:trace, info # Set trace level for all alepha modules and info for all other modules
   */
  LOG_LEVEL: _alepha_core0.TOptional<_alepha_core0.TString>;
  /**
   * Built-in log formats.
   * - "json" - JSON format, useful for structured logging and log aggregation. {@link JsonFormatterProvider}
   * - "text" - Simple text format, human-readable, with colors. {@link SimpleFormatterProvider}
   * - "raw" - Raw format, no formatting, just the message.  {@link RawFormatterProvider}
   */
  LOG_FORMAT: _alepha_core0.TOptional<typebox0.TUnsafe<"json" | "text" | "raw">>;
}>;
declare module "alepha" {
  interface Env extends Partial<Static<typeof envSchema>> {}
  interface State {
    logLevel?: string;
  }
  interface Hooks {
    log: {
      message: string;
      entry: LogEntry;
    };
  }
}
//# sourceMappingURL=index.d.ts.map
//#endregion
export { $logger, AlephaLogger, ConsoleColorProvider, ConsoleDestinationProvider, JsonFormatterProvider, LogDestinationProvider, LogEntry, LogFormatterProvider, Logger, LoggerDescriptorOptions, MemoryDestinationProvider, SimpleFormatterProvider };
//# sourceMappingURL=index.d.ts.map