diff --git a/src/basic.ts b/src/basic.ts index 5b19882e..d17ea1ae 100644 --- a/src/basic.ts +++ b/src/basic.ts @@ -5,6 +5,12 @@ import { ConsolaInstance, createConsola as _createConsola } from "./consola"; export * from "./shared"; +/** + * Factory function to create a new Consola instance + * + * @param {Partial} [options={}] - Optional configuration options. See {@link ConsolaOptions}. + * @returns {ConsolaInstance} A new Consola instance configured with the given options. + */ export function createConsola( options: Partial = {}, ): ConsolaInstance { @@ -27,6 +33,12 @@ export function createConsola( return consola; } +/** + * Creates and exports a standard instance of Consola with the default configuration. + * This instance can be used directly for logging throughout the application. + * + * @type {ConsolaInstance} consola - The default instance of Consola. + */ export const consola = createConsola(); export default consola; diff --git a/src/browser.ts b/src/browser.ts index 685e0878..5a845333 100644 --- a/src/browser.ts +++ b/src/browser.ts @@ -4,6 +4,14 @@ import type { ConsolaOptions } from "./types"; export * from "./shared"; +/** + * Creates a new Consola instance configured specifically for browser environments. + * This function sets up default reporters and a prompt method tailored to the browser's dialogue APIs. + * + * @param {Partial} [options={}] - Optional configuration options. + * The options can override the default reporter and prompt behaviour. See {@link ConsolaOptions}. + * @returns {ConsolaInstance} A new Consola instance optimised for use in browser environments. + */ export function createConsola(options: Partial = {}) { const consola = _createConsola({ reporters: options.reporters || [new BrowserReporter({})], @@ -18,6 +26,12 @@ export function createConsola(options: Partial = {}) { return consola; } +/** + * A standard Consola instance created with browser-specific configurations. + * This instance can be used throughout a browser-based project. + * + * @type {ConsolaInstance} consola - The default browser-configured Consola instance. + */ export const consola = createConsola(); export default consola; diff --git a/src/consola.ts b/src/consola.ts index 1f1f2fc1..6e92408c 100644 --- a/src/consola.ts +++ b/src/consola.ts @@ -12,6 +12,12 @@ import type { PromptOptions } from "./prompt"; let paused = false; const queue: any[] = []; +/** + * Consola class for logging management with support for pause/resume, mocking and customisable reporting. + * Provides flexible logging capabilities including level-based logging, custom reporters and integration options. + * + * @class Consola + */ export class Consola { options: ConsolaOptions; @@ -25,6 +31,11 @@ export class Consola { _mockFn?: ConsolaOptions["mockFn"]; + /** + * Creates an instance of Consola with specified options or defaults. + * + * @param {Partial} [options={}] - Configuration options for the Consola instance. + */ constructor(options: Partial = {}) { // Options const types = options.types || LogTypes; @@ -73,10 +84,20 @@ export class Consola { this._lastLog = {}; } + /** + * Gets the current log level of the Consola instance. + * + * @returns {number} The current log level. + */ get level() { return this.options.level; } + /** + * Sets the minimum log level that will be output by the instance. + * + * @param {number} level - The new log level to set. + */ set level(level) { this.options.level = _normalizeLogLevel( level, @@ -85,6 +106,15 @@ export class Consola { ); } + /** + * Displays a prompt to the user and returns the response. + * Throw an error if `prompt` is not supported by the current configuration. + * + * @template T + * @param {string} message - The message to display in the prompt. + * @param {T} [opts] - Optional options for the prompt. See {@link PromptOptions}. + * @returns {promise} A promise that infer with the prompt options. See {@link PromptOptions}. + */ prompt(message: string, opts?: T) { if (!this.options.prompt) { throw new Error("prompt is not supported!"); @@ -92,6 +122,12 @@ export class Consola { return this.options.prompt(message, opts); } + /** + * Creates a new instance of Consola, inheriting options from the current instance, with possible overrides. + * + * @param {Partial} options - Optional overrides for the new instance. See {@link ConsolaOptions}. + * @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}. + */ create(options: Partial): ConsolaInstance { const instance = new Consola({ ...this.options, @@ -105,6 +141,12 @@ export class Consola { return instance; } + /** + * Creates a new Consola instance with the specified default log object properties. + * + * @param {InputLogObject} defaults - Default properties to include in any log from the new instance. See {@link InputLogObject}. + * @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}. + */ withDefaults(defaults: InputLogObject): ConsolaInstance { return this.create({ ...this.options, @@ -115,6 +157,12 @@ export class Consola { }); } + /** + * Creates a new Consola instance with a specified tag, which will be included in every log. + * + * @param {string} tag - The tag to include in each log of the new instance. + * @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}. + */ withTag(tag: string): ConsolaInstance { return this.withDefaults({ tag: this.options.defaults.tag @@ -123,11 +171,25 @@ export class Consola { }); } + /** + * Adds a custom reporter to the Consola instance. + * Reporters will be called for each log message, depending on their implementation and log level. + * + * @param {ConsolaReporter} reporter - The reporter to add. See {@link ConsolaReporter}. + * @returns {Consola} The current Consola instance. + */ addReporter(reporter: ConsolaReporter) { this.options.reporters.push(reporter); return this; } + /** + * Removes a custom reporter from the Consola instance. + * If no reporter is specified, all reporters will be removed. + * + * @param {ConsolaReporter} reporter - The reporter to remove. See {@link ConsolaReporter}. + * @returns {Consola} The current Consola instance. + */ removeReporter(reporter: ConsolaReporter) { if (reporter) { const i = this.options.reporters.indexOf(reporter); @@ -140,6 +202,12 @@ export class Consola { return this; } + /** + * Replaces all reporters of the Consola instance with the specified array of reporters. + * + * @param {ConsolaReporter[]} reporters - The new reporters to set. See {@link ConsolaReporter}. + * @returns {Consola} The current Consola instance. + */ setReporters(reporters: ConsolaReporter[]) { this.options.reporters = Array.isArray(reporters) ? reporters : [reporters]; return this; @@ -155,6 +223,9 @@ export class Consola { this.restoreStd(); } + /** + * Overrides console methods with Consola logging methods for consistent logging. + */ wrapConsole() { for (const type in this.options.types) { // Backup original value @@ -169,6 +240,9 @@ export class Consola { } } + /** + * Restores the original console methods, removing Consola overrides. + */ restoreConsole() { for (const type in this.options.types) { // Restore if backup is available @@ -180,6 +254,9 @@ export class Consola { } } + /** + * Overrides standard output and error streams to redirect them through Consola. + */ wrapStd() { this._wrapStream(this.options.stdout, "log"); this._wrapStream(this.options.stderr, "log"); @@ -201,6 +278,9 @@ export class Consola { }; } + /** + * Restores the original standard output and error streams, removing the Consola redirection. + */ restoreStd() { this._restoreStream(this.options.stdout); this._restoreStream(this.options.stderr); @@ -217,10 +297,16 @@ export class Consola { } } + /** + * Pauses logging, queues incoming logs until resumed. + */ pauseLogs() { paused = true; } + /** + * Resumes logging, processing any queued logs. + */ resumeLogs() { paused = false; @@ -231,6 +317,11 @@ export class Consola { } } + /** + * Replaces logging methods with mocks if a mock function is provided. + * + * @param {ConsolaOptions["mockFn"]} mockFn - The function to use for mocking logging methods. See {@link ConsolaOptions["mockFn"]}. + */ mockTypes(mockFn?: ConsolaOptions["mockFn"]) { const _mockFn = mockFn || this.options.mockFn; @@ -408,6 +499,12 @@ Consola.prototype.pause = Consola.prototype.pauseLogs; // @ts-expect-error Consola.prototype.resume = Consola.prototype.resumeLogs; +/** + * Utility for creating a new Consola instance with optional configuration. + * + * @param {Partial} [options={}] - Optional configuration options for the new Consola instance. See {@link ConsolaOptions}. + * @returns {ConsolaInstance} A new instance of Consola. See {@link ConsolaInstance}. + */ export function createConsola( options: Partial = {}, ): ConsolaInstance { diff --git a/src/constants.ts b/src/constants.ts index 67560251..04850bc0 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -1,8 +1,19 @@ import { LogObject } from "./types"; +/** + * Defines the level of logs as specific numbers or special number types. + * + * @type {0 | 1 | 2 | 3 | 4 | 5 | (number & {})} LogLevel - Represents the log level. + * @default 0 - Represents the default log level. + */ // eslint-disable-next-line @typescript-eslint/ban-types export type LogLevel = 0 | 1 | 2 | 3 | 4 | 5 | (number & {}); +/** + * A mapping of `LogType` to its corresponding numeric log level. + * + * @type {Record} LogLevels - key-value pairs of log types to their numeric levels. See {@link LogType}. + */ export const LogLevels: Record = { silent: Number.NEGATIVE_INFINITY, @@ -27,6 +38,11 @@ export const LogLevels: Record = { verbose: Number.POSITIVE_INFINITY, }; +/** + * Lists the types of log messages supported by the system. + * + * @type {"silent" | "fatal" | "error" | "warn" | "log" | "info" | "success" | "fail" | "ready" | "start" | "box" | "debug" | "trace" | "verbose"} LogType - Represents the specific type of log message. + */ export type LogType = // 0 | "silent" @@ -48,6 +64,11 @@ export type LogType = | "trace" | "verbose"; +/** + * Maps `LogType` to a `Partial`, primarily defining the log level. + * + * @type {Record>} LogTypes - key-value pairs of log types to partial log objects, specifying log levels. See {@link LogType} and {@link LogObject}. + */ export const LogTypes: Record> = { // Silent silent: { diff --git a/src/index.ts b/src/index.ts index 084bc28f..372b5c37 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,6 +7,13 @@ import { ConsolaInstance, createConsola as _createConsola } from "./consola"; export * from "./shared"; +/** + * Factory function to create a new Consola instance tailored for use in different environments. + * It automatically adjusts logging levels based on environment variables and execution context. + * + * @param {Partial} [options={}] - Optional configuration options. See {@link ConsolaOptions}. + * @returns {ConsolaInstance} A new Consola instance with configurations based on the given options and the execution environment. + */ export function createConsola( options: Partial = {}, ): ConsolaInstance { @@ -44,6 +51,12 @@ function _getDefaultLogLevel() { return LogLevels.info; } +/** + * A default instance of Consola, created and configured for immediate use. + * This instance is configured based on the execution environment and the options provided. + * + * @type {ConsolaInstance} consola - The default Consola instance, ready to use. + */ export const consola = createConsola(); export default consola; diff --git a/src/prompt.ts b/src/prompt.ts index 8ab8d353..f2857010 100644 --- a/src/prompt.ts +++ b/src/prompt.ts @@ -7,30 +7,88 @@ type SelectOption = { }; export type TextOptions = { + /** + * Specifies the prompt type as text. + * @optional + * @default "text" + */ type?: "text"; + + /** + * The default text value. + * @optional + */ default?: string; + + /** + * A placeholder text displayed in the prompt. + * @optional + */ placeholder?: string; + + /** + * The initial text value. + * @optional + */ initial?: string; }; export type ConfirmOptions = { + /** + * Specifies the prompt type as confirm. + */ type: "confirm"; + + /** + * The initial value for the confirm prompt. + * @optional + */ initial?: boolean; }; export type SelectOptions = { + /** + * Specifies the prompt type as select. + */ type: "select"; + + /** + * The initial value for the select prompt. + * @optional + */ initial?: string; + + /** + * The options to select from. See {@link SelectOption}. + */ options: (string | SelectOption)[]; }; export type MultiSelectOptions = { + /** + * Specifies the prompt type as multiselect. + */ type: "multiselect"; + + /** + * The options to select from. See {@link SelectOption}. + */ initial?: string[]; + + /** + * The options to select from. See {@link SelectOption}. + */ options: (string | SelectOption)[]; + + /** + * Whether the prompt requires at least one selection. + */ required?: boolean; }; +/** + * Defines a combined type for all prompt options. + */ export type PromptOptions = | TextOptions | ConfirmOptions @@ -49,6 +107,14 @@ type inferPromptReturnType = T extends TextOptions ? T["options"] : unknown; +/** + * Asynchronously prompts the user for input based on specified options. + * Supports text, confirm, select and multi-select prompts. + * + * @param {string} message - The message to display in the prompt. + * @param {PromptOptions} [opts={}] - The prompt options. See {@link PromptOptions}. + * @returns {Promise>} - A promise that resolves with the user's response, the type of which is inferred from the options. See {@link inferPromptReturnType}. + */ export async function prompt< _ = any, __ = any, diff --git a/src/types.ts b/src/types.ts index 62b907fd..d3d8ca45 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,16 +1,64 @@ import type { LogLevel, LogType } from "./constants"; export interface ConsolaOptions { + /** + * An array of ConsolaReporter instances used to handle and output log messages. + */ reporters: ConsolaReporter[]; + + /** + * A record mapping LogType to InputLogObject, defining the log configuration for each log type. + * See {@link LogType} and {@link InputLogObject}. + */ types: Record; + + /** + * The minimum log level to output. See {@link LogLevel}. + */ level: LogLevel; + + /** + * Default properties applied to all log messages unless overridden. See {@link InputLogObject}. + */ defaults: InputLogObject; + + /** + * The maximum number of times a log message can be repeated within a given timeframe. + */ throttle: number; + + /** + * The minimum time in milliseconds that must elapse before a throttled log message can be logged again. + */ throttleMin: number; + + /** + * The Node.js writable stream for standard output. See {@link NodeJS.WriteStream}. + * @optional + */ stdout?: NodeJS.WriteStream; + + /** + * The Node.js writeable stream for standard error output. See {@link NodeJS.WriteStream}. + * @optional + */ stderr?: NodeJS.WriteStream; + + /** + * A function that allows you to mock log messages for testing purposes. + * @optional + */ mockFn?: (type: LogType, defaults: InputLogObject) => (...args: any) => void; + + /** + * Custom prompt function to use. It can be undefined. + * @optional + */ prompt?: typeof import("./prompt").prompt | undefined; + + /** + * Configuration options for formatting log messages. See {@link FormatOptions}. + */ formatOptions: FormatOptions; } @@ -18,33 +66,118 @@ export interface ConsolaOptions { * @see https://nodejs.org/api/util.html#util_util_inspect_object_showhidden_depth_colors */ export interface FormatOptions { + /** + * The maximum number of columns to output, affects formatting. + * @optional + */ columns?: number; + + /** + * Whether to include timestamp information in log messages. + * @optional + */ date?: boolean; + + /** + * Whether to use colors in the output. + * @optional + */ colors?: boolean; + + /** + * Specifies whether or not the output should be compact. Accepts a boolean or numeric level of compactness. + * @optional + */ compact?: boolean | number; + + /** + * Allows additional custom formatting options. + */ [key: string]: unknown; } export interface InputLogObject { + /** + * The logging level of the message. See {@link LogLevel}. + * @optional + */ level?: LogLevel; + + /** + * A string tag to categorise or identify the log message. + * @optional + */ tag?: string; + + /** + * The type of log message, which affects how it's processed and displayed. See {@link LogType}. + * @optional + */ type?: LogType; + + /** + * The main log message text. + * @optional + */ message?: string; + + /** + * Additional text or texts to be logged with the message. + * @optional + */ additional?: string | string[]; + + /** + * Additional arguments to be logged with the message. + * @optional + */ args?: any[]; + + /** + * The date and time when the log message was created. + * @optional + */ date?: Date; } export interface LogObject extends InputLogObject { + /** + * The logging level of the message, overridden if required. See {@link LogLevel}. + */ level: LogLevel; + + /** + * The type of log message, overridden if required. See {@link LogType}. + */ type: LogType; + + /** + * A string tag to categorise or identify the log message, overridden if necessary. + */ tag: string; + + /** + * Additional arguments to be logged with the message, overridden if necessary. + */ args: any[]; + + /** + * The date and time the log message was created, overridden if necessary. + */ date: Date; + + /** + * Allows additional custom properties to be set on the log object. + */ [key: string]: unknown; } export interface ConsolaReporter { + /** + * Defines how a log message is processed and displayed by this reporter. + * @param logObj The LogObject containing the log information to process. See {@link LogObject}. + * @param ctx An object containing context information such as options. See {@link ConsolaOptions}. + */ log: ( logObj: LogObject, ctx: {