diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 13c69a709d69..8969cc161fef 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -78,6 +78,7 @@ const ENTRY_POINTS = [ "../log/info.ts", "../log/console_handler.ts", "../log/formatters.ts", + "../log/get_logger.ts", "../media_types/mod.ts", "../msgpack/mod.ts", "../net/mod.ts", diff --git a/log/get_logger.ts b/log/get_logger.ts index 98df3dfebf78..f466b6e510ac 100644 --- a/log/get_logger.ts +++ b/log/get_logger.ts @@ -4,7 +4,63 @@ import { Logger } from "./logger.ts"; import { state } from "./_state.ts"; -/** Get a logger instance. If not specified `name`, get the default logger. */ +export type { Logger }; + +/** + * Get a logger instance. If not specified `name`, get the default logger. + * + * @param name The name of the logger. + * @returns The logger instance. + * + * @example Usage (without defined name and minimal setup) + * ```ts + * import { getLogger } from "@std/log/get-logger"; + * import "@std/log/setup"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = getLogger(); + * const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue + * + * assertEquals(result, "Hello world!"); + * ``` + * + * @example Usage (without defined name and custom setup) + * ```ts + * import { getLogger } from "@std/log/get-logger"; + * import { ConsoleHandler } from "@std/log/console-handler"; + * import { setup } from "@std/log/setup"; + * import { assertEquals } from "@std/assert/equals"; + * + * setup({ + * handlers: { + * console: new ConsoleHandler("DEBUG"), + * }, + * loggers: { + * default: { + * level: "DEBUG", + * handlers: ["console"], + * }, + * }, + * }); + * + * const logger = getLogger(); + * + * const result = logger.info("Hello world!"); // Prints "INFO Hello world!" in blue + * + * assertEquals(result, "Hello world!"); + * ``` + * + * @example Usage (with defined name) + * ```ts + * import { getLogger } from "@std/log/get-logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = getLogger("my-logger"); + * const result = logger.info("Hello world!"); + * + * assertEquals(result, "Hello world!"); + * ``` + */ export function getLogger(name?: string): Logger { if (!name) { const d = state.loggers.get("default"); diff --git a/log/logger.ts b/log/logger.ts index 5bac6bee00ab..8e31e4ebec4a 100644 --- a/log/logger.ts +++ b/log/logger.ts @@ -220,7 +220,9 @@ export class LogRecord { } } +/** Options for {@linkcode Logger}. */ export interface LoggerOptions { + /** The handlers to use for the logger. */ handlers?: BaseHandler[]; } @@ -249,11 +251,49 @@ function asString(data: unknown, isProperty = false): string { return "undefined"; } +/** + * A logger that can log messages at different levels. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * const result = logger.info("Hello, world!"); + * + * assertEquals(result, "Hello, world!"); + * ``` + */ export class Logger { #level: LogLevel; + /** + * The handlers to use for the logger. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { ConsoleHandler } from "@std/log/console-handler"; + * import { assertEquals } from "@std/assert/equals"; + * + * const handler = new ConsoleHandler("INFO"); + * const logger = new Logger("example", "INFO", { + * handlers: [handler], + * }); + * + * assertEquals(logger.handlers, [handler]); + * ``` + */ handlers: BaseHandler[]; readonly #loggerName: string; + /** + * Constructs a new instance. + * + * @param loggerName The name of the logger. + * @param levelName The name of the log level. + * @param options The options to create a new logger. + */ constructor( loggerName: string, levelName: LevelName, @@ -264,12 +304,42 @@ export class Logger { this.handlers = options.handlers ?? []; } - /** Use this to retrieve the current numeric log level. */ + /** + * Getter for the log level. + * + * @returns The log level. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { LogLevels } from "@std/log/levels"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * assertEquals(logger.level, LogLevels.INFO); + * ``` + */ get level(): LogLevel { return this.#level; } - /** Use this to set the numeric log level. */ + /** + * Setter for the log level. + * + * @param level The log level to set. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { LogLevels } from "@std/log/levels"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * logger.level = LogLevels.DEBUG; + * + * assertEquals(logger.level, LogLevels.DEBUG); + * ``` + */ set level(level: LogLevel) { try { this.#level = getLevelByName(getLevelName(level)); @@ -278,13 +348,60 @@ export class Logger { } } + /** + * Getter for the name of the log level. + * + * @returns The name of the log level. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * assertEquals(logger.levelName, "INFO"); + * ``` + */ get levelName(): LevelName { return getLevelName(this.#level); } + + /** + * Setter for the name of the log level. + * + * @param levelName The name of the log level to set. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { LogLevels } from "@std/log/levels"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * logger.levelName = "DEBUG"; + * + * assertEquals(logger.level, LogLevels.DEBUG); + * ``` + */ set levelName(levelName: LevelName) { this.#level = getLevelByName(levelName); } + /** + * Getter for the name of the logger. + * + * @returns The name of the logger. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.loggerName, "example"); + * ``` + */ get loggerName(): string { return this.#loggerName; } @@ -328,7 +445,47 @@ export class Logger { return msg instanceof Function ? fnResult : msg; } + /** + * Log at the debug level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.debug("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.debug(() => "Hello, world!"), undefined); + * ``` + */ debug(msg: () => T, ...args: unknown[]): T | undefined; + /** + * Log at the debug level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.debug("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.debug(() => "Hello, world!"), undefined); + * ``` + */ debug(msg: T extends GenericFunction ? never : T, ...args: unknown[]): T; debug( msg: (T extends GenericFunction ? never : T) | (() => T), @@ -337,7 +494,47 @@ export class Logger { return this.#log(LogLevels.DEBUG, msg, ...args); } + /** + * Log at the info level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.info("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.info(() => "Hello, world!"), "Hello, world!"); + * ``` + */ info(msg: () => T, ...args: unknown[]): T | undefined; + /** + * Log at the info level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.info("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.info(() => "Hello, world!"), "Hello, world!"); + * ``` + */ info(msg: T extends GenericFunction ? never : T, ...args: unknown[]): T; info( msg: (T extends GenericFunction ? never : T) | (() => T), @@ -346,7 +543,47 @@ export class Logger { return this.#log(LogLevels.INFO, msg, ...args); } + /** + * Log at the warning level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.warn("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.warn(() => "Hello, world!"), "Hello, world!"); + * ``` + */ warn(msg: () => T, ...args: unknown[]): T | undefined; + /** + * Log at the warning level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.warn("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.warn(() => "Hello, world!"), "Hello, world!"); + * ``` + */ warn(msg: T extends GenericFunction ? never : T, ...args: unknown[]): T; warn( msg: (T extends GenericFunction ? never : T) | (() => T), @@ -355,7 +592,47 @@ export class Logger { return this.#log(LogLevels.WARN, msg, ...args); } + /** + * Log at the error level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.error("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.error(() => "Hello, world!"), "Hello, world!"); + * ``` + */ error(msg: () => T, ...args: unknown[]): T | undefined; + /** + * Log at the error level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.error("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.error(() => "Hello, world!"), "Hello, world!"); + * ``` + */ error(msg: T extends GenericFunction ? never : T, ...args: unknown[]): T; error( msg: (T extends GenericFunction ? never : T) | (() => T), @@ -364,7 +641,47 @@ export class Logger { return this.#log(LogLevels.ERROR, msg, ...args); } + /** + * Log at the critical level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.critical("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.critical(() => "Hello, world!"), "Hello, world!"); + * ``` + */ critical(msg: () => T, ...args: unknown[]): T | undefined; + /** + * Log at the critical level. + * + * @template T The type of the message to log. + * @param msg The message to log. + * @param args Arguments to be formatted into the message. + * @returns The message that was logged. + * + * @example Usage + * ```ts + * import { Logger } from "@std/log/logger"; + * import { assertEquals } from "@std/assert/equals"; + * + * const logger = new Logger("example", "INFO"); + * + * assertEquals(logger.critical("Hello, world!"), "Hello, world!"); + * + * assertEquals(logger.critical(() => "Hello, world!"), "Hello, world!"); + * ``` + */ critical( msg: T extends GenericFunction ? never : T, ...args: unknown[]