evg_observable 2.14.61 → 2.15.1

package/BREAKING_CHANGES.md

@@ -0,0 +1,70 @@
+# Breaking Changes - Performance Optimizations Branch
+
+## Version 2.15.0
+
+### Internal Field Renaming
+
+**Affected field:** `value` renamed to `_value`
+
+The internal field storing the current observable value has been renamed from `value` to `_value` to follow TypeScript conventions for protected/private members.
+
+**Before:**
+```typescript
+export class Observable<T> {
+    constructor(private value: T) {}
+}
+```
+
+**After:**
+```typescript
+export class Observable<T> {
+    protected _value: T;
+    constructor(value: T) {
+        this._value = value;
+    }
+}
+```
+
+**Migration:**
+- If you were extending `Observable` and accessing `this.value`, change to `this._value`
+- Use the public `getValue()` method for reading the current value (recommended)
+
+### Visibility Changes
+
+The following fields changed from `private` to `protected` to enable better inheritance:
+
+| Field | Before | After |
+|-------|--------|-------|
+| `enabled` | private | protected |
+| `filters` | private | protected |
+| `_value` (formerly `value`) | private | protected |
+
+**Impact:** This is not a breaking change for most users, but allows subclasses to access these fields.
+
+### Recommended Migration Path
+
+Instead of accessing internal fields directly, use the public API:
+
+```typescript
+// Instead of:
+// @ts-ignore
+const val = observable._value;
+
+// Use:
+const val = observable.getValue();
+
+// Instead of:
+// @ts-ignore
+const count = observable.subs.length;
+
+// Use:
+const count = observable.size();
+```
+
+### New Behavior
+
+1. **`destroy()` now uses `Promise.resolve()`** instead of `setInterval()` for async cleanup when called during emission
+2. **`unsubscribeAll()` is now safe to call during `next()`** - uses deferred cleanup mechanism
+3. **Early exit optimization** - `next()` returns immediately if there are no subscribers
+
+These behavioral changes improve performance and memory management but should not require code changes.

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "evg_observable",
-  "version": "2.14.61",
+  "version": "2.15.1",
   "description": "Alternative fast and light library version - observable.",
   "main": "src/outLib/index.js",
