luckystarry-collections v1.1.0

luckystarry-collections

English | 中文

A .NET-style collection library that provides LINQ-like methods for arrays, such as Select, Where, ToList, etc.

Install

Package Installation

npm install -S luckystarry-collections

When using this method, add the following code at your project entry point to extend the Array prototype:

import 'luckystarry-collections'

Browser Usage

<script src="https://cdn.jsdelivr.net/npm/luckystarry-collections/dist/index.min.js"></script>

Usage

Classes and Interfaces

IEnumerable

Interface for enumerable collections

List and IList

List object and list interface

Dictionary<TKey, TValue> and IDictionary<TKey, TValue>

Dictionary object and dictionary interface

ReadOnlyCollection

Read-only list

Array

Array

Common Collection Methods

All(predicate: (item: T) => boolean): boolean

Determines whether all elements in the collection satisfy the specified condition. Returns true if all elements meet the condition, otherwise returns false.

[1, 2, 3].All(x => x > 0)    // true
[1, 2, 3].All(x => x > 1)    // false

Any(predicate: (item: T) => boolean): boolean

Determines whether any element in the collection satisfies the specified condition. Returns true if any element meets the condition, otherwise returns false.

[1, 2, 3].Any(x => x > 0)    // true
[1, 2, 3].Any(x => x > 1)    // true
[1, 2, 3].Any(x => x > 3)    // false

AsEnumerable(): IEnumerable

Converts the collection to its enumerable interface form.

[1, 2, 3].AsEnumerable()     // [1, 2, 3]

Average(selector?: (item: T) => number): number | null

Computes the average of the collection. For non-numeric collections, use the selector to map elements to numbers.

[1, 2, 3].Average()          // 2
[1, 2, 3].Average(x => x * 2)    // 4

Concat(second: IEnumerable): IEnumerable

Concatenates two collections.

[1, 2, 3].Concat([3, 4, 5])    // [1, 2, 3, 3, 4, 5]

Contains(value: T, comparer?: IEqualityComparer): boolean

Determines whether the collection contains the specified element. An optional equality comparer can be provided.

[1, 2, 3].Contains(2)    // true

Count(predicate?: (item: T) => boolean): number

Counts the number of elements that satisfy the specified condition. If no condition is provided, returns the total count of elements.

[1, 2, 3].Count()            // 3
[1, 2, 3].Count(x => x > 1)  // 2

DefaultIfEmpty(defaultValue?: IEnumerable): IEnumerable

Returns defaultValue if the collection is empty; otherwise, returns a new collection containing all original elements.

[1, 2, 3].DefaultIfEmpty()   // [1, 2, 3]
[].DefaultIfEmpty([1])       // [1]

Distinct(comparer?: IEqualityComparer): IEnumerable

Returns distinct elements from the collection. An optional equality comparer can be provided.

[1, 2, 3].Distinct()         // [1, 2, 3]
[1, 2, 3, 3, 4].Distinct()   // [1, 2, 3, 4]

ElementAt(index: number): T

Returns the element at the specified index.

[1, 2, 3].ElementAt(1)       // 2

ElementAtOrDefault(defaultValue: T, index: number): T

Returns the element at the specified index or defaultValue if the index is out of range.

[1, 2, 3].ElementAtOrDefault(0, 1)    // 2
[1, 2, 3].ElementAtOrDefault(0, 3)    // 0

Except(second: IEnumerable, comparer?: IEqualityComparer): IEnumerable

Returns elements that exist in the first collection but not in the second collection.

[1, 2, 3].Except([3, 4])    // [1, 2]

First(predicate?: (item: T) => boolean): T

Returns the first element that satisfies the condition. If no condition is provided, returns the first element.

[1, 2, 3].First()           // 1
[1, 2, 3].First(x => x > 1) // 2

FirstOrDefault(defaultValue: T, predicate?: (item: T) => boolean): T

Returns the first element that satisfies the condition, or defaultValue if no element is found. If no condition is provided, returns the first element or defaultValue if the collection is empty.

[1, 2, 3].FirstOrDefault(0)                // 1
[1, 2, 3].FirstOrDefault(0, x => x > 1)    // 2
[1, 2, 3].FirstOrDefault(0, x => x > 3)    // 0

GroupBy<TKey, TElement = T>(keySelector: (item: T) => TKey, elementSelector?: (item: T) => TElement, comparer?: IEqualityComparer): IEnumerable<IGrouping<TKey, TElement>>

Groups elements by a key selector and maps elements using an optional element selector. An optional comparer can be used for key equality comparison.

[1, 2, 3].GroupBy(x => x)    
// [{ Key: 1, [1] }, { Key: 2, [2] }, { Key: 3, [3] }]

[{ Value: 1 }, { Value: 1 }, { Value: 2 }].GroupBy(x => x.Value, e => e)
// [{ Key: 1, [{ Value: 1 }, { Value: 1}] }, { Key: 2, [{ Value: 2}] }]

GroupJoin<TInner, TKey, TResult>(inner: IEnumerable, outerKeySelector: (item: T) => TKey, innerKeySelector: (item: TInner) => TKey, resultSelector?: (item: T, inners: IEnumerable) => TResult, comparer?: IEqualityComparer): IEnumerable

Correlates elements of two sequences based on key equality and groups the results.

[1, 2, 3].GroupJoin([3, 4, 5], o => o, i => i)
// [{ Outer: 1, Inners: [] }, { Outer: 2, Inners: [] }, { Outer: 3, Inners: [3] }]

Intersect(second: IEnumerable, comparer?: IEqualityComparer): IEnumerable

Returns elements that exist in both collections. An optional comparer can be used for element equality comparison.

