@valkyriestudios/utils 12.34.0 → 12.36.0

package/LICENSE.md

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2017 Valkyrie Studios (www.valkyriestudios.be)
+Copyright (c) 2017  - present, Peter Vermeulen and @valkyriestudios/utils contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,8 +1,8 @@
 # @valkyriestudios/utils
 
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![CodeCov](https://codecov.io/gh/ValkyrieStudios/utils/branch/main/graph/badge.svg)](https://codecov.io/gh/ValkyrieStudios/utils)
-[![Test](https://github.com/ValkyrieStudios/utils/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ValkyrieStudios/utils/actions/workflows/test.yml)
-[![Lint](https://github.com/ValkyrieStudios/utils/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/ValkyrieStudios/utils/actions/workflows/lint.yml)
+[![CI](https://github.com/ValkyrieStudios/utils/actions/workflows/ci.yml/badge.svg)](https://github.com/ValkyrieStudios/utils/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/ValkyrieStudios/utils/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/ValkyrieStudios/utils/actions/workflows/github-code-scanning/codeql)
 [![npm](https://img.shields.io/npm/v/@valkyriestudios/utils.svg)](https://www.npmjs.com/package/@valkyriestudios/utils)
 [![npm](https://img.shields.io/npm/dm/@valkyriestudios/utils.svg)](https://www.npmjs.com/package/@valkyriestudios/utils)
@@ -30,7 +30,7 @@ isNotEmptyArray([]); // FALSE
 isNotEmptyArray([0, 1, 2]); // TRUE
 ```
 
-### array/mapKey(val:Record[], key:string, opts?:{merge?:boolean;filter_fn?:(el:T) => boolean})
+### array/mapKey(val:Record[], key:string, opts?:{merge?:boolean;filter_fn?:(el:T) => boolean;transform_fn?:(el:T) => U})
 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
@@ -110,7 +110,7 @@ mapKey([
     {name: 'Alana', isActive: true},
     {uid: 87, name: 'Josh', isActive: false},
     {uid: 12, name: 'Farah', isActive: false},
-], 'uid', {merge: true})
+], 'uid', {merge: true, filter_fn: el => el.isActive})
 /* Expected output: */
 {
     12: {uid: 12, name: 'Peter', isActive: true},
@@ -118,6 +118,24 @@ mapKey([
 }
 ```
 
+also allows transforming objects at the same time with a custom transform_fn. Take Note that all of these operations are run in O(n):
+```typescript
+import mapKey from '@valkyriestudios/utils/array/mapKey';
+mapKey([
+    {uid: 12, name: 'Peter', isActive: true},
+    {uid: 15, name: 'Jonas', dob: '2022-02-07', isActive: true},
+    {uid: 15, name: 'Bob', isActive: false},
+    {name: 'Alana', isActive: true},
+    {uid: 87, name: 'Josh', isActive: false},
+    {uid: 12, name: 'Farah', isActive: false},
+], 'uid', {merge: true, filter_fn: el => el.isActive, transform_fn: el => pick(el, ["name"])})
+/* Expected output: */
+{
+    12: {name: 'Peter'},
+    15: {name: 'Jonas'},
+}
+```
+
 ### 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
 
@@ -560,6 +578,7 @@ Format a date according to a spec/locale and zone
 | `L` | Locale-Specific date | 15 jul 2024 |
 | `t` | Locale-specific short time | 10:28 AM |
 | `T` | Locale-specific time with seconds | 10:28:30 AM |
+| `ISO` | Alias for `YYYY-MM-DD[T]HH:mm:ss.SSS[Z]` | 2025-03-16T14:24:59.010Z |
 
 **Additional**:
 Format has several additional functions defined which help usage inside of an ecosystem (eg: webapp) by **overriding the global defaults** used by format.
@@ -1111,6 +1130,182 @@ Both synchronous and asynchronous errors are logged via the custom logger (if pr
 - **Flexibility:**
 The storage behavior can be controlled globally through the constructor or overridden for individual publish calls.
 
+### modules/Scheduler
+A Lightweight scheduler module that works with a cron-like syntax and can be easily configured/run at runtime.
+
+**Take Note**: This does **not replace** cron, it is a module that runs at runtime and could be used to simulate cron-like behavior, but it is **not a replacement**.
+
+##### Usage
+Supports baseline operation:
+```typescript
+import { Scheduler } from '@valkyriestudios/utils/modules/Scheduler';
+import * as Handlers from "..."; /* Example methods */
+
+const mySchedule = new Scheduler({name: 'MyScheduler'});
+
+mySchedule.add({schedule: '0 * * * *', name: 'send_emails', fn: Handlers.SendEmails});
+mySchedule.add({schedule: '0 */3 * * *', name: 'cleanup', fn: Handlers.Cleanup});
+mySchedule.add({schedule: '0,15,30,45 * * * *', name: 'synchronize', fn: Handlers.Synchronize});
+await mySchedule.run();
+```
+
+Let's say you need to send something out in different timezones:
+```typescript
+import { Scheduler } from '@valkyriestudios/utils/modules/Scheduler';
+import * as Handlers from "..."; /* Example methods */
+
+...
+
+const mySchedule = new Scheduler({name: 'MyScheduler'});
+
+/* This is an example */
+for (const user of users) {
+    mySchedule.add({
+        schedule: '0 * * * *',
+        name: 'send_emails',
+        fn: Handlers.SendEmail,
+        timeZone: user.timeZone, /* Given a user has a timezone */
+    });
+}
+
+await mySchedule.run();
+```
+
+Too much flooding! let's turn off parallelization and have it run them in linear fashion:
+```typescript
+import { Scheduler } from '@valkyriestudios/utils/modules/Scheduler';
+import * as Handlers from "..."; /* Example methods */
+
+...
+
+const mySchedule = new Scheduler({
+    name: 'MyScheduler',
+    parallel: false, /* By setting parallel to false we will ensure one at a time */
+});
+
+/* This is an example */
+for (const user of users) {
+    mySchedule.add({
+        schedule: '0 * * * *',
+        name: 'send_emails',
+        fn: Handlers.SendEmail,
+        timeZone: user.timeZone, /* Given a user has a timezone */
+    });
+}
+
+await mySchedule.run();
+```
+
+Okay we can actually send 3 at a time, let's set that up:
+```typescript
+import { Scheduler } from '@valkyriestudios/utils/modules/Scheduler';
+import * as Handlers from "..."; /* Example methods */
+
+...
+
+const mySchedule = new Scheduler({
+    name: 'MyScheduler',
+    parallel: 3, /* By setting parallel to a specific integer above 0 we will run X jobs in parallel at a time */
+});
+
+/* This is an example */
+for (const user of users) {
+    mySchedule.add({
+        schedule: '0 * * * *',
+        name: 'send_emails',
+        fn: Handlers.SendEmail,
+        timeZone: user.timeZone, /* Given a user has a timezone */
+    });
+}
+
+await mySchedule.run();
+```
+
+Oh no the emails aren't going out to the right user because we didn't pass our data:
+```typescript
+import { Scheduler } from '@valkyriestudios/utils/modules/Scheduler';
+import * as Handlers from "..."; /* Example methods */
+
+...
+
+const mySchedule = new Scheduler({
+    name: 'MyScheduler',
+    parallel: 3,
+});
+
+/* This is an example */
+for (const user of users) {
+    mySchedule.add({
+        schedule: '0 * * * *',
+        name: 'send_emails',
+        fn: Handlers.SendEmail,
+        timeZone: user.timeZone, /* Given a user has a timezone */
+        data: user, /* You will have automatic type hinting on this with the first val of SendEmail handler */
+    });
+}
+
+await mySchedule.run();
+```
+
+I want this to run continuously so that I can just leave it running on a server:
+```typescript
+import { Scheduler } from '@valkyriestudios/utils/modules/Scheduler';
+import * as Handlers from "..."; /* Example methods */
+
+...
+
+const mySchedule = new Scheduler({
+    name: 'MyScheduler',
+    parallel: 3,
+    auto: true, /* By enabling this the schedule will automatically check once per minute which ones it needs to run */
+});
+
+/* This is an example */
+for (const user of users) {
+    mySchedule.add({
+        schedule: '0 * * * *',
+        name: 'send_emails',
+        fn: Handlers.SendEmail,
+        timeZone: user.timeZone,
+        data: user,
+    });
+}
+
+await mySchedule.run();
+```
+
+##### API Overview
+- **new Scheduler(options?: { logger?: LogFn; name?: string; timeZone?: string|null; parallel?:boolean|number; auto?: boolean })**
+Creates a new Scheduler instance.
+-- **logger (optional)**: Custom logging function to capture errors.
+-- **name (optional)**: A non‑empty string to name the instance.
+-- **timeZone (optional)**: (default=local timezone) The default timeZone the scheduler is run in
+-- **parallel (optional)**: (default=true) Scheduler will run jobs that need to run in parallel, set to false to run linear, set to a number to run X jobs in parallel
+-- **auto (optional)**: (default=false) Set to true to automatically run the schedule every 60 seconds
+- **add(job: {name:string; schedule:string; fn: Function; timeZone?: string | null; data?: unknown}): boolean**
+Add a job to the schedule
+-- If a timeZone is passed we will automatically check against local time in that timeZone on whether or not the job needs to run.
+-- If a data object is passed we will pass this data object to the provided function when run.
+-- Schedule uses cron-like schedule and is compatible with most of the standard cron formats.
+- **remove(name:string|string[]):void**
+Removes one or multiple jobs by name from the schedule.
+- **run(): Promise<void>**
+Runs the schedule.
+- **stopAutomaticRun():void**
+Stops automatic running (if enabled)
+- **startAutomaticRun():void**
+Start automatic running (if not enabled)
+- **static isCronSchedule(val:string):boolean**
+Returns true if the provided value is a valid cron schedule, false if it isnt
+- **static cronShouldRun(val:string, timeZone: string|null):boolean**
+Given a cron schedule and an optional timeZone returns whether or not the cron schedule should be run now
+
+##### Notes:
+- **cron:**
+This is not a cron replacement but rather a module that can be used at runtime to handle cron-like schedules in a seamless way.
+- **auto:**
+If running this on a system that is replicated it **is highly advised** to not turn on automatic runs but rather build a way to trigger the schedule on a single instance into your networking.
+
 ### number/is(val:unknown)
 Check if a variable is a number
 ```typescript

package/array/index.d.ts

@@ -1,14 +1,14 @@
-import { dedupe } from './dedupe';
-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, mapFnAsMap, mapKey, mapKeyAsMap, mapPrimitive, groupBy, shuffle, split, sort };
+export { dedupe } from './dedupe';
+export { join } from './join';
+export { mapFn } from './mapFn';
+export { mapFnAsMap } from './mapFnAsMap';
+export { mapKey } from './mapKey';
+export { mapKeyAsMap } from './mapKeyAsMap';
+export { mapPrimitive } from './mapPrimitive';
+export { groupBy } from './groupBy';
+export { shuffle } from './shuffle';
+export { split } from './split';
+export { sort } from './sort';
+export { isArray } from './is';
+export { isNotEmptyArray } from './isNotEmpty';
+export { isNotEmptyArray as isNeArray } from './isNotEmpty';

package/array/index.js

@@ -1,33 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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");
+exports.isNeArray = exports.isNotEmptyArray = exports.isArray = exports.sort = exports.split = exports.shuffle = exports.groupBy = exports.mapPrimitive = exports.mapKeyAsMap = exports.mapKey = exports.mapFnAsMap = exports.mapFn = exports.join = exports.dedupe = void 0;
+var dedupe_1 = require("./dedupe");
 Object.defineProperty(exports, "dedupe", { enumerable: true, get: function () { return dedupe_1.dedupe; } });
-const is_1 = require("./is");
-Object.defineProperty(exports, "isArray", { enumerable: true, get: function () { return is_1.isArray; } });
-Object.defineProperty(exports, "is", { enumerable: true, get: function () { return is_1.isArray; } });
-const isNotEmpty_1 = require("./isNotEmpty");
-Object.defineProperty(exports, "isNotEmptyArray", { enumerable: true, get: function () { return isNotEmpty_1.isNotEmptyArray; } });
-Object.defineProperty(exports, "isNotEmpty", { enumerable: true, get: function () { return isNotEmpty_1.isNotEmptyArray; } });
-Object.defineProperty(exports, "isNeArray", { enumerable: true, get: function () { return isNotEmpty_1.isNotEmptyArray; } });
-Object.defineProperty(exports, "isNe", { enumerable: true, get: function () { return isNotEmpty_1.isNotEmptyArray; } });
-const join_1 = require("./join");
+var join_1 = require("./join");
 Object.defineProperty(exports, "join", { enumerable: true, get: function () { return join_1.join; } });
-const mapFn_1 = require("./mapFn");
+var mapFn_1 = require("./mapFn");
 Object.defineProperty(exports, "mapFn", { enumerable: true, get: function () { return mapFn_1.mapFn; } });
-const mapFnAsMap_1 = require("./mapFnAsMap");
+var mapFnAsMap_1 = require("./mapFnAsMap");
 Object.defineProperty(exports, "mapFnAsMap", { enumerable: true, get: function () { return mapFnAsMap_1.mapFnAsMap; } });
-const mapKey_1 = require("./mapKey");
+var mapKey_1 = require("./mapKey");
 Object.defineProperty(exports, "mapKey", { enumerable: true, get: function () { return mapKey_1.mapKey; } });
-const mapKeyAsMap_1 = require("./mapKeyAsMap");
+var mapKeyAsMap_1 = require("./mapKeyAsMap");
 Object.defineProperty(exports, "mapKeyAsMap", { enumerable: true, get: function () { return mapKeyAsMap_1.mapKeyAsMap; } });
-const mapPrimitive_1 = require("./mapPrimitive");
+var mapPrimitive_1 = require("./mapPrimitive");
 Object.defineProperty(exports, "mapPrimitive", { enumerable: true, get: function () { return mapPrimitive_1.mapPrimitive; } });
-const groupBy_1 = require("./groupBy");
+var groupBy_1 = require("./groupBy");
 Object.defineProperty(exports, "groupBy", { enumerable: true, get: function () { return groupBy_1.groupBy; } });
-const shuffle_1 = require("./shuffle");
+var shuffle_1 = require("./shuffle");
 Object.defineProperty(exports, "shuffle", { enumerable: true, get: function () { return shuffle_1.shuffle; } });
-const split_1 = require("./split");
+var split_1 = require("./split");
 Object.defineProperty(exports, "split", { enumerable: true, get: function () { return split_1.split; } });
-const sort_1 = require("./sort");
+var sort_1 = require("./sort");
 Object.defineProperty(exports, "sort", { enumerable: true, get: function () { return sort_1.sort; } });
+var is_1 = require("./is");
+Object.defineProperty(exports, "isArray", { enumerable: true, get: function () { return is_1.isArray; } });
+var isNotEmpty_1 = require("./isNotEmpty");
+Object.defineProperty(exports, "isNotEmptyArray", { enumerable: true, get: function () { return isNotEmpty_1.isNotEmptyArray; } });
+var isNotEmpty_2 = require("./isNotEmpty");
+Object.defineProperty(exports, "isNeArray", { enumerable: true, get: function () { return isNotEmpty_2.isNotEmptyArray; } });

package/array/mapFn.d.ts

@@ -1,4 +1,4 @@
-type MapOptions = {
+type MapOptions<T, U = T> = {
     /**
      * Allow merging existing keys or not, if not keys will be overriden if they exist
      * (default=false)
@@ -11,6 +11,11 @@ type MapOptions = {
      *  {12: {uid: 12, b: 'ho'}}
      */
     merge?: boolean;
+    /**
+     * A custom transform function that is applied to each element before mapping.
+     * Its output type `U` becomes the value type of the resulting map.
+     */
+    transform_fn?: (el: T) => U;
 };
 type MapFn<T extends Record<string, any>> = (entry: T) => (string | number | boolean);
 /**
@@ -26,5 +31,5 @@ type MapFn<T extends Record<string, any>> = (entry: T) => (string | number | boo
  * @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 mapFn<T extends Record<string, any>>(arr: T[], fn: MapFn<T>, opts?: MapOptions): Record<string, T>;
+declare function mapFn<T extends Record<string, any>, U extends Record<string, any> = T>(arr: T[], fn: MapFn<T>, opts?: MapOptions<T, U>): Record<string, U>;
 export { mapFn, mapFn as default };

package/array/mapFn.js

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

package/array/mapFnAsMap.d.ts

@@ -1,4 +1,4 @@
-type MapOptions = {
+type MapOptions<T, U = T> = {
     /**
      * Allow merging existing keys or not, if not keys will be overriden if they exist
      * (default=false)
@@ -11,6 +11,11 @@ type MapOptions = {
      *  {12: {uid: 12, b: 'ho'}}
      */
     merge?: boolean;
+    /**
+     * A custom transform function that is applied to each element before mapping.
+     * Its output type `U` becomes the value type of the resulting map.
+     */
+    transform_fn?: (el: T) => U;
 };
 type MapFn<T extends Record<string, any>> = (entry: T) => string | number | null;
 /**
@@ -29,5 +34,5 @@ type MapFn<T extends Record<string, any>> = (entry: T) => string | number | null
  * @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>;
+declare function mapFnAsMap<T extends Record<string, any>, TFN extends MapFn<T>, U extends Record<string, any> = T>(arr: T[], fn: TFN, opts?: MapOptions<T, U>): Map<NonNullable<ReturnType<TFN>>, U>;
 export { mapFnAsMap, mapFnAsMap as default };

package/array/mapFnAsMap.js

@@ -8,15 +8,17 @@ function mapFnAsMap(arr, fn, opts) {
         typeof fn !== 'function')
         return new Map();
     const MERGE = opts?.merge === true;
+    const TRANSFORM_FN = opts?.transform_fn;
     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);
+        if (Number.isFinite(hash) || (typeof hash === 'string' && hash.trim().length)) {
+            const transformed = TRANSFORM_FN ? TRANSFORM_FN(el) : el;
+            map.set(hash, MERGE && map.has(hash) ? (0, merge_1.merge)(map.get(hash), transformed, { union: true }) : transformed);
+        }
     }
     return map;
 }

package/array/mapKey.d.ts

@@ -1,4 +1,4 @@
-type MapOptions<T> = {
+type MapOptions<T, U = T> = {
     /**
      * Allow merging existing keys or not, if not keys will be overriden if they exist
      * (default=false)
@@ -15,6 +15,11 @@ type MapOptions<T> = {
      * Pass a custom filter function which will be run in O(n) while iterating
      */
     filter_fn?: (el: T) => boolean;
+    /**
+     * A custom transformer function to modify each element before mapping.
+     * Its output type `U` becomes the value type of the resulting map.
+     */
+    transform_fn?: (el: T) => U;
 };
 /**
  * Map an object array into a kv-object by passing a common key that exists on the objects. Objects for
@@ -29,5 +34,5 @@ type MapOptions<T> = {
  * @param {string} key - Key to map by
  * @param {MapOptions?} opts - Options object to override built-in defaults
  */
-declare function mapKey<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Record<string, T>;
+declare function mapKey<T extends Record<string, any>, U extends Record<string, any> = T, TKey extends keyof T = string>(arr: T[], key: TKey, opts?: MapOptions<T, U>): Record<string, U>;
 export { mapKey, mapKey as default };

package/array/mapKey.js

@@ -11,13 +11,15 @@ function mapKey(arr, key, opts) {
         return {};
     const FILTER_FN = opts?.filter_fn;
     const MERGE = opts?.merge === true;
+    const TRANSFORMER = opts?.transform_fn;
     const 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[el_key] = (MERGE && el_key in map ? (0, merge_1.merge)(map[el_key], el, { union: true }) : el);
+        if (el_key !== undefined && (!FILTER_FN || FILTER_FN(el))) {
+            const transformed = TRANSFORMER ? TRANSFORMER(el) : el;
+            map[el_key] = MERGE && el_key in map ? (0, merge_1.merge)(map[el_key], transformed, { union: true }) : transformed;
+        }
     }
     return map;
 }

package/array/mapKeyAsMap.d.ts

@@ -1,4 +1,4 @@
-type MapOptions<T> = {
+type MapOptions<T, U = T> = {
     /**
      * Allow merging existing keys or not, if not keys will be overriden if they exist
      * (default=false)
@@ -15,6 +15,11 @@ type MapOptions<T> = {
      * Pass a custom filter function which will be run in O(n) while iterating
      */
     filter_fn?: (el: T) => boolean;
+    /**
+     * A custom transformer function to modify each element before mapping.
+     * Its output type `U` becomes the value type of the resulting map.
+     */
+    transform_fn?: (el: T) => U;
 };
 /**
  * Map an object array into a Map by passing a common key that exists on the objects. Objects for
@@ -32,5 +37,5 @@ type MapOptions<T> = {
  * @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>;
+declare function mapKeyAsMap<T extends Record<string, any>, U extends Record<string, any> = T, TKey extends keyof T = string>(arr: T[], key: TKey, opts?: MapOptions<T, U>): Map<T[TKey], U>;
 export { mapKeyAsMap, mapKeyAsMap as default };

package/array/mapKeyAsMap.js

@@ -11,13 +11,15 @@ function mapKeyAsMap(arr, key, opts) {
         return new Map();
     const FILTER_FN = opts?.filter_fn;
     const MERGE = opts?.merge === true;
+    const TRANSFORMER = opts?.transform_fn;
     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);
+        if (el_key !== undefined && (!FILTER_FN || FILTER_FN(el))) {
+            const transformed = (TRANSFORMER ? TRANSFORMER(el) : el);
+            map.set(el_key, MERGE && map.has(el_key) ? (0, merge_1.merge)(map.get(el_key), transformed, { union: true }) : transformed);
+        }
     }
     return map;
 }