@naturalcycles/js-lib 15.90.0 → 15.91.0

package/src/log/commonLogger.ts

@@ -1,6 +1,3 @@
-import { _isPlainObject } from '../is.util.js'
-import type { AnyObject, MutateOptions } from '../types.js'
-
 // copy-pasted to avoid weird circular dependency
 const _noop = (..._args: any[]): undefined => undefined
 
@@ -23,23 +20,37 @@ export type CommonLogLevel = 'debug' | 'log' | 'warn' | 'error'
 export const commonLogLevelNumber: Record<CommonLogLevel, number> = {
   debug: 10,
   log: 20,
-  warn: 20,
-  error: 30,
+  warn: 30,
+  error: 40,
 }
 
 /**
- * Function that takes any number of arguments and logs them all.
- * It is expected that logged arguments are separated by "space", like console.log does.
- *
- * @experimental
+ * Structured log data: a message, an error, and any other fields.
  */
-export type CommonLogFunction = (...args: any[]) => void
-export type CommonLogWithLevelFunction = (level: CommonLogLevel, args: any[]) => void
+export interface LogData {
+  msg?: string
+  err?: unknown
+  [field: string]: unknown
+}
+
+/**
+ * What a log call accepts: a string is `{ msg }`, an Error is `{ err }`.
+ * A non-Error error value (e.g an `unknown` from a catch) is passed as `{ err }`.
+ */
+export type LogInput = string | Error | LogData
+
+/**
+ * What a sink receives: the logger's context, the log data and the level.
+ */
+export interface LogEntry extends LogData {
+  level: CommonLogLevel
+}
+
+export type LogSink = (entry: LogEntry) => void
+
+export type CommonLogFunction = (input: LogInput) => void
 
 /**
- * Interface is inspired/compatible with `console.*`
- * So, `console` is a valid CommonLogger implementation as-is.
- *
  * @experimental
  */
 export interface CommonLogger {
@@ -47,161 +58,90 @@ export interface CommonLogger {
   log: CommonLogFunction
   warn: CommonLogFunction
   error: CommonLogFunction
+  /**
+   * Creates a logger that adds `context` to every entry.
+   */
+  child: (context: LogData) => CommonLogger
 }
 
 /**
- * SimpleLogger that does nothing (noop).
+ * Creates a CommonLogger that writes every entry to `sink`.
+ * `context` is called on every log call, so it can return values that change
+ * after the logger is created (e.g a request context whose user is resolved later).
+ */
+export function commonLoggerCreate(sink: LogSink, context?: () => LogData): CommonLogger {
+  const emit = (level: CommonLogLevel, input: LogInput): void =>
+    sink({ ...context?.(), ...toLogData(input), level })
+
+  return {
+    debug: input => emit('debug', input),
+    log: input => emit('log', input),
+    warn: input => emit('warn', input),
+    error: input => emit('error', input),
+    child: childContext => commonLoggerCreate(sink, () => ({ ...context?.(), ...childContext })),
+  }
+}
+
+function toLogData(input: LogInput): LogData {
+  if (typeof input === 'string') return { msg: input }
+  if (input instanceof Error) return { err: input }
+  return input
+}
+
+/**
+ * CommonLogger that logs to `console`.
+ */
+export const consoleLogger: CommonLogger = commonLoggerCreate(({ level, msg, err, ...fields }) => {
+  const args: unknown[] = []
+  if (msg !== undefined) args.push(msg)
+  if (err !== undefined) args.push(err)
+  if (Object.keys(fields).length) args.push(fields)
+  console[level](...args)
+})
+
+/**
+ * CommonLogger that does nothing (noop).
  */
 export const commonLoggerNoop: CommonLogger = {
   debug: _noop,
   log: _noop,
   warn: _noop,
   error: _noop,
+  child: () => commonLoggerNoop,
 }
 
 /**
- * Creates a "child" logger that is "limited" to the specified CommonLogLevel.
+ * Creates a CommonLogger that is "limited" to the specified CommonLogLevel.
  */
 export function createCommonLoggerAtLevel(
-  logger: CommonLogger = console,
+  logger: CommonLogger = consoleLogger,
   minLevel: CommonLogLevel = 'log',
-  opt: MutateOptions = {},
 ): CommonLogger {
   const level = commonLogLevelNumber[minLevel]
-  if (opt.mutate) {
-    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['debug']) {
     // All levels are kept
     return logger
   }
 
-  if (level > commonLogLevelNumber['error']) {
-    // "Log nothing" logger
-    return commonLoggerNoop
-  }
-
   return {
     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)
+    log: level <= commonLogLevelNumber['log'] ? input => logger.log(input) : _noop,
+    warn: level <= commonLogLevelNumber['warn'] ? input => logger.warn(input) : _noop,
+    error: input => logger.error(input),
+    child: context => createCommonLoggerAtLevel(logger.child(context), minLevel),
   }
 }
 
 /**
- * Creates a "proxy" CommonLogger that pipes log messages to all provided sub-loggers.
+ * Creates a "proxy" CommonLogger that pipes log entries to all provided sub-loggers.
  */
 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)),
