@decaf-ts/logging 0.24.2 → 0.26.2

package/lib/types/logging.d.cts

@@ -46,14 +46,29 @@ export declare class MiniLogger implements Logger {
     /**
      * @description Creates a formatted log string.
      * @summary Generates a log string with timestamp, colored log level, context, and message.
-     * @param {LogLevel} level - The log level for this message.
+     * @param {LogLevel} [level] - The log level for this message. Omitted (`undefined`) for action entries, which carry no severity level.
      * @param {StringLike | Error} message - The message to log or an Error object.
      * @param {Error} [error] - Optional error to extract stack trace to include in the log.
      * @return {string} A formatted log string with all components.
      */
-    protected createLog(level: LogLevel, message: StringLike | Error, error?: Error, meta?: LogMeta): string;
+    protected createLog(level: LogLevel | undefined, message: StringLike | Error, error?: Error, meta?: LogMeta, action?: string, actionCode?: number): string;
     private formatMeta;
     protected normalizePatternSpacing(value: string): string;
+    /**
+     * @description Resolves the console method used to emit a given log level.
+     * @summary Maps each {@link LogLevel} to the console method that should carry it (error levels to `console.error`, warn to `console.warn`, etc).
+     * @param {LogLevel} level - The log level to resolve a console method for.
+     * @return The console method for that level.
+     */
+    protected methodFor(level: LogLevel): (...args: any[]) => void;
+    /**
+     * @description Emits an already-formatted log line.
+     * @summary The single place every logging method funnels through to actually write output, so console access stays in one spot.
+     * @param method - The console method to invoke (e.g. `console.log`, `console.error`).
+     * @param {string} formatted - The fully formatted log line, as produced by {@link createLog}.
+     * @return {void}
+     */
+    protected write(method: (...args: any[]) => void, formatted: string): void;
     /**
      * @description Logs a message with the specified log level.
      * @summary Checks if the message should be logged based on the current log level, then uses the appropriate console method to output the formatted log.
@@ -71,6 +86,16 @@ export declare class MiniLogger implements Logger {
      * @return {void}
      */
     benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs an action: a discrete, named event carrying its own metadata rather than a severity level or a message.
+     * @summary Action entries are a separate, more controlled channel from the rest of the {@link Logger} API - they carry no message, are not tied to any {@link LogLevel}, and always print regardless of the configured minimum level. The action name (plus its optional numeric code) is rendered where the level would otherwise appear, and the structured meta is always rendered too, regardless of the `meta` display setting. An entry's payload is exactly: the action string, an optional code, and meta - nothing else.
+     * @param {string} action - The action name/identifier.
+     * @param {number} [code] - An optional numeric classification code for the action.
+     * @param {LogMeta} [meta] - Optional structured metadata, always rendered regardless of the `meta` display setting.
+     * @return {void}
+     */
+    action(action: string, meta?: LogMeta): void;
+    action(action: string, code: number, meta?: LogMeta): void;
     /**
      * @description Logs a message at the fatal level.
      * @summary Logs a message at the fatal level for unrecoverable failures.
@@ -306,6 +331,16 @@ export declare class Logging {
      * @return {void}
      */
     static benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs an action.
+     * @summary Delegates the action logging to the global logger instance.
+     * @param {string} action - The action name/identifier.
+     * @param {number} [code] - An optional numeric classification code for the action.
+     * @param {LogMeta} [meta] - Optional structured metadata, always rendered regardless of the `meta` display setting.
+     * @return {void}
+     */
+    static action(action: string, meta?: LogMeta): void;
+    static action(action: string, code: number, meta?: LogMeta): void;
     /**
      * @description Logs a fatal message.
      * @summary Delegates the fatal logging to the global logger instance.
@@ -403,7 +438,7 @@ export declare class Logging {
      *     end
      *   end
      */
-    static theme(text: string, type: keyof Theme | keyof LogLevel, loggerLevel: LogLevel, template?: Theme): string;
+    static theme(text: string, type: keyof Theme | keyof LogLevel, loggerLevel: LogLevel | undefined, template?: Theme): string;
     static register(descriptor: LogParameterDescriptor): import("./logParameters.d.cts").LogParameterRegistry;
     static unregister(key: string): import("./logParameters.d.cts").LogParameterRegistry;
 }

package/lib/types/logging.d.mts

