docs: add jsdocs for top-level functions (#288)

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<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 {
@@ -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;

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<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({})],
@@ -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;

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<ConsolaOptions>} [options={}] - Configuration options for the Consola instance.
+   */
   constructor(options: Partial<ConsolaOptions> = {}) {
     // 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,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,
@@ -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
@@ -168,6 +239,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
@@ -178,6 +252,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");
@@ -199,6 +276,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);
@@ -215,10 +295,16 @@ export class Consola {
     }
   }
 
+  /**
+   * Pauses logging, queues incoming logs until resumed.
+   */
   pauseLogs() {
     paused = true;
   }
 
+  /**
+   * Resumes logging, processing any queued logs.
+   */
   resumeLogs() {
     paused = false;
 
@@ -229,6 +315,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;
 
@@ -405,6 +496,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 {

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<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,
 
@@ -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"
@@ -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: {

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<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 {
@@ -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;