-  }
-}
-
-/**
- * Creates a "child" CommonLogger with prefix (one or multiple).
- */
-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),
-  }
-}
-
-export type CommonLogSink = CommonLogger | CommonLogWithLevelFunction
-
-/**
- * A plain object is copied once, at creation.
- * A function is called on every log call, for context that changes after the logger is created
- * (e.g a request context whose user is resolved later).
- */
-export type CommonLogContext = AnyObject | (() => AnyObject)
-
-export interface CommonLoggerWithContext extends CommonLogger {
-  child: (context: CommonLogContext) => CommonLoggerWithContext
-}
-
-/**
- * Creates a CommonLogger from a single function that takes `level` and `args`.
- *
- * With a context, every call emits one object: plain-object args merged in, first Error as `err`,
- * the rest joined into `msg`.
- */
-export function commonLoggerCreate(sink: CommonLogSink): CommonLogger
-export function commonLoggerCreate(
-  sink: CommonLogSink,
-  context: CommonLogContext,
-): CommonLoggerWithContext
-export function commonLoggerCreate(sink: CommonLogSink, context?: CommonLogContext): CommonLogger {
-  const fn: CommonLogWithLevelFunction =
-    typeof sink === 'function' ? sink : (level, args) => sink[level](...args)
-
-  if (!context) {
-    return {
-      debug: (...args) => fn('debug', args),
-      log: (...args) => fn('log', args),
-      warn: (...args) => fn('warn', args),
-      error: (...args) => fn('error', args),
-    }
-  }
-
-  const getContext = contextGetter(context)
-
-  const logger: CommonLoggerWithContext = {
-    debug: (...args) => fn('debug', [toLogEntry(getContext(), args)]),
-    log: (...args) => fn('log', [toLogEntry(getContext(), args)]),
-    warn: (...args) => fn('warn', [toLogEntry(getContext(), args)]),
-    error: (...args) => fn('error', [toLogEntry(getContext(), args)]),
-    child: c => {
-      const getChild = contextGetter(c)
-      return commonLoggerCreate(fn, () => ({ ...getContext(), ...getChild() }))
-    },
+    debug: input => loggers.forEach(logger => logger.debug(input)),
+    log: input => loggers.forEach(logger => logger.log(input)),
+    warn: input => loggers.forEach(logger => logger.warn(input)),
+    error: input => loggers.forEach(logger => logger.error(input)),
+    child: context => commonLoggerPipe(loggers.map(logger => logger.child(context))),
   }
-  return logger
-}
-
-function contextGetter(context: CommonLogContext): () => AnyObject {
-  // AnyObject also admits functions, so typeof does not narrow the union
-  if (typeof context === 'function') return context as () => AnyObject
-  const copy = { ...context }
-  return () => copy
-}
-
-function toLogEntry(context: AnyObject, args: any[]): AnyObject {
-  const entry: AnyObject = { ...context }
-  let err: Error | undefined
-  let msg: string | undefined
-
-  for (const arg of args) {
-    if (_isPlainObject(arg)) {
-      Object.assign(entry, arg)
-    } else if (!err && arg instanceof Error) {
-      err = arg
-    } else {
-      const s = String(arg)
-      msg = msg === undefined ? s : `${msg} ${s}`
-    }
-  }
-
-  if (err) entry['err'] = err
-  if (msg !== undefined) entry['msg'] = msg
-  return entry
 }

