Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add jsdocs for top-level functions #288

Merged
merged 1 commit into from
Jun 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions src/basic.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ import { ConsolaInstance, createConsola as _createConsola } from "./consola";

export * from "./shared";

/**
* Factory function to create a new Consola instance
*
* @param {Partial<ConsolaOptions & { fancy: boolean }>} [options={}] - Optional configuration options. See {@link ConsolaOptions}.
* @returns {ConsolaInstance} A new Consola instance configured with the given options.
*/
export function createConsola(
options: Partial<ConsolaOptions & { fancy: boolean }> = {},
): ConsolaInstance {
Expand All @@ -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;
14 changes: 14 additions & 0 deletions src/browser.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<ConsolaOptions>} [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<ConsolaOptions> = {}) {
const consola = _createConsola({
reporters: options.reporters || [new BrowserReporter({})],
Expand All @@ -18,6 +26,12 @@ export function createConsola(options: Partial<ConsolaOptions> = {}) {
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;
97 changes: 97 additions & 0 deletions src/consola.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -25,6 +31,11 @@ export class Consola {

_mockFn?: ConsolaOptions["mockFn"];

/**
* Creates an instance of Consola with specified options or defaults.
*
* @param {Partial<ConsolaOptions>} [options={}] - Configuration options for the Consola instance.
*/
constructor(options: Partial<ConsolaOptions> = {}) {
// Options
const types = options.types || LogTypes;
Expand Down Expand Up @@ -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,
Expand All @@ -85,13 +106,28 @@ 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<T>} A promise that infer with the prompt options. See {@link PromptOptions}.
*/
prompt<T extends PromptOptions>(message: string, opts?: T) {
if (!this.options.prompt) {
throw new Error("prompt is not supported!");
}
return this.options.prompt<any, any, T>(message, opts);
}

/**
* Creates a new instance of Consola, inheriting options from the current instance, with possible overrides.
*
* @param {Partial<ConsolaOptions>} options - Optional overrides for the new instance. See {@link ConsolaOptions}.
* @returns {ConsolaInstance} A new Consola instance. See {@link ConsolaInstance}.
*/
create(options: Partial<ConsolaOptions>): ConsolaInstance {
const instance = new Consola({
...this.options,
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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);
Expand All @@ -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;
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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");
Expand All @@ -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);
Expand All @@ -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;

Expand All @@ -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;

Expand Down Expand Up @@ -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<ConsolaOptions>} [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<ConsolaOptions> = {},
): ConsolaInstance {
Expand Down
21 changes: 21 additions & 0 deletions src/constants.ts
Original file line number Diff line number Diff line change
@@ -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<LogType, number>} LogLevels - key-value pairs of log types to their numeric levels. See {@link LogType}.
*/
export const LogLevels: Record<LogType, number> = {
silent: Number.NEGATIVE_INFINITY,

Expand All @@ -27,6 +38,11 @@ export const LogLevels: Record<LogType, number> = {
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"
Expand All @@ -48,6 +64,11 @@ export type LogType =
| "trace"
| "verbose";

/**
* Maps `LogType` to a `Partial<LogObject>`, primarily defining the log level.
*
* @type {Record<LogType, Partial<LogObject>>} LogTypes - key-value pairs of log types to partial log objects, specifying log levels. See {@link LogType} and {@link LogObject}.
*/
export const LogTypes: Record<LogType, Partial<LogObject>> = {
// Silent
silent: {
Expand Down
13 changes: 13 additions & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<ConsolaOptions & { fancy: boolean }>} [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<ConsolaOptions & { fancy: boolean }> = {},
): ConsolaInstance {
Expand Down Expand Up @@ -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;
Loading