evg_observable 2.14.61 → 2.15.0

package/src/outLib/src/Libraries/Observables/FunctionLibs.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortAscending = sortAscending;
+exports.sortDescending = sortDescending;
+exports.deleteFromArray = deleteFromArray;
+exports.quickDeleteFromArray = quickDeleteFromArray;
+exports.getListener = getListener;
+/**
+ * Compares two ISubscribeObject items based on their `order` property
+ * and sorts them in ascending order.
+ *
+ * @param {ISubscribeObject<any>} a - The first object to compare.
+ * @param {ISubscribeObject<any>} b - The second object to compare.
+ * @return {number} - Returns 1 if the `order` property of `a` is greater than `b`,
+ *                    -1 if the `order` property of `a` is less than `b`,
+ *                     or 0 if they are equal.
+ */
+function sortAscending(a, b) {
+    if (a.order > b.order)
+        return 1;
+    if (a.order < b.order)
+        return -1;
+    return 0;
+}
+/**
+ * Compares two objects based on their `order` property for descending sorting.
+ *
+ * @param {ISubscribeObject<any>} a - The first object to compare, expected to have an `order` property.
+ * @param {ISubscribeObject<any>} b - The second object to compare, expected to have an `order` property.
+ * @return {number} - Returns -1 if `a.order` is greater than `b.order`, 1 if `a.order` is less than `b.order`, and 0 if they are equal.
+ */
+function sortDescending(a, b) {
+    if (a.order > b.order)
+        return -1;
+    if (a.order < b.order)
+        return 1;
+    return 0;
+}
+/**
+ * Removes the specified component from the provided array if it exists.
+ *
+ * @param {T[]} arr - The array from which the component will be removed.
+ * @param {T} component - The component to be removed from the array.
+ * @return {boolean} Returns true if the component was successfully removed, false otherwise.
+ */
+function deleteFromArray(arr, component) {
+    const index = arr.indexOf(component);
+    if (index === -1)
+        return false;
+    arr.splice(index, 1);
+    return true;
+}
+/**
+ * Removes a specified element from an array by replacing it with the last element
+ * and reducing the array's length. This method avoids maintaining order but performs
+ * the deletion operation efficiently.
+ *
+ * @param {T[]} arr - The array from which the element will be removed.
+ * @param {T} component - The element to be removed from the array.
+ * @return {boolean} - Returns true if the element was found and removed;
+ *                     otherwise, returns false.
+ */
+function quickDeleteFromArray(arr, component) {
+    const index = arr.indexOf(component);
+    if (index === -1)
+        return false;
+    arr[index] = arr[arr.length - 1];
+    arr.length--;
+    return true;
+}
+/**
+ * Returns a listener function based on the provided listener group.
+ *
+ * @param {ISubscribeGroup<T>} listenerGroup - The group of listener(s). It can be a single listener
+ *        or an array of listeners that are invoked when the returned listener is called.
+ * @return {IListener<T>} A single listener function that wraps the provided listener or group of listeners
+ *         and invokes them with the provided data.
+ */
+function getListener(listenerGroup) {
+    if (Array.isArray(listenerGroup)) {
+        const group = [];
+        for (let i = 0; i < listenerGroup.length; i++)
+            group.push(wrapListener(listenerGroup[i]));
+        return (data) => {
+            for (let i = 0; i < group.length; i++)
+                group[i](data);
+        };
+    }
+    return wrapListener(listenerGroup);
+}
+/**
+ * Wraps the provided listener, ensuring it conforms to the IListener<T> interface.
+ *
+ * @param listener The listener to be wrapped. Can be either an IListener<T> or an ISetObservableValue.
+ * @return Returns a listener that adheres to the IListener<T> interface.
+ */
+function wrapListener(listener) {
+    if ("next" in listener)
+        return (value) => listener.next(value);
+    return listener;
+}

package/src/outLib/src/Libraries/Observables/Observable.d.ts

