@naturalcycles/js-lib 15.31.0 → 15.32.0

package/dist/log/commonLogger.d.ts

@@ -3,13 +3,17 @@ import type { MutateOptions } from '../array/array.util.js';
  * These levels follow console.* naming,
  * so you can use console[level] safely.
  *
- * `log` is considered default level.
+ * `debug` is not enabled by default, and is useful when debugging is needed.
  *
- * For simplicity - only these 3 levels are kept.
+ * `log` is considered default level, and is enabled by default.
+ *
+ * `warn` is for warnings - things that are not super-severe to be an error, but should not happen
+ *
+ * `error` level would only log errors
  *
  * @experimental
  */
-export type CommonLogLevel = 'log' | 'warn' | 'error';
+export type CommonLogLevel = 'debug' | 'log' | 'warn' | 'error';
 export declare const commonLogLevelNumber: Record<CommonLogLevel, number>;
 /**
  * Function that takes any number of arguments and logs them all.
@@ -26,20 +30,19 @@ export type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) =>
  * @experimental
  */
 export interface CommonLogger {
+    debug: CommonLogFunction;
     log: CommonLogFunction;
     warn: CommonLogFunction;
     error: CommonLogFunction;
 }
 /**
  * SimpleLogger that does nothing (noop).
- *
- * @experimental
  */
 export declare const commonLoggerNoop: CommonLogger;
 /**
  * Creates a "child" logger that is "limited" to the specified CommonLogLevel.
  */
-export declare function commonLoggerMinLevel(logger: CommonLogger, minLevel: CommonLogLevel, opt?: MutateOptions): CommonLogger;
+export declare function createCommonLoggerAtLevel(logger?: CommonLogger, minLevel?: CommonLogLevel, opt?: MutateOptions): CommonLogger;
 /**
  * Creates a "proxy" CommonLogger that pipes log messages to all provided sub-loggers.
  */

package/dist/log/commonLogger.js

