@develia/commons 0.4.14 → 0.4.16

package/dist/esm/{from.js → collections/from.js}

@@ -1,5 +1,12 @@
-import { shallowEqual, toPairs } from "./utilities.js";
-import Order from "./order.js";
+import { shallowEqual, toPairs } from "../utilities.js";
+import Order from "../order.js";
+/**
+ * Creates a new From instance from an Iterable or a Supplier of an Iterable.
+ * @template T - The type of elements in the source.
+ * @param {Iterable<T> | Supplier<Iterable<T>>} source - The source data.
+ * @returns {From<T> | From<KeyValuePair<any, any>>} A new From instance.
+ * @throws {string} If source is null or invalid.
+ */
 export default function from(source) {
     if (source == null)
         throw "Source is null.";
@@ -13,7 +20,16 @@ export default function from(source) {
     }
     throw "Invalid source.";
 }
+/**
+ * A LINQ-like wrapper for iterables that provides various transformation and query methods.
+ * @template T - The type of elements in the sequence.
+ */
 export class From {
+    /**
+     * Creates a From instance from an object's entries.
+     * @param {any} obj - The object to convert to pairs.
+     * @returns {From<KeyValuePair<any, any>>} A From instance of key-value pairs.
+     */
     static object(obj) {
         return new From(function () {
             return toPairs(obj);
@@ -22,14 +38,30 @@ export class From {
     constructor(fn) {
         this._fn = fn;
     }
+    /**
+     * Creates a From instance from a supplier function.
+     * @template T
+     * @param {Supplier<Iterable<T>>} callable - A function that returns an Iterable.
+     * @returns {From<T>} A new From instance.
+     */
     static fn(callable) {
         return new From(callable);
     }
-    ;
+    /**
+     * Collects all elements into an array and returns a new From instance from it.
+     * Useful for freezing the sequence and preventing multiple iterations over a generator.
+     * @returns {From<T>} A new From instance with cached data.
+     */
     collect() {
         const cache = Array.from(this);
         return From.iterable(cache);
     }
+    /**
+     * Creates a From instance from an Iterable.
+     * @template T
+     * @param {Iterable<T>} iterable - The source iterable.
+     * @returns {From<T>} A new From instance.
+     */
     static iterable(iterable) {
         return From.fn(function* () {
             for (const item of iterable) {
@@ -37,7 +69,12 @@ export class From {
             }
         });
     }
-    ;
+    /**
+     * Maps each element of the sequence into a new form.
+     * @template R
+     * @param {UnaryFunction<T, R>} mapper - A transformation function.
+     * @returns {From<R>} A new From instance with the mapped elements.
+     */
     map(mapper) {
         const self = this;
         return From.fn(function* () {
@@ -49,6 +86,11 @@ export class From {
     *[Symbol.iterator]() {
         yield* this._fn();
     }
+    /**
+     * Checks if all elements in the sequence satisfy the given predicate.
+     * @param {Predicate<T>} predicate - A function to test each element.
+     * @returns {boolean} True if all elements satisfy the predicate.
+     */
     all(predicate) {
         for (let item of this._fn()) {
             if (!predicate(item)) {
@@ -57,6 +99,12 @@ export class From {
         }
         return true;
     }
+    /**
+     * Checks if any element in the sequence satisfies the given predicate.
+     * If no predicate is provided, checks if the sequence is not empty.
+     * @param {Optional<Predicate<T>>} predicate - A function to test each element.
+     * @returns {boolean} True if any element satisfies the predicate.
+     */
     any(predicate = undefined) {
         for (let item of this) {
             if (predicate == null || predicate(item)) {
@@ -65,9 +113,19 @@ export class From {
         }
         return false;
     }
+    /**
+     * Gets the number of elements in the sequence.
+     * @returns {number} The count of elements.
+     */
     get length() {
         return this.count();
     }
+    /**
+     * Counts the number of elements that satisfy the given predicate.
+     * If no predicate is provided, counts all elements.
+     * @param {Optional<Predicate<T>>} predicate - A function to test each element.
+     * @returns {number} The count of elements.
+     */
     count(predicate = undefined) {
         let output = 0;
         for (let item of this) {
@@ -77,6 +135,11 @@ export class From {
         }
         return output;
     }
+    /**
+     * Filters the sequence based on a predicate.
+     * @param {Predicate<T>} predicate - A function to test each element.
+     * @returns {From<T>} A new From instance with the filtered elements.
+     */
     filter(predicate) {
         const self = this;
         return From.fn(function* () {
@@ -87,6 +150,11 @@ export class From {
             }
         });
     }
+    /**
+     * Checks if the sequence contains a specific value.
+     * @param {T} value - The value to search for.
+     * @returns {boolean} True if the value is found.
+     */
     contains(value) {
         for (let item of this) {
             if (item === value) {
@@ -95,6 +163,11 @@ export class From {
         }
         return false;
     }
+    /**
+     * Returns the first element of the sequence that satisfies a condition.
+     * @param {Predicate<T>} [predicate] - Optional condition.
+     * @returns {T | undefined} The first element or undefined.
+     */
     first(predicate) {
         if (predicate) {
             for (let item of this) {
@@ -104,12 +177,19 @@ export class From {
             }
         }
         else {
+            // noinspection LoopStatementThatDoesntLoopJS
             for (let item of this) {
                 return item;
             }
         }
         return undefined;
     }
+    /**
+     * Returns the only element of the sequence that satisfies a condition, or throws if more than one exists.
+     * @param {Predicate<T>} [predicate] - Optional condition.
+     * @returns {T | null} The single element or null if not found.
+     * @throws {Error} If more than one element is found.
+     */
     single(predicate) {
         let found = false;
         let output = null;
@@ -125,6 +205,7 @@ export class From {
             }
         }
         else {
+            // noinspection LoopStatementThatDoesntLoopJS
             for (let item of this) {
                 if (found) {
                     throw new Error("Sequence contains more than one element.");
@@ -135,6 +216,11 @@ export class From {
         }
         return output;
     }
+    /**
+     * Appends an item to the end of the sequence.
+     * @param {T} item - The item to append.
+     * @returns {From<T>} A new From instance.
+     */
     append(item) {
         const self = this;
         return From.fn(function* () {
@@ -144,6 +230,11 @@ export class From {
             yield item;
         });
     }
+    /**
+     * Prepends an item to the beginning of the sequence.
+     * @param {T} item - The item to prepend.
+     * @returns {From<T>} A new From instance.
+     */
     prepend(item) {
         const self = this;
         return From.fn(function* () {
@@ -153,6 +244,11 @@ export class From {
             }
         });
     }
+    /**
+     * Gets the element at a specific index.
+     * @param {number} index - The zero-based index.
+     * @returns {T | undefined} The element at the index or undefined.
+     */
     at(index) {
         let idx = 0;
         for (let item of this) {
@@ -162,6 +258,11 @@ export class From {
         }
         return undefined;
     }
+    /**
+     * Returns the last element of the sequence that satisfies a condition.
+     * @param {Predicate<T>} [predicate] - Optional condition.
+     * @returns {T | undefined} The last element or undefined.
+     */
     last(predicate) {
         let last = undefined;
         if (predicate)
@@ -177,6 +278,12 @@ export class From {
         }
         return last;
     }
+    /**
+     * Projects each element of a sequence to an Iterable and flattens the resulting sequences into one sequence.
+     * @template R
+     * @param {UnaryFunction<T, Iterable<R>>} mapper - A transformation function.
+     * @returns {From<R>} A new From instance.
+     */
     mapMany(mapper) {
         const self = this;
         return From.fn(function* () {
@@ -188,6 +295,10 @@ export class From {
             }
         });
     }
+    /**
+     * Flattens a sequence of iterables.
+     * @returns {From<any>} A new From instance.
+     */
     flatten() {
         const self = this;
         return From.fn(function* () {
@@ -199,6 +310,11 @@ export class From {
             }
         });
     }
+    /**
+     * Calculates the sum of the elements in the sequence.
+     * @param {UnaryFunction<T, number>} [mapper] - Optional projection function.
+     * @returns {number} The sum.
+     */
     sum(mapper) {
         let total = 0;
         if (mapper)
@@ -211,6 +327,11 @@ export class From {
             }
         return total;
     }
+    /**
+     * Calculates the average of the elements in the sequence.
+     * @param {UnaryFunction<T, number>} [mapper] - Optional projection function.
+     * @returns {number} The average.
+     */
     avg(mapper) {
         let total = 0;
         let count = 0;
@@ -226,6 +347,11 @@ export class From {
             }
         return count > 0 ? total / count : 0;
     }
+    /**
+     * Returns the maximum value in the sequence.
+     * @param {UnaryFunction<T, number>} mapper - Projection function.
+     * @returns {number} The maximum value.
+     */
     max(mapper) {
         let max = -Infinity;
         for (let item of this) {
@@ -234,6 +360,11 @@ export class From {
         }
         return max;
     }
+    /**
+     * Returns the minimum value in the sequence.
+     * @param {UnaryFunction<T, number>} mapper - Projection function.
+     * @returns {number} The minimum value.
+     */
     min(mapper) {
         let min = Infinity;
         for (let item of this) {
@@ -242,6 +373,11 @@ export class From {
         }
         return min;
     }
+    /**
+     * Returns the element with the maximum value.
+     * @param {UnaryFunction<T, number>} mapper - Projection function.
+     * @returns {T | undefined} The element with the maximum value.
+     */
     maxBy(mapper) {
         let max = -Infinity;
         let maxItem;
@@ -254,6 +390,11 @@ export class From {
         }
         return maxItem;
     }
+    /**
+     * Returns the element with the minimum value.
+     * @param {UnaryFunction<T, number>} mapper - Projection function.
+     * @returns {T | undefined} The element with the minimum value.
+     */
     minBy(mapper) {
         let min = Infinity;
         let minItem;
@@ -266,6 +407,13 @@ export class From {
         }
         return minItem;
     }
+    /**
+     * Sorts the elements of the sequence.
+     * @template R
+     * @param {UnaryFunction<T, R>} mapper - Projection function for the key to sort by.
+     * @param {Order} [order] - Ascending or Descending.
+     * @returns {From<T>} A new From instance.
+     */
     orderBy(mapper, order = Order.Ascending) {
         const array = Array.from(this._fn());
         if (order == Order.Ascending) {
@@ -287,6 +435,13 @@ export class From {
         }
         return From.iterable(array);
     }
+    /**
+     * Groups the elements of the sequence.
+     * @template TKey
+     * @param {UnaryFunction<T, TKey>} keySelector - Function to extract the key for each element.
+     * @param {EqualityComparer<TKey>} [equalityComparer] - Optional comparer for keys.
+     * @returns {From<Grouping<TKey, T>>} A new From instance.
+     */
     groupBy(keySelector, equalityComparer) {
         equalityComparer = (equalityComparer == null ? shallowEqual : equalityComparer);
         const self = this;
@@ -309,6 +464,11 @@ export class From {
             yield* groups.map(([key, values]) => new Grouping(key, values));
         });
     }
+    /**
+     * Returns a specified number of contiguous elements from the start of the sequence.
+     * @param {number} n - The number of elements to return.
+     * @returns {From<T>} A new From instance.
+     */
     head(n) {
         const self = this;
         return From.fn(function* () {
@@ -323,6 +483,11 @@ export class From {
             }
         });
     }
+    /**
+     * Returns a specified number of contiguous elements from the end of the sequence.
+     * @param {number} n - The number of elements to return.
+     * @returns {From<T>} A new From instance.
+     */
     tail(n) {
         const self = this;
         return From.fn(function* () {
@@ -336,14 +501,29 @@ export class From {
             yield* buffer;
         });
     }
+    /**
+     * Performs the specified action on each element of the sequence.
+     * @param {Consumer<T>} action - The action to perform.
+     */
     forEach(action) {
         for (let item of this) {
             action(item);
         }
     }
+    /**
+     * Converts the sequence to an array.
+     * @returns {T[]} The array.
+     */
     toArray() {
         return Array.from(this);
     }
+    /**
+     * Converts the sequence to a record.
+     * @template R
+     * @param {UnaryFunction<T, string | symbol | number>} keySelector - Key selector.
+     * @param {UnaryFunction<T, R>} valueSelector - Value selector.
+     * @returns {Record<string | symbol | number, R>} The record.
+     */
     toRecord(keySelector, valueSelector) {
         const output = {};
         for (let item of this) {
@@ -351,6 +531,13 @@ export class From {
         }
         return output;
     }
+    /**
+     * Converts the sequence to a Map.
+     * @template RKey, RValue
+     * @param {UnaryFunction<T, RKey>} keySelector - Key selector.
+     * @param {UnaryFunction<T, RValue>} valueSelector - Value selector.
+     * @returns {Map<RKey, RValue>} The map.
+     */
     toMap(keySelector, valueSelector) {
         const map = new Map();
         for (let item of this) {
@@ -360,9 +547,19 @@ export class From {
         }
         return map;
     }
+    /**
+     * Returns elements that are instances of a specific primitive type.
+     * @param {string} type - The type string (e.g., 'string', 'number').
+     * @returns {From<T>} A new From instance.
+     */
     instancesOf(type) {
         return this.filter(item => typeof item === type);
     }
+    /**
+     * Checks if all elements are instances of a specific class.
+     * @param {new (...args: any[]) => any} type - The class constructor.
+     * @returns {boolean} True if all elements are instances of the type.
+     */
     allInstanceOf(type) {
         for (let item of this) {
             if (!(item instanceof type)) {
@@ -371,6 +568,11 @@ export class From {
         }
         return true;
     }
+    /**
+     * Returns distinct elements from the sequence.
+     * @param {EqualityComparer<T>} [eq_comparer] - Optional equality comparer.
+     * @returns {From<T>} A new From instance.
+     */
     distinct(eq_comparer) {
         if (eq_comparer == null)
             eq_comparer = shallowEqual;
@@ -385,6 +587,12 @@ export class From {
             }
         });
     }
+    /**
+     * Inserts an item at a specific index.
+     * @param {T} item - The item to insert.
+     * @param {number} index - The zero-based index.
+     * @returns {From<T>} A new From instance.
+     */
     insert(item, index) {
         const self = this;
         return From.fn(function* () {
@@ -403,6 +611,11 @@ export class From {
             }
         });
     }
+    /**
+     * Bypasses a specified number of elements in a sequence and then returns the remaining elements.
+     * @param {number} n - The number of elements to skip.
+     * @returns {From<T>} A new From instance.
+     */
     skip(n) {
         const self = this;
         return From.fn(function* () {
@@ -415,6 +628,11 @@ export class From {
             }
         });
     }
+    /**
+     * Concatenates two sequences.
+     * @param {Iterable<T>} other - The other sequence.
+     * @returns {From<T>} A new From instance.
+     */
     union(other) {
         const self = this;
         return From.fn(function* () {
@@ -422,6 +640,15 @@ export class From {
             yield* other;
         });
     }
+    /**
+     * Correlates the elements of two sequences based on matching keys.
+     * @template T2, R, R2
+     * @param {Iterable<T2>} other - The other sequence.
+     * @param {UnaryFunction<T, R>} thisKeySelector - Key selector for this sequence.
+     * @param {UnaryFunction<T2, R>} otherKeySelector - Key selector for the other sequence.
+     * @param {(thisItem: T, otherItem: T2) => R2} resultSelector - Function to create a result element from two matching elements.
+     * @returns {From<R2>} A new From instance.
+     */
     innerJoin(other, thisKeySelector, otherKeySelector, resultSelector) {
         const self = this;
         return From.fn(() => {
@@ -434,6 +661,15 @@ export class From {
                 .map(item => resultSelector(item, otherByKey.get(thisKeySelector(item))));
         });
     }
+    /**
+     * Performs a left join on two sequences.
+     * @template U, K, R
+     * @param {Iterable<U>} other - The other sequence.
+     * @param {UnaryFunction<T, K>} thisKeySelector - Key selector for this sequence.
+     * @param {UnaryFunction<U, K>} otherKeySelector - Key selector for the other sequence.
+     * @param {(thisItem: T, otherItem: U | undefined) => R} resultSelector - Function to create a result element.
+     * @returns {From<R>} A new From instance.
+     */
     leftJoin(other, thisKeySelector, otherKeySelector, resultSelector) {
         const self = this;
         return From.fn(() => {
@@ -444,6 +680,15 @@ export class From {
             return Array.from(self).map(item => resultSelector(item, otherByKey.get(thisKeySelector(item))));
         });
     }
+    /**
+     * Performs a left group join on two sequences.
+     * @template U, K, R
+     * @param {Iterable<U>} other - The other sequence.
+     * @param {UnaryFunction<T, K>} thisKeySelector - Key selector for this sequence.
+     * @param {UnaryFunction<U, K>} otherKeySelector - Key selector for the other sequence.
+     * @param {(thisItem: T, otherItems: Array<U>) => R} resultSelector - Function to create a result element.
+     * @returns {From<R>} A new From instance.
+     */
     leftGroupJoin(other, thisKeySelector, otherKeySelector, resultSelector) {
         const self = this;
         return From.fn(() => {
@@ -458,6 +703,15 @@ export class From {
             return Array.from(self).map(item => resultSelector(item, otherByKeys.get(thisKeySelector(item)) || []));
         });
     }
+    /**
+     * Performs a right group join on two sequences.
+     * @template U, K, R
+     * @param {Iterable<U>} other - The other sequence.
+     * @param {UnaryFunction<T, K>} thisKeySelector - Key selector for this sequence.
+     * @param {UnaryFunction<U, K>} otherKeySelector - Key selector for the other sequence.
+     * @param {(thisItems: Array<T>, otherItem: U) => R} resultSelector - Function to create a result element.
+     * @returns {From<R>} A new From instance.
+     */
     rightGroupJoin(other, thisKeySelector, otherKeySelector, resultSelector) {
         const self = this;
         return From.fn(() => {
@@ -472,6 +726,15 @@ export class From {
             return Array.from(other).map(item => resultSelector(thisByKeys.get(otherKeySelector(item)) || [], item));
         });
     }
+    /**
+     * Performs a right join on two sequences.
+     * @template U, K, R
+     * @param {Iterable<U>} other - The other sequence.
+     * @param {UnaryFunction<T, K>} thisKeySelector - Key selector for this sequence.
+     * @param {UnaryFunction<U, K>} otherKeySelector - Key selector for the other sequence.
+     * @param {(thisItem: T | undefined, otherItem: U) => R} resultSelector - Function to create a result element.
+     * @returns {From<R>} A new From instance.
+     */
     rightJoin(other, thisKeySelector, otherKeySelector, resultSelector) {
         const self = this;
         return From.fn(() => {
@@ -483,10 +746,21 @@ export class From {
         });
     }
 }
+/**
+ * Represents a group of elements that have a common key.
+ * @template TKey, T
+ */
 export class Grouping extends From {
+    /**
+     * Gets the key of the group.
+     */
     get key() {
         return this._key;
     }
+    /**
+     * @param {TKey} key - The group key.
+     * @param {Array<T>} values - The values in the group.
+     */
     constructor(key, values) {
         super(() => values);
         this._key = key;