@develia/commons 0.4.14 → 0.4.16

package/src/{from.ts → collections/from.ts}

@@ -1,9 +1,16 @@
-import type {Consumer, EqualityComparer, UnaryFunction, Predicate, Supplier, Optional, Nullable} from "./types.js";
-import {shallowEqual, toPairs} from "./utilities.js";
-import KeyValuePair from "./key-value-pair.js";
-import Order from "./order.js";
-
-
+import type {Consumer, EqualityComparer, UnaryFunction, Predicate, Supplier, Optional, Nullable} from "../types.js";
+import {shallowEqual, toPairs} from "../utilities.js";
+import KeyValuePair from "../key-value-pair.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<T>(source: Iterable<T> | Supplier<Iterable<T>>): From<T> | From<KeyValuePair<any, any>> {
     if (source == null)
         throw "Source is null.";
@@ -12,14 +19,23 @@ export default function from<T>(source: Iterable<T> | Supplier<Iterable<T>>): Fr
     if (typeof source[Symbol.iterator] === 'function') {
         return From.iterable<T>(source);
     } else if (typeof source === 'object') {
-        return From.object(source)
+        return From.object(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<T> implements Iterable<T> {
 
+    /**
+     * 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.
+     */
     public static object(obj: any): From<KeyValuePair<any, any>> {
         return new From<KeyValuePair<any, any>>(function () {
             return toPairs(obj);
@@ -33,37 +49,65 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public static fn<T>(callable: Supplier<Iterable<T>>): From<T> {
         return new From<T>(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.
+     */
     public collect(): From<T> {
         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.
+     */
     public static iterable<T>(iterable: Iterable<T>): From<T> {
         return From.fn<T>(function* () {
             for (const item of iterable) {
                 yield item;
             }
         });
-    };
+    }
 
+    /**
+     * 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.
+     */
     public map<R>(mapper: UnaryFunction<T, R>): From<R> {
         const self = this;
         return From.fn<R>(function* () {
             for (let item of self) {
                 yield mapper(item);
             }
-        })
+        });
     }
 
     * [Symbol.iterator](): Iterator<T> {
-        yield* this._fn()
+        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.
+     */
     public all(predicate: Predicate<T>): boolean {
         for (let item of this._fn()) {
             if (!predicate(item)) {
@@ -73,6 +117,12 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public any(predicate: Optional<Predicate<T>> = undefined): boolean {
         for (let item of this) {
             if (predicate == null || predicate(item)) {
@@ -82,10 +132,20 @@ export class From<T> implements Iterable<T> {
         return false;
     }
 
+    /**
+     * Gets the number of elements in the sequence.
+     * @returns {number} The count of elements.
+     */
     public get length(): number {
         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.
+     */
     public count(predicate: Optional<Predicate<T>> = undefined): number {
 
         let output = 0;
@@ -99,6 +159,11 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public filter(predicate: Predicate<T>): From<T> {
         const self = this;
         return From.fn<T>(function* () {
@@ -110,6 +175,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * Checks if the sequence contains a specific value.
+     * @param {T} value - The value to search for.
+     * @returns {boolean} True if the value is found.
+     */
     public contains(value: T): boolean {
         for (let item of this) {
             if (item === value) {
@@ -120,7 +190,11 @@ export class From<T> implements Iterable<T> {
     }
 
 
-    // noinspection LoopStatementThatDoesntLoopJS
+    /**
+     * 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.
+     */
     public first(predicate?: Predicate<T>): T | undefined {
 
         if (predicate) {
@@ -139,7 +213,12 @@ export class From<T> implements Iterable<T> {
         return undefined;
     }
 
-    // noinspection LoopStatementThatDoesntLoopJS
+    /**
+     * 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.
+     */
     public single(predicate?: Predicate<T>): T | null {
 
         let found = false;
@@ -169,6 +248,11 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public append(item: T): From<T> {
         const self = this;
         return From.fn<T>(function* () {
@@ -179,6 +263,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * Prepends an item to the beginning of the sequence.
+     * @param {T} item - The item to prepend.
+     * @returns {From<T>} A new From instance.
+     */
     public prepend(item: T): From<T> {
         const self = this;
         return From.fn<T>(function* () {
@@ -189,6 +278,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * Gets the element at a specific index.
+     * @param {number} index - The zero-based index.
+     * @returns {T | undefined} The element at the index or undefined.
+     */
     public at(index: number): T | undefined {
         let idx = 0;
         for (let item of this) {
@@ -199,6 +293,11 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public last(predicate?: Predicate<T>): T | undefined {
 
 
@@ -218,6 +317,12 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public mapMany<R>(mapper: UnaryFunction<T, Iterable<R>>): From<R> {
         const self = this;
         return From.fn(function* () {
@@ -230,6 +335,10 @@ export class From<T> implements Iterable<T> {
         })
     }
 
+    /**
+     * Flattens a sequence of iterables.
+     * @returns {From<any>} A new From instance.
+     */
     public flatten(): From<any> {
         const self = this;
         return From.fn<T>(function* () {
@@ -242,6 +351,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * Calculates the sum of the elements in the sequence.
+     * @param {UnaryFunction<T, number>} [mapper] - Optional projection function.
+     * @returns {number} The sum.
+     */
     public sum(mapper?: UnaryFunction<T, number>): number {
         let total = 0;
 
@@ -256,6 +370,11 @@ export class From<T> implements Iterable<T> {
         return total;
     }
 
+    /**
+     * Calculates the average of the elements in the sequence.
+     * @param {UnaryFunction<T, number>} [mapper] - Optional projection function.
+     * @returns {number} The average.
+     */
     public avg(mapper?: UnaryFunction<T, number>): number {
         let total = 0;
         let count = 0;
@@ -273,6 +392,11 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public max(mapper: UnaryFunction<T, number>): number {
         let max = -Infinity;
         for (let item of this) {
@@ -282,6 +406,11 @@ export class From<T> implements Iterable<T> {
         return max;
     }
 
+    /**
+     * Returns the minimum value in the sequence.
+     * @param {UnaryFunction<T, number>} mapper - Projection function.
+     * @returns {number} The minimum value.
+     */
     public min(mapper: UnaryFunction<T, number>): number {
         let min = Infinity;
         for (let item of this) {
@@ -291,6 +420,11 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public maxBy(mapper: UnaryFunction<T, number>): T | undefined {
         let max = -Infinity;
         let maxItem: T | undefined;
@@ -304,6 +438,11 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public minBy(mapper: UnaryFunction<T, number>): T | undefined {
         let min = Infinity;
         let minItem: T | undefined;
@@ -317,6 +456,13 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public orderBy<R>(mapper: UnaryFunction<T, R>, order: Order = Order.Ascending): From<T> {
         const array = Array.from(this._fn());
         if (order == Order.Ascending) {
@@ -338,6 +484,13 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public groupBy<TKey>(keySelector: UnaryFunction<T, TKey>, equalityComparer?: EqualityComparer<TKey>): From<Grouping<TKey, T>> {
 
         equalityComparer = (equalityComparer == null ? shallowEqual : equalityComparer);
@@ -363,6 +516,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public head(n: number): From<T> {
 
         const self = this;
@@ -378,6 +536,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public tail(n: number): From<T> {
 
         const self = this;
@@ -393,16 +556,31 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * Performs the specified action on each element of the sequence.
+     * @param {Consumer<T>} action - The action to perform.
+     */
     public forEach(action: Consumer<T>): void {
         for (let item of this) {
             action(item);
         }
     }
 
+    /**
+     * Converts the sequence to an array.
+     * @returns {T[]} The array.
+     */
     public toArray(): T[] {
         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.
+     */
     public toRecord<R>(keySelector: UnaryFunction<T, string | symbol | number>, valueSelector: UnaryFunction<T, R>): Record<string | symbol | number, R> {
         const output: Record<string | symbol | number, R> = {};
 
@@ -412,6 +590,13 @@ export class From<T> implements Iterable<T> {
         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.
+     */
     public toMap<RKey, RValue>(keySelector: UnaryFunction<T, RKey>, valueSelector: UnaryFunction<T, RValue>): Map<RKey, RValue> {
         const map = new Map<any, any>();
 
@@ -425,10 +610,20 @@ export class From<T> implements Iterable<T> {
     }
 
 
+    /**
+     * 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.
+     */
     public instancesOf(type: string): From<T> {
         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.
+     */
     public allInstanceOf(type: new (...args: any[]) => any): boolean {
         for (let item of this) {
             if (!(item instanceof type)) {
@@ -438,6 +633,11 @@ export class From<T> implements Iterable<T> {
         return true;
     }
 
+    /**
+     * Returns distinct elements from the sequence.
+     * @param {EqualityComparer<T>} [eq_comparer] - Optional equality comparer.
+     * @returns {From<T>} A new From instance.
+     */
     public distinct(eq_comparer?: EqualityComparer<T>): From<T> {
 
         if (eq_comparer == null)
@@ -457,6 +657,12 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public insert(item: T, index: number): From<T> {
 
         const self = this;
@@ -477,6 +683,11 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public skip(n: number): From<T> {
         const self = this;
         return From.fn<T>(function* () {
@@ -491,6 +702,11 @@ export class From<T> implements Iterable<T> {
     }
 
 
+    /**
+     * Concatenates two sequences.
+     * @param {Iterable<T>} other - The other sequence.
+     * @returns {From<T>} A new From instance.
+     */
     public union(other: Iterable<T>): From<T> {
         const self = this;
         return From.fn<T>(function* () {
@@ -499,6 +715,15 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public innerJoin<T2, R, R2>(other: Iterable<T2>, thisKeySelector: UnaryFunction<T, R>, otherKeySelector: UnaryFunction<T2, R>, resultSelector: (thisItem: T, otherItem: T2) => R2): From<R2> {
 
         const self = this;
@@ -513,6 +738,15 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public leftJoin<U, K, R>(other: Iterable<U>, thisKeySelector: UnaryFunction<T, K>, otherKeySelector: UnaryFunction<U, K>, resultSelector: (thisItem: T, otherItem: U | undefined) => R): From<R> {
 
         const self = this;
@@ -526,6 +760,15 @@ export class From<T> implements Iterable<T> {
     }
 
 
+    /**
+     * 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.
+     */
     public leftGroupJoin<U, K, R>(other: Iterable<U>, thisKeySelector: UnaryFunction<T, K>, otherKeySelector: UnaryFunction<U, K>, resultSelector: (thisItem: T, otherItems: Array<U>) => R): From<R> {
 
         const self = this;
@@ -542,6 +785,15 @@ export class From<T> implements Iterable<T> {
         });
     }
 
+    /**
+     * 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.
+     */
     public rightGroupJoin<U, K, R>(other: Iterable<U>, thisKeySelector: UnaryFunction<T, K>, otherKeySelector: UnaryFunction<U, K>, resultSelector: (thisItems: Array<T>, otherItem: U) => R): From<R> {
 
         const self = this;
@@ -559,6 +811,15 @@ export class From<T> implements Iterable<T> {
     }
 
 
+    /**
+     * 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.
+     */
     public rightJoin<U, K, R>(other: Iterable<U>, thisKeySelector: UnaryFunction<T, K>, otherKeySelector: UnaryFunction<U, K>, resultSelector: (thisItem: T | undefined, otherItem: U) => R): From<R> {
 
         const self = this;
@@ -573,18 +834,27 @@ export class From<T> implements Iterable<T> {
 
 }
 
+/**
+ * Represents a group of elements that have a common key.
+ * @template TKey, T
+ */
 export class Grouping<TKey, T> extends From<T> {
 
     private readonly _key: TKey;
 
+    /**
+     * Gets the key of the group.
+     */
     public get key(): TKey {
         return this._key;
     }
 
+    /**
+     * @param {TKey} key - The group key.
+     * @param {Array<T>} values - The values in the group.
+     */
     public constructor(key: TKey, values: Array<T>) {
         super(() => values);
         this._key = key;
     }
-
-
 }

package/src/collections/index.ts

@@ -1,3 +1,4 @@
-export {default as DefaultWeakMap} from './default-weak-map.js'
-export {default as DefaultMap} from './default-map.js'
-export {default as CacheDictionary} from './cache-dictionary.js';
+export {default as DefaultWeakMap} from './default-weak-map.js';
+export {default as DefaultMap} from './default-map.js';
+export {default as CacheDictionary} from './cache-dictionary.js';
+export {default as from} from './from.js';