@naturalcycles/js-lib 15.88.0 → 15.90.0

package/dist/is.util.d.ts

@@ -1,4 +1,4 @@
-import type { AnyObject, FalsyValue, NullishValue, Primitive } from './types.js';
+import type { AnyObject, FalsyValue, NullishValue, PlainObject, Primitive } from './types.js';
 type Nullish<T> = T extends NullishValue ? T : never;
 type Truthy<T> = T extends FalsyValue ? never : T;
 type Falsy<T> = T extends FalsyValue ? T : never;
@@ -25,6 +25,10 @@ export declare const _isFalsy: <T>(v: T) => v is Falsy<T>;
  * Currently treats RegEx as Object too, e.g _isObject(/some/) === true
  */
 export declare function _isObject(obj: any): obj is AnyObject;
+/**
+ * Returns true if item is an object literal: not an Array, Error, RegExp or class instance.
+ */
+export declare function _isPlainObject(v: any): v is PlainObject;
 export declare function _isPrimitive(v: any): v is Primitive;
 export declare function _isEmptyObject(obj: AnyObject): boolean;
 export declare function _isNotEmptyObject(obj: AnyObject): boolean;

package/dist/is.util.js

@@ -23,6 +23,15 @@ export const _isFalsy = (v) => !v;
 export function _isObject(obj) {
     return (typeof obj === 'object' && obj !== null && !Array.isArray(obj)) || false;
 }
+/**
+ * Returns true if item is an object literal: not an Array, Error, RegExp or class instance.
+ */
+export function _isPlainObject(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
 export function _isPrimitive(v) {
     return (v === null ||
         v === undefined ||

package/dist/log/commonLogger.d.ts

@@ -1,4 +1,4 @@
-import type { MutateOptions } from '../types.js';
+import type { AnyObject, MutateOptions } from '../types.js';
 /**
  * These levels follow console.* naming,
  * so you can use console[level] safely.
@@ -51,7 +51,21 @@ export declare function commonLoggerPipe(loggers: CommonLogger[]): CommonLogger;
  * Creates a "child" CommonLogger with prefix (one or multiple).
  */
 export declare function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): CommonLogger;
+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 declare function commonLoggerCreate(fn: CommonLogWithLevelFunction): CommonLogger;
+export declare function commonLoggerCreate(sink: CommonLogSink): CommonLogger;
+export declare function commonLoggerCreate(sink: CommonLogSink, context: CommonLogContext): CommonLoggerWithContext;

package/dist/log/commonLogger.js

@@ -1,3 +1,4 @@
+import { _isPlainObject } from '../is.util.js';
 // copy-pasted to avoid weird circular dependency
 const _noop = (..._args) => undefined;
 export const commonLogLevelNumber = {
@@ -72,14 +73,55 @@ export function commonLoggerPrefix(logger, ...prefixes) {
         error: (...args) => logger.error(...prefixes, ...args),
     };
 }
-/**
- * Creates a CommonLogger from a single function that takes `level` and `args`.
- */
-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),
+export function commonLoggerCreate(sink, context) {
+    const fn = 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 = {
+        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() }));
+        },
     };
+    return logger;
+}
+function contextGetter(context) {
+    // AnyObject also admits functions, so typeof does not narrow the union
+    if (typeof context === 'function')
+        return context;
+    const copy = { ...context };
+    return () => copy;
+}
+function toLogEntry(context, args) {
+    const entry = { ...context };
+    let err;
+    let msg;
+    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/dist/types.d.ts

@@ -25,6 +25,10 @@ export interface StringMap<T = string> {
  * Because `object` type is not safe/recommended to be used (e.g discouraged by eslint-typescript due to: https://github.com/microsoft/TypeScript/issues/21732)
  */
 export type AnyObject = Record<string, any>;
+/**
+ * Object literal, with a prototype of `Object.prototype` or `null`. What `_isPlainObject` narrows to.
+ */
+export type PlainObject = Branded<AnyObject, 'PlainObject'>;
 export type AnyEnum = NumberEnum;
 export type NumberEnum = Record<string, number | string>;
 export type StringEnum = Record<string, string>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.88.0",
+  "version": "15.90.0",
   "dependencies": {
     "tslib": "^2"
   },

package/src/is.util.ts

@@ -1,4 +1,4 @@
-import type { AnyObject, FalsyValue, NullishValue, Primitive } from './types.js'
+import type { AnyObject, FalsyValue, NullishValue, PlainObject, Primitive } from './types.js'
 
 type Nullish<T> = T extends NullishValue ? T : never
 type Truthy<T> = T extends FalsyValue ? never : T
@@ -32,6 +32,15 @@ export function _isObject(obj: any): obj is AnyObject {
   return (typeof obj === 'object' && obj !== null && !Array.isArray(obj)) || false
 }
 
+/**
+ * Returns true if item is an object literal: not an Array, Error, RegExp or class instance.
+ */
+export function _isPlainObject(v: any): v is PlainObject {
+  if (typeof v !== 'object' || v === null) return false
+  const proto = Object.getPrototypeOf(v)
+  return proto === Object.prototype || proto === null
+}
+
 export function _isPrimitive(v: any): v is Primitive {
   return (
     v === null ||

package/src/log/commonLogger.ts

@@ -1,4 +1,5 @@
-import type { MutateOptions } from '../types.js'
+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
@@ -125,14 +126,82 @@ export function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): Co
   }
 }
 
+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(fn: CommonLogWithLevelFunction): CommonLogger {
-  return {
-    debug: (...args) => fn('debug', args),
-    log: (...args) => fn('log', args),
-    warn: (...args) => fn('warn', args),
-    error: (...args) => fn('error', args),
+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() }))
+    },
+  }
+  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/types.ts

@@ -30,6 +30,11 @@ export interface StringMap<T = string> {
  */
 export type AnyObject = Record<string, any>
 
+/**
+ * Object literal, with a prototype of `Object.prototype` or `null`. What `_isPlainObject` narrows to.
+ */
+export type PlainObject = Branded<AnyObject, 'PlainObject'>
+
 export type AnyEnum = NumberEnum
 export type NumberEnum = Record<string, number | string>
 export type StringEnum = Record<string, string>