@@ -1,15 +1,16 @@
+// copy-pasted to avoid weird circular dependency
 const _noop = (..._args) => undefined;
 export const commonLogLevelNumber = {
-    log: 10,
+    debug: 10,
+    log: 20,
     warn: 20,
     error: 30,
 };
 /**
  * SimpleLogger that does nothing (noop).
- *
- * @experimental
  */
 export const commonLoggerNoop = {
+    debug: _noop,
     log: _noop,
     warn: _noop,
     error: _noop,
@@ -17,21 +18,24 @@ export const commonLoggerNoop = {
 /**
  * Creates a "child" logger that is "limited" to the specified CommonLogLevel.
  */
-export function commonLoggerMinLevel(logger, minLevel, opt = {}) {
+export function createCommonLoggerAtLevel(logger = console, minLevel = 'log', opt = {}) {
     const level = commonLogLevelNumber[minLevel];
     if (opt.mutate) {
-        if (level > commonLogLevelNumber['log']) {
-            logger.log = _noop;
-            if (level > commonLogLevelNumber['warn']) {
-                logger.warn = _noop;
-                if (level > commonLogLevelNumber['error']) {
-                    logger.error = _noop;
+        if (level > commonLogLevelNumber['debug']) {
+            logger.debug = _noop;
+            if (level > commonLogLevelNumber['log']) {
+                logger.log = _noop;
+                if (level > commonLogLevelNumber['warn']) {
+                    logger.warn = _noop;
+                    if (level > commonLogLevelNumber['error']) {
+                        logger.error = _noop;
+                    }
                 }
             }
         }
         return logger;
     }
-    if (level <= commonLogLevelNumber['log']) {
+    if (level <= commonLogLevelNumber['debug']) {
         // All levels are kept
         return logger;
     }
@@ -40,7 +44,8 @@ export function commonLoggerMinLevel(logger, minLevel, opt = {}) {
         return commonLoggerNoop;
     }
     return {
-        log: _noop, // otherwise it is "log everything" logger (same logger as input)
+        debug: _noop, // otherwise it is "log everything" logger (same logger as input)
+        log: level <= commonLogLevelNumber['log'] ? logger.log.bind(logger) : _noop,
         warn: level <= commonLogLevelNumber['warn'] ? logger.warn.bind(logger) : _noop,
         error: logger.error.bind(logger), // otherwise it's "log nothing" logger (same as noopLogger)
     };
@@ -50,6 +55,7 @@ export function commonLoggerMinLevel(logger, minLevel, opt = {}) {
  */
 export function commonLoggerPipe(loggers) {
     return {
+        debug: (...args) => loggers.forEach(logger => logger.debug(...args)),
         log: (...args) => loggers.forEach(logger => logger.log(...args)),
         warn: (...args) => loggers.forEach(logger => logger.warn(...args)),
         error: (...args) => loggers.forEach(logger => logger.error(...args)),
@@ -60,6 +66,7 @@ export function commonLoggerPipe(loggers) {
  */
 export function commonLoggerPrefix(logger, ...prefixes) {
     return {
+        debug: (...args) => logger.debug(...prefixes, ...args),
         log: (...args) => logger.log(...prefixes, ...args),
         warn: (...args) => logger.warn(...prefixes, ...args),
         error: (...args) => logger.error(...prefixes, ...args),
@@ -70,6 +77,7 @@ export function commonLoggerPrefix(logger, ...prefixes) {
  */
 export function commonLoggerCreate(fn) {
     return {
+        debug: (...args) => fn('debug', args),
         log: (...args) => fn('log', args),
         warn: (...args) => fn('warn', args),
         error: (...args) => fn('error', args),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.31.0",
+  "version": "15.32.0",
   "dependencies": {
     "tslib": "^2",
     "undici": "^7",

package/src/log/commonLogger.ts

@@ -1,22 +1,27 @@
-// copy-pasted to avoid weird circular dependency
 import type { MutateOptions } from '../array/array.util.js'
 
+// copy-pasted to avoid weird circular dependency
 const _noop = (..._args: any[]): undefined => undefined
 
 /**
  * These levels follow console.* naming,
  * so you can use console[level] safely.
  *
- * `log` is considered default level.
+ * `debug` is not enabled by default, and is useful when debugging is needed.
+ *
+ * `log` is considered default level, and is enabled by default.
  *
- * For simplicity - only these 3 levels are kept.
+ * `warn` is for warnings - things that are not super-severe to be an error, but should not happen
+ *
+ * `error` level would only log errors
  *
  * @experimental
  */
-export type CommonLogLevel = 'log' | 'warn' | 'error'
+export type CommonLogLevel = 'debug' | 'log' | 'warn' | 'error'
 
 export const commonLogLevelNumber: Record<CommonLogLevel, number> = {
-  log: 10,
+  debug: 10,
+  log: 20,
   warn: 20,
   error: 30,
 }
@@ -37,6 +42,7 @@ export type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) =>
  * @experimental
  */
 export interface CommonLogger {
+  debug: CommonLogFunction
   log: CommonLogFunction
   warn: CommonLogFunction
   error: CommonLogFunction
@@ -44,10 +50,9 @@ export interface CommonLogger {
 
 /**
  * SimpleLogger that does nothing (noop).
- *
- * @experimental
  */
 export const commonLoggerNoop: CommonLogger = {
+  debug: _noop,
   log: _noop,
   warn: _noop,
   error: _noop,
@@ -56,26 +61,29 @@ export const commonLoggerNoop: CommonLogger = {
 /**
  * Creates a "child" logger that is "limited" to the specified CommonLogLevel.
  */
-export function commonLoggerMinLevel(
-  logger: CommonLogger,
-  minLevel: CommonLogLevel,
+export function createCommonLoggerAtLevel(
+  logger: CommonLogger = console,
+  minLevel: CommonLogLevel = 'log',
   opt: MutateOptions = {},
 ): CommonLogger {
   const level = commonLogLevelNumber[minLevel]
   if (opt.mutate) {
-    if (level > commonLogLevelNumber['log']) {
-      logger.log = _noop
-      if (level > commonLogLevelNumber['warn']) {
-        logger.warn = _noop
-        if (level > commonLogLevelNumber['error']) {
-          logger.error = _noop
+    if (level > commonLogLevelNumber['debug']) {
+      logger.debug = _noop
+      if (level > commonLogLevelNumber['log']) {
+        logger.log = _noop
+        if (level > commonLogLevelNumber['warn']) {
+          logger.warn = _noop
+          if (level > commonLogLevelNumber['error']) {
+            logger.error = _noop
+          }
         }
       }
     }
     return logger
   }
 
-  if (level <= commonLogLevelNumber['log']) {
+  if (level <= commonLogLevelNumber['debug']) {
     // All levels are kept
     return logger
   }
@@ -86,7 +94,8 @@ export function commonLoggerMinLevel(
   }
 
   return {
-    log: _noop, // otherwise it is "log everything" logger (same logger as input)
+    debug: _noop, // otherwise it is "log everything" logger (same logger as input)
+    log: level <= commonLogLevelNumber['log'] ? logger.log.bind(logger) : _noop,
     warn: level <= commonLogLevelNumber['warn'] ? logger.warn.bind(logger) : _noop,
     error: logger.error.bind(logger), // otherwise it's "log nothing" logger (same as noopLogger)
   }
@@ -97,6 +106,7 @@ export function commonLoggerMinLevel(
  */
 export function commonLoggerPipe(loggers: CommonLogger[]): CommonLogger {
   return {
+    debug: (...args) => loggers.forEach(logger => logger.debug(...args)),
     log: (...args) => loggers.forEach(logger => logger.log(...args)),
     warn: (...args) => loggers.forEach(logger => logger.warn(...args)),
     error: (...args) => loggers.forEach(logger => logger.error(...args)),
@@ -108,6 +118,7 @@ export function commonLoggerPipe(loggers: CommonLogger[]): CommonLogger {
  */
 export function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): CommonLogger {
   return {
+    debug: (...args) => logger.debug(...prefixes, ...args),
     log: (...args) => logger.log(...prefixes, ...args),
     warn: (...args) => logger.warn(...prefixes, ...args),
     error: (...args) => logger.error(...prefixes, ...args),
@@ -119,6 +130,7 @@ export function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): Co
  */
 export function commonLoggerCreate(fn: CommonLogWithLevelFunction): CommonLogger {
   return {
+    debug: (...args) => fn('debug', args),
     log: (...args) => fn('log', args),
     warn: (...args) => fn('warn', args),
     error: (...args) => fn('error', args),