[1, 2, 3].Intersect([3, 4])    // [3]

Join<TInner, TKey, TResult>(inner: IEnumerable, outerKeySelector: (item: T) => TKey, innerKeySelector: (item: TInner) => TKey, resultSelector?: (item: T, inners: TInner) => TResult, comparer?: IEqualityComparer): IEnumerable

Correlates elements of two sequences based on matching keys.

[1, 2, 3].Join([3, 4, 5], o => o, i => i)
// [{ Outer: 3, Inner: 3 }]

Last(predicate?: (item: T) => boolean): T

Returns the last element that satisfies the condition. If no condition is provided, returns the last element.

[1, 2, 3].Last()            // 3
[1, 2, 3].Last(x => x > 1)  // 3

LastOrDefault(defaultValue: T, predicate?: (item: T) => boolean): T

Returns the last element that satisfies the condition, or defaultValue if no element is found. If no condition is provided, returns the last element or defaultValue if the collection is empty.

[1, 2, 3].LastOrDefault(0)                 // 3
[1, 2, 3].LastOrDefault(0, x => x > 1)     // 3
[1, 2, 3].LastOrDefault(0, x => x < 1)     // 0

Max(selector?: (item: T) => number): number | null

Returns the maximum value in the collection. For non-numeric collections, use the selector to map elements to numbers.

[1, 2, 3].Max()             // 3
[1, 2, 3].Max(x => x * 2)   // 6

Min(selector?: (item: T) => number): number | null

Returns the minimum value in the collection. For non-numeric collections, use the selector to map elements to numbers.

[1, 2, 3].Min()             // 1
[1, 2, 3].Min(x => x * 2)   // 2

Reverse(): IEnumerable

Returns a new collection with elements in reverse order.

[1, 2, 3].Reverse()         // [3, 2, 1]

Select(selector: (item: T, index?: number) => TResult): IEnumerable

Projects each element into a new form using the selector function.

[1, 2, 3].Select(x => x)        // [1, 2, 3]
[1, 2, 3].Select(x => x * 3)    // [3, 6, 9]

SelectMany<TCollection, TResult = TCollection>(collectionSelector: (item: T, index?: number) => IEnumerable, resultSelector?: (item: T, collection: TCollection) => TResult): IEnumerable

Projects each element to an IEnumerable and flattens the resulting sequences into one sequence.

[[1, 2], [2, 3], [3, 4]].SelectMany(x => x)    // [1, 2, 2, 3, 3, 4]

SequenceEqual(second: Iterable, comparer?: IEqualityComparer): boolean

Determines whether two sequences are equal by comparing their elements.

[1, 2, 3].SequenceEqual([1, 2, 3])         // true
[1, 2, 3, 4].SequenceEqual([1, 2, 3])      // false
[1, 2, 3].SequenceEqual([3, 2, 1])         // false

Single(predicate?: (item: T) => boolean): T

Returns the only element that satisfies the condition. Throws an exception if there is not exactly one element.

[1].Single()                    // 1
[1, 2, 3].Single(x => x > 2)   // 3

SingleOrDefault(defaultValue: T, predicate?: (item: T) => boolean): T

Returns the only element that satisfies the condition, or defaultValue if no element is found. Throws an exception if there is more than one matching element.

[1].SingleOrDefault(0)                      // 1
[1, 2, 3].SingleOrDefault(0, x => x > 2)    // 3
[1, 2, 3].SingleOrDefault(0, x => x > 3)    // 0

Skip(count: number): IEnumerable

Bypasses a specified number of elements and returns the remaining elements.

[1, 2, 3].Skip(1)    // [2, 3]

SkipWhile(predicate: (item: T, index?: number) => boolean): IEnumerable

Bypasses elements while the predicate is true and returns the remaining elements.

[1, 2, 3].SkipWhile(x => x < 2)    // [2, 3]

Sum(selector?: (item: T) => number): number | null

Computes the sum of the sequence. For non-numeric collections, use the selector to map elements to numbers.

[1, 2, 3].Sum()                 // 6
[1, 2, 3].Sum(x => x * 2)       // 12

Take(count: number): IEnumerable

Returns a specified number of contiguous elements from the start of the sequence.

[1, 2, 3].Take(2)    // [1, 2]

TakeWhile(predicate: (item: T, index?: number) => boolean): IEnumerable

Returns elements from the start of the sequence while the predicate is true.

[1, 2, 3].TakeWhile(x => x < 2)    // [1]

ToArray(): Array

Creates an array from the collection.

[1, 2, 3].ToArray()    // [1, 2, 3]

ToDictionary<TKey, TElement = T>(keySelector: (item: T) => TKey, elementSelector?: (item: T) => TElement, comparer?: IEqualityComparer): Dictionary<TKey, TElement>

Creates a Dictionary<TKey, TElement> from the collection using the specified key and element selectors.

[1, 2, 3].ToDictionary(x => x)    // Dictionary { 1 => 1, 2 => 2, 3 => 3 }

ToList(): List

Creates a List from the collection.

[1, 2, 3].ToList()    // List [1, 2, 3]

Union(second: Iterable, comparer?: IEqualityComparer): IEnumerable

Produces the set union of two sequences by using the specified equality comparer.

[1, 2, 3].Union([3, 4, 5])    // [1, 2, 3, 4, 5]

Where(predicate: (item: T, index?: number) => boolean): IEnumerable

Filters a sequence of values based on a predicate.

[1, 2, 3].Where(x => x > 1)    // [2, 3]

LICENSE

MIT License

Copyright (c) 2018 SUN BO starry@vip.qq.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.