@valkyriestudios/utils 12.33.0 → 12.34.0

package/README.md

@@ -31,7 +31,11 @@ isNotEmptyArray([0, 1, 2]); // TRUE
 ```
 
 ### array/mapKey(val:Record[], key:string, opts?:{merge?:boolean;filter_fn?:(el:T) => boolean})
-Map a non-primitive object array into an object map by key
+Map a non-primitive object array into an object map by key.
+
+**Take Note**: The function `array/mapKeyAsMap` has the same behavior as the mapKey function with the sole difference being that it returns a
+**Map** instead of an object.
+
 ```typescript
 import mapKey from '@valkyriestudios/utils/array/mapKey';
 mapKey([
@@ -114,6 +118,9 @@ mapKey([
 }
 ```
 
+### array/mapKeyAsMap(val:Record[], key:string, opts?:{merge?:boolean;filter_fn?:(el:T) => boolean})
+Same behavior as mapKey but returns a Map instead of an object
+
 ### array/mapFn(val:Record[], key:Function, opts:object={})
 Same behavior as mapKey but instead of a key, a function is passed to generate your own key. Eg:
 
@@ -134,6 +141,9 @@ mapFn([
 
 options are the same as the mapKey function
 
+### array/mapFnAsMap(val:Record[], key:Function, opts:object={})
+Same behavior as mapFn but returns a Map instead of an object
+
 ### array/mapPrimitive(val:any[], opts?:{valtrim:false;keyround:false;valround:false;filter_fn:(el)=>boolean})
 Map an array of primitives (number/string)
 ```typescript

package/array/index.d.ts

@@ -3,10 +3,12 @@ import { isArray } from './is';
 import { isNotEmptyArray } from './isNotEmpty';
 import { join } from './join';
 import { mapFn } from './mapFn';
+import { mapFnAsMap } from './mapFnAsMap';
 import { mapKey } from './mapKey';
+import { mapKeyAsMap } from './mapKeyAsMap';
 import { mapPrimitive } from './mapPrimitive';
 import { groupBy } from './groupBy';
 import { shuffle } from './shuffle';
 import { split } from './split';
 import { sort } from './sort';
-export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapKey, mapPrimitive, groupBy, shuffle, split, sort };
+export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapFnAsMap, mapKey, mapKeyAsMap, mapPrimitive, groupBy, shuffle, split, sort };

package/array/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sort = exports.split = exports.shuffle = exports.groupBy = exports.mapPrimitive = exports.mapKey = exports.mapFn = exports.join = exports.isNe = exports.isNeArray = exports.isNotEmpty = exports.isNotEmptyArray = exports.is = exports.isArray = exports.dedupe = void 0;
+exports.sort = exports.split = exports.shuffle = exports.groupBy = exports.mapPrimitive = exports.mapKeyAsMap = exports.mapKey = exports.mapFnAsMap = exports.mapFn = exports.join = exports.isNe = exports.isNeArray = exports.isNotEmpty = exports.isNotEmptyArray = exports.is = exports.isArray = exports.dedupe = void 0;
 const dedupe_1 = require("./dedupe");
 Object.defineProperty(exports, "dedupe", { enumerable: true, get: function () { return dedupe_1.dedupe; } });
 const is_1 = require("./is");
@@ -15,8 +15,12 @@ const join_1 = require("./join");
 Object.defineProperty(exports, "join", { enumerable: true, get: function () { return join_1.join; } });
 const mapFn_1 = require("./mapFn");
 Object.defineProperty(exports, "mapFn", { enumerable: true, get: function () { return mapFn_1.mapFn; } });
+const mapFnAsMap_1 = require("./mapFnAsMap");
+Object.defineProperty(exports, "mapFnAsMap", { enumerable: true, get: function () { return mapFnAsMap_1.mapFnAsMap; } });
 const mapKey_1 = require("./mapKey");
 Object.defineProperty(exports, "mapKey", { enumerable: true, get: function () { return mapKey_1.mapKey; } });
+const mapKeyAsMap_1 = require("./mapKeyAsMap");
+Object.defineProperty(exports, "mapKeyAsMap", { enumerable: true, get: function () { return mapKeyAsMap_1.mapKeyAsMap; } });
 const mapPrimitive_1 = require("./mapPrimitive");
 Object.defineProperty(exports, "mapPrimitive", { enumerable: true, get: function () { return mapPrimitive_1.mapPrimitive; } });
 const groupBy_1 = require("./groupBy");

package/array/mapFn.d.ts

@@ -25,8 +25,6 @@ type MapFn<T extends Record<string, any>> = (entry: T) => (string | number | boo
  * @param {Record<string, any>[]} val - Array to map
  * @param {MapFn} fn - Handler function which is run for each of the objects and should return a string or number
  * @param {MapOptions?} opts - Options object to override built-in defaults
- *
- * @returns {Record<string, T>} KV-Map object
  */
 declare function mapFn<T extends Record<string, any>>(arr: T[], fn: MapFn<T>, opts?: MapOptions): Record<string, T>;
 export { mapFn, mapFn as default };

package/array/mapFn.js

@@ -9,16 +9,16 @@ function mapFn(arr, fn, opts) {
         return {};
     const MERGE = opts?.merge === true;
     const map = {};
-    let hash = false;
     for (let i = 0; i < arr.length; i++) {
         const el = arr[i];
         if (Object.prototype.toString.call(el) !== '[object Object]')
             continue;
-        hash = fn(el);
-        if (!Number.isFinite(hash) && !(typeof hash === 'string' && hash.trim().length))
-            continue;
-        hash = hash + '';
-        map[hash] = (MERGE && hash in map ? (0, merge_1.merge)(map[hash], el, { union: true }) : el);
+        let hash = fn(el);
+        if (Number.isFinite(hash) ||
+            (typeof hash === 'string' && hash.length)) {
+            hash = hash + '';
+            map[hash] = MERGE && hash in map ? (0, merge_1.merge)(map[hash], el, { union: true }) : el;
+        }
     }
     return map;
 }

package/array/mapFnAsMap.d.ts

@@ -0,0 +1,33 @@
+type MapOptions = {
+    /**
+     * Allow merging existing keys or not, if not keys will be overriden if they exist
+     * (default=false)
+     *
+     * Example:
+     *  mapFnAsMap([{uid: 12, a: 'hi'}, {uid: 12, b: 'ho'}], el => el.uid, {merge: true})
+     * Output:
+     *  {12: {uid: 12, a: 'hi', b: 'ho'}}
+     * Output if merge is false
+     *  {12: {uid: 12, b: 'ho'}}
+     */
+    merge?: boolean;
+};
+type MapFn<T extends Record<string, any>> = (entry: T) => string | number | null;
+/**
+ * Map an object array into a Map through a function that generates a key. Returning a non-string,
+ * non-numeric value from the function (eg: null) will filter out the object.
+ *
+ * Example:
+ *  mapFnAsMap([{uid: 12, name: 'Peter'}, {uid: 15, name: 'Jonas'}], el => el.uid);
+ * Output:
+ *  new Map([
+ *    [12, {uid: 12, name: 'Peter'}],
+ *    [15, {uid: 15, name: 'Jonas'}],
+ *  ])
+ *
+ * @param {Record<string, any>[]} val - Array to map
+ * @param {MapFn} fn - Handler function which is run for each of the objects and should return a string or number
+ * @param {MapOptions?} opts - Options object to override built-in defaults
+ */
+declare function mapFnAsMap<T extends Record<string, any>, TFN extends MapFn<T>>(arr: T[], fn: TFN, opts?: MapOptions): Map<NonNullable<ReturnType<TFN>>, T>;
+export { mapFnAsMap, mapFnAsMap as default };

package/array/mapFnAsMap.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapFnAsMap = mapFnAsMap;
+exports.default = mapFnAsMap;
+const merge_1 = require("../object/merge");
+function mapFnAsMap(arr, fn, opts) {
+    if ((!Array.isArray(arr) || !arr.length) ||
+        typeof fn !== 'function')
+        return new Map();
+    const MERGE = opts?.merge === true;
+    const map = new Map();
+    for (let i = 0; i < arr.length; i++) {
+        const el = arr[i];
+        if (Object.prototype.toString.call(el) !== '[object Object]')
+            continue;
+        const hash = fn(el);
+        if (Number.isFinite(hash) ||
+            (typeof hash === 'string' && hash.trim().length))
+            map.set(hash, MERGE && map.has(hash) ? (0, merge_1.merge)(map.get(hash), el, { union: true }) : el);
+    }
+    return map;
+}

package/array/mapKey.d.ts

@@ -28,8 +28,6 @@ type MapOptions<T> = {
  * @param {Record<string,any>[]} val - Array to map
  * @param {string} key - Key to map by
  * @param {MapOptions?} opts - Options object to override built-in defaults
- *
- * @returns {Record<string, T>} KV-Map object
  */
-declare function mapKey<T extends Record<string, any>>(arr: T[], key: string, opts?: MapOptions<T>): Record<string, T>;
+declare function mapKey<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Record<string, T>;
 export { mapKey, mapKey as default };

package/array/mapKey.js

@@ -4,25 +4,20 @@ exports.mapKey = mapKey;
 exports.default = mapKey;
 const merge_1 = require("../object/merge");
 function mapKey(arr, key, opts) {
-    if (!Array.isArray(arr) || typeof key !== 'string')
-        return {};
-    const len = arr.length;
-    if (!len)
-        return {};
-    const key_s = key.trim();
-    if (!key_s.length)
+    if (!Array.isArray(arr) ||
+        !arr.length ||
+        typeof key !== 'string' ||
+        !key.length)
         return {};
     const FILTER_FN = opts?.filter_fn;
     const MERGE = opts?.merge === true;
     const map = {};
-    for (let i = 0; i < len; i++) {
+    for (let i = 0; i < arr.length; i++) {
         const el = arr[i];
-        const el_key = el?.[key_s];
-        if (el_key === undefined)
-            continue;
-        if (FILTER_FN && !FILTER_FN(el))
-            continue;
-        map[el_key] = (MERGE && el_key in map ? (0, merge_1.merge)(map[el_key], el, { union: true }) : el);
+        const el_key = el?.[key];
+        if (el_key !== undefined &&
+            (!FILTER_FN || FILTER_FN(el)))
+            map[el_key] = (MERGE && el_key in map ? (0, merge_1.merge)(map[el_key], el, { union: true }) : el);
     }
     return map;
 }

package/array/mapKeyAsMap.d.ts

@@ -0,0 +1,36 @@
+type MapOptions<T> = {
+    /**
+     * Allow merging existing keys or not, if not keys will be overriden if they exist
+     * (default=false)
+     *
+     * Example:
+     *  mapKey([{uid: 12, a: 'hi'}, {uid: 12, b: 'ho'}], 'uid', {merge: true})
+     * Output:
+     *  {12: {uid: 12, a: 'hi', b: 'ho'}}
+     * Output if merge is false
+     *  {12: {uid: 12, b: 'ho'}}
+     */
+    merge?: boolean;
+    /**
+     * Pass a custom filter function which will be run in O(n) while iterating
+     */
+    filter_fn?: (el: T) => boolean;
+};
+/**
+ * Map an object array into a Map by passing a common key that exists on the objects. Objects for
+ * which the key doesn't exist will be filtered out automatically
+ *
+ * Example:
+ *  mapKey([{uid: 12, name: 'Peter'}, {uid: 15, name: 'Jonas'}], 'uid');
+ * Output:
+ *  new Map([
+ *    [12, {uid: 12, name: 'Peter'}],
+ *    [15, {uid: 15, name: 'Jonas'}],
+ *  ])
+ *
+ * @param {Record<string,any>[]} val - Array to map
+ * @param {string} key - Key to map by
+ * @param {MapOptions?} opts - Options object to override built-in defaults
+ */
+declare function mapKeyAsMap<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Map<T[TKey], T>;
+export { mapKeyAsMap, mapKeyAsMap as default };

package/array/mapKeyAsMap.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapKeyAsMap = mapKeyAsMap;
+exports.default = mapKeyAsMap;
+const merge_1 = require("../object/merge");
+function mapKeyAsMap(arr, key, opts) {
+    if (!Array.isArray(arr) ||
+        !arr.length ||
+        typeof key !== 'string' ||
+        !key.length)
+        return new Map();
+    const FILTER_FN = opts?.filter_fn;
+    const MERGE = opts?.merge === true;
+    const map = new Map();
+    for (let i = 0; i < arr.length; i++) {
+        const el = arr[i];
+        const el_key = el?.[key];
+        if (el_key !== undefined &&
+            (!FILTER_FN || FILTER_FN(el)))
+            map.set(el_key, MERGE && map.has(el_key) ? (0, merge_1.merge)(map.get(el_key), el, { union: true }) : el);
+    }
+    return map;
+}

package/index.d.ts

@@ -45,18 +45,10 @@ declare module "object/merge" {
         [K in keyof T]: K extends keyof U ? U[K] : T[K];
     };
     type MergeArray<T, U extends Record<string, unknown>[], Union extends boolean> = U extends [infer Head, ...infer Tail] ? Head extends Record<string, unknown> ? Tail extends Record<string, unknown>[] ? MergeArray<Union extends true ? Merge<T, Head> : MergeNonUnion<T, Head>, Tail, Union> : Union extends true ? Merge<T, Head> : MergeNonUnion<T, Head> : T : T;
-    function merge<T extends Record<string, unknown>, U extends Record<string, unknown>>(target: T, source: U, opts: {
-        union: true;
-    }): Merge<T, U>;
-    function merge<T extends Record<string, unknown>, U extends Record<string, unknown>>(target: T, source: U, opts?: {
-        union?: false;
-    }): MergeNonUnion<T, U>;
-    function merge<T extends Record<string, unknown>, U extends Record<string, unknown>[]>(target: T, sources: [...U], opts: {
-        union: true;
-    }): MergeArray<T, U, true>;
-    function merge<T extends Record<string, unknown>, U extends Record<string, unknown>[]>(target: T, sources: [...U], opts?: {
-        union?: false;
-    }): MergeArray<T, U, false>;
+    type Merged<T extends Record<string, unknown>, U extends Record<string, unknown> | Record<string, unknown>[], Union extends boolean> = U extends any[] ? MergeArray<T, U, Union> : Union extends true ? Merge<T, U> : MergeNonUnion<T, U>;
+    function merge<T extends Record<string, unknown>, U extends Record<string, unknown> | [Record<string, unknown>, ...Record<string, unknown>[]], Union extends boolean = false>(target: T, source: U, opts?: {
+        union?: Union;
+    }): Merged<T, U, Union>;
     export { merge, merge as default };
 }
 declare module "array/mapFn" {
@@ -67,14 +59,30 @@ declare module "array/mapFn" {
     function mapFn<T extends Record<string, any>>(arr: T[], fn: MapFn<T>, opts?: MapOptions): Record<string, T>;
     export { mapFn, mapFn as default };
 }
+declare module "array/mapFnAsMap" {
+    type MapOptions = {
+        merge?: boolean;
+    };
+    type MapFn<T extends Record<string, any>> = (entry: T) => string | number | null;
+    function mapFnAsMap<T extends Record<string, any>, TFN extends MapFn<T>>(arr: T[], fn: TFN, opts?: MapOptions): Map<NonNullable<ReturnType<TFN>>, T>;
+    export { mapFnAsMap, mapFnAsMap as default };
+}
 declare module "array/mapKey" {
     type MapOptions<T> = {
         merge?: boolean;
         filter_fn?: (el: T) => boolean;
     };
-    function mapKey<T extends Record<string, any>>(arr: T[], key: string, opts?: MapOptions<T>): Record<string, T>;
+    function mapKey<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Record<string, T>;
     export { mapKey, mapKey as default };
 }
+declare module "array/mapKeyAsMap" {
+    type MapOptions<T> = {
+        merge?: boolean;
+        filter_fn?: (el: T) => boolean;
+    };
+    function mapKeyAsMap<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Map<T[TKey], T>;
+    export { mapKeyAsMap, mapKeyAsMap as default };
+}
 declare module "array/mapPrimitive" {
     type MapOptions = {
         valtrim?: boolean;
@@ -128,13 +136,15 @@ declare module "array/index" {
     import { isNotEmptyArray } from "array/isNotEmpty";
     import { join } from "array/join";
     import { mapFn } from "array/mapFn";
+    import { mapFnAsMap } from "array/mapFnAsMap";
     import { mapKey } from "array/mapKey";
+    import { mapKeyAsMap } from "array/mapKeyAsMap";
     import { mapPrimitive } from "array/mapPrimitive";
     import { groupBy } from "array/groupBy";
     import { shuffle } from "array/shuffle";
     import { split } from "array/split";
     import { sort } from "array/sort";
-    export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapKey, mapPrimitive, groupBy, shuffle, split, sort };
+    export { dedupe, isArray, isArray as is, isNotEmptyArray, isNotEmptyArray as isNotEmpty, isNotEmptyArray as isNeArray, isNotEmptyArray as isNe, join, mapFn, mapFnAsMap, mapKey, mapKeyAsMap, mapPrimitive, groupBy, shuffle, split, sort };
 }
 declare module "boolean/is" {
     function isBoolean(val: unknown): val is boolean;

package/object/merge.d.ts

@@ -16,16 +16,20 @@ type MergeNonUnion<T, U> = {
  * or MergeNonUnion (if union is false).
  */
 type MergeArray<T, U extends Record<string, unknown>[], Union extends boolean> = U extends [infer Head, ...infer Tail] ? Head extends Record<string, unknown> ? Tail extends Record<string, unknown>[] ? MergeArray<Union extends true ? Merge<T, Head> : MergeNonUnion<T, Head>, Tail, Union> : Union extends true ? Merge<T, Head> : MergeNonUnion<T, Head> : T : T;
-declare function merge<T extends Record<string, unknown>, U extends Record<string, unknown>>(target: T, source: U, opts: {
-    union: true;
-}): Merge<T, U>;
-declare function merge<T extends Record<string, unknown>, U extends Record<string, unknown>>(target: T, source: U, opts?: {
-    union?: false;
-}): MergeNonUnion<T, U>;
-declare function merge<T extends Record<string, unknown>, U extends Record<string, unknown>[]>(target: T, sources: [...U], opts: {
-    union: true;
-}): MergeArray<T, U, true>;
-declare function merge<T extends Record<string, unknown>, U extends Record<string, unknown>[]>(target: T, sources: [...U], opts?: {
-    union?: false;
-}): MergeArray<T, U, false>;
+type Merged<T extends Record<string, unknown>, U extends Record<string, unknown> | Record<string, unknown>[], Union extends boolean> = U extends any[] ? MergeArray<T, U, Union> : Union extends true ? Merge<T, U> : MergeNonUnion<T, U>;
+/**
+ * Deep merge two objects together while ensuring nested objects also get merged,
+ * take note: this does not merge onto passed objects by reference but instead
+ * returns a new object
+ *
+ * @param {Record<string,unknown>} target - Base Object
+ * @param {Record<string,unknown>|Record<string,unknown>[]} source - (default={}) Object to merge onto base object
+ */
+declare function merge<T extends Record<string, unknown>, U extends Record<string, unknown> | [Record<string, unknown>, ...Record<string, unknown>[]], Union extends boolean = false>(target: T, source: U, opts?: {
+    /**
+     * Defaults to false, when passed as true it ensures all keys from both objects
+     * are available in the merged object
+     */
+    union?: Union;
+}): Merged<T, U, Union>;
 export { merge, merge as default };

package/object/merge.js

@@ -18,7 +18,7 @@ function innerMerge(target, source, UNION) {
     }
     return target;
 }
-function merge(target, source = {}, opts = {}) {
+function merge(target, source, opts = {}) {
     if (Object.prototype.toString.call(target) !== PROTO_OBJ)
         throw new Error('object/merge: Please ensure valid target/source is passed');
     const union = opts?.union === true;
@@ -26,7 +26,7 @@ function merge(target, source = {}, opts = {}) {
     let acc = { ...target };
     for (let i = 0; i < sources.length; i++) {
         const el = sources[i];
-        if (Object.prototype.toString.call(el) !== PROTO_OBJ)
+        if (!el || Object.prototype.toString.call(el) !== PROTO_OBJ)
             continue;
         acc = innerMerge(acc, el, union);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyriestudios/utils",
-    "version": "12.33.0",
+    "version": "12.34.0",
     "description": "A collection of single-function utilities for common tasks",
     "author": {
         "name": "Peter Vermeulen",
@@ -158,6 +158,18 @@
             "default": "./array/mapFn.js",
             "types": "./array/mapFn.d.ts"
         },
+        "./array/mapFnAsMap": {
+            "import": {
+                "default": "./array/mapFnAsMap.js",
+                "types": "./array/mapFnAsMap.d.ts"
+            },
+            "require": {
+                "default": "./array/mapFnAsMap.js",
+                "types": "./array/mapFnAsMap.d.ts"
+            },
+            "default": "./array/mapFnAsMap.js",
+            "types": "./array/mapFnAsMap.d.ts"
+        },
         "./array/mapKey": {
             "import": {
                 "default": "./array/mapKey.js",
@@ -170,6 +182,18 @@
             "default": "./array/mapKey.js",
             "types": "./array/mapKey.d.ts"
         },
+        "./array/mapKeyAsMap": {
+            "import": {
+                "default": "./array/mapKeyAsMap.js",
+                "types": "./array/mapKeyAsMap.d.ts"
+            },
+            "require": {
+                "default": "./array/mapKeyAsMap.js",
+                "types": "./array/mapKeyAsMap.d.ts"
+            },
+            "default": "./array/mapKeyAsMap.js",
+            "types": "./array/mapKeyAsMap.d.ts"
+        },
         "./array/mapPrimitive": {
             "import": {
                 "default": "./array/mapPrimitive.js",
@@ -686,6 +710,18 @@
             "default": "./hash/guid.js",
             "types": "./hash/guid.d.ts"
         },
+        "./modules/PubSub": {
+            "import": {
+                "default": "./modules/PubSub.js",
+                "types": "./modules/PubSub.d.ts"
+            },
+            "require": {
+                "default": "./modules/PubSub.js",
+                "types": "./modules/PubSub.d.ts"
+            },
+            "default": "./modules/PubSub.js",
+            "types": "./modules/PubSub.d.ts"
+        },
         "./number": {
             "import": {
                 "default": "./number/index.js",
@@ -1108,11 +1144,11 @@
         }
     },
     "devDependencies": {
-        "@types/node": "^22.13.5",
+        "@types/node": "^22.13.10",
         "esbuild-register": "^3.6.0",
-        "eslint": "^9.21.0",
+        "eslint": "^9.22.0",
         "nyc": "^17.1.0",
-        "typescript": "^5.7.3",
-        "typescript-eslint": "^8.25.0"
+        "typescript": "^5.8.2",
+        "typescript-eslint": "^8.26.0"
     }
 }