emitnlog/dist/node/environment-logger-CxZMG4uq.d.cts

Emit n' Log: a modern, type-safe library for logging, event notifications, and observability in JavaScript/TypeScript apps.

import { a as LogLevel, L as Logger } from './definition-DjCH_-8D.cjs';

/**
 * The format of the emitted lines. The possible values are:
 *
 * - 'plain': The line is emitted as a plain string.
 * - 'colorful': The line is emitted with ANSI color codes.
 * - 'json': The line is emitted as a JSON string.
 * - 'unformatted-json': The line is emitted as a JSON string without formatting.
 */
type EmitterFormat = 'plain' | 'colorful' | 'json' | 'unformatted-json';

/**
 * The options for the `fromEnv` function.
 */
type EnvironmentLoggerOptions = {
    /**
     * The level to use if the environment variable `EMITNLOG_LEVEL` is not set.
     */
    readonly level?: LogLevel;
    /**
     * The format to use if the environment variable `EMITNLOG_FORMAT` is not set.
     */
    readonly format?: EmitterFormat;
    /**
     * Returns the fallback logger to use if the environment variable `ENV_LOGGER` is not set.
     *
     * @param level The level to use set, which is `EMITNLOG_LEVEL`, `options.level`, or undefined.
     * @param format The format to use, which is `EMITNLOG_FORMAT`, `options.format`, or undefined.
     * @returns The fallback logger to use or undefined.
     */
    readonly fallbackLogger?: (level?: LogLevel, format?: EmitterFormat) => Logger | undefined;
};

/**
 * Returns the logger to use based on the environment variables.
 *
 * The environment variables are:
 *
 * ```
 * EMITNLOG_LOGGER: The logger to use.
 * The possible values are
 *   - `console`: The console logger.
 *   - `console-error`: The console error logger.
 *   - `file:<path>`: The file logger with the (required) file path information (Node.js only)
 *
 * EMITNLOG_LEVEL: The level to use.
 * The possible values are
 *   - `trace`
 *   - `debug`
 *   - `info`
 *   - `notice`
 *   - `warning`
 *   - `error`
 *   - `critical`
 *   - `alert`
 *   - `emergency`
 *
 * EMITNLOG_FORMAT: The format to use.
 * The possible values are
 *   - `plain`
 *   - `colorful`
 *   - `json`
 *   - `unformatted-json`
 * ```
 *
 * If a environment variable is not set, the associated value in `options` is used.
 *
 * @example
 *
 * ```typescript
 * import { fromEnv } from 'emitnlog/logger/environment';
 *
 * // Basic usage - uses environment variables if set, otherwise returns OFF_LOGGER
 * const logger = fromEnv();
 * ```
 *
 * @example
 *
 * ```typescript
 * import { fromEnv } from 'emitnlog/logger/environment';
 *
 * // With fallback options when environment variables are not set
 * const logger = fromEnv({
 *   // Used if EMITNLOG_LEVEL is not set
 *   level: 'debug',
 *
 *   // Used if EMITNLOG_FORMAT is not set
 *   format: 'plain',
 * });
 * ```
 *
 * @example
 *
 * ```typescript
 * import { fromEnv } from 'emitnlog/logger/environment';
 *
 * // With a custom fallback logger
 * const logger = fromEnv({
 *   // Used if EMITNLOG_LOGGER is not set
 *   fallbackLogger: (level, format) => new CustomLogger(level, format),
 * });
 * ```
 *
 * @example
 *
 * ```typescript
 * import { fromEnv } from 'emitnlog/logger/node/environment';
 *
 * // Using console logger with info level and colorful format
 * process.env.EMITNLOG_LOGGER = 'console';
 * process.env.EMITNLOG_LEVEL = 'info';
 * process.env.EMITNLOG_FORMAT = 'colorful';
 * const logger = fromEnv();
 * logger.info('Hello, world!'); // Will output with colors to console
 * ```
 *
 * @param options The options to use.
 * @returns The logger to use.
 */
declare const fromEnv: (options?: EnvironmentLoggerOptions) => Logger;

export { type EmitterFormat as E, fromEnv as f };