evg_observable 2.14.61 → 2.15.1

package/src/outLib/FunctionLibs.js

@@ -1,6 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getListener = exports.quickDeleteFromArray = exports.deleteFromArray = exports.sortDescending = exports.sortAscending = void 0;
+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;
@@ -8,7 +22,13 @@ function sortAscending(a, b) {
         return -1;
     return 0;
 }
-exports.sortAscending = sortAscending;
+/**
+ * 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;
@@ -16,7 +36,13 @@ function sortDescending(a, b) {
         return 1;
     return 0;
 }
-exports.sortDescending = sortDescending;
+/**
+ * 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)
@@ -24,29 +50,50 @@ function deleteFromArray(arr, component) {
     arr.splice(index, 1);
     return true;
 }
-exports.deleteFromArray = deleteFromArray;
+/**
+ * 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 = arr.length - 1;
+    arr.length--;
     return true;
 }
-exports.quickDeleteFromArray = quickDeleteFromArray;
-function getListener(listener) {
-    if (Array.isArray(listener)) {
+/**
+ * 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 < listener.length; i++)
-            group.push(wrapListener(listener[i]));
+        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(listener);
+    return wrapListener(listenerGroup);
 }
-exports.getListener = getListener;
+/**
+ * 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);

package/src/outLib/Observable.d.ts

@@ -1,29 +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> {
-    private value;
     protected subs: ISubscribeObject<T>[];
-    private enabled;
+    protected enabled: boolean;
     protected killed: boolean;
     protected process: boolean;
     protected trash: ISubscriptionLike[];
-    private filters;
+    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/Observable.js

@@ -4,45 +4,106 @@ 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 {
-    value;
     subs = [];
     enabled = true;
     killed = false;
     process = false;
     trash = [];
     filters = new FilterCollection_1.FilterCollection();
+    _value;
     constructor(value) {
-        this.value = 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;
-        for (let i = 0; i < this.subs.length; i++)
-            this.subs[i].send(value);
+        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;
@@ -51,12 +112,24 @@ class Observable {
         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;
@@ -66,38 +139,76 @@ class Observable {
         }
         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._value = null;
             this.subs.length = 0;
             return;
         }
-        const timer = setInterval(() => {
-            if (this.process)
-                return;
-            clearInterval(timer);
-            this.value = null;
+        Promise.resolve().then(() => {
+            this._value = null;
             this.subs.length = 0;
-        }, 10);
+        });
     }
+    /**
+     * 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;
+        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;
@@ -107,15 +218,37 @@ class Observable {
         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;
@@ -123,6 +256,11 @@ class Observable {
         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;
     }

package/src/outLib/OrderedObservable.d.ts

@@ -1,11 +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;
 }