@naturalcycles/js-lib 15.87.0 → 15.89.0

package/dist/enum.util.d.ts

@@ -1,4 +1,32 @@
-import type { AnyObject, NumberEnum, StringEnum } from './types.js';
+import type { AnyObject, Enum, NumberEnum, StringEnum } from './types.js';
+/**
+ * Creates a runtime Enum object. A replacement for a native TypeScript enum,
+ * which is not supported by type-stripping runtimes (e.g `node --experimental-strip-types`).
+ *
+ * Declare the type with the same name as the const, to mimic how native enums merge value and type.
+ *
+ * @example
+ * export const Color = _enum({ RED: 'red', GREEN: 'green' })
+ * export type Color = typeof Color.type // 'red' | 'green'
+ *
+ * Color.RED // 'red'
+ * Color.keys // ['RED', 'GREEN']
+ * Color.values // ['red', 'green']
+ * Color.entries // [['RED', 'red'], ['GREEN', 'green']]
+ * Color.is(x) // type-guard for 'red' | 'green'
+ * Color.keyOf('red') // 'RED'
+ * JSON.stringify(Color) // '{"RED":"red","GREEN":"green"}', no reverse-mapping, no helper leakage
+ *
+ * The result doesn't satisfy `StringEnum`/`NumberEnum`, so the `_stringEnum*`/`_numberEnum*`
+ * functions don't accept it. Use the helpers on the returned object instead.
+ *
+ * Nothing is frozen, immutability is expressed through `readonly` types only.
+ *
+ * Throws if the input contains a key that collides with one of the helper names.
+ *
+ * @experimental
+ */
+export declare function _enum<const T extends Record<string, string> | Record<string, number>>(obj: T): EnumObject<T>;
 export declare function getEnumType(en: AnyObject): 'StringEnum' | 'NumberEnum' | undefined;
 /**
  * Returns all String keys of a number-enum.
@@ -91,3 +119,51 @@ export declare function _numberEnumKeyOrUndefined<T extends NumberEnum>(en: T, v
 export declare function _numberEnumKey<T extends NumberEnum>(en: T, v: T[keyof T] | undefined | null): keyof T;
 export declare function _stringEnumKeyOrUndefined<T extends StringEnum>(en: T, v: string | undefined | null): keyof T | undefined;
 export declare function _stringEnumKey<T extends StringEnum>(en: T, v: string | undefined | null): keyof T;
+/**
+ * @experimental
+ */
+export type EnumObject<T> = Readonly<T> & EnumHelpers<T>;
+/**
+ * Helpers that `_enum()` hangs off the returned object.
+ * Defined as non-enumerable, so that `Object.keys/values/entries`, `JSON.stringify`
+ * and `for..in` still only see the actual Enum members.
+ *
+ * `keys`/`values`/`entries` are precomputed, and keep the literal types
+ * that the `Object.*` equivalents would widen to `string`.
+ *
+ * @experimental
+ */
+interface EnumHelpers<T> {
+    /**
+     * Type-only carrier for the union of all values, so that the Enum's type can be declared
+     * without a second import: `export type Color = typeof Color.type`.
+     *
+     * It has no runtime counterpart, reading it as a value returns undefined.
+     */
+    readonly type: Enum<T>;
+    readonly keys: readonly (keyof T)[];
+    readonly values: readonly Enum<T>[];
+    readonly entries: EnumEntries<T>;
+    /**
+     * Type-guard. O(1), backed by a Map.
+     */
+    readonly is: (v: unknown) => v is Enum<T>;
+    /**
+     * Reverse lookup, the counterpart of `Color.RED`. O(1). Throws if the value is not a member.
+     */
+    readonly keyOf: (v: Enum<T>) => keyof T;
+    /**
+     * Like `keyOf`, but takes untrusted input and returns undefined instead of throwing.
+     */
+    readonly keyOfOrUndefined: (v: unknown) => keyof T | undefined;
+}
+/**
+ * The mapped type (rather than `readonly [keyof T, Enum<T>][]`) keeps each key paired
+ * with its own value, instead of allowing any key/value combination.
+ *
+ * @experimental
+ */
+type EnumEntries<T> = readonly {
+    [K in keyof T]: readonly [k: K, v: T[K]];
+}[keyof T][];
+export {};

package/dist/enum.util.js

