@naturalcycles/js-lib 14.110.0 → 14.112.0

package/dist/enum.util.d.ts

@@ -39,7 +39,7 @@ export declare function _stringEnumEntries<T extends StringEnum>(en: T): [k: str
  */
 export declare function _numberEnumInverse<T extends NumberEnum>(en: T, v: string): T[keyof T];
 /**
- * _enumInverse, but allows to get/return undefined output.
+ * _numberEnumInverse, but allows to get/return undefined output.
  */
 export declare function _numberEnumInverseNullable<T extends NumberEnum>(en: T, v: string | undefined): T[keyof T] | undefined;
 /**
@@ -50,6 +50,14 @@ export declare function _numberEnumInverseNullable<T extends NumberEnum>(en: T,
  */
 export declare function _numberEnumNormalize<T extends NumberEnum>(en: T, v: string | number): T[keyof T];
 /**
- * Same as _enumNormalize, but allows to return undefined values.
+ * Same as _numberEnumNormalize, but allows to return undefined values.
  */
 export declare function _numberEnumNormalizeNullable<T extends NumberEnum>(en: T, v: string | number | undefined): T[keyof T] | undefined;
+/**
+ * Returns a String key for given NumberEnum value, or undefined if not found.
+ */
+export declare function _numberEnumKeyNullable<T extends NumberEnum>(en: T, v: T[keyof T] | undefined | null): keyof T | undefined;
+/**
+ * Returns a String key for given NumberEnum value, throws if not found.
+ */
+export declare function _numberEnumKey<T extends NumberEnum>(en: T, v: T[keyof T] | undefined | null): keyof T;

package/dist/enum.util.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._numberEnumNormalizeNullable = exports._numberEnumNormalize = exports._numberEnumInverseNullable = exports._numberEnumInverse = exports._stringEnumEntries = exports._numberEnumEntries = exports._stringEnumValues = exports._stringEnumKeys = exports._numberEnumValues = exports._numberEnumKeys = void 0;
+exports._numberEnumKey = exports._numberEnumKeyNullable = exports._numberEnumNormalizeNullable = exports._numberEnumNormalize = exports._numberEnumInverseNullable = exports._numberEnumInverse = exports._stringEnumEntries = exports._numberEnumEntries = exports._stringEnumValues = exports._stringEnumKeys = exports._numberEnumValues = exports._numberEnumKeys = void 0;
 /**
  * Returns all number keys of a number-enum.
  */
@@ -63,12 +63,12 @@ exports._stringEnumEntries = _stringEnumEntries;
 function _numberEnumInverse(en, v) {
     const r = en[v];
     if (!r)
-        throw new Error(`enumInverse value not found for: ${v}`);
+        throw new Error(`_numberEnumInverse value not found for: ${v}`);
     return r;
 }
 exports._numberEnumInverse = _numberEnumInverse;
 /**
- * _enumInverse, but allows to get/return undefined output.
+ * _numberEnumInverse, but allows to get/return undefined output.
  */
 function _numberEnumInverseNullable(en, v) {
     return en[v];
@@ -83,14 +83,34 @@ exports._numberEnumInverseNullable = _numberEnumInverseNullable;
 function _numberEnumNormalize(en, v) {
     const r = _numberEnumNormalizeNullable(en, v);
     if (!r || !en[r])
-        throw new Error(`enumNormalize value not found for: ${v}`);
+        throw new Error(`_numberEnumNormalize value not found for: ${v}`);
     return r;
 }
 exports._numberEnumNormalize = _numberEnumNormalize;
 /**
- * Same as _enumNormalize, but allows to return undefined values.
+ * Same as _numberEnumNormalize, but allows to return undefined values.
  */
 function _numberEnumNormalizeNullable(en, v) {
     return typeof v === 'string' ? en[v] : v;
 }
 exports._numberEnumNormalizeNullable = _numberEnumNormalizeNullable;
+/**
+ * Returns a String key for given NumberEnum value, or undefined if not found.
+ */
+function _numberEnumKeyNullable(en, v) {
+    const key = en[v];
+    // This prevents passing a Key (not a Value) of enum here, which returns unexpected result (number, not string)
+    return typeof key === 'string' ? key : undefined;
+}
+exports._numberEnumKeyNullable = _numberEnumKeyNullable;
+/**
+ * Returns a String key for given NumberEnum value, throws if not found.
+ */
+function _numberEnumKey(en, v) {
+    const key = en[v];
+    // This prevents passing a Key (not a Value) of enum here, which returns unexpected result (number, not string)
+    if (typeof key !== 'string')
+        throw new Error(`_enumKey value not found for: ${v}`);
+    return key;
+}
+exports._numberEnumKey = _numberEnumKey;

package/dist/object/object.util.d.ts

@@ -135,19 +135,19 @@ export declare function _invert<T extends AnyObject>(o: T): {
 };
 export declare function _invertMap<K, V>(m: ReadonlyMap<K, V>): Map<V, K>;
 /**
- * Gets the property value at path of object. If the resolved value is undefined the defaultValue is used
- * in its place.
+ * Gets the property value at path of object.
  *
- * @param obj The object to query.
- * @param path The path of the property to get.
- * @param def The value returned if the resolved value is undefined.
- * @return Returns the resolved value.
+ * @example
+ * const obj = {a: 'a', b: 'b', c: { cc: 'cc' }}
+ * _get(obj, 'a') // 'a'
+ * _get(obj, 'c.cc') // 'cc'
+ * _get(obj, 'c[cc]') // 'cc'
+ * _get(obj, 'unknown.path') // undefined
  */
-export declare function _get<T extends AnyObject>(obj?: T, path?: string, def?: any): any;
+export declare function _get<T extends AnyObject>(obj?: T, path?: string): unknown;
 /**
  * Sets the value at path of object. If a portion of path doesn’t exist it’s created. Arrays are created for
- * missing index properties while objects are created for all other missing properties. Use _.setWith to
- * customize path creation.
+ * missing index properties while objects are created for all other missing properties.
  *
  * @param obj The object to modify.
  * @param path The path of the property to set.
@@ -156,7 +156,7 @@ export declare function _get<T extends AnyObject>(obj?: T, path?: string, def?:
  *
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
-export declare function _set<IN extends AnyObject, OUT = IN>(obj: IN, path: PropertyPath, value?: any): OUT;
+export declare function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any): T;
 /**
  * Checks if `path` is a direct property of `object` (not null, not undefined).
  *
@@ -181,4 +181,4 @@ export declare function _set<IN extends AnyObject, OUT = IN>(obj: IN, path: Prop
  * _.has(other, 'a');
  * // => false
  */
-export declare function _has<T extends AnyObject>(obj: T, path?: string): boolean;
+export declare function _has<T extends AnyObject>(obj: T, path: string): boolean;

package/dist/object/object.util.js

@@ -286,26 +286,25 @@ function _invertMap(m) {
 }
 exports._invertMap = _invertMap;
 /**
- * Gets the property value at path of object. If the resolved value is undefined the defaultValue is used
- * in its place.
+ * Gets the property value at path of object.
  *
- * @param obj The object to query.
- * @param path The path of the property to get.
- * @param def The value returned if the resolved value is undefined.
- * @return Returns the resolved value.
+ * @example
+ * const obj = {a: 'a', b: 'b', c: { cc: 'cc' }}
+ * _get(obj, 'a') // 'a'
+ * _get(obj, 'c.cc') // 'cc'
+ * _get(obj, 'c[cc]') // 'cc'
+ * _get(obj, 'unknown.path') // undefined
  */
-function _get(obj = {}, path = '', def) {
-    const res = path
+function _get(obj = {}, path = '') {
+    return path
         .replace(/\[([^\]]+)]/g, '.$1')
         .split('.')
-        .reduce((o, p) => o[p], obj);
-    return res === undefined ? def : res;
+        .reduce((o, p) => o?.[p], obj);
 }
 exports._get = _get;
 /**
  * Sets the value at path of object. If a portion of path doesn’t exist it’s created. Arrays are created for
- * missing index properties while objects are created for all other missing properties. Use _.setWith to
- * customize path creation.
+ * missing index properties while objects are created for all other missing properties.
  *
  * @param obj The object to modify.
  * @param path The path of the property to set.
@@ -336,7 +335,7 @@ function _set(obj, path, value) {
                     ? [] // Yes: assign a new array object
                     : {}), // No: assign a new plain object
     obj)[path[path.length - 1]] = value; // Finally assign the value to the last key
-    return obj; // Return the top-level object to allow chaining
+    return obj; // allow chaining
 }
 exports._set = _set;
 /**

package/dist-esm/enum.util.js

@@ -54,11 +54,11 @@ export function _stringEnumEntries(en) {
 export function _numberEnumInverse(en, v) {
     const r = en[v];
     if (!r)
-        throw new Error(`enumInverse value not found for: ${v}`);
+        throw new Error(`_numberEnumInverse value not found for: ${v}`);
     return r;
 }
 /**
- * _enumInverse, but allows to get/return undefined output.
+ * _numberEnumInverse, but allows to get/return undefined output.
  */
 export function _numberEnumInverseNullable(en, v) {
     return en[v];
@@ -72,12 +72,30 @@ export function _numberEnumInverseNullable(en, v) {
 export function _numberEnumNormalize(en, v) {
     const r = _numberEnumNormalizeNullable(en, v);
     if (!r || !en[r])
-        throw new Error(`enumNormalize value not found for: ${v}`);
+        throw new Error(`_numberEnumNormalize value not found for: ${v}`);
     return r;
 }
 /**
- * Same as _enumNormalize, but allows to return undefined values.
+ * Same as _numberEnumNormalize, but allows to return undefined values.
  */
 export function _numberEnumNormalizeNullable(en, v) {
     return typeof v === 'string' ? en[v] : v;
 }
+/**
+ * Returns a String key for given NumberEnum value, or undefined if not found.
+ */
+export function _numberEnumKeyNullable(en, v) {
+    const key = en[v];
+    // This prevents passing a Key (not a Value) of enum here, which returns unexpected result (number, not string)
+    return typeof key === 'string' ? key : undefined;
+}
+/**
+ * Returns a String key for given NumberEnum value, throws if not found.
+ */
+export function _numberEnumKey(en, v) {
+    const key = en[v];
+    // This prevents passing a Key (not a Value) of enum here, which returns unexpected result (number, not string)
+    if (typeof key !== 'string')
+        throw new Error(`_enumKey value not found for: ${v}`);
+    return key;
+}

package/dist-esm/object/object.util.js

@@ -263,25 +263,24 @@ export function _invertMap(m) {
     return inv;
 }
 /**
- * Gets the property value at path of object. If the resolved value is undefined the defaultValue is used
- * in its place.
+ * Gets the property value at path of object.
  *
- * @param obj The object to query.
- * @param path The path of the property to get.
- * @param def The value returned if the resolved value is undefined.
- * @return Returns the resolved value.
+ * @example
+ * const obj = {a: 'a', b: 'b', c: { cc: 'cc' }}
+ * _get(obj, 'a') // 'a'
+ * _get(obj, 'c.cc') // 'cc'
+ * _get(obj, 'c[cc]') // 'cc'
+ * _get(obj, 'unknown.path') // undefined
  */
-export function _get(obj = {}, path = '', def) {
-    const res = path
+export function _get(obj = {}, path = '') {
+    return path
         .replace(/\[([^\]]+)]/g, '.$1')
         .split('.')
-        .reduce((o, p) => o[p], obj);
-    return res === undefined ? def : res;
+        .reduce((o, p) => o === null || o === void 0 ? void 0 : o[p], obj);
 }
 /**
  * Sets the value at path of object. If a portion of path doesn’t exist it’s created. Arrays are created for
- * missing index properties while objects are created for all other missing properties. Use _.setWith to
- * customize path creation.
+ * missing index properties while objects are created for all other missing properties.
  *
  * @param obj The object to modify.
  * @param path The path of the property to set.
@@ -312,7 +311,7 @@ export function _set(obj, path, value) {
                     ? [] // Yes: assign a new array object
                     : {}), // No: assign a new plain object
     obj)[path[path.length - 1]] = value; // Finally assign the value to the last key
-    return obj; // Return the top-level object to allow chaining
+    return obj; // allow chaining
 }
 /**
  * Checks if `path` is a direct property of `object` (not null, not undefined).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.110.0",
+  "version": "14.112.0",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",
@@ -16,7 +16,7 @@
     "@naturalcycles/nodejs-lib": "^12.33.4",
     "@naturalcycles/time-lib": "^3.5.1",
     "@types/node": "^18.0.0",
-    "expect-type": "^0.13.0",
+    "expect-type": "^0.14.2",
     "jest": "^29.0.0",
     "prettier": "^2.1.2",
     "rxjs": "^7.0.1",

package/src/enum.util.ts

@@ -61,12 +61,12 @@ export function _stringEnumEntries<T extends StringEnum>(en: T): [k: string, v:
  */
 export function _numberEnumInverse<T extends NumberEnum>(en: T, v: string): T[keyof T] {
   const r = en[v as keyof T] as any
-  if (!r) throw new Error(`enumInverse value not found for: ${v}`)
+  if (!r) throw new Error(`_numberEnumInverse value not found for: ${v}`)
   return r
 }
 
 /**
- * _enumInverse, but allows to get/return undefined output.
+ * _numberEnumInverse, but allows to get/return undefined output.
  */
 export function _numberEnumInverseNullable<T extends NumberEnum>(
   en: T,
@@ -83,12 +83,12 @@ export function _numberEnumInverseNullable<T extends NumberEnum>(
  */
 export function _numberEnumNormalize<T extends NumberEnum>(en: T, v: string | number): T[keyof T] {
   const r = _numberEnumNormalizeNullable(en, v)
-  if (!r || !en[r as keyof T]) throw new Error(`enumNormalize value not found for: ${v}`)
+  if (!r || !en[r as keyof T]) throw new Error(`_numberEnumNormalize value not found for: ${v}`)
   return r
 }
 
 /**
- * Same as _enumNormalize, but allows to return undefined values.
+ * Same as _numberEnumNormalize, but allows to return undefined values.
  */
 export function _numberEnumNormalizeNullable<T extends NumberEnum>(
   en: T,
@@ -96,3 +96,28 @@ export function _numberEnumNormalizeNullable<T extends NumberEnum>(
 ): T[keyof T] | undefined {
   return typeof v === 'string' ? en[v as keyof T] : (v as any)
 }
+
+/**
+ * Returns a String key for given NumberEnum value, or undefined if not found.
+ */
+export function _numberEnumKeyNullable<T extends NumberEnum>(
+  en: T,
+  v: T[keyof T] | undefined | null,
+): keyof T | undefined {
+  const key = (en as any)[v]
+  // This prevents passing a Key (not a Value) of enum here, which returns unexpected result (number, not string)
+  return typeof key === 'string' ? key : undefined
+}
+
+/**
+ * Returns a String key for given NumberEnum value, throws if not found.
+ */
+export function _numberEnumKey<T extends NumberEnum>(
+  en: T,
+  v: T[keyof T] | undefined | null,
+): keyof T {
+  const key = (en as any)[v]
+  // This prevents passing a Key (not a Value) of enum here, which returns unexpected result (number, not string)
+  if (typeof key !== 'string') throw new Error(`_enumKey value not found for: ${v}`)
+  return key
+}

package/src/object/object.util.ts

@@ -311,27 +311,25 @@ export function _invertMap<K, V>(m: ReadonlyMap<K, V>): Map<V, K> {
 }
 
 /**
- * Gets the property value at path of object. If the resolved value is undefined the defaultValue is used
- * in its place.
+ * Gets the property value at path of object.
  *
- * @param obj The object to query.
- * @param path The path of the property to get.
- * @param def The value returned if the resolved value is undefined.
- * @return Returns the resolved value.
+ * @example
+ * const obj = {a: 'a', b: 'b', c: { cc: 'cc' }}
+ * _get(obj, 'a') // 'a'
+ * _get(obj, 'c.cc') // 'cc'
+ * _get(obj, 'c[cc]') // 'cc'
+ * _get(obj, 'unknown.path') // undefined
  */
-export function _get<T extends AnyObject>(obj = {} as T, path = '', def?: any): any {
-  const res = path
+export function _get<T extends AnyObject>(obj = {} as T, path = ''): unknown {
+  return path
     .replace(/\[([^\]]+)]/g, '.$1')
     .split('.')
-    .reduce((o, p) => o[p], obj)
-
-  return res === undefined ? def : res
+    .reduce((o, p) => o?.[p], obj)
 }
 
 /**
  * Sets the value at path of object. If a portion of path doesn’t exist it’s created. Arrays are created for
- * missing index properties while objects are created for all other missing properties. Use _.setWith to
- * customize path creation.
+ * missing index properties while objects are created for all other missing properties.
  *
  * @param obj The object to modify.
  * @param path The path of the property to set.
@@ -340,11 +338,7 @@ export function _get<T extends AnyObject>(obj = {} as T, path = '', def?: any):
  *
  * Based on: https://stackoverflow.com/a/54733755/4919972
  */
-export function _set<IN extends AnyObject, OUT = IN>(
-  obj: IN,
-  path: PropertyPath,
-  value?: any,
-): OUT {
+export function _set<T extends AnyObject>(obj: T, path: PropertyPath, value: any): T {
   if (!obj || Object(obj) !== obj || !path) return obj as any // When obj is not an object
 
   // If not yet an array, get the keys from the string-path
@@ -373,7 +367,7 @@ export function _set<IN extends AnyObject, OUT = IN>(
     obj,
   )[path[path.length - 1]!] = value // Finally assign the value to the last key
 
-  return obj as any // Return the top-level object to allow chaining
+  return obj // allow chaining
 }
 
 /**
@@ -400,7 +394,7 @@ export function _set<IN extends AnyObject, OUT = IN>(
  * _.has(other, 'a');
  * // => false
  */
-export function _has<T extends AnyObject>(obj: T, path?: string): boolean {
+export function _has<T extends AnyObject>(obj: T, path: string): boolean {
   const v = _get(obj, path)
   return v !== undefined && v !== null
 }