@@ -0,0 +1,160 @@
+import { IAddFilter, IErrorCallback, IFilterSetup, IObserver, ISetup, IStream, ISubscribeGroup, ISubscribeObject, ISubscriptionLike } from "./Types";
+import { SubscribeObject } from "./SubscribeObject";
+import { FilterCollection } from "./FilterCollection";
+/**
+ * Observable is a generic class that represents an entity capable of emitting values
+ * over time to subscribers. It provides mechanisms for managing subscribers and controlling
+ * the flow of emitted data through filters and utility functions.
+ *
+ * @template T The type of the data managed by the Observable.
+ *
+ * Implements:
+ * - IObserver<T>: For observing value changes.
+ * - IStream<T>: For emitting streams of values.
+ * - IAddFilter<T>: For adding and managing filters in the value processing.
+ *
+ * The Observable class provides the following key features:
+ *
+ * - Allows subscribers to listen for emitted values.
+ * - Provides methods for enabling/disabling value emissions.
+ * - Supports applying filters to process or validate values before emission.
+ * - Allows streaming multiple values sequentially.
+ * - Supports safe termination of resources through unsubscription and destruction.
+ * - Handles asynchronous cleanup when active operations are in progress.
+ */
+export declare class Observable<T> implements IObserver<T>, IStream<T>, IAddFilter<T> {
+    protected subs: ISubscribeObject<T>[];
+    protected enabled: boolean;
+    protected killed: boolean;
+    protected process: boolean;
+    protected trash: ISubscriptionLike[];
+    protected filters: FilterCollection<T>;
+    protected _value: T;
+    constructor(value: T);
+    /**
+     * Adds an error handler filter to the current filter setup.
+     *
+     * @param {IErrorCallback} [errorHandler] - An optional error handler callback to handle errors in the filter.
+     * @return {IFilterSetup<T>} The updated filter setup object with the specified error handler added.
+     */
+    addFilter(errorHandler?: IErrorCallback): IFilterSetup<T>;
+    /**
+     * Disables the current instance or functionality associated with this method.
+     * Updates the internal state to reflect that it is no longer active or enabled.
+     *
+     * @return {void} This method does not return a value.
+     */
+    disable(): void;
+    /**
+     * Enables the current feature or functionality by setting its state to active.
+     * Updates the internal state to indicate that it is enabled.
+     *
+     * @return {void} No return value.
+     */
+    enable(): void;
+    /**
+     * Indicates whether the current object or feature is enabled.
+     *
+     * @return {boolean} Returns true if enabled, otherwise false.
+     */
+    get isEnable(): boolean;
+    /**
+     * Processes the given value and sends it to all subscribers, respecting the enabled status, filters, and processing state.
+     *
+     * @param {T} value - The value to be processed and passed to subscribers.
+     * @return {void} This method does not return a value.
+     */
+    next(value: T): void;
+    /**
+     * Processes an array of values and triggers the next method for each value if the stream
+     * is not killed or disabled.
+     *
+     * @param {T[]} values - An array of values to be processed by the stream.
+     * @return {void} This method does not return a value.
+     */
+    stream(values: T[]): void;
+    /**
+     * Clears all items in the `trash` array by unsubscribing each item and resetting the array length to zero.
+     *
+     * @return {void} No return value.
+     */
+    private clearTrash;
+    /**
+     * Unsubscribes the provided listener by removing it from the subscribers' list
+     * or marking it for cleanup if the process is currently active.
+     *
+     * @param {ISubscriptionLike} listener - The subscription listener to be unsubscribed.
+     * @return {void} No return value.
+     */
+    unSubscribe(listener: ISubscriptionLike): void;
+    /**
+     * Cleans up resources and terminates any ongoing processes or subscriptions associated with the instance.
+     *
+     * Sets the internal state to indicate it has been destroyed. If a process is associated, waits until the process is no longer active
+     * before clearing internal data and subscriptions.
+     *
+     * @return {void} Does not return any value.
+     */
+    destroy(): void;
+    /**
+     * Unsubscribes from all active subscriptions by clearing the subscriptions list.
+     * Prevents further operations if the instance has already been marked as killed.
+     * Safe to call during next() - uses deferred cleanup mechanism.
+     *
+     * @return {void} Does not return a value.
+     */
+    unsubscribeAll(): void;
+    /**
+     * Retrieves the current value if the instance is active.
+     * If the instance is marked as killed, undefined is returned.
+     *
+     * @return {T | undefined} The current value or undefined if the instance is killed.
+     */
+    getValue(): T | undefined;
+    /**
+     * Calculates and returns the size based on the current state.
+     *
+     * @return {number} The size, which is the number of subscriptions if not killed; otherwise, 0.
+     */
+    size(): number;
+    /**
+     * Subscribes an observer to this instance, monitoring its changes and handling errors if any.
+     *
+     * @param observer The observer object that implements the ISubscribeGroup interface which will be subscribed.
+     * @param errorHandler Optional callback function to handle errors encountered during the subscription process.
+     * @return An object implementing the ISubscriptionLike interface that represents the subscription,
+     *         or undefined if the subscription is not successful.
+     */
+    subscribe(observer: ISubscribeGroup<T>, errorHandler?: IErrorCallback): ISubscriptionLike | undefined;
+    /**
+     * Adds an observer to the subscribe object and associates it with a potential error handler.
+     * The subscribe object is added to the list of subscriptions for tracking purposes.
+     *
+     * @param {SubscribeObject<T>} subscribeObject - The object that manages the subscription to observers.
+     * @param {ISubscribeGroup<T>} observer - The observer to be subscribed to the subscribe object.
+     * @param {IErrorCallback} [errorHandler] - Optional error handler callback to handle errors during subscription.
+     * @return {void} This method does not return a value.
+     */
+    protected addObserver(subscribeObject: SubscribeObject<T>, observer: ISubscribeGroup<T>, errorHandler?: IErrorCallback): void;
+    /**
+     * Determines if the provided object is a valid listener.
+     *
+     * @param listener An instance of ISubscribeGroup of type T to validate as a listener.
+     * @return Returns true if the provided listener is valid and the object is not marked as killed; otherwise, returns false.
+     */
+    protected isListener(listener: ISubscribeGroup<T>): boolean;
+    /**
+     * Handles the creation and management of a SubscribeObject if the current instance is active.
+     * It returns an `ISetup<T>` object to allow additional configurations or operations.
+     * If the instance is in a "killed" state, it will not proceed and returns undefined.
+     *
+     * @return {ISetup<T> | undefined} The created SubscribeObject wrapped in an ISetup<T> interface if the instance is active, otherwise undefined.
+     */
+    pipe(): ISetup<T> | undefined;
+    /**
+     * Determines if the object has been destroyed.
+     *
+     * @return {boolean} True if the object is destroyed, false otherwise.
+     */
+    get isDestroyed(): boolean;
+}

