@valkyriestudios/utils 12.34.0 → 12.35.0

package/README.md

@@ -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/PubSub';
+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/PubSub';
+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/PubSub';
+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/PubSub';
+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/PubSub';
+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/PubSub';
+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/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;
 }

package/date/format.js

@@ -178,6 +178,9 @@ function getSpecChain(spec) {
     spec_cache.set(spec, result);
     return result;
 }
+const SPEC_ALIASES = {
+    ISO: 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]',
+};
 function format(val, spec, locale = DEFAULT_LOCALE, zone = DEFAULT_TZ, sow = DEFAULT_SOW) {
     const n_val = (0, convertToDate_1.convertToDate)(val);
     if (n_val === null)
@@ -188,7 +191,7 @@ function format(val, spec, locale = DEFAULT_LOCALE, zone = DEFAULT_TZ, sow = DEF
         throw new TypeError('format: locale must be a string');
     if (typeof zone !== 'string')
         throw new TypeError('format: zone must be a string');
-    const n_spec = getSpecChain(spec);
+    const n_spec = getSpecChain(SPEC_ALIASES[spec] || spec);
     if (!n_spec)
         return n_val.toISOString();
     const d = toZone(n_val, zone);

package/index.d.ts

@@ -52,35 +52,39 @@ declare module "object/merge" {
     export { merge, merge as default };
 }
 declare module "array/mapFn" {
-    type MapOptions = {
+    type MapOptions<T, U = T> = {
         merge?: boolean;
+        transform_fn?: (el: T) => U;
     };
     type MapFn<T extends Record<string, any>> = (entry: T) => (string | number | boolean);
-    function mapFn<T extends Record<string, any>>(arr: T[], fn: MapFn<T>, opts?: MapOptions): Record<string, T>;
+    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 };
 }
 declare module "array/mapFnAsMap" {
-    type MapOptions = {
+    type MapOptions<T, U = T> = {
         merge?: boolean;
+        transform_fn?: (el: T) => U;
     };
     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>;
+    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 };
 }
 declare module "array/mapKey" {
-    type MapOptions<T> = {
+    type MapOptions<T, U = T> = {
         merge?: boolean;
         filter_fn?: (el: T) => boolean;
+        transform_fn?: (el: T) => U;
     };
-    function mapKey<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Record<string, T>;
+    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 };
 }
 declare module "array/mapKeyAsMap" {
-    type MapOptions<T> = {
+    type MapOptions<T, U = T> = {
         merge?: boolean;
         filter_fn?: (el: T) => boolean;
+        transform_fn?: (el: T) => U;
     };
-    function mapKeyAsMap<T extends Record<string, any>, TKey extends keyof T>(arr: T[], key: TKey, opts?: MapOptions<T>): Map<T[TKey], T>;
+    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 };
 }
 declare module "array/mapPrimitive" {
@@ -691,3 +695,54 @@ declare module "modules/PubSub" {
     }
     export { PubSub, PubSub as default };
 }
+declare module "modules/Scheduler" {
+    export type LogObject = {
+        name: string;
+        msg: string;
+        on: Date;
+        data?: unknown;
+        err: Error;
+    };
+    export type LogFn = (log: LogObject) => void;
+    export type SchedulerOptions = {
+        logger?: LogFn;
+        name?: string;
+        timeZone?: string | null;
+        parallel?: boolean | number;
+        auto?: boolean;
+    };
+    type SchedulerJobFn = ((data: any) => void | Promise<void>);
+    type SchedulerJobFnDefault = (data: unknown) => void | Promise<void>;
+    export type SchedulerJob<T extends SchedulerJobFn = SchedulerJobFnDefault> = {
+        name: string;
+        schedule: string;
+        timeZone?: string | null;
+        fn: T;
+        data?: Parameters<T>[0];
+    };
+    class Scheduler {
+        #private;
+        constructor(options?: SchedulerOptions);
+        get name(): string;
+        get timeZone(): string | null;
+        get parallel(): number | boolean;
+        get isAutomatic(): boolean;
+        get jobs(): {
+            data?: {} | undefined;
+            name: string;
+            schedule: string;
+            timeZone: string | null;
+        }[];
+        add<T extends SchedulerJobFn>(job: SchedulerJob<T>): boolean;
+        remove(name: string | string[]): void;
+        run(): Promise<void>;
+        stopAutomaticRun(): void;
+        startAutomaticRun(): void;
+        private static convertToMap;
+        private static getTimeParts;
+        private static checkTimeAgainstMap;
+        static isCronSchedule(raw: string): boolean;
+        static cronShouldRun(schedule: string, timeZone?: string | null): boolean;
+    }
+    export { Scheduler, Scheduler as default };
+}

package/modules/PubSub.js

@@ -163,7 +163,7 @@ _PubSub_subscriptions = new WeakMap(), _PubSub_name = new WeakMap(), _PubSub_log
         const out = sub.run(data);
         if (sub.once)
             map.subscribers.delete(client_id);
-        if (out && (0, is_2.isFunction)(out?.catch) && (0, is_2.isFunction)(out?.then)) {
+        if ((0, is_2.isFunction)(out?.catch) && (0, is_2.isFunction)(out?.then)) {
             Promise.resolve(out).catch(err => {
                 __classPrivateFieldGet(this, _PubSub_log, "f").call(this, {
                     name: __classPrivateFieldGet(this, _PubSub_name, "f"),

package/modules/Scheduler.d.ts

@@ -0,0 +1,139 @@
+export type LogObject = {
+    name: string;
+    msg: string;
+    on: Date;
+    data?: unknown;
+    err: Error;
+};
+export type LogFn = (log: LogObject) => void;
+export type SchedulerOptions = {
+    /**
+     * Custom logger function, will receive an instance of LogObject when an error is thrown
+     */
+    logger?: LogFn;
+    /**
+     * Name of the pubsub (used in logs as well)
+     */
+    name?: string;
+    /**
+     * Default timeZone to use
+     */
+    timeZone?: string | null;
+    /**
+     * Whether or not to run async jobs in parallel or not (defaults to true)
+     */
+    parallel?: boolean | number;
+    /**
+     * If set to true will automatically run the schedule every 60 seconds (defaults to false)
+     */
+    auto?: boolean;
+};
+type SchedulerJobFn = ((data: any) => void | Promise<void>);
+type SchedulerJobFnDefault = (data: unknown) => void | Promise<void>;
+export type SchedulerJob<T extends SchedulerJobFn = SchedulerJobFnDefault> = {
+    name: string;
+    schedule: string;
+    timeZone?: string | null;
+    fn: T;
+    data?: Parameters<T>[0];
+};
+/**
+ * The Scheduler class.
+ *
+ * Instantiate this module, add multiple scheduled tasks,
+ * and then call run() to execute those whose cron schedule matches the current time.
+ */
+declare class Scheduler {
+    #private;
+    constructor(options?: SchedulerOptions);
+    /**
+     * Getter returning the name of the scheduler.
+     */
+    get name(): string;
+    /**
+     * Getter returning the scheduler's timeZone setting
+     */
+    get timeZone(): string | null;
+    /**
+     * Getter returning the scheduler's parallel setting
+     */
+    get parallel(): number | boolean;
+    /**
+     * Getter returning whether or not the schedule is automatically running every 60 seconds
+     */
+    get isAutomatic(): boolean;
+    /**
+     * Returns the configured jobs array (bar fn/internals) to allow for introspection and debugging
+     */
+    get jobs(): {
+        data?: {} | undefined;
+        name: string;
+        schedule: string;
+        timeZone: string | null;
+    }[];
+    /**
+     * Add a job to the scheduler.
+     *
+     * @param {SchedulerJob} job - Raw job object to be added to the jobs list
+     */
+    add<T extends SchedulerJobFn>(job: SchedulerJob<T>): boolean;
+    /**
+     * Remove a job from the schedule by name
+     *
+     * @param {string|string[]} name - Name or array of names of the job(s) to remove
+     */
+    remove(name: string | string[]): void;
+    /**
+     * Iterate through all added jobs and execute those that should run at the current time.
+     */
+    run(): Promise<void>;
+    /**
+     * Stops automatic running of the schedule
+     */
+    stopAutomaticRun(): void;
+    /**
+     * Starts automatic running of the schedule
+     */
+    startAutomaticRun(): void;
+    /**
+     * MARK: Private
+     */
+    /**
+     * Helper which converts a cron schedule to a map for easy processing down the line
+     *
+     * @param {string} schedule - Raw cron schedule to process
+     */
+    private static convertToMap;
+    /**
+     * Returns the time in the provided zone as an object of parts
+     *
+     * @param {Date} date - Date to get parts from
+     * @param {string|null} timeZone - Zone to use
+     */
+    private static getTimeParts;
+    /**
+     * Checks the processed time against the processed map and returns true/false if matches or not
+     *
+     * @param {CronMap} map - Cron Map
+     * @param {TimeMap} time - Time Map
+     */
+    private static checkTimeAgainstMap;
+    /**
+     * MARK: Static
+     */
+    /**
+     * Checks if a string is a valid cron schedule
+     *
+     * @param {string} raw - Value to verify is a valid schedule
+     */
+    static isCronSchedule(raw: string): boolean;
+    /**
+     * Check if a given cron schedule should run at the current (or specified) time.
+     *
+     * @param schedule A cron string (5 fields: minute, hour, day of month, month, day of week).
+     * @param timeZone Optional IANA time zone string.
+     * @returns true if the schedule matches the current time.
+     */
+    static cronShouldRun(schedule: string, timeZone?: string | null): boolean;
+}
+export { Scheduler, Scheduler as default };

package/modules/Scheduler.js

@@ -0,0 +1,347 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Scheduler_jobs, _Scheduler_name, _Scheduler_log, _Scheduler_timeZone, _Scheduler_parallel, _Scheduler_timer;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.Scheduler = void 0;
+const format_1 = require("../date/format");
+const toUTC_1 = require("../date/toUTC");
+const isNotEmpty_1 = require("../string/isNotEmpty");
+const is_1 = require("../function/is");
+const number_1 = require("../number");
+const object_1 = require("../object");
+const function_1 = require("../function");
+const boolean_1 = require("../boolean");
+const array_1 = require("../array");
+const RGX_DIGITS = /^\d+$/;
+const LIMITS = {
+    minute: [0, 59],
+    hour: [0, 23],
+    day_of_month: [1, 31],
+    month: [1, 12],
+    day_of_week: [0, 6],
+};
+function convertPart(part, min, max) {
+    if (part === '*')
+        return '*';
+    const set = new Set();
+    if (part.indexOf('/') > -1) {
+        const [base, raw_step] = part.split('/', 2);
+        const step = parseInt(raw_step, 10);
+        let start;
+        let end = max;
+        if (base === '*') {
+            start = min;
+        }
+        else if (base.indexOf('-') > -1) {
+            const chunks = base.split('-', 2);
+            start = parseInt(chunks[0], 10);
+            end = parseInt(chunks[1], 10);
+        }
+        else {
+            start = parseInt(base, 10);
+        }
+        for (let i = start; i <= end; i += step)
+            set.add(i);
+    }
+    else if (part.indexOf('-') > -1) {
+        const chunks = part.split('-', 2);
+        const start = parseInt(chunks[0], 10);
+        const end = parseInt(chunks[1], 10);
+        for (let i = start; i <= end; i++)
+            set.add(i);
+    }
+    else if (part.indexOf(',') > -1) {
+        const chunks = part.split(',');
+        for (let i = 0; i < chunks.length; i++)
+            set.add(parseInt(chunks[i], 10));
+    }
+    else {
+        set.add(parseInt(part, 10));
+    }
+    return set;
+}
+function isCronSubpart(part, min, max) {
+    if (!RGX_DIGITS.test(part))
+        return null;
+    const normalized = parseFloat(part);
+    if (!(0, number_1.isIntegerBetween)(normalized, min, max))
+        return null;
+    return normalized;
+}
+function isCronPart(part, min, max) {
+    if (part === '*') {
+        return true;
+    }
+    else if (part.indexOf('/') > -1) {
+        const [base, stepStr] = part.split('/', 2);
+        const step = parseFloat(stepStr);
+        if (!(0, number_1.isIntegerAbove)(step, 0) || !(0, number_1.isIntegerBetween)(step, min, max))
+            return false;
+        if (base === '*')
+            return true;
+        let start = min;
+        let end = max;
+        if (base.indexOf('-') > -1) {
+            const chunks = base.split('-');
+            if (chunks.length !== 2)
+                return false;
+            start = isCronSubpart(chunks[0], min, max);
+            end = isCronSubpart(chunks[1], min, max);
+        }
+        else {
+            start = isCronSubpart(base, min, max);
+        }
+        if (start === null || end === null)
+            return false;
+        if (start > end)
+            return false;
+        if (step > (end - start))
+            return false;
+        return true;
+    }
+    else if (part.indexOf('-') > -1) {
+        const chunks = part.split('-');
+        if (chunks.length !== 2)
+            return false;
+        const start = isCronSubpart(chunks[0], min, max);
+        const end = isCronSubpart(chunks[1], min, max);
+        if (start === null || end === null)
+            return false;
+        return start < end;
+    }
+    else if (part.indexOf(',') > -1) {
+        const chunks = part.split(',');
+        for (let i = 0; i < chunks.length; i++) {
+            if (isCronSubpart(chunks[i], min, max) === null)
+                return false;
+        }
+        return true;
+    }
+    else {
+        return isCronSubpart(part, min, max) !== null;
+    }
+}
+class Scheduler {
+    constructor(options = {}) {
+        _Scheduler_jobs.set(this, []);
+        _Scheduler_name.set(this, 'Scheduler');
+        _Scheduler_log.set(this, function_1.noop);
+        _Scheduler_timeZone.set(this, null);
+        _Scheduler_parallel.set(this, true);
+        _Scheduler_timer.set(this, null);
+        if (!(0, object_1.isObject)(options))
+            throw new Error('Scheduler@ctor: options should be an object');
+        if ('logger' in options) {
+            if (!(0, is_1.isFunction)(options.logger))
+                throw new Error('Scheduler@ctor: logger should be a function');
+            __classPrivateFieldSet(this, _Scheduler_log, options.logger, "f");
+        }
+        if ('name' in options) {
+            if (!(0, isNotEmpty_1.isNotEmptyString)(options.name))
+                throw new Error('Scheduler@ctor: name should be a non-empty string');
+            __classPrivateFieldSet(this, _Scheduler_name, options.name.trim(), "f");
+        }
+        if ('timeZone' in options) {
+            if (options.timeZone !== null &&
+                !(0, isNotEmpty_1.isNotEmptyString)(options.timeZone))
+                throw new Error('Scheduler@ctor: timeZone should be null or a non-empty string');
+            __classPrivateFieldSet(this, _Scheduler_timeZone, options.timeZone, "f");
+        }
+        if ('parallel' in options) {
+            if (!(0, boolean_1.isBoolean)(options.parallel) &&
+                !(0, number_1.isIntegerAbove)(options.parallel, 0))
+                throw new Error('Scheduler@ctor: parallel should be passed as a boolean or int above 0');
+            __classPrivateFieldSet(this, _Scheduler_parallel, options.parallel, "f");
+        }
+        if (options.auto === true)
+            this.startAutomaticRun();
+    }
+    get name() {
+        return __classPrivateFieldGet(this, _Scheduler_name, "f");
+    }
+    get timeZone() {
+        return __classPrivateFieldGet(this, _Scheduler_timeZone, "f");
+    }
+    get parallel() {
+        return __classPrivateFieldGet(this, _Scheduler_parallel, "f");
+    }
+    get isAutomatic() {
+        return __classPrivateFieldGet(this, _Scheduler_timer, "f") !== null;
+    }
+    get jobs() {
+        const acc = [];
+        for (let i = 0; i < __classPrivateFieldGet(this, _Scheduler_jobs, "f").length; i++) {
+            const { name, schedule, timeZone, data = null } = __classPrivateFieldGet(this, _Scheduler_jobs, "f")[i];
+            acc.push({
+                name,
+                schedule,
+                timeZone,
+                ...data !== null && { data: { ...data } },
+            });
+        }
+        return acc;
+    }
+    add(job) {
+        try {
+            if (!Scheduler.isCronSchedule(job?.schedule))
+                throw new Error(`${__classPrivateFieldGet(this, _Scheduler_name, "f")}@add: Invalid cron schedule`);
+            if (!(0, is_1.isFunction)(job.fn))
+                throw new Error(`${__classPrivateFieldGet(this, _Scheduler_name, "f")}@add: Invalid function for job`);
+            if (!(0, isNotEmpty_1.isNotEmptyString)(job.name))
+                throw new Error(`${__classPrivateFieldGet(this, _Scheduler_name, "f")}@add: Invalid name for job`);
+            if ('data' in job && !(0, object_1.isObject)(job.data))
+                throw new Error(`${__classPrivateFieldGet(this, _Scheduler_name, "f")}@add: Job data should be an object`);
+            __classPrivateFieldGet(this, _Scheduler_jobs, "f").push({
+                name: job.name,
+                schedule: job.schedule,
+                fn: job.fn,
+                timeZone: (0, isNotEmpty_1.isNotEmptyString)(job.timeZone) ? job.timeZone : __classPrivateFieldGet(this, _Scheduler_timeZone, "f"),
+                map: Scheduler.convertToMap(job.schedule),
+                ...job.data ? { data: job.data } : {},
+            });
+            return true;
+        }
+        catch (err) {
+            __classPrivateFieldGet(this, _Scheduler_log, "f").call(this, {
+                name: __classPrivateFieldGet(this, _Scheduler_name, "f"),
+                msg: err.message,
+                on: new Date(),
+                data: job,
+                err: err,
+            });
+            return false;
+        }
+    }
+    remove(name) {
+        const names = new Set((0, isNotEmpty_1.isNotEmptyString)(name) ? [name] : Array.isArray(name) ? name : []);
+        const jobs = [];
+        for (let i = 0; i < __classPrivateFieldGet(this, _Scheduler_jobs, "f").length; i++) {
+            const el = __classPrivateFieldGet(this, _Scheduler_jobs, "f")[i];
+            if (!names.has(el.name))
+                jobs.push(el);
+        }
+        __classPrivateFieldSet(this, _Scheduler_jobs, jobs, "f");
+    }
+    async run() {
+        const promises = [];
+        for (let i = 0; i < __classPrivateFieldGet(this, _Scheduler_jobs, "f").length; i++) {
+            const job = __classPrivateFieldGet(this, _Scheduler_jobs, "f")[i];
+            const time = Scheduler.getTimeParts(new Date(), job.timeZone);
+            if (Scheduler.checkTimeAgainstMap(job.map, time)) {
+                try {
+                    if (__classPrivateFieldGet(this, _Scheduler_parallel, "f")) {
+                        promises.push(job);
+                    }
+                    else {
+                        await job.fn(job.data);
+                    }
+                }
+                catch (err) {
+                    __classPrivateFieldGet(this, _Scheduler_log, "f").call(this, {
+                        name: __classPrivateFieldGet(this, _Scheduler_name, "f"),
+                        msg: `${job.name}: ${err.message}`,
+                        on: new Date(),
+                        data: (0, object_1.pick)(job, ['schedule', 'timeZone', 'name', 'data']),
+                        err,
+                    });
+                }
+            }
+        }
+        if (__classPrivateFieldGet(this, _Scheduler_parallel, "f") && promises.length) {
+            const batches = __classPrivateFieldGet(this, _Scheduler_parallel, "f") === true
+                ? [promises]
+                : (0, array_1.split)(promises, __classPrivateFieldGet(this, _Scheduler_parallel, "f"));
+            for (const batch of batches) {
+                await Promise.allSettled(batch.map(el => (async () => {
+                    try {
+                        await el.fn(el.data);
+                    }
+                    catch (err) {
+                        __classPrivateFieldGet(this, _Scheduler_log, "f").call(this, {
+                            name: __classPrivateFieldGet(this, _Scheduler_name, "f"),
+                            msg: `${el.name}: ${err.message}`,
+                            on: new Date(),
+                            data: (0, object_1.pick)(el, ['schedule', 'timeZone', 'name', 'data']),
+                            err: err,
+                        });
+                    }
+                })()));
+            }
+        }
+    }
+    stopAutomaticRun() {
+        if (!__classPrivateFieldGet(this, _Scheduler_timer, "f"))
+            return;
+        clearInterval(__classPrivateFieldGet(this, _Scheduler_timer, "f"));
+        __classPrivateFieldSet(this, _Scheduler_timer, null, "f");
+    }
+    startAutomaticRun() {
+        this.stopAutomaticRun();
+        __classPrivateFieldSet(this, _Scheduler_timer, setInterval(this.run.bind(this), 60000), "f");
+    }
+    static convertToMap(schedule) {
+        const parts = schedule.split(' ');
+        return {
+            minute: convertPart(parts[0], LIMITS.minute[0], LIMITS.minute[1]),
+            hour: convertPart(parts[1], LIMITS.hour[0], LIMITS.hour[1]),
+            day_of_month: convertPart(parts[2], LIMITS.day_of_month[0], LIMITS.day_of_month[1]),
+            month: convertPart(parts[3], LIMITS.month[0], LIMITS.month[1]),
+            day_of_week: convertPart(parts[4], LIMITS.day_of_week[0], LIMITS.day_of_week[1]),
+        };
+    }
+    static getTimeParts(date, timeZone) {
+        const now = (0, toUTC_1.toUTC)(timeZone !== null
+            ? new Date((0, format_1.format)(date, 'ISO', 'en-US', timeZone))
+            : date);
+        return {
+            minute: now.getUTCMinutes(),
+            hour: now.getUTCHours(),
+            day_of_month: now.getUTCDate(),
+            month: now.getUTCMonth() + 1,
+            day_of_week: now.getUTCDay(),
+        };
+    }
+    static checkTimeAgainstMap(map, time) {
+        const { minute, hour, day_of_month, month, day_of_week } = map;
+        if (minute !== '*' && !minute.has(time.minute))
+            return false;
+        if (hour !== '*' && !hour.has(time.hour))
+            return false;
+        if (day_of_month !== '*' && !day_of_month.has(time.day_of_month))
+            return false;
+        if (month !== '*' && !month.has(time.month))
+            return false;
+        if (day_of_week !== '*' && !day_of_week.has(time.day_of_week))
+            return false;
+        return true;
+    }
+    static isCronSchedule(raw) {
+        if (!(0, isNotEmpty_1.isNotEmptyString)(raw))
+            return false;
+        const parts = raw.split(' ');
+        return (parts.length === 5 &&
+            isCronPart(parts[0], LIMITS.minute[0], LIMITS.minute[1]) &&
+            isCronPart(parts[1], LIMITS.hour[0], LIMITS.hour[1]) &&
+            isCronPart(parts[2], LIMITS.day_of_month[0], LIMITS.day_of_month[1]) &&
+            isCronPart(parts[3], LIMITS.month[0], LIMITS.month[1]) &&
+            isCronPart(parts[4], LIMITS.day_of_week[0], LIMITS.day_of_week[1]));
+    }
+    static cronShouldRun(schedule, timeZone = null) {
+        if (!Scheduler.isCronSchedule(schedule))
+            return false;
+        return Scheduler.checkTimeAgainstMap(Scheduler.convertToMap(schedule), Scheduler.getTimeParts(new Date(), (0, isNotEmpty_1.isNotEmptyString)(timeZone) ? timeZone : null));
+    }
+}
+exports.Scheduler = Scheduler;
+exports.default = Scheduler;
+_Scheduler_jobs = new WeakMap(), _Scheduler_name = new WeakMap(), _Scheduler_log = new WeakMap(), _Scheduler_timeZone = new WeakMap(), _Scheduler_parallel = new WeakMap(), _Scheduler_timer = new WeakMap();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyriestudios/utils",
-    "version": "12.34.0",
+    "version": "12.35.0",
     "description": "A collection of single-function utilities for common tasks",
     "author": {
         "name": "Peter Vermeulen",
@@ -722,6 +722,18 @@
             "default": "./modules/PubSub.js",
             "types": "./modules/PubSub.d.ts"
         },
+        "./modules/Scheduler": {
+            "import": {
+                "default": "./modules/Scheduler.js",
+                "types": "./modules/Scheduler.d.ts"
+            },
+            "require": {
+                "default": "./modules/Scheduler.js",
+                "types": "./modules/Scheduler.d.ts"
+            },
+            "default": "./modules/Scheduler.js",
+            "types": "./modules/Scheduler.d.ts"
+        },
         "./number": {
             "import": {
                 "default": "./number/index.js",
@@ -1144,11 +1156,11 @@
         }
     },
     "devDependencies": {
-        "@types/node": "^22.13.10",
+        "@types/node": "^22.13.11",
         "esbuild-register": "^3.6.0",
-        "eslint": "^9.22.0",
+        "eslint": "^9.23.0",
         "nyc": "^17.1.0",
         "typescript": "^5.8.2",
-        "typescript-eslint": "^8.26.0"
+        "typescript-eslint": "^8.27.0"
     }
 }