@naturalcycles/js-lib 15.89.0 → 15.91.0

package/dist/promise/pRetry.d.ts

@@ -67,7 +67,7 @@ export interface PRetryOptions {
      */
     logNone?: boolean;
     /**
-     * Default to `console`
+     * Default to `consoleLogger`
      */
     logger?: CommonLogger;
     /**

package/dist/promise/pRetry.js

@@ -1,5 +1,6 @@
 import { _since } from '../datetime/time.util.js';
 import { _errorDataAppend } from '../error/error.util.js';
+import { consoleLogger } from '../log/commonLogger.js';
 import { pDelay } from './pDelay.js';
 import { pTimeout } from './pTimeout.js';
 /**
@@ -12,7 +13,7 @@ export function pRetryFn(fn, opt = {}) {
     };
 }
 export async function pRetry(fn, opt = {}) {
-    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = console, name, timeout, } = opt;
+    const { maxAttempts = 4, delay: initialDelay = 1000, delayMultiplier = 2, predicate, logger = consoleLogger, name, timeout, } = opt;
     const fakeError = timeout ? new Error('TimeoutError') : undefined;
     let { logFirstAttempt = false, logRetries = true, logFailures = true, logSuccess = false } = opt;
     if (opt.logAll) {
@@ -52,7 +53,7 @@ export async function pRetry(fn, opt = {}) {
             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, attempt, maxAttempts))) {
                 // Give up

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.89.0",
+  "version": "15.91.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -14,7 +14,7 @@
     }
   },
   "devDependencies": {
-    "@naturalcycles/dev-lib": "0.0.0",
+    "@naturalcycles/dev-lib": "20.64.0",
     "@types/node": "^26",
     "@types/semver": "^7",
     "typescript": "^7",

package/src/asyncManager.ts

@@ -1,8 +1,9 @@
+import { consoleLogger } from './log/commonLogger.js'
 import type { CommonLogger } from './log/commonLogger.js'
 import type { NumberOfMilliseconds } from './types.js'
 
 class AsyncManagerImpl {
-  logger: CommonLogger = console
+  logger: CommonLogger = consoleLogger
 
   pendingOps = new Set<Promise<unknown>>()
 
@@ -58,7 +59,7 @@ class AsyncManagerImpl {
     if (this.onErrorHooks.length) {
       this.onErrorHooks.forEach(hook => hook(err))
     } else {
-      this.logger.error('AsyncManager unhandled rejection:', err)
+      this.logger.error({ msg: 'AsyncManager unhandled rejection', err })
     }
   }
 }

package/src/decorators/asyncMemo.decorator.ts

@@ -1,4 +1,5 @@
 import { _assert, _assertTypeOf } from '../error/assert.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import type { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types.js'
 import { _objectAssign, MISS } from '../types.js'
@@ -20,7 +21,7 @@ export interface AsyncMemoOptions<FN> {
   cacheKeyFn?: (args: MaybeParameters<FN>) => any
 
   /**
-   * Default to `console`
+   * Default to `consoleLogger`
    */
   logger?: CommonLogger
 }
@@ -64,7 +65,7 @@ export const _AsyncMemo =
     // After it's resolved - it's evicted from the cache and moved to the "proper" `instanceCache`
     const instancePromiseCache = new Map<AnyObject, Map<any, Promise<any>>>()
 
-    const { logger = console, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt
+    const { logger = consoleLogger, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt
 
     const keyStr = String(key)
     const methodSignature = _getTargetMethodSignature(target, keyStr)
@@ -109,7 +110,7 @@ export const _AsyncMemo =
         },
         async err => {
           // Log the cache error and proceed "as cache Miss"
-          logger.error(err)
+          logger.error({ err })
           return await onMiss()
         },
       )
