@develia/commons 0.4.15 → 0.4.18

package/src/collections/from.ts

@@ -1,860 +1,860 @@
-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.";
-    if (typeof source === 'function')
-        return From.fn<T>(source);
-    if (typeof source[Symbol.iterator] === 'function') {
-        return From.iterable<T>(source);
-    } else if (typeof source === 'object') {
-        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);
-        });
-    }
-
-
-    private readonly _fn: Supplier<Iterable<T>>
-
-    protected constructor(fn: Supplier<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();
-    }
-
-
-    /**
-     * 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)) {
-                return false;
-            }
-        }
-        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)) {
-                return true;
-            }
-        }
-        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;
-
-        for (let item of this) {
-            if (predicate == null || predicate(item)) {
-                output++;
-            }
-        }
-
-        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* () {
-            for (let item of self) {
-                if (predicate(item)) {
-                    yield item;
-                }
-            }
-        });
-    }
-
-    /**
-     * 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) {
-                return true;
-            }
-        }
-        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.
-     */
-    public first(predicate?: Predicate<T>): T | undefined {
-
-        if (predicate) {
-            for (let item of this) {
-                if (predicate(item)) {
-                    return item;
-                }
-            }
-        } 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.
-     */
-    public single(predicate?: Predicate<T>): T | null {
-
-        let found = false;
-        let output: T | null = null;
-
-        if (predicate) {
-            for (let item of this) {
-                if (predicate(item)) {
-                    if (found) {
-                        throw new Error("Sequence contains more than one element.");
-                    }
-                    found = true;
-                    output = item;
-                }
-            }
-        } else {
-            // noinspection LoopStatementThatDoesntLoopJS
-            for (let item of this) {
-                if (found) {
-                    throw new Error("Sequence contains more than one element.");
-                }
-                found = true;
-                output = item;
-            }
-        }
-
-        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* () {
-            for (let element of self) {
-                yield element;
-            }
-            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.
-     */
-    public prepend(item: T): From<T> {
-        const self = this;
-        return From.fn<T>(function* () {
-            yield item;
-            for (let element of self) {
-                yield element;
-            }
-        });
-    }
-
-    /**
-     * 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) {
-            if (idx++ === index) {
-                return item;
-            }
-        }
-        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 {
-
-
-        let last: T | undefined = undefined;
-
-        if (predicate)
-            for (let item of this) {
-                if (!predicate || predicate(item)) {
-                    last = item;
-                }
-            }
-        else {
-            for (let item of this) {
-                last = item;
-            }
-        }
-        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* () {
-            for (const item of self) {
-                const subitems = mapper(item)
-                for (const subitem of subitems) {
-                    yield subitem;
-                }
-            }
-        })
-    }
-
-    /**
-     * Flattens a sequence of iterables.
-     * @returns {From<any>} A new From instance.
-     */
-    public flatten(): From<any> {
-        const self = this;
-        return From.fn<T>(function* () {
-            for (let item of self) {
-                let temp = <Iterable<any>>item;
-                for (let subitem of temp) {
-                    yield subitem
-                }
-            }
-        });
-    }
-
-    /**
-     * 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;
-
-        if (mapper)
-            for (let item of this) {
-                total += mapper(item);
-            }
-        else
-            for (let item of this) {
-                total += item as number;
-            }
-        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;
-
-        if (mapper)
-            for (let item of this) {
-                total += mapper(item);
-                count++;
-            }
-        else
-            for (let item of this) {
-                total += item as number;
-                count++;
-            }
-        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) {
-            let value = mapper(item);
-            max = value > max ? value : max;
-        }
-        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) {
-            let value = mapper(item);
-            min = value < min ? value : min;
-        }
-        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;
-        for (let item of this) {
-            let value = mapper(item);
-            if (value > max) {
-                max = value;
-                maxItem = item;
-            }
-        }
-        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;
-        for (let item of this) {
-            let value = mapper(item);
-            if (value < min) {
-                min = value;
-                minItem = item;
-            }
-        }
-        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) {
-            array.sort((a, b) => {
-                const aValue = mapper(a);
-                const bValue = mapper(b);
-                return aValue > bValue ? 1 : bValue > aValue ? -1 : 0;
-            });
-        } else if (order == Order.Descending) {
-            array.sort((a, b) => {
-                const aValue = mapper(a);
-                const bValue = mapper(b);
-                return aValue > bValue ? 1 : bValue < aValue ? -1 : 0;
-            });
-        } else {
-            throw new Error("invalid order argument");
-        }
-
-        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);
-        const self = this;
-
-        return From.fn<Grouping<TKey, T>>(function* () {
-            const groups: Array<[TKey, T[]]> = [];
-            for (let item of self) {
-                const key = keySelector(item);
-                let found = false;
-                for (let [entryKey, group] of groups) {
-                    if (equalityComparer(key, entryKey)) {
-                        group.push(item);
-                        found = true;
-                        break;
-                    }
-                }
-                if (!found) {
-                    groups.push([key, [item]]);
-                }
-            }
-            yield* groups.map(([key, values]) => new Grouping<TKey, T>(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.
-     */
-    public head(n: number): From<T> {
-
-        const self = this;
-        return From.fn<T>(function* () {
-            let count = 0;
-            for (let item of self) {
-                if (count++ < n) {
-                    yield item;
-                } else {
-                    return;
-                }
-            }
-        });
-    }
-
-    /**
-     * 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;
-        return From.fn<T>(function* () {
-            let buffer = [];
-            for (let item of self) {
-                buffer.push(item);
-                if (buffer.length > n) {
-                    buffer.shift();
-                }
-            }
-            yield* buffer;
-        });
-    }
-
-    /**
-     * 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> = {};
-
-        for (let item of this) {
-            output[keySelector(item)] = valueSelector(item);
-        }
-        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>();
-
-        for (let item of this) {
-            const key = keySelector(item);
-            const value = valueSelector(item);
-            map.set(key, value);
-        }
-
-        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.
-     */
-    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)) {
-                return false;
-            }
-        }
-        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)
-            eq_comparer = shallowEqual;
-
-        const self = this;
-        return From.fn<T>(function* () {
-
-            const included = [];
-
-            for (let item of self) {
-                if (!From.iterable(included).any(x => eq_comparer(x, item))) {
-                    included.push(item);
-                    yield item;
-                }
-            }
-        });
-    }
-
-    /**
-     * 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;
-        return From.fn<T>(function* () {
-            let i = 0;
-            let inserted = false;
-            for (let existingItem of self) {
-                if (i === index) {
-                    yield item;
-                    inserted = true;
-                }
-                yield existingItem;
-                i++;
-            }
-            if (!inserted) {
-                yield item;
-            }
-        });
-    }
-
-    /**
-     * 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* () {
-            let i = 0;
-            for (let item of self) {
-                if (i >= n) {
-                    yield item;
-                }
-                i++;
-            }
-        });
-    }
-
-
-    /**
-     * 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* () {
-            yield* self;
-            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.
-     */
-    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;
-        return From.fn<R2>(() => {
-            const otherByKey = new Map<R, T2>();
-            for (let item of other) {
-                otherByKey.set(otherKeySelector(item), item);
-            }
-            return Array.from(self)
-                        .filter(item => otherByKey.has(thisKeySelector(item)))
-                        .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.
-     */
-    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;
-        return From.fn<R>(() => {
-            const otherByKey = new Map<K, U>();
-            for (let item of other) {
-                otherByKey.set(otherKeySelector(item), item);
-            }
-            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.
-     */
-    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;
-        return From.fn<R>(() => {
-            const otherByKeys = new Map<K, Array<U>>();
-            for (let item of other) {
-                const key = otherKeySelector(item);
-                if (!otherByKeys.has(key)) {
-                    otherByKeys.set(key, []);
-                }
-                otherByKeys.get(key)!.push(item);
-            }
-            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.
-     */
-    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;
-        return From.fn<R>(() => {
-            const thisByKeys = new Map<K, Array<T>>();
-            for (let item of self) {
-                const key = thisKeySelector(item);
-                if (!thisByKeys.has(key)) {
-                    thisByKeys.set(key, []);
-                }
-                thisByKeys.get(key)!.push(item);
-            }
-            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.
-     */
-    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;
-        return From.fn<R>(() => {
-            const thisByKey = new Map<K, T>();
-            for (let item of self) {
-                thisByKey.set(thisKeySelector(item), item);
-            }
-            return Array.from(other).map(item => resultSelector(thisByKey.get(otherKeySelector(item)), item));
-        });
-    }
-
-}
-
-/**
- * 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;
-    }
+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 {Error} 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 new Error("Source is null.");
+    if (typeof source === 'function')
+        return From.fn<T>(source);
+    if (typeof source[Symbol.iterator] === 'function') {
+        return From.iterable<T>(source);
+    } else if (typeof source === 'object') {
+        return From.object(source);
+    }
+
+    throw new Error("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);
+        });
+    }
+
+
+    private readonly _fn: Supplier<Iterable<T>>
+
+    protected constructor(fn: Supplier<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();
+    }
+
+
+    /**
+     * 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)) {
+                return false;
+            }
+        }
+        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)) {
+                return true;
+            }
+        }
+        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;
+
+        for (let item of this) {
+            if (predicate == null || predicate(item)) {
+                output++;
+            }
+        }
+
+        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* () {
+            for (let item of self) {
+                if (predicate(item)) {
+                    yield item;
+                }
+            }
+        });
+    }
+
+    /**
+     * 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) {
+                return true;
+            }
+        }
+        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.
+     */
+    public first(predicate?: Predicate<T>): T | undefined {
+
+        if (predicate) {
+            for (let item of this) {
+                if (predicate(item)) {
+                    return item;
+                }
+            }
+        } 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.
+     */
+    public single(predicate?: Predicate<T>): T | null {
+
+        let found = false;
+        let output: T | null = null;
+
+        if (predicate) {
+            for (let item of this) {
+                if (predicate(item)) {
+                    if (found) {
+                        throw new Error("Sequence contains more than one element.");
+                    }
+                    found = true;
+                    output = item;
+                }
+            }
+        } else {
+            // noinspection LoopStatementThatDoesntLoopJS
+            for (let item of this) {
+                if (found) {
+                    throw new Error("Sequence contains more than one element.");
+                }
+                found = true;
+                output = item;
+            }
+        }
+
+        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* () {
+            for (let element of self) {
+                yield element;
+            }
+            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.
+     */
+    public prepend(item: T): From<T> {
+        const self = this;
+        return From.fn<T>(function* () {
+            yield item;
+            for (let element of self) {
+                yield element;
+            }
+        });
+    }
+
+    /**
+     * 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) {
+            if (idx++ === index) {
+                return item;
+            }
+        }
+        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 {
+
+
+        let last: T | undefined = undefined;
+
+        if (predicate)
+            for (let item of this) {
+                if (!predicate || predicate(item)) {
+                    last = item;
+                }
+            }
+        else {
+            for (let item of this) {
+                last = item;
+            }
+        }
+        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* () {
+            for (const item of self) {
+                const subitems = mapper(item)
+                for (const subitem of subitems) {
+                    yield subitem;
+                }
+            }
+        })
+    }
+
+    /**
+     * Flattens a sequence of iterables.
+     * @returns {From<any>} A new From instance.
+     */
+    public flatten(): From<any> {
+        const self = this;
+        return From.fn<T>(function* () {
+            for (let item of self) {
+                let temp = <Iterable<any>>item;
+                for (let subitem of temp) {
+                    yield subitem
+                }
+            }
+        });
+    }
+
+    /**
+     * 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;
+
+        if (mapper)
+            for (let item of this) {
+                total += mapper(item);
+            }
+        else
+            for (let item of this) {
+                total += item as number;
+            }
+        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;
+
+        if (mapper)
+            for (let item of this) {
+                total += mapper(item);
+                count++;
+            }
+        else
+            for (let item of this) {
+                total += item as number;
+                count++;
+            }
+        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) {
+            let value = mapper(item);
+            max = value > max ? value : max;
+        }
+        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) {
+            let value = mapper(item);
+            min = value < min ? value : min;
+        }
+        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;
+        for (let item of this) {
+            let value = mapper(item);
+            if (value > max) {
+                max = value;
+                maxItem = item;
+            }
+        }
+        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;
+        for (let item of this) {
+            let value = mapper(item);
+            if (value < min) {
+                min = value;
+                minItem = item;
+            }
+        }
+        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) {
+            array.sort((a, b) => {
+                const aValue = mapper(a);
+                const bValue = mapper(b);
+                return aValue > bValue ? 1 : bValue > aValue ? -1 : 0;
+            });
+        } else if (order == Order.Descending) {
+            array.sort((a, b) => {
+                const aValue = mapper(a);
+                const bValue = mapper(b);
+                return aValue > bValue ? 1 : bValue < aValue ? -1 : 0;
+            });
+        } else {
+            throw new Error("invalid order argument");
+        }
+
+        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);
+        const self = this;
+
+        return From.fn<Grouping<TKey, T>>(function* () {
+            const groups: Array<[TKey, T[]]> = [];
+            for (let item of self) {
+                const key = keySelector(item);
+                let found = false;
+                for (let [entryKey, group] of groups) {
+                    if (equalityComparer(key, entryKey)) {
+                        group.push(item);
+                        found = true;
+                        break;
+                    }
+                }
+                if (!found) {
+                    groups.push([key, [item]]);
+                }
+            }
+            yield* groups.map(([key, values]) => new Grouping<TKey, T>(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.
+     */
+    public head(n: number): From<T> {
+
+        const self = this;
+        return From.fn<T>(function* () {
+            let count = 0;
+            for (let item of self) {
+                if (count++ < n) {
+                    yield item;
+                } else {
+                    return;
+                }
+            }
+        });
+    }
+
+    /**
+     * 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;
+        return From.fn<T>(function* () {
+            let buffer = [];
+            for (let item of self) {
+                buffer.push(item);
+                if (buffer.length > n) {
+                    buffer.shift();
+                }
+            }
+            yield* buffer;
+        });
+    }
+
+    /**
+     * 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> = {};
+
+        for (let item of this) {
+            output[keySelector(item)] = valueSelector(item);
+        }
+        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>();
+
+        for (let item of this) {
+            const key = keySelector(item);
+            const value = valueSelector(item);
+            map.set(key, value);
+        }
+
+        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.
+     */
+    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)) {
+                return false;
+            }
+        }
+        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)
+            eq_comparer = shallowEqual;
+
+        const self = this;
+        return From.fn<T>(function* () {
+
+            const included = [];
+
+            for (let item of self) {
+                if (!From.iterable(included).any(x => eq_comparer(x, item))) {
+                    included.push(item);
+                    yield item;
+                }
+            }
+        });
+    }
+
+    /**
+     * 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;
+        return From.fn<T>(function* () {
+            let i = 0;
+            let inserted = false;
+            for (let existingItem of self) {
+                if (i === index) {
+                    yield item;
+                    inserted = true;
+                }
+                yield existingItem;
+                i++;
+            }
+            if (!inserted) {
+                yield item;
+            }
+        });
+    }
+
+    /**
+     * 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* () {
+            let i = 0;
+            for (let item of self) {
+                if (i >= n) {
+                    yield item;
+                }
+                i++;
+            }
+        });
+    }
+
+
+    /**
+     * 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* () {
+            yield* self;
+            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.
+     */
+    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;
+        return From.fn<R2>(() => {
+            const otherByKey = new Map<R, T2>();
+            for (let item of other) {
+                otherByKey.set(otherKeySelector(item), item);
+            }
+            return Array.from(self)
+                        .filter(item => otherByKey.has(thisKeySelector(item)))
+                        .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.
+     */
+    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;
+        return From.fn<R>(() => {
+            const otherByKey = new Map<K, U>();
+            for (let item of other) {
+                otherByKey.set(otherKeySelector(item), item);
+            }
+            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.
+     */
+    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;
+        return From.fn<R>(() => {
+            const otherByKeys = new Map<K, Array<U>>();
+            for (let item of other) {
+                const key = otherKeySelector(item);
+                if (!otherByKeys.has(key)) {
+                    otherByKeys.set(key, []);
+                }
+                otherByKeys.get(key)!.push(item);
+            }
+            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.
+     */
+    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;
+        return From.fn<R>(() => {
+            const thisByKeys = new Map<K, Array<T>>();
+            for (let item of self) {
+                const key = thisKeySelector(item);
+                if (!thisByKeys.has(key)) {
+                    thisByKeys.set(key, []);
+                }
+                thisByKeys.get(key)!.push(item);
+            }
+            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.
+     */
+    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;
+        return From.fn<R>(() => {
+            const thisByKey = new Map<K, T>();
+            for (let item of self) {
+                thisByKey.set(thisKeySelector(item), item);
+            }
+            return Array.from(other).map(item => resultSelector(thisByKey.get(otherKeySelector(item)), item));
+        });
+    }
+
+}
+
+/**
+ * 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;
+    }
 }