+  "types": "src/outLib/index.d.ts",
   "directories": {
     "test": "test"
   },
   "scripts": {
     "test": "nyc ./node_modules/.bin/_mocha 'test/**/*.test.ts'",
     "remove": "rm -rf ./src/Libraries; rm -rf ./test; rm .mocharc.json; rm .nyrc.json; rm register.js; rm tsconfig.json",
-    "build": "tsc --declaration; npm run remove"
+    "build": "tsc --declaration; npm run remove",
+    "benchmark": "ts-node benchmark.ts",
+    "benchmark:comparison": "ts-node benchmark-comparison.ts"
   },
   "repository": {
     "type": "git",
@@ -22,13 +25,17 @@
   },
   "homepage": "https://github.com/BarushevEA/light-observable-ts#readme",
   "devDependencies": {
-    "typescript": "^5.4.5",
     "@testdeck/mocha": "^0.3.3",
+    "@types/benchmark": "^2.1.5",
     "@types/chai": "^4.3.4",
+    "benchmark": "^2.1.4",
     "chai": "^4.3.7",
-    "mocha": "^10.2.0",
-    "nyc": "^15.1.0",
-    "ts-node": "^10.9.1"
+    "microtime": "^3.1.1",
+    "mocha": "^11.7.5",
+    "nyc": "^17.1.0",
+    "rxjs": "^7.8.2",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.4.5"
   },
   "keywords": [
     "EVG Observable",

package/src/outLib/AbstractSwitchCase.d.ts

@@ -1,8 +1,37 @@
 import { ICallback, IChainContainer } from "./Types";
+/**
+ * Abstract class representing a Switch-Case control structure for handling
+ * conditional chains of operations.
+ *
+ * @template T - The type of the input payload expected by the conditions.
+ * @template P - The type extending IChainContainer, representing the container for the chain of operations.
+ * @template W - The type of the subclass or the expected return type for method chaining.
+ */
 export declare abstract class SwitchCase<T, P extends IChainContainer, W> {
     protected pipe: P;
     protected counter: number;
+    /**
+     * Creates an instance of the class and initializes the pipe and counter.
+     *
+     * @param {P} pipe - The pipe object used for initialization.
+     * @return {void}
+     */
     constructor(pipe: P);
+    /**
+     * Adds a conditional case to the processing chain. The case determines
+     * whether further processing should continue based on the provided condition.
+     *
+     * @param {ICallback<any>} condition - A callback function that takes a payload
+     * and evaluates a condition. If the condition is met, further processing may be stopped.
+     * @return {W} Returns the current instance for method chaining.
+     */
     case(condition: ICallback<any>): W;
+    /**
+     * Adds an array of conditions to the current instance by iterating through the provided array
+     * and adding each individual condition using the `case` method of the instance.
+     *
+     * @param {ICallback<any>[]} conditions - An array of callback functions representing conditions to be added.
+     * @return {W} The current instance after all conditions have been added.
+     */
     pushCases(conditions: ICallback<any>[]): W;
 }

package/src/outLib/AbstractSwitchCase.js

@@ -1,13 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SwitchCase = void 0;
+/**
+ * Abstract class representing a Switch-Case control structure for handling
+ * conditional chains of operations.
+ *
+ * @template T - The type of the input payload expected by the conditions.
+ * @template P - The type extending IChainContainer, representing the container for the chain of operations.
+ * @template W - The type of the subclass or the expected return type for method chaining.
+ */
 class SwitchCase {
     pipe;
     counter;
+    /**
+     * Creates an instance of the class and initializes the pipe and counter.
+     *
+     * @param {P} pipe - The pipe object used for initialization.
+     * @return {void}
+     */
     constructor(pipe) {
         this.pipe = pipe;
         this.counter = pipe.chain.length ? pipe.chain.length : 0;
     }
+    /**
+     * Adds a conditional case to the processing chain. The case determines
+     * whether further processing should continue based on the provided condition.
+     *
+     * @param {ICallback<any>} condition - A callback function that takes a payload
+     * and evaluates a condition. If the condition is met, further processing may be stopped.
+     * @return {W} Returns the current instance for method chaining.
+     */
     case(condition) {
         this.counter++;
         const id = this.counter;
@@ -21,6 +43,13 @@ class SwitchCase {
         });
         return this;
     }
+    /**
+     * Adds an array of conditions to the current instance by iterating through the provided array
+     * and adding each individual condition using the `case` method of the instance.
+     *
+     * @param {ICallback<any>[]} conditions - An array of callback functions representing conditions to be added.
+     * @return {W} The current instance after all conditions have been added.
+     */
     pushCases(conditions) {
         if (!Array.isArray(conditions))
             return this;

package/src/outLib/Collector.d.ts

@@ -1,11 +1,56 @@
 import { ICollector, ISubscriptionLike } from "./Types";
+/**
+ * The Collector class is responsible for managing a collection of resources or subscription-like objects
+ * that need to be cleaned up or unsubscribed from, ensuring proper resource management.
+ * Implements the ICollector interface.
+ *
+ * The typical lifecycle of a Collector involves collecting subscription-like items, optionally
+ * unsubscribing from specific ones, unsubscribing from all resources, and destroying the collector
+ * when it's no longer needed.
+ */
 export declare class Collector implements ICollector {
     protected arr: ISubscriptionLike[];
     private killed;
+    /**
+     * Adds one or more subscription-like objects to the internal collection.
+     * Ensures the subscriptions are saved for future management if the object
+     * is not in a "killed" state.
+     *
+     * @param {ISubscriptionLike[]} subscriptionLikeList - The subscription-like objects to be collected.
+     * @return {void} This method does not return a value.
+     */
     collect(...subscriptionLikeList: ISubscriptionLike[]): void;
+    /**
+     * Unsubscribes a given subscription and removes it from the internal array.
+     *
+     * @param {ISubscriptionLike | undefined} subscriptionLike - The subscription to unsubscribe and remove. If undefined, no action is taken.
+     * @return {void} This method does not return a value.
+     */
     unsubscribe(subscriptionLike: ISubscriptionLike | undefined): void;
+    /**
+     * Unsubscribes from all the currently active subscriptions managed by this instance.
+     * If the instance is marked as killed, the method will exit without performing any action.
+     *
+     * @return {void | null} Returns `null` if the instance is killed, otherwise does not return a value.
+     */
     unsubscribeAll(): void | null;
+    /**
+     * Determines the size of the array managed by the instance.
+     * If the instance is marked as killed, the size is returned as 0.
+     *
+     * @return {number} The number of elements in the array, or 0 if the instance is killed.
+     */
     size(): number;
+    /**
+     * Cleans up resources by unsubscribing from all subscriptions, clearing the array, and marking the instance as destroyed.
+     *
+     * @return {void} Does not return any value.
+     */
     destroy(): void;
+    /**
+     * Checks if the object is destroyed.
+     *
+     * @return {boolean} Returns true if the object is destroyed, otherwise false.
+     */
     get isDestroyed(): boolean;
 }

package/src/outLib/Collector.js

@@ -2,36 +2,83 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Collector = void 0;
 const FunctionLibs_1 = require("./FunctionLibs");
+/**
+ * The Collector class is responsible for managing a collection of resources or subscription-like objects
+ * that need to be cleaned up or unsubscribed from, ensuring proper resource management.
+ * Implements the ICollector interface.
+ *
+ * The typical lifecycle of a Collector involves collecting subscription-like items, optionally
+ * unsubscribing from specific ones, unsubscribing from all resources, and destroying the collector
+ * when it's no longer needed.
+ */
 class Collector {
     arr = [];
     killed = false;
+    /**
+     * Adds one or more subscription-like objects to the internal collection.
+     * Ensures the subscriptions are saved for future management if the object
+     * is not in a "killed" state.
+     *
+     * @param {ISubscriptionLike[]} subscriptionLikeList - The subscription-like objects to be collected.
+     * @return {void} This method does not return a value.
+     */
     collect(...subscriptionLikeList) {
         if (!this.killed)
             this.arr.push(...subscriptionLikeList);
     }
+    /**
+     * Unsubscribes a given subscription and removes it from the internal array.
+     *
+     * @param {ISubscriptionLike | undefined} subscriptionLike - The subscription to unsubscribe and remove. If undefined, no action is taken.
+     * @return {void} This method does not return a value.
+     */
     unsubscribe(subscriptionLike) {
         if (this.killed)
             return;
         subscriptionLike?.unsubscribe();
         (0, FunctionLibs_1.quickDeleteFromArray)(this.arr, subscriptionLike);
     }
+    /**
+     * Unsubscribes from all the currently active subscriptions managed by this instance.
+     * If the instance is marked as killed, the method will exit without performing any action.
+     *
+     * @return {void | null} Returns `null` if the instance is killed, otherwise does not return a value.
+     */
     unsubscribeAll() {
         if (this.killed)
             return;
-        while (this.arr.length > 0)
-            this.unsubscribe(this.arr.pop());
+        const arr = this.arr;
+        for (let i = 0; i < arr.length; i++)
+            arr[i].unsubscribe();
+        arr.length = 0;
     }
+    /**
+     * Determines the size of the array managed by the instance.
+     * If the instance is marked as killed, the size is returned as 0.
+     *
+     * @return {number} The number of elements in the array, or 0 if the instance is killed.
+     */
     size() {
         if (this.killed)
             return 0;
         return this.arr.length;
     }
+    /**
+     * Cleans up resources by unsubscribing from all subscriptions, clearing the array, and marking the instance as destroyed.
+     *
+     * @return {void} Does not return any value.
+     */
     destroy() {
         this.unsubscribeAll();
         this.arr.length = 0;
         this.arr = 0;
         this.killed = true;
     }
+    /**
+     * Checks if the object is destroyed.
+     *
+     * @return {boolean} Returns true if the object is destroyed, otherwise false.
+     */
     get isDestroyed() {
         return this.killed;
     }

package/src/outLib/FilterCollection.d.ts

@@ -1,17 +1,70 @@
 import { ICallback, IErrorCallback, IFilter, IFilterCase, IFilterChainCallback, IFilterPayload, IFilterResponse, IFilterSetup, IFilterSwitch } from "./Types";
 import { SwitchCase } from "./AbstractSwitchCase";
+/**
+ * FilterCollection is a generic class implementing the IFilter and IFilterSwitch interfaces.
+ * It is designed to handle a series of filtering operations on a given payload, structured as a chain of filter methods.
+ * The class allows addition of filters, chaining of multiple filters, and provides mechanisms for handling payload processing flow.
+ *
+ * @template T The type of data that the filters will operate upon.
+ */
 export declare class FilterCollection<T> implements IFilter<T>, IFilterSwitch<T> {
     chain: IFilterChainCallback[];
     flow: IFilterPayload;
     response: IFilterResponse;
     private errHandler;
+    /**
+     * Determines whether the chain is empty.
+     * @return {boolean} Returns true if the chain contains no elements, otherwise false.
+     */
     get isEmpty(): boolean;
+    /**
+     * Adds a callback to the filter chain and returns the current instance.
+     *
+     * @param {IFilterChainCallback} callback - The callback function to be added to the filter chain.
+     * @return {IFilterSetup<T>} The current instance of IFilterSetup.
+     */
     private push;
+    /**
+     * Filters the data based on the given condition.
+     *
+     * @param {ICallback<any>} condition - A callback function that determines whether a data item should be included.
+     *                                      Should return a truthy value to include the item.
+     * @return {IFilterSetup<T>} - The updated filter setup after applying the condition.
+     */
     filter(condition: ICallback<any>): IFilterSetup<T>;
+    /**
+     * Adds an array of filter conditions to the current filter setup.
+     *
+     * @param {ICallback<any>[]} conditions - An array of callback functions representing filter conditions.
+     * @return {IFilterSetup<T>} The updated filter setup instance.
+     */
     pushFilters(conditions: ICallback<any>[]): IFilterSetup<T>;
+    /**
+     * Creates and returns a new instance of the `FilterSwitchCase` class to handle switch case logic with the current context.
+     *
+     * @return {FilterSwitchCase<T>} A new instance of `FilterSwitchCase` initialized with the current context.
+     */
     switch(): FilterSwitchCase<T>;
+    /**
+     * Processes a chain of functions with the given input value and manages the execution flow through the chain.
+     *
+     * @param {T} value - The input value to be processed through the chain.
+     * @return {IFilterResponse} The final response containing the processing status and payload.
+     */
     processChain(value: T): IFilterResponse;
+    /**
+     * Assigns an error handler function to manage errors within the application.
+     *
+     * @param {IErrorCallback} errorHandler - A callback function that will handle error events.
+     * @return {void}
+     */
     addErrorHandler(errorHandler: IErrorCallback): void;
 }
+/**
+ * The FilterSwitchCase class extends the SwitchCase class and represents a specific type of switch case
+ * logic applied to a collection of filters. It is used for branching logic based on filter cases.
+ *
+ * @template T - The type of the elements being processed by the filters.
+ */
 export declare class FilterSwitchCase<T> extends SwitchCase<T, FilterCollection<T>, IFilterCase<T>> {
 }

package/src/outLib/FilterCollection.js

@@ -2,21 +2,51 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilterSwitchCase = exports.FilterCollection = void 0;
 const AbstractSwitchCase_1 = require("./AbstractSwitchCase");
+/**
+ * FilterCollection is a generic class implementing the IFilter and IFilterSwitch interfaces.
+ * It is designed to handle a series of filtering operations on a given payload, structured as a chain of filter methods.
+ * The class allows addition of filters, chaining of multiple filters, and provides mechanisms for handling payload processing flow.
+ *
+ * @template T The type of data that the filters will operate upon.
+ */
 class FilterCollection {
     chain = [];
     flow = { isBreak: false, isAvailable: false, payload: null };
     response = { isOK: false, payload: undefined };
     errHandler;
+    /**
+     * Determines whether the chain is empty.
+     * @return {boolean} Returns true if the chain contains no elements, otherwise false.
+     */
     get isEmpty() {
         return !this.chain.length;
     }
+    /**
+     * Adds a callback to the filter chain and returns the current instance.
+     *
+     * @param {IFilterChainCallback} callback - The callback function to be added to the filter chain.
+     * @return {IFilterSetup<T>} The current instance of IFilterSetup.
+     */
     push(callback) {
         this.chain.push(callback);
         return this;
     }
+    /**
+     * Filters the data based on the given condition.
+     *
+     * @param {ICallback<any>} condition - A callback function that determines whether a data item should be included.
+     *                                      Should return a truthy value to include the item.
+     * @return {IFilterSetup<T>} - The updated filter setup after applying the condition.
+     */
     filter(condition) {
         return this.push((data) => condition(data.payload) && (data.isAvailable = true));
     }
+    /**
+     * Adds an array of filter conditions to the current filter setup.
+     *
+     * @param {ICallback<any>[]} conditions - An array of callback functions representing filter conditions.
+     * @return {IFilterSetup<T>} The updated filter setup instance.
+     */
     pushFilters(conditions) {
         if (!Array.isArray(conditions))
             return this;
@@ -24,9 +54,20 @@ class FilterCollection {
             this.filter(conditions[i]);
         return this;
     }
+    /**
+     * Creates and returns a new instance of the `FilterSwitchCase` class to handle switch case logic with the current context.
+     *
+     * @return {FilterSwitchCase<T>} A new instance of `FilterSwitchCase` initialized with the current context.
+     */
     switch() {
         return new FilterSwitchCase(this);
     }
+    /**
+     * Processes a chain of functions with the given input value and manages the execution flow through the chain.
+     *
+     * @param {T} value - The input value to be processed through the chain.
+     * @return {IFilterResponse} The final response containing the processing status and payload.
+     */
     processChain(value) {
         const chain = this.chain;
         const data = this.flow;
@@ -36,7 +77,8 @@ class FilterCollection {
         data.payload = value;
         data.isBreak = false;
         try {
-            for (let i = 0; i < chain.length; i++) {
+            const len = chain.length;
+            for (let i = 0; i < len; i++) {
                 data.isAvailable = false;
                 chain[i](data);
                 if (!data.isAvailable)
@@ -58,11 +100,23 @@ class FilterCollection {
         response.payload = data.payload;
         return response;
     }
+    /**
+     * Assigns an error handler function to manage errors within the application.
+     *
+     * @param {IErrorCallback} errorHandler - A callback function that will handle error events.
+     * @return {void}
+     */
     addErrorHandler(errorHandler) {
         this.errHandler = errorHandler;
     }
 }
 exports.FilterCollection = FilterCollection;
+/**
+ * The FilterSwitchCase class extends the SwitchCase class and represents a specific type of switch case
+ * logic applied to a collection of filters. It is used for branching logic based on filter cases.
+ *
+ * @template T - The type of the elements being processed by the filters.
+ */
 class FilterSwitchCase extends AbstractSwitchCase_1.SwitchCase {
 }
 exports.FilterSwitchCase = FilterSwitchCase;

package/src/outLib/FunctionLibs.d.ts

@@ -1,6 +1,48 @@
 import { IListener, ISubscribeGroup, ISubscribeObject } from "./Types";
+/**
+ * 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.
+ */
 export declare function sortAscending(a: ISubscribeObject<any>, b: ISubscribeObject<any>): number;
+/**
+ * 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.
+ */
 export declare function sortDescending(a: ISubscribeObject<any>, b: ISubscribeObject<any>): number;
+/**
+ * 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.
+ */
 export declare function deleteFromArray<T>(arr: T[], component: T): boolean;
+/**
+ * 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.
+ */
 export declare function quickDeleteFromArray<T>(arr: T[], component: T): boolean;
-export declare function getListener<T>(listener: ISubscribeGroup<T>): IListener<T>;
+/**
+ * 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.
+ */
+export declare function getListener<T>(listenerGroup: ISubscribeGroup<T>): IListener<T>;