@@ -130,7 +131,7 @@ export const _AsyncMemo =
             try {
               await cache!.set(cacheKey, value)
             } catch (err) {
-              logger.error(err) // log and ignore the error
+              logger.error({ err }) // log and ignore the error
             } finally {
               // Clear the "in-flight" promise cache entry, as we now have a "permanent" cache entry
               promiseCache!.delete(cacheKey)

package/src/decorators/logMethod.decorator.ts

@@ -1,5 +1,6 @@
 import { _ms } from '../datetime/time.util.js'
 import { _assert } from '../error/assert.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import { SimpleMovingAverage } from '../math/sma.js'
 import { _stringify } from '../string/stringify.js'
@@ -53,7 +54,7 @@ export interface LogMethodOptions {
   logResultFn?: LogResultFn
 
   /**
-   * Defaults to `console`
+   * Defaults to `consoleLogger`
    */
   logger?: CommonLogger
 }
@@ -84,7 +85,7 @@ export function _LogMethod(opt: LogMethodOptions = {}): MethodDecorator {
       logStart,
       logResult,
       logResultLength = true,
-      logger = console,
+      logger = consoleLogger,
     } = opt
     let { logResultFn } = opt
     if (!logResultFn) {
@@ -156,10 +157,14 @@ function logFinished(
   }
 
   if (err !== undefined) {
-    t.push('ERROR:', err)
+    t.push('ERROR:')
   } else if (logResultFn) {
     t.push(...logResultFn(res))
   }
 
-  logger.log(...t.filter(Boolean))
+  const msg = t
+    .filter(Boolean)
+    .map(part => _stringify(part))
+    .join(' ')
+  logger.log(err === undefined ? msg : { msg, err })
 }

package/src/decorators/memo.decorator.ts

@@ -1,4 +1,5 @@
 import { _assert, _assertTypeOf } from '../error/assert.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import type { AnyFunction, AnyObject, MaybeParameters } from '../types.js'
 import { _objectAssign } from '../types.js'
@@ -21,7 +22,7 @@ export interface MemoOptions<FN> {
   cacheKeyFn?: (args: MaybeParameters<FN>) => any
 
   /**
-   * Default to `console`
+   * Default to `consoleLogger`
    */
   logger?: CommonLogger
 }
@@ -78,7 +79,7 @@ export const _Memo =
     const instanceCache = new Map<AnyObject, MemoCache>()
 
     const {
-      logger = console,
+      logger = consoleLogger,
       cacheFactory = () => new MapMemoCache(),
       cacheKeyFn = jsonMemoSerializer,
     } = opt
@@ -107,7 +108,7 @@ export const _Memo =
       try {
         cache.set(cacheKey, value)
       } catch (err) {
-        logger.error(err)
+        logger.error({ err })
       }
 
       return value

package/src/decorators/memoSimple.decorator.ts

@@ -11,6 +11,7 @@ Otherwise resorts to JSON.stringify.
 Benchmark shows similar perf for ObjectCache and MapCache.
  */
 
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import { _getTargetMethodSignature } from './decorator.util.js'
 import type { MemoCache } from './memo.util.js'
@@ -55,7 +56,7 @@ export const memoSimple =
    */
     const cache: MemoCache = new MapMemoCache()
 
-    const { logger = console } = opt
+    const { logger = consoleLogger } = opt
     const keyStr = String(key)
     const methodSignature = _getTargetMethodSignature(target, keyStr)
 

package/src/decorators/memoized.ts

@@ -1,3 +1,4 @@
+import { consoleLogger } from '../log/commonLogger.js'
 import type { AnyFunction, MaybeParameters } from '../types.js'
 import type { MemoOptions } from './memo.decorator.js'
 import type { MemoCache } from './memo.util.js'
@@ -17,7 +18,7 @@ export function _memoized<FN extends AnyFunction>(
   opt: MemoOptions<FN> = {},
 ): FN & MemoizedFunction {
   const {
-    logger = console,
+    logger = consoleLogger,
     cacheFactory = () => new MapMemoCache(),
     cacheKeyFn = jsonMemoSerializer,
   } = opt
@@ -37,7 +38,7 @@ export function _memoized<FN extends AnyFunction>(
     try {
       cache.set(cacheKey, value)
     } catch (err) {
-      logger.error(err)
+      logger.error({ err })
     }
 
     return value

package/src/decorators/memoizedAsync.ts

@@ -1,3 +1,4 @@
+import { consoleLogger } from '../log/commonLogger.js'
 import type { AnyAsyncFunction, MaybeParameters } from '../types.js'
 import { MISS } from '../types.js'
 import type { AsyncMemoOptions } from './asyncMemo.decorator.js'
@@ -12,7 +13,7 @@ export function _memoizedAsync<FN extends AnyAsyncFunction>(
   fn: FN,
   opt: AsyncMemoOptions<FN>,
 ): FN & MemoizedAsyncFunction {
-  const { logger = console, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt
+  const { logger = consoleLogger, cacheFactory, cacheKeyFn = jsonMemoSerializer } = opt
 
   const cache = cacheFactory()
 
@@ -24,7 +25,7 @@ export function _memoizedAsync<FN extends AnyAsyncFunction>(
     try {
       value = await cache.get(cacheKey)
     } catch (err) {
-      logger.error(err)
+      logger.error({ err })
     }
 
     if (value !== MISS) {
@@ -37,7 +38,7 @@ export function _memoizedAsync<FN extends AnyAsyncFunction>(
       try {
         await cache.set(cacheKey, value)
       } catch (err) {
-        logger.error(err)
+        logger.error({ err })
       }
     })()
 

package/src/error/tryCatch.ts

@@ -1,4 +1,5 @@
 import { _since } from '../datetime/time.util.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import type { AnyFunction, UnixTimestampMillis } from '../types.js'
 import { _anyToError } from './error.util.js'
@@ -21,7 +22,7 @@ export interface TryCatchOptions {
   logError?: boolean
 
   /**
-   * Default to `console`
+   * Default to `consoleLogger`
    */
   logger?: CommonLogger
 }
@@ -35,7 +36,7 @@ export interface TryCatchOptions {
  * @experimental
  */
 export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {}): T {
-  const { onError, logError = true, logSuccess = false, logger = console } = opt
+  const { onError, logError = true, logSuccess = false, logger = consoleLogger } = opt
 
   const fname = fn.name || 'anonymous'
 
@@ -52,7 +53,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
       return r
     } catch (err) {
       if (logError) {
-        logger.warn(`tryCatch.${fname} error in ${_since(started)}:`, err)
+        logger.warn({ msg: `tryCatch.${fname} error in ${_since(started)}`, err })
       }
 
       if (onError) {

package/src/http/fetcher.model.ts

@@ -162,7 +162,7 @@ export interface FetcherCfg {
   logWithSearchParams?: boolean
 
   /**
-   * Defaults to `console`.
+   * Defaults to `consoleLogger`.
    */
   logger?: CommonLogger
 

package/src/http/fetcher.ts

@@ -16,6 +16,7 @@ import {
   HttpRequestError,
   UnexpectedPassError,
 } from '../error/error.util.js'
+import { consoleLogger } from '../log/commonLogger.js'
 import { _clamp } from '../number/number.util.js'
 import {
   _filterFalsyValues,
@@ -30,7 +31,6 @@ import { pDelaySignal } from '../promise/pDelay.js'
 import { pTimeout } from '../promise/pTimeout.js'
 import { _toUrlOrNull } from '../string/index.js'
 import { _jsonParse, _jsonParseIfPossible } from '../string/json.util.js'
-import { _stringify } from '../string/stringify.js'
 import type {
   AnyObject,
   ErrorDataTuple,
@@ -416,7 +416,7 @@ export class Fetcher {
             .join(' '),
         )
         if (req.logRequestBody && req.init.body) {
-          logger.log(req.init.body) // todo: check if we can _inspect it
+          logger.log({ body: req.init.body }) // todo: check if we can _inspect it
         }
       }
 
@@ -584,7 +584,7 @@ export class Fetcher {
       )
 
       if (req.logResponseBody && res.body !== undefined) {
-        logger.log(res.body)
+        logger.log({ body: res.body })
       }
     }
   }
@@ -688,8 +688,8 @@ export class Fetcher {
     // lastError = retryStatus.retryStopped
     // We need to log the response "anyway" if logResponse is true
     if (res.err && (!retryStatus.retryStopped || res.req.logResponse)) {
-      this.cfg.logger.error(
-        [
+      this.cfg.logger.error({
+        msg: [
           ' <<',
           res.fetchResponse?.status || 0,
           res.signature,
@@ -699,10 +699,9 @@ export class Fetcher {
           _since(res.req.started),
         ]
           .filter(Boolean)
-          .join(' ') + '\n',
-        // We're stringifying the error here, otherwise Sentry shows it as [object Object]
-        _stringify(res.err.cause || res.err),
-      )
+          .join(' '),
+        err: res.err.cause || res.err,
+      })
     }
 
     if (retryStatus.retryStopped) return
@@ -847,7 +846,7 @@ export class Fetcher {
   }
 
   private normalizeCfg(cfg: FetcherCfg & FetcherOptions): FetcherNormalizedCfg {
-    const { debug = false, logger = console } = cfg
+    const { debug = false, logger = consoleLogger } = cfg
 
     if (cfg.baseUrl?.endsWith('/')) {
       logger.warn(`Fetcher: baseUrl should not end with slash: ${cfg.baseUrl}`)

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,141 +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
-
-export interface CommonLoggerWithContext extends CommonLogger {
-  child: (context: AnyObject) => 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: AnyObject): CommonLoggerWithContext
-export function commonLoggerCreate(sink: CommonLogSink, context?: AnyObject): 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),
-    }
+    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))),
   }
-
-  const ctx: AnyObject = { ...context }
-
-  const logger: CommonLoggerWithContext = {
-    debug: (...args) => fn('debug', [toLogEntry(ctx, args)]),
-    log: (...args) => fn('log', [toLogEntry(ctx, args)]),
-    warn: (...args) => fn('warn', [toLogEntry(ctx, args)]),
-    error: (...args) => fn('error', [toLogEntry(ctx, args)]),
-    child: c => commonLoggerCreate(fn, { ...ctx, ...c }),
-  }
-  return logger
-}
-
-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