package/src/promise/pGradualQueue.ts

@@ -26,7 +26,7 @@ export interface PGradualQueueCfg {
   errorMode?: ErrorMode
 
   /**
-   * Default to `console`
+   * Default to `consoleLogger`
    */
   logger?: CommonLogger
 

package/src/promise/pMap.ts

@@ -1,4 +1,5 @@
 import { ErrorMode } from '../error/errorMode.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import { END, SKIP } from '../types.js'
 import type { AbortableAsyncMapper } from '../types.js'
@@ -17,12 +18,12 @@ export interface PMapOptions {
    * When set to THROW_AGGREGATED, instead of stopping when a promise rejects, it will wait for all the promises to settle and then reject with an Aggregated error.
    *
    * When set to SUPPRESS - will ignore errors and return results from successful operations.
-   * When in SUPPRESS - errors are still logged via the `logger` (which defaults to console).
+   * When in SUPPRESS - errors are still logged via the `logger` (which defaults to consoleLogger).
    */
   errorMode?: ErrorMode
 
   /**
-   * Default to `console`.
+   * Default to `consoleLogger`.
    * Pass `null` to skip logging completely.
    */
   logger?: CommonLogger | null
@@ -71,7 +72,11 @@ export async function pMap<IN, OUT>(
   const itemsLength = items.length
   if (itemsLength === 0) return [] // short circuit
 
-  const { concurrency = Infinity, errorMode = ErrorMode.THROW_IMMEDIATELY, logger = console } = opt
+  const {
+    concurrency = Infinity,
+    errorMode = ErrorMode.THROW_IMMEDIATELY,
+    logger = consoleLogger,
+  } = opt
 
   // Special cases that are able to preserve async stack traces
   // Special case: serial execution
@@ -181,7 +186,7 @@ async function pMap1<IN, OUT>(
         errors.push(err as Error)
       } else {
         // otherwise, suppress (but still log via logger)
-        logger?.error(err)
+        logger?.error({ err })
       }
     }
   }
@@ -219,7 +224,7 @@ async function pMapAll<IN, OUT>(
       errors.push(r.reason)
     } else {
       // otherwise, suppress (but still log via logger)
-      logger?.error(r.reason)
+      logger?.error({ err: r.reason })
     }
   }
 

package/src/promise/pQueue.ts

@@ -18,7 +18,7 @@ export interface PQueueCfg {
   errorMode?: ErrorMode
 
   /**
-   * Default to `console`
+   * Default to `consoleLogger`
    */
   logger?: CommonLogger
 

package/src/promise/pRetry.ts

@@ -1,6 +1,7 @@
 import { _since } from '../datetime/time.util.js'
 import type { ErrorData } from '../error/error.model.js'
 import { _errorDataAppend } from '../error/error.util.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import type { AnyAsyncFunction, UnixTimestampMillis } from '../types.js'
 import { pDelay } from './pDelay.js'
@@ -84,7 +85,7 @@ export interface PRetryOptions {
   logNone?: boolean
 
   /**
-   * Default to `console`
+   * Default to `consoleLogger`
    */
   logger?: CommonLogger
 
@@ -113,7 +114,7 @@ export async function pRetry<T>(
     delay: initialDelay = 1000,
     delayMultiplier = 2,
     predicate,
-    logger = console,
+    logger = consoleLogger,
     name,
     timeout,
   } = opt
@@ -164,7 +165,7 @@ export async function pRetry<T>(
       if (logFailures) {
         // Logger at warn (not error) level, because it's not a fatal error, but a retriable one
         // Fatal one is not logged either, because it's been thrown instead
-        logger.warn(`${fname} attempt #${attempt} error in ${_since(started)}:`, err)
+        logger.warn({ msg: `${fname} attempt #${attempt} error in ${_since(started)}`, err })
       }
 
       if (attempt >= maxAttempts || (predicate && !predicate(err as Error, attempt, maxAttempts))) {