@@ -46,14 +46,29 @@ export declare class MiniLogger implements Logger {
     /**
      * @description Creates a formatted log string.
      * @summary Generates a log string with timestamp, colored log level, context, and message.
-     * @param {LogLevel} level - The log level for this message.
+     * @param {LogLevel} [level] - The log level for this message. Omitted (`undefined`) for action entries, which carry no severity level.
      * @param {StringLike | Error} message - The message to log or an Error object.
      * @param {Error} [error] - Optional error to extract stack trace to include in the log.
      * @return {string} A formatted log string with all components.
      */
-    protected createLog(level: LogLevel, message: StringLike | Error, error?: Error, meta?: LogMeta): string;
+    protected createLog(level: LogLevel | undefined, message: StringLike | Error, error?: Error, meta?: LogMeta, action?: string, actionCode?: number): string;
     private formatMeta;
     protected normalizePatternSpacing(value: string): string;
+    /**
+     * @description Resolves the console method used to emit a given log level.
+     * @summary Maps each {@link LogLevel} to the console method that should carry it (error levels to `console.error`, warn to `console.warn`, etc).
+     * @param {LogLevel} level - The log level to resolve a console method for.
+     * @return The console method for that level.
+     */
+    protected methodFor(level: LogLevel): (...args: any[]) => void;
+    /**
+     * @description Emits an already-formatted log line.
+     * @summary The single place every logging method funnels through to actually write output, so console access stays in one spot.
+     * @param method - The console method to invoke (e.g. `console.log`, `console.error`).
+     * @param {string} formatted - The fully formatted log line, as produced by {@link createLog}.
+     * @return {void}
+     */
+    protected write(method: (...args: any[]) => void, formatted: string): void;
     /**
      * @description Logs a message with the specified log level.
      * @summary Checks if the message should be logged based on the current log level, then uses the appropriate console method to output the formatted log.
@@ -71,6 +86,16 @@ export declare class MiniLogger implements Logger {
      * @return {void}
      */
     benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs an action: a discrete, named event carrying its own metadata rather than a severity level or a message.
+     * @summary Action entries are a separate, more controlled channel from the rest of the {@link Logger} API - they carry no message, are not tied to any {@link LogLevel}, and always print regardless of the configured minimum level. The action name (plus its optional numeric code) is rendered where the level would otherwise appear, and the structured meta is always rendered too, regardless of the `meta` display setting. An entry's payload is exactly: the action string, an optional code, and meta - nothing else.
+     * @param {string} action - The action name/identifier.
+     * @param {number} [code] - An optional numeric classification code for the action.
+     * @param {LogMeta} [meta] - Optional structured metadata, always rendered regardless of the `meta` display setting.
+     * @return {void}
+     */
+    action(action: string, meta?: LogMeta): void;
+    action(action: string, code: number, meta?: LogMeta): void;
     /**
      * @description Logs a message at the fatal level.
      * @summary Logs a message at the fatal level for unrecoverable failures.
@@ -306,6 +331,16 @@ export declare class Logging {
      * @return {void}
      */
     static benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs an action.
+     * @summary Delegates the action logging to the global logger instance.
+     * @param {string} action - The action name/identifier.
+     * @param {number} [code] - An optional numeric classification code for the action.
+     * @param {LogMeta} [meta] - Optional structured metadata, always rendered regardless of the `meta` display setting.
+     * @return {void}
+     */
+    static action(action: string, meta?: LogMeta): void;
+    static action(action: string, code: number, meta?: LogMeta): void;
     /**
      * @description Logs a fatal message.
      * @summary Delegates the fatal logging to the global logger instance.
@@ -403,7 +438,7 @@ export declare class Logging {
      *     end
      *   end
      */
-    static theme(text: string, type: keyof Theme | keyof LogLevel, loggerLevel: LogLevel, template?: Theme): string;
+    static theme(text: string, type: keyof Theme | keyof LogLevel, loggerLevel: LogLevel | undefined, template?: Theme): string;
     static register(descriptor: LogParameterDescriptor): import("./logParameters.d.mts").LogParameterRegistry;
     static unregister(key: string): import("./logParameters.d.mts").LogParameterRegistry;
 }

package/lib/types/types.d.cts

@@ -71,6 +71,16 @@ export interface Logger extends Impersonatable<Logger, [
      * @return {void}
      */
     benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs a named action: a discrete event carrying its own metadata rather than a severity level or a message.
+     * @summary Action entries are a separate, more controlled channel from the rest of this interface - they carry no message, are not tied to a {@link LogLevel}, and always print regardless of the configured minimum level. The action name (plus optional numeric code) is rendered where a level would otherwise appear, and `meta` is always rendered too, regardless of the logger's `meta` display setting. An entry's payload is exactly: the action string, an optional code, and meta.
+     * @param {string} action - The action name/identifier.
+     * @param {number} [code] - An optional numeric classification code for the action.
+     * @param {LogMeta} [meta] - Optional structured metadata, always rendered regardless of the `meta` display setting.
+     * @return {void}
+     */
+    action(action: string, meta?: LogMeta): void;
+    action(action: string, code: number, meta?: LogMeta): void;
     /**
      * @description Logs a fatal message.
      * @summary Emits the most severe failure events at the `fatal` log level.
@@ -286,6 +296,7 @@ export interface Theme {
      * @description Styling for the main message text in the output.
      */
     message: ThemeOption | ThemeOptionByLogLevel;
+    action: ThemeOption | ThemeOptionByLogLevel;
     /**
      * @description Styling for method names in the output.
      */

package/lib/types/types.d.mts

@@ -71,6 +71,16 @@ export interface Logger extends Impersonatable<Logger, [
      * @return {void}
      */
     benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs a named action: a discrete event carrying its own metadata rather than a severity level or a message.
+     * @summary Action entries are a separate, more controlled channel from the rest of this interface - they carry no message, are not tied to a {@link LogLevel}, and always print regardless of the configured minimum level. The action name (plus optional numeric code) is rendered where a level would otherwise appear, and `meta` is always rendered too, regardless of the logger's `meta` display setting. An entry's payload is exactly: the action string, an optional code, and meta.
+     * @param {string} action - The action name/identifier.
+     * @param {number} [code] - An optional numeric classification code for the action.
+     * @param {LogMeta} [meta] - Optional structured metadata, always rendered regardless of the `meta` display setting.
+     * @return {void}
+     */
+    action(action: string, meta?: LogMeta): void;
+    action(action: string, code: number, meta?: LogMeta): void;
     /**
      * @description Logs a fatal message.
      * @summary Emits the most severe failure events at the `fatal` log level.
@@ -286,6 +296,7 @@ export interface Theme {
      * @description Styling for the main message text in the output.
      */
     message: ThemeOption | ThemeOptionByLogLevel;
+    action: ThemeOption | ThemeOptionByLogLevel;
     /**
      * @description Styling for method names in the output.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/logging",
-  "version": "0.24.2",
+  "version": "0.26.2",
   "description": "simple winston inspired wrapper for cross lib logging",
   "type": "module",
   "exports": {