package/src/outLib/src/Libraries/Observables/Observable.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Observable = void 0;
+const FunctionLibs_1 = require("./FunctionLibs");
+const SubscribeObject_1 = require("./SubscribeObject");
+const FilterCollection_1 = require("./FilterCollection");
+/**
+ * Observable is a generic class that represents an entity capable of emitting values
+ * over time to subscribers. It provides mechanisms for managing subscribers and controlling
+ * the flow of emitted data through filters and utility functions.
+ *
+ * @template T The type of the data managed by the Observable.
+ *
+ * Implements:
+ * - IObserver<T>: For observing value changes.
+ * - IStream<T>: For emitting streams of values.
+ * - IAddFilter<T>: For adding and managing filters in the value processing.
+ *
+ * The Observable class provides the following key features:
+ *
+ * - Allows subscribers to listen for emitted values.
+ * - Provides methods for enabling/disabling value emissions.
+ * - Supports applying filters to process or validate values before emission.
+ * - Allows streaming multiple values sequentially.
+ * - Supports safe termination of resources through unsubscription and destruction.
+ * - Handles asynchronous cleanup when active operations are in progress.
+ */
+class Observable {
+    subs = [];
+    enabled = true;
+    killed = false;
+    process = false;
+    trash = [];
+    filters = new FilterCollection_1.FilterCollection();
+    _value;
+    constructor(value) {
+        this._value = value;
+    }
+    /**
+     * Adds an error handler filter to the current filter setup.
+     *
+     * @param {IErrorCallback} [errorHandler] - An optional error handler callback to handle errors in the filter.
+     * @return {IFilterSetup<T>} The updated filter setup object with the specified error handler added.
+     */
+    addFilter(errorHandler) {
+        if (errorHandler)
+            this.filters.addErrorHandler(errorHandler);
+        return this.filters;
+    }
+    /**
+     * Disables the current instance or functionality associated with this method.
+     * Updates the internal state to reflect that it is no longer active or enabled.
+     *
+     * @return {void} This method does not return a value.
+     */
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Enables the current feature or functionality by setting its state to active.
+     * Updates the internal state to indicate that it is enabled.
+     *
+     * @return {void} No return value.
+     */
+    enable() {
+        this.enabled = true;
+    }
+    /**
+     * Indicates whether the current object or feature is enabled.
+     *
+     * @return {boolean} Returns true if enabled, otherwise false.
+     */
+    get isEnable() {
+        return this.enabled;
+    }
+    /**
+     * Processes the given value and sends it to all subscribers, respecting the enabled status, filters, and processing state.
+     *
+     * @param {T} value - The value to be processed and passed to subscribers.
+     * @return {void} This method does not return a value.
+     */
+    next(value) {
+        if (this.killed)
+            return;
+        if (!this.enabled)
+            return;
+        if (!this.subs.length)
+            return;
+        if (!this.filters.isEmpty && !this.filters.processChain(value).isOK)
+            return;
+        this.process = true;
+        this._value = value;
+        const subs = this.subs;
+        const len = subs.length;
+        for (let i = 0; i < len; i++)
+            subs[i].send(value);
+        this.process = false;
+        this.trash.length && this.clearTrash();
+    }
+    /**
+     * Processes an array of values and triggers the next method for each value if the stream
+     * is not killed or disabled.
+     *
+     * @param {T[]} values - An array of values to be processed by the stream.
+     * @return {void} This method does not return a value.
+     */
+    stream(values) {
+        if (this.killed)
+            return;
+        if (!this.enabled)
+            return;
+        for (let i = 0; i < values.length; i++)
+            this.next(values[i]);
+    }
+    /**
+     * Clears all items in the `trash` array by unsubscribing each item and resetting the array length to zero.
+     *
+     * @return {void} No return value.
+     */
+    clearTrash() {
+        const length = this.trash.length;
+        for (let i = 0; i < length; i++)
+            this.unSubscribe(this.trash[i]);
+        this.trash.length = 0;
+    }
+    /**
+     * Unsubscribes the provided listener by removing it from the subscribers' list
+     * or marking it for cleanup if the process is currently active.
+     *
+     * @param {ISubscriptionLike} listener - The subscription listener to be unsubscribed.
+     * @return {void} No return value.
+     */
+    unSubscribe(listener) {
+        if (this.killed)
+            return;
+        if (this.process && listener) {
+            this.trash.push(listener);
+            return;
+        }
+        this.subs && !(0, FunctionLibs_1.quickDeleteFromArray)(this.subs, listener);
+    }
+    /**
+     * Cleans up resources and terminates any ongoing processes or subscriptions associated with the instance.
+     *
+     * Sets the internal state to indicate it has been destroyed. If a process is associated, waits until the process is no longer active
+     * before clearing internal data and subscriptions.
+     *
+     * @return {void} Does not return any value.
+     */
+    destroy() {
+        if (this.killed)
+            return;
+        this.killed = true;
+        if (!this.process) {
+            this._value = null;
+            this.subs.length = 0;
+            return;
+        }
+        Promise.resolve().then(() => {
+            this._value = null;
+            this.subs.length = 0;
+        });
+    }
+    /**
+     * Unsubscribes from all active subscriptions by clearing the subscriptions list.
+     * Prevents further operations if the instance has already been marked as killed.
+     * Safe to call during next() - uses deferred cleanup mechanism.
+     *
+     * @return {void} Does not return a value.
+     */
+    unsubscribeAll() {
+        if (this.killed)
+            return;
+        if (this.process) {
+            // Defer removal until next() completes
+            const subs = this.subs;
+            for (let i = 0; i < subs.length; i++)
+                this.trash.push(subs[i]);
+            return;
+        }
+        this.subs.length = 0;
+    }
+    /**
+     * Retrieves the current value if the instance is active.
+     * If the instance is marked as killed, undefined is returned.
+     *
+     * @return {T | undefined} The current value or undefined if the instance is killed.
+     */
+    getValue() {
+        if (this.killed)
+            return undefined;
+        return this._value;
+    }
+    /**
+     * Calculates and returns the size based on the current state.
+     *
+     * @return {number} The size, which is the number of subscriptions if not killed; otherwise, 0.
+     */
+    size() {
+        if (this.killed)
+            return 0;
+        return this.subs.length;
+    }
+    /**
+     * Subscribes an observer to this instance, monitoring its changes and handling errors if any.
+     *
+     * @param observer The observer object that implements the ISubscribeGroup interface which will be subscribed.
+     * @param errorHandler Optional callback function to handle errors encountered during the subscription process.
+     * @return An object implementing the ISubscriptionLike interface that represents the subscription,
+     *         or undefined if the subscription is not successful.
+     */
+    subscribe(observer, errorHandler) {
+        if (this.killed)
+            return undefined;
+        if (!this.isListener(observer))
+            return undefined;
+        const subscribeObject = new SubscribeObject_1.SubscribeObject(this, false);
+        this.addObserver(subscribeObject, observer, errorHandler);
+        return subscribeObject;
+    }
+    /**
+     * Adds an observer to the subscribe object and associates it with a potential error handler.
+     * The subscribe object is added to the list of subscriptions for tracking purposes.
+     *
+     * @param {SubscribeObject<T>} subscribeObject - The object that manages the subscription to observers.
+     * @param {ISubscribeGroup<T>} observer - The observer to be subscribed to the subscribe object.
+     * @param {IErrorCallback} [errorHandler] - Optional error handler callback to handle errors during subscription.
+     * @return {void} This method does not return a value.
+     */
+    addObserver(subscribeObject, observer, errorHandler) {
+        subscribeObject.subscribe(observer, errorHandler);
+        this.subs.push(subscribeObject);
+    }
+    /**
+     * Determines if the provided object is a valid listener.
+     *
+     * @param listener An instance of ISubscribeGroup of type T to validate as a listener.
+     * @return Returns true if the provided listener is valid and the object is not marked as killed; otherwise, returns false.
+     */
+    isListener(listener) {
+        if (this.killed)
+            return false;
+        return !!listener;
+    }
+    /**
+     * Handles the creation and management of a SubscribeObject if the current instance is active.
+     * It returns an `ISetup<T>` object to allow additional configurations or operations.
+     * If the instance is in a "killed" state, it will not proceed and returns undefined.
+     *
+     * @return {ISetup<T> | undefined} The created SubscribeObject wrapped in an ISetup<T> interface if the instance is active, otherwise undefined.
+     */
+    pipe() {
+        if (this.killed)
+            return undefined;
+        const subscribeObject = new SubscribeObject_1.SubscribeObject(this, true);
+        this.subs.push(subscribeObject);
+        return subscribeObject;
+    }
+    /**
+     * Determines if the object has been destroyed.
+     *
+     * @return {boolean} True if the object is destroyed, false otherwise.
+     */
+    get isDestroyed() {
+        return this.killed;
+    }
+}
+exports.Observable = Observable;

