@naturalcycles/js-lib 15.87.0 → 15.88.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/types.d.ts

@@ -28,6 +28,20 @@ export type AnyObject = Record<string, any>;
 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.88.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/types.ts

@@ -34,6 +34,21 @@ 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