@@ -1,3 +1,68 @@
+/**
+ * Creates a runtime Enum object. A replacement for a native TypeScript enum,
+ * which is not supported by type-stripping runtimes (e.g `node --experimental-strip-types`).
+ *
+ * Declare the type with the same name as the const, to mimic how native enums merge value and type.
+ *
+ * @example
+ * export const Color = _enum({ RED: 'red', GREEN: 'green' })
+ * export type Color = typeof Color.type // 'red' | 'green'
+ *
+ * Color.RED // 'red'
+ * Color.keys // ['RED', 'GREEN']
+ * Color.values // ['red', 'green']
+ * Color.entries // [['RED', 'red'], ['GREEN', 'green']]
+ * Color.is(x) // type-guard for 'red' | 'green'
+ * Color.keyOf('red') // 'RED'
+ * JSON.stringify(Color) // '{"RED":"red","GREEN":"green"}', no reverse-mapping, no helper leakage
+ *
+ * The result doesn't satisfy `StringEnum`/`NumberEnum`, so the `_stringEnum*`/`_numberEnum*`
+ * functions don't accept it. Use the helpers on the returned object instead.
+ *
+ * Nothing is frozen, immutability is expressed through `readonly` types only.
+ *
+ * Throws if the input contains a key that collides with one of the helper names.
+ *
+ * @experimental
+ */
+export function _enum(obj) {
+    if (RESERVED_KEYS.some(k => Object.hasOwn(obj, k))) {
+        throw new Error(`_enum keys must not be named ${RESERVED_KEYS.join(', ')}, as they collide with the helpers`);
+    }
+    const rawEntries = Object.entries(obj);
+    const keys = Object.keys(obj);
+    const values = Object.values(obj);
+    const entries = rawEntries;
+    // Backs both `is` and `keyOf`. On duplicate values the last key wins, like a native number enum.
+    const keyByValue = new Map(rawEntries.map(([k, v]) => [v, k]));
+    return Object.defineProperties({ ...obj }, {
+        keys: { value: keys },
+        values: { value: values },
+        entries: { value: entries },
+        is: { value: (v) => keyByValue.has(v) },
+        keyOf: {
+            value: (v) => {
+                const key = keyByValue.get(v);
+                if (key === undefined)
+                    throw new Error(`_enum keyOf not found for: ${String(v)}`);
+                return key;
+            },
+        },
+        keyOfOrUndefined: { value: (v) => keyByValue.get(v) },
+    });
+}
+/**
+ * Keys that `_enum()` reserves for its helpers, and therefore rejects as Enum member names.
+ */
+const RESERVED_KEYS = [
+    'type',
+    'keys',
+    'values',
+    'entries',
+    'is',
+    'keyOf',
+    'keyOfOrUndefined',
+];
 export function getEnumType(en) {
     /*
      * enum Foo { A = 1, B = 2 }

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,15 @@ 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;
+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 declare function commonLoggerCreate(fn: CommonLogWithLevelFunction): CommonLogger;
+export declare function commonLoggerCreate(sink: CommonLogSink): CommonLogger;
+export declare function commonLoggerCreate(sink: CommonLogSink, context: AnyObject): 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,45 @@ 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 ctx = { ...context };
+    const logger = {
+        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, 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,9 +25,27 @@ 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>;
+/**
+ * Union of all values of an Enum-like object: both native TypeScript enums and `_enum()` objects.
+ *
+ * For an `_enum()` object prefer `typeof Color.type`, which needs no import.
+ *
+ * @example
+ * enum Color { RED = 'red', GREEN = 'green' }
+ * type ColorValue = Enum<typeof Color> // 'red' | 'green'
+ *
+ * @experimental
+ */
+export type Enum<T> = T extends {
+    values: readonly (infer V)[];
+} ? V : T[keyof T];
 export type CreatedUpdated = {
     created: UnixTimestamp;
     updated: UnixTimestamp;

package/package.json

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

package/src/enum.util.ts

@@ -1,4 +1,79 @@
-import type { AnyObject, NumberEnum, StringEnum } from './types.js'
+import type { AnyObject, Enum, NumberEnum, StringEnum } from './types.js'
+
+/**
+ * Creates a runtime Enum object. A replacement for a native TypeScript enum,
+ * which is not supported by type-stripping runtimes (e.g `node --experimental-strip-types`).
+ *
+ * Declare the type with the same name as the const, to mimic how native enums merge value and type.
+ *
+ * @example
+ * export const Color = _enum({ RED: 'red', GREEN: 'green' })
+ * export type Color = typeof Color.type // 'red' | 'green'
+ *
+ * Color.RED // 'red'
+ * Color.keys // ['RED', 'GREEN']
+ * Color.values // ['red', 'green']
+ * Color.entries // [['RED', 'red'], ['GREEN', 'green']]
+ * Color.is(x) // type-guard for 'red' | 'green'
+ * Color.keyOf('red') // 'RED'
+ * JSON.stringify(Color) // '{"RED":"red","GREEN":"green"}', no reverse-mapping, no helper leakage
+ *
+ * The result doesn't satisfy `StringEnum`/`NumberEnum`, so the `_stringEnum*`/`_numberEnum*`
+ * functions don't accept it. Use the helpers on the returned object instead.
+ *
+ * Nothing is frozen, immutability is expressed through `readonly` types only.
+ *
+ * Throws if the input contains a key that collides with one of the helper names.
+ *
+ * @experimental
+ */
+export function _enum<const T extends Record<string, string> | Record<string, number>>(
+  obj: T,
+): EnumObject<T> {
+  if (RESERVED_KEYS.some(k => Object.hasOwn(obj, k))) {
+    throw new Error(
+      `_enum keys must not be named ${RESERVED_KEYS.join(', ')}, as they collide with the helpers`,
+    )
+  }
+
+  const rawEntries = Object.entries(obj)
+  const keys = Object.keys(obj) as (keyof T)[]
+  const values = Object.values(obj) as Enum<T>[]
+  const entries = rawEntries as unknown as EnumEntries<T>
+  // Backs both `is` and `keyOf`. On duplicate values the last key wins, like a native number enum.
+  const keyByValue = new Map<unknown, keyof T>(rawEntries.map(([k, v]) => [v, k]))
+
+  return Object.defineProperties(
+    { ...obj },
+    {
+      keys: { value: keys },
+      values: { value: values },
+      entries: { value: entries },
+      is: { value: (v: unknown): v is Enum<T> => keyByValue.has(v) },
+      keyOf: {
+        value: (v: Enum<T>): keyof T => {
+          const key = keyByValue.get(v)
+          if (key === undefined) throw new Error(`_enum keyOf not found for: ${String(v)}`)
+          return key
+        },
+      },
+      keyOfOrUndefined: { value: (v: unknown): keyof T | undefined => keyByValue.get(v) },
+    },
+  ) as EnumObject<T>
+}
+
+/**
+ * Keys that `_enum()` reserves for its helpers, and therefore rejects as Enum member names.
+ */
+const RESERVED_KEYS = [
+  'type',
+  'keys',
+  'values',
+  'entries',
+  'is',
+  'keyOf',
+  'keyOfOrUndefined',
+] as const
 
 export function getEnumType(en: AnyObject): 'StringEnum' | 'NumberEnum' | undefined {
   /*
@@ -226,3 +301,51 @@ export function _stringEnumKey<T extends StringEnum>(en: T, v: string | undefine
   if (!r) throw new Error(`_stringEnumKey not found for: ${v}`)
   return r
 }
+
+/**
+ * @experimental
+ */
+export type EnumObject<T> = Readonly<T> & EnumHelpers<T>
+
+/**
+ * Helpers that `_enum()` hangs off the returned object.
+ * Defined as non-enumerable, so that `Object.keys/values/entries`, `JSON.stringify`
+ * and `for..in` still only see the actual Enum members.
+ *
+ * `keys`/`values`/`entries` are precomputed, and keep the literal types
+ * that the `Object.*` equivalents would widen to `string`.
+ *
+ * @experimental
+ */
+interface EnumHelpers<T> {
+  /**
+   * Type-only carrier for the union of all values, so that the Enum's type can be declared
+   * without a second import: `export type Color = typeof Color.type`.
+   *
+   * It has no runtime counterpart, reading it as a value returns undefined.
+   */
+  readonly type: Enum<T>
+  readonly keys: readonly (keyof T)[]
+  readonly values: readonly Enum<T>[]
+  readonly entries: EnumEntries<T>
+  /**
+   * Type-guard. O(1), backed by a Map.
+   */
+  readonly is: (v: unknown) => v is Enum<T>
+  /**
+   * Reverse lookup, the counterpart of `Color.RED`. O(1). Throws if the value is not a member.
+   */
+  readonly keyOf: (v: Enum<T>) => keyof T
+  /**
+   * Like `keyOf`, but takes untrusted input and returns undefined instead of throwing.
+   */
+  readonly keyOfOrUndefined: (v: unknown) => keyof T | undefined
+}
+
+/**
+ * The mapped type (rather than `readonly [keyof T, Enum<T>][]`) keeps each key paired
+ * with its own value, instead of allowing any key/value combination.
+ *
+ * @experimental
+ */
+type EnumEntries<T> = readonly { [K in keyof T]: readonly [k: K, v: T[K]] }[keyof T][]

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,62 @@ export function commonLoggerPrefix(logger: CommonLogger, ...prefixes: any[]): Co
   }
 }
 
+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(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: 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),
+    }
+  }
+
+  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/types.ts

@@ -30,10 +30,30 @@ 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>
 
+/**
+ * Union of all values of an Enum-like object: both native TypeScript enums and `_enum()` objects.
+ *
+ * For an `_enum()` object prefer `typeof Color.type`, which needs no import.
+ *
+ * @example
+ * enum Color { RED = 'red', GREEN = 'green' }
+ * type ColorValue = Enum<typeof Color> // 'red' | 'green'
+ *
+ * @experimental
+ */
+// The first branch is for `_enum()` objects, whose helpers `T[keyof T]` would otherwise pull into
+// the union. Native enums never match it, since their values are `string | number`, never an array.
+export type Enum<T> = T extends { values: readonly (infer V)[] } ? V : T[keyof T]
+
 // oxlint-disable-next-line @typescript-eslint/consistent-type-definitions
 export type CreatedUpdated = {
   created: UnixTimestamp