package/src/outLib/src/Libraries/Observables/OrderedObservable.d.ts

@@ -0,0 +1,70 @@
+import { Observable } from "./Observable";
+import { IErrorCallback, IOrdered, IOrderedSetup, IOrderedSubscriptionLike, ISubscribeGroup, ISubscriptionLike } from "./Types";
+/**
+ * Represents an observable data structure that maintains elements in a specific order and provides
+ * methods to manipulate and subscribe to its elements.
+ *
+ * The `OrderedObservable` class supports sorting elements in ascending or descending order and allows
+ * for subscription to changes in its state. It extends the capabilities of a basic `Observable` by
+ * incorporating sorting and ordered processing mechanisms.
+ *
+ * @template T The type of data stored and handled by the observable.
+ * @extends Observable<T>
+ * @implements IOrdered<T>
+ */
+export declare class OrderedObservable<T> extends Observable<T> implements IOrdered<T> {
+    /**
+     * Represents the direction in which sorting should occur.
+     * The value is expected to indicate whether the sorting
+     * should be performed in ascending or descending order.
+     *
+     * Possible values:
+     * - `sortAscending`: Sorting in ascending order.
+     * - `sortDescending`: Sorting in descending order.
+     */
+    private sortDirection;
+    /**
+     * Sets the sorting order to ascending and applies the sorting.
+     *
+     * @return {boolean} Returns true if the sorting operation is successful, otherwise false.
+     */
+    setAscendingSort(): boolean;
+    /**
+     * Sets the sorting order to descending and updates the sort configuration.
+     *
+     * @return {boolean} Returns `true` if the sorting operation is configured and applied successfully, otherwise returns `false`.
+     */
+    setDescendingSort(): boolean;
+    /**
+     * Sorts the `subs` array based on the specified sort direction if the object is not in a "killed" state.
+     *
+     * @return {boolean} Returns true if the sorting was performed, false if the object is in a "killed" state.
+     */
+    sortByOrder(): boolean;
+    /**
+     * Subscribes a listener to this instance with an optional error handler.
+     *
+     * @param {ISubscribeGroup<T>} listener - The listener object that should be notified of changes.
+     * @param {IErrorCallback} [errorHandler] - An optional handler to process errors during execution.
+     * @return {IOrderedSubscriptionLike | undefined} Returns an instance of IOrderedSubscriptionLike if the listener is valid; otherwise, returns undefined.
+     */
+    subscribe(listener: ISubscribeGroup<T>, errorHandler?: IErrorCallback): IOrderedSubscriptionLike | undefined;
+    /**
+     * Creates and returns an instance of `OrderedSubscribeObject` tied to the current object,
+     * facilitating ordered subscription setup. If the instance is marked as killed, it returns undefined.
+     *
+     * @return {IOrderedSetup<T> | undefined} An instance of `OrderedSubscribeObject` for subscription setup,
+     *         or undefined if the operation is not allowed.
+     */
+    pipe(): IOrderedSetup<T> | undefined;
+    /**
+     * Removes a previously subscribed listener from the subscription list,
+     * preventing it from receiving further updates. If the system is in a
+     * "killed" state or specific conditions in the process flow are met,
+     * the listener may instead be added to a trash list.
+     *
+     * @param {ISubscriptionLike} listener - The subscription listener to be unsubscribed or handled accordingly.
+     * @return {void} Does not return any value.
+     */
+    unSubscribe(listener: ISubscriptionLike): void;
+}