@valkyriestudios/utils 12.32.0 → 12.33.0

package/README.md

@@ -1010,6 +1010,97 @@ These functions are the following:
 - **Is.Equal**
 - **Is.Eq**
 
+### modules/PubSub
+A lightweight fire-and-forget publish–subscribe utility that supports both synchronous and asynchronous subscribers, with built‑in support for storing the last published data for each event.
+
+This feature lets new subscribers immediately receive the most recent value for specific events.
+
+The default storage behavior is configurable via the constructor or can be overridden on a per‑publish basis.
+
+##### Usage
+Simple fire-and-foreget without storage:
+```typescript
+import { PubSub } from '@valkyriestudios/utils/modules/PubSub';
+
+const relay = new PubSub({ name: 'MyPubSub', store: true });
+
+/* Subscribe to events. */
+relay.subscribe({
+  onDataUpdate: (data) => ...,
+  onModalOpen: (...) => ...,
+}, 'client1');
+
+/* Subscribe to events. */
+const client2 = relay.subscribe({
+  onUserUpdate: (...) => ...,
+}); /* If not passing a client id a client id will be generated and returned */
+
+/* Publish events. Since storage is enabled, the data is saved */
+relay.publish('onDataUpdate', {foo: 'bar'});
+relay.publish('onUserUpdate', {language: 'nl'});
+
+/* When not necessary anymore */
+relay.unsubscribe(client2);
+```
+
+In-Memory storage included:
+```typescript
+import { PubSub } from '@valkyriestudios/utils/modules/PubSub';
+
+/* Create a PubSub instance that stores published data by default */
+const relay = new PubSub({ name: 'MyPubSub', store: true });
+
+/* Subscribe to events. */
+relay.subscribe({
+  dataUpdate: (data) => console.log('Subscriber 1 received dataUpdate:', data),
+  /* This event will automatically unsubscribe after the first time its called */
+  onceEvent: {
+    run: (data) => console.log('This runs only once:', data),
+    once: true,
+  },
+}, 'client1');
+
+/* Publish events. Since storage is enabled, the data is saved */
+relay.publish('dataUpdate', { foo: 'bar' });
+relay.publish('onceEvent', 'only once');
+
+/* Later, a new subscriber immediately gets the last published value */
+relay.subscribe({
+  dataUpdate: (data) => console.log('Late subscriber received dataUpdate:', data)
+}, 'client2');
+```
+
+##### API Overview
+- **new PubSub(options?: { logger?: LogFn; name?: string; store?: boolean })**
+Creates a new PubSub instance.
+-- **logger (optional)**: Custom logging function to capture errors.
+-- **name (optional)**: A non‑empty string to name the instance.
+-- **store (optional)**: A boolean to set the default behavior for storing published data (default is false).
+- **publish(event: string, data?: unknown, store?: boolean): void**
+Publishes data for a specific event.
+-- If storage is enabled (via the default or the store override), the published data is stored for that event.
+-- All subscribers for the event are invoked.
+-- Supports both synchronous and asynchronous subscriber functions. Asynchronous errors are caught and logged.
+- **subscribe(events: RawEvents, client_id?: string, override?: boolean): string | null**
+Subscribes a client to one or more events.
+-- Returns a client ID (either provided or generated) which can later be used to unsubscribe.
+-- If stored data exists for an event, the new subscriber is immediately invoked with that data.
+-- The override flag (defaults to true) determines whether existing subscriptions for the same client are replaced.
+- **unsubscribe(client_id: string, event?: string | string[]): void**
+Unsubscribes a client from the specified event(s) or all events if none are provided.
+- **clientIds(event?: string | string[]): Set<string>**
+Retrieves a set of client IDs subscribed to one or more events.
+- **clear(event?: string | string[]): void**
+Clears subscriptions for specific event(s) or all events if no event is specified.
+
+##### Notes:
+- **Data Storage:**
+When storage is enabled, the last published value is tied to an event’s subscription entry. If there are no subscribers left, the stored value is automatically cleaned up.
+- **Error Handling:**
+Both synchronous and asynchronous errors are logged via the custom logger (if provided). The utility checks for thenables by verifying that the returned object has both then and catch methods.
+- **Flexibility:**
+The storage behavior can be controlled globally through the constructor or overridden for individual publish calls.
+
 ### number/is(val:unknown)
 Check if a variable is a number
 ```typescript

package/deep/get.js

@@ -32,21 +32,17 @@ function deepGet(obj, path, get_parent = false) {
                         const extracted = [];
                         for (let y = 0; y < node.length; y++) {
                             const el = deepGet(node[y], key);
-                            if (el !== undefined)
-                                extracted.push(el);
+                            if (el !== undefined) {
+                                extracted.push(...Array.isArray(el) ? el : [el]);
+                            }
                         }
-                        node = extracted.length ? extracted.flat() : undefined;
+                        node = extracted;
                         nodes.push(node);
                     }
                 }
                 else if (typeof node === 'object' && node !== null) {
                     node = node[key];
                     nodes.push(node);
-                    if (node === undefined)
-                        return undefined;
-                }
-                else {
-                    return undefined;
                 }
                 key = '';
                 break;
@@ -67,9 +63,9 @@ function deepGet(obj, path, get_parent = false) {
             else {
                 const extracted = [];
                 for (let i = 0; i < node.length; i++) {
-                    const el = node[i];
-                    if (el?.[key] !== undefined)
-                        extracted.push(el?.[key]);
+                    const val = node[i]?.[key];
+                    if (val !== undefined)
+                        extracted.push(...Array.isArray(val) ? val : [val]);
                 }
                 node = extracted.length ? extracted : undefined;
                 nodes.push(node);

package/index.d.ts

@@ -644,3 +644,40 @@ declare module "hash/index" {
     import { guid } from "hash/guid";
     export { fnv1A, guid };
 }
+declare module "modules/PubSub" {
+    type SyncFn = (data: unknown) => void;
+    type AsyncFn = (data: unknown) => Promise<void>;
+    type Fn = SyncFn | AsyncFn;
+    export type RawEvents = {
+        [key: string]: Fn | {
+            run: Fn;
+            once?: boolean;
+        };
+    };
+    export type LogObject = {
+        name: string;
+        event: string;
+        client_id: string;
+        msg: string;
+        on: Date;
+        data: unknown;
+        err: Error;
+    };
+    export type LogFn = (log: LogObject) => void;
+    export type PubSubOptions = {
+        logger?: LogFn;
+        name?: string;
+        store?: boolean;
+    };
+    class PubSub {
+        #private;
+        constructor(options?: PubSubOptions);
+        get name(): string;
+        publish(event: string, data?: unknown, store?: boolean): void;
+        subscribe(events: RawEvents, client_id?: string, override?: boolean): string | null;
+        unsubscribe(client_id: string, event?: string | string[]): void;
+        clientIds(event?: string | string[]): Set<string>;
+        clear(event?: string | string[]): void;
+    }
+    export { PubSub, PubSub as default };
+}

package/modules/PubSub.d.ts

@@ -0,0 +1,90 @@
+type SyncFn = (data: unknown) => void;
+type AsyncFn = (data: unknown) => Promise<void>;
+type Fn = SyncFn | AsyncFn;
+export type RawEvents = {
+    [key: string]: Fn | {
+        run: Fn;
+        once?: boolean;
+    };
+};
+/**
+ * Types of Log Object shapes
+ */
+export type LogObject = {
+    name: string;
+    event: string;
+    client_id: string;
+    msg: string;
+    on: Date;
+    data: unknown;
+    err: Error;
+};
+/**
+ * Logger Function type
+ */
+export type LogFn = (log: LogObject) => void;
+export type PubSubOptions = {
+    /**
+     * 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;
+    /**
+     * Whether or not the default is for the last provided value to be stored. (if not passed = false)
+     */
+    store?: boolean;
+};
+declare class PubSub {
+    #private;
+    constructor(options?: PubSubOptions);
+    /**
+     * Getter returning the name of the pubsub.
+     */
+    get name(): string;
+    /**
+     * Publish data for a specific event.
+     *
+     * An optional third parameter allows the producer to override the default storage behavior.
+     * If storage is enabled, the published data is saved so that new subscribers receive it immediately.
+     *
+     * @param {string} event - Name of the event.
+     * @param {unknown} data - (Optional) Data to publish.
+     * @param {boolean?} store - (Optional) Override for storing this event’s data.
+     */
+    publish(event: string, data?: unknown, store?: boolean): void;
+    /**
+     * Subscribes to one or more events as a client.
+     *
+     * After adding the subscription, if there is stored data for an event,
+     * the new subscriber's callback is immediately invoked with that data.
+     *
+     * @param {RawEvents} events - Raw Events object to subscribe to.
+     * @param {string?} client_id - Optional client id. If not provided one will be generated.
+     * @param {boolean?} override - Defaults to true. If false, existing subscriptions for the same event are preserved.
+     * @returns Client id if successful, or null for invalid input.
+     */
+    subscribe(events: RawEvents, client_id?: string, override?: boolean): string | null;
+    /**
+     * Unsubscribes a client from specified event(s) or from all events if none are specified.
+     *
+     * @param {string} client_id - Client ID to unsubscribe.
+     * @param {string|string[]?} event - (Optional) Unsubscribe only from these event(s).
+     */
+    unsubscribe(client_id: string, event?: string | string[]): void;
+    /**
+     * Retrieve the client IDs subscribed to a single, multiple, or all events.
+     *
+     * @param {string|string[]?} event - Optional event or events array.
+     */
+    clientIds(event?: string | string[]): Set<string>;
+    /**
+     * Clear subscriptions for specific event(s) or all events.
+     *
+     * @param {string|string[]?} event - Events to clear.
+     */
+    clear(event?: string | string[]): void;
+}
+export { PubSub, PubSub as default };

package/modules/PubSub.js

@@ -0,0 +1,191 @@
+"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 _PubSub_instances, _PubSub_subscriptions, _PubSub_name, _PubSub_log, _PubSub_store_by_default, _PubSub_publishToSubscriber;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.PubSub = void 0;
+const is_1 = require("../array/is");
+const is_2 = require("../function/is");
+const noop_1 = require("../function/noop");
+const guid_1 = require("../hash/guid");
+const is_3 = require("../object/is");
+const isNotEmpty_1 = require("../object/isNotEmpty");
+const isNotEmpty_2 = require("../string/isNotEmpty");
+class PubSub {
+    constructor(options = {}) {
+        _PubSub_instances.add(this);
+        _PubSub_subscriptions.set(this, new Map());
+        _PubSub_name.set(this, 'PubSub');
+        _PubSub_log.set(this, noop_1.noop);
+        _PubSub_store_by_default.set(this, false);
+        if (!(0, is_3.isObject)(options))
+            throw new Error('PubSub@ctor: options should be an object');
+        if ('logger' in options) {
+            if (!(0, is_2.isFunction)(options.logger))
+                throw new Error('PubSub@ctor: logger should be a function');
+            __classPrivateFieldSet(this, _PubSub_log, options.logger, "f");
+        }
+        if ('name' in options) {
+            if (!(0, isNotEmpty_2.isNotEmptyString)(options.name))
+                throw new Error('PubSub@ctor: name should be a non-empty string');
+            __classPrivateFieldSet(this, _PubSub_name, options.name.trim(), "f");
+        }
+        if ('store' in options) {
+            if (options.store !== true && options.store !== false)
+                throw new Error('PubSub@ctor: store should be a boolean');
+            __classPrivateFieldSet(this, _PubSub_store_by_default, !!options.store, "f");
+        }
+    }
+    get name() {
+        return __classPrivateFieldGet(this, _PubSub_name, "f");
+    }
+    publish(event, data, store) {
+        if (!(0, isNotEmpty_2.isNotEmptyString)(event))
+            return;
+        let entry = __classPrivateFieldGet(this, _PubSub_subscriptions, "f").get(event);
+        const shouldStore = store !== undefined ? store : __classPrivateFieldGet(this, _PubSub_store_by_default, "f");
+        if (!entry) {
+            if (!shouldStore)
+                return;
+            entry = { value: data, subscribers: new Map() };
+            __classPrivateFieldGet(this, _PubSub_subscriptions, "f").set(event, entry);
+        }
+        else if (shouldStore) {
+            entry.value = data;
+        }
+        const entriesArray = [...entry.subscribers.entries()];
+        for (const [client_id, client_handler] of entriesArray) {
+            __classPrivateFieldGet(this, _PubSub_instances, "m", _PubSub_publishToSubscriber).call(this, event, entry, client_id, client_handler, data);
+        }
+        if (!shouldStore && !entry.subscribers.size)
+            __classPrivateFieldGet(this, _PubSub_subscriptions, "f").delete(event);
+    }
+    subscribe(events, client_id, override = true) {
+        if (!(0, isNotEmpty_1.isNotEmptyObject)(events))
+            return null;
+        const uid = (0, isNotEmpty_2.isNotEmptyString)(client_id) ? client_id : (0, guid_1.guid)();
+        for (const event of Object.keys(events)) {
+            const raw_payload = events[event];
+            let normalized_payload = null;
+            if ((0, is_2.isFunction)(raw_payload)) {
+                normalized_payload = { run: raw_payload, once: false };
+            }
+            else if ((0, is_2.isFunction)(raw_payload?.run)) {
+                normalized_payload = {
+                    run: raw_payload.run,
+                    once: raw_payload.once === true,
+                };
+            }
+            if (!normalized_payload)
+                continue;
+            let entry = __classPrivateFieldGet(this, _PubSub_subscriptions, "f").get(event);
+            if (!entry) {
+                entry = { subscribers: new Map(), value: undefined };
+                __classPrivateFieldGet(this, _PubSub_subscriptions, "f").set(event, entry);
+            }
+            if (override === false && entry.subscribers.has(uid))
+                continue;
+            entry.subscribers.set(uid, normalized_payload);
+            if (entry.value !== undefined) {
+                __classPrivateFieldGet(this, _PubSub_instances, "m", _PubSub_publishToSubscriber).call(this, event, entry, uid, normalized_payload, entry.value);
+            }
+        }
+        return uid;
+    }
+    unsubscribe(client_id, event) {
+        if (!(0, isNotEmpty_2.isNotEmptyString)(client_id))
+            return;
+        const events = (0, isNotEmpty_2.isNotEmptyString)(event)
+            ? [event]
+            : (0, is_1.isArray)(event)
+                ? event
+                : [...__classPrivateFieldGet(this, _PubSub_subscriptions, "f").keys()];
+        for (let i = 0; i < events.length; i++) {
+            const ev = events[i];
+            if (!(0, isNotEmpty_2.isNotEmptyString)(ev))
+                continue;
+            const entry = __classPrivateFieldGet(this, _PubSub_subscriptions, "f").get(ev);
+            if (entry) {
+                entry.subscribers.delete(client_id);
+                if (!entry.subscribers.size) {
+                    __classPrivateFieldGet(this, _PubSub_subscriptions, "f").delete(ev);
+                }
+            }
+        }
+    }
+    clientIds(event) {
+        const events = (0, isNotEmpty_2.isNotEmptyString)(event)
+            ? [event]
+            : (0, is_1.isArray)(event)
+                ? event
+                : [...__classPrivateFieldGet(this, _PubSub_subscriptions, "f").keys()];
+        const result = new Set();
+        for (let i = 0; i < events.length; i++) {
+            const entry = __classPrivateFieldGet(this, _PubSub_subscriptions, "f").get(events[i]);
+            if (entry) {
+                for (const key of entry.subscribers.keys()) {
+                    result.add(key);
+                }
+            }
+        }
+        return result;
+    }
+    clear(event) {
+        if ((0, isNotEmpty_2.isNotEmptyString)(event)) {
+            __classPrivateFieldGet(this, _PubSub_subscriptions, "f").delete(event);
+        }
+        else if ((0, is_1.isArray)(event)) {
+            for (let i = 0; i < event.length; i++) {
+                const ev = event[i];
+                if ((0, isNotEmpty_2.isNotEmptyString)(ev)) {
+                    __classPrivateFieldGet(this, _PubSub_subscriptions, "f").delete(ev);
+                }
+            }
+        }
+        else {
+            __classPrivateFieldSet(this, _PubSub_subscriptions, new Map(), "f");
+        }
+    }
+}
+exports.PubSub = PubSub;
+exports.default = PubSub;
+_PubSub_subscriptions = new WeakMap(), _PubSub_name = new WeakMap(), _PubSub_log = new WeakMap(), _PubSub_store_by_default = new WeakMap(), _PubSub_instances = new WeakSet(), _PubSub_publishToSubscriber = function _PubSub_publishToSubscriber(event, map, client_id, sub, data) {
+    try {
+        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)) {
+            Promise.resolve(out).catch(err => {
+                __classPrivateFieldGet(this, _PubSub_log, "f").call(this, {
+                    name: __classPrivateFieldGet(this, _PubSub_name, "f"),
+                    event,
+                    client_id,
+                    msg: '[async] ' + __classPrivateFieldGet(this, _PubSub_name, "f") + '@publish: ' + (err?.message || 'Unknown Error'),
+                    on: new Date(),
+                    data,
+                    err: err,
+                });
+            });
+        }
+    }
+    catch (err) {
+        __classPrivateFieldGet(this, _PubSub_log, "f").call(this, {
+            name: __classPrivateFieldGet(this, _PubSub_name, "f"),
+            event,
+            client_id,
+            msg: '[sync] ' + __classPrivateFieldGet(this, _PubSub_name, "f") + '@publish: ' + (err?.message || 'Unknown Error'),
+            on: new Date(),
+            data,
+            err: err,
+        });
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@valkyriestudios/utils",
-    "version": "12.32.0",
+    "version": "12.33.0",
     "description": "A collection of single-function utilities for common tasks",
     "author": {
         "name": "Peter Vermeulen",