@alwatr/logger
Version:
Fancy colorful console debugger with custom scope written in tiny TypeScript, ES module.
226 lines (211 loc) • 6.99 kB
text/typescript
/**
* Represents the AlwatrLogger interface for logging various types of information at different levels of detail.
* This interface allows for structured logging of events, method calls, errors, and more,
* aiding in debugging and understanding application behavior.
*
* @example
* import {createLogger} from '@alwatr/logger';
* const logger = createLogger('my-module'); // Create a logger with a specific scope
*
* function greet(name: string) {
* logger.logMethodArgs?.('greet', {name}); // Log the method call with its arguments
* // ...
* }
*
* greet('Ali');
*/
export interface AlwatrLogger {
/**
* Logger name
*/
readonly name: string;
/**
* Logs a property change with its new value using `console.debug`. Useful for tracking changes in application state.
*
* @param propertyName The name of the property that has changed.
* @param value The new value of the property.
*
* @example
* ```ts
* logger.logProperty?.('name', 'ali');
* ```
*/
logProperty?(propertyName: string, value: unknown): void;
/**
* Logs the file name of the current module using `console.debug`.
* Helpful for identifying the source of log messages.
*
* @param fileName The name of the file representing the module.
*
* @example
* ```ts
* logger.logFileModule?.('app');
* ```
*/
logFileModule?(fileName: string): void;
/**
* Logs the entry into a function or method using `console.debug`.
* Provides a basic trace of program execution.
*
* @param methodName The name of the function or method being called.
*
* @example
* ```ts
* function myMethod () {
* logger.logMethod?.('myMethod');
* }
* ```
*/
logMethod?(methodName: string): void;
/**
* Logs the entry into a function or method along with its arguments using `console.debug`.
* Aids in understanding the context of method calls.
*
* @param methodName The name of the function or method being called.
* @param args An object containing the arguments passed to the method.
*
* @example
* ```ts
* function myMethod (a: number, b: number) {
* logger.logMethodArgs?.('myMethod', {a, b});
* }
* ```
*/
logMethodArgs?(methodName: string, args: unknown): void;
/**
* Logs specific steps or milestones within a method using `console.debug`.
* Facilitates tracking progress within complex functions.
*
* @param methodName The name of the method where the step occurs.
* @param stepName The name or identifier of the specific step.
* @param props (Optional) Additional properties or data related to the step.
*
* @example
* ```ts
* function myMethod () {
* logger.logMethod?.('myMethod');
* ...
* logger.logStep?.('myMethod', 'step1');
* ...
* logger.logStep?.('myMethod', 'step2');
* ...
* }
* ```
*/
logStep?(methodName: string, stepName: string, props?: unknown): void;
/**
* Logs a complete method call, including its arguments and result, using `console.debug`.
* Useful for debugging and understanding the output of functions.
*
* @param methodName The name of the function or method being called.
* @param args An object containing the arguments passed to the method.
* @param result The result returned by the method.
*
* @example
* ```ts
* function add (a: number, b: number): number {
* const result = a + b;
* logger.logMethodFull?.('add', {a, b}, result);
* return result;
* }
* ```
*/
logMethodFull?(methodName: string, args: unknown, result: unknown): void;
/**
* Logs an event or expected incident using `console.log`. Intended for noteworthy information that doesn't represent an error or warning.
*
* @param methodName The name or context of the event or incident.
* @param warningCode A code or identifier for the specific type of event or incident.
* @param args Additional details or context related to the event or incident.
*
* @example
* ```ts
* logger.incident?.('fetch', 'abort_signal', {url: '/test.json'});
* ```
*/
incident?(methodName: string, warningCode: string, ...args: unknown[]): void;
/**
* Logs an unexpected incident or handled error as a warning using `console.warn`.
* Indicates a potential issue that has been addressed but warrants attention.
*
* @param methodName The name or context of the incident or error.
* @param warningCode A code or identifier for the specific type of incident or error.
* @param args Additional details or context related to the incident or error.
*
* @example
* ```ts
* logger.accident('fetch', 'file_not_found', {url: '/test.json'});
* ```
*/
accident(methodName: string, warningCode: string, ...args: unknown[]): void;
/**
* Logs an unexpected error using `console.error`. Highlights critical issues that need to be addressed.
*
* @param methodName The name or context where the error occurred.
* @param errorCode A code or identifier for the specific type of error.
* @param args Additional details or context related to the error, including the error object itself.
*
* @example
* ```ts
* try {
* ...
* }
* catch (err) {
* logger.error('myMethod', 'error_code', err, {a: 1, b: 2});
* }
* ```
*/
error(methodName: string, errorCode: string, ...args: unknown[]): void;
/**
* Performs a simple `console.debug` log with styled scope for general debugging purposes.
*
* @param args Any number of arguments to be logged.
*
* @example
* ```ts
* logger.logOther?.('foo:', 'bar', {a: 1});
* ```
*/
logOther?(...args: unknown[]): void;
/**
* Try to construct a table with the columns of the properties of `tabularData` (or use `properties`)
* and rows of `tabularData` and log it.
* Falls back to just logging the argument if it can't be parsed as tabular.
* @param tabularData Any data that can be represented in tabular form.
* @param properties Alternate properties for constructing the table.
*/
logTable?(tabularData: unknown, properties?: readonly string[]): void;
/**
* Starts a timer with a specified label using `console.time`. Useful for measuring performance.
*
* @param label The label for the timer.
*
* @example
* ```ts
* logger.time?.('foo');
* ```
*/
time?(label: string): void;
/**
* Ends a timer with a specified label and logs the elapsed time using `console.timeEnd`.
*
* @param label The label for the timer.
*
* @example
* ```ts
* logger.timeEnd?.('foo');
* ```
*/
timeEnd?(label: string): void;
/**
* Logs a prominent banner message, typically used for displaying important announcements or version information.
*
* @param message The message to be displayed in the banner.
*
* @example
* ```ts
* logger.banner('Alwatr PWA v2');
* ```
*/
banner(message: string): void;
}