@adamburgess/linq
Version:
A linq library.
664 lines (663 loc) • 21.8 kB
TypeScript
/**
* ```js
* import from from '@adamburgess/linq'
* const sequence = from(['an', 'iterable', 'here!']);
* // now use all the methods on sequence!
* ```
*
* See {@link AnySequence} for all the transformations you can do to a sequence.
* @module
*/
/** A sequence of values.
*
* To create me, use from:
* ```js
* const sequence = from(['an', 'iterable', 'here!']);
* // now use all the methods on sequence!
* ```
*/
export interface AnySequence<T> extends Iterable<T> {
/** Map each element to another
*
* ```js
* from([2, 1, 5]).map(x => x + 1)
* // => [3, 2, 6]
* ```
*/
map<TResult>(f: (arg: T, index: number) => TResult): Sequence<TResult>;
/** Filters with a TS type assertion ('is'), narrowing to that type
*
* ```typescript
* function isNumber(x: number | string): x is number {
* return typeof x === 'number';
* }
* from(['string', 12, 'str']).where(isNumber)
* // => [12]
* // sequence is now Sequence<number>
* ```
*/
where<TNarrowed extends T>(f: (arg: T | TNarrowed, index: number) => arg is TNarrowed): Sequence<TNarrowed>;
/** Filters with and narrows to a type
*
* ```typescript
* from(['string', 12, 'str']).where<number>(x => typeof x === 'number')
* // => [12]
* // sequence is now Sequence<number>
* ```
* note! must use generic type! otherwise this overload is not used, and the type is not narrowed.
*/
where<TNarrowed extends T>(f: (arg: T | TNarrowed, index: number) => boolean): Sequence<TNarrowed>;
/** Filters with a predicate that must return a truthy value
*
* ```js
* from([5, 10, 20]).where(x => x >= 8)
* // => [10, 20]
* ```
*/
where(f: (arg: T, index: number) => any): Sequence<T>;
/** Reverses the sequence.
*
* ```js
* from([2, 1, 5]).reverse()
* // => [5, 1, 2]
* ```
*/
reverse(): Sequence<T>;
/** Project each element to get a key, and group all items by that key.
*
* ```js
* from([10, 15, 20]).groupBy(x => Math.trunc(x / 10))
* .map(g => ({ key: g.key, values: Array.from(g) }))
* // => [{ key: 1, values: [10, 15] },
* // { key: 2, values: [20] }]
* ```
*/
groupBy<TKey>(keySelector: (arg: T) => TKey): ArraySequence<KeySequence<TKey, T>>;
/** Project each element to get a key, and group all items, each projected onto another type.
*
* ```js
* from([10, 15, 20]).groupBy(x => Math.trunc(x / 10), x => x.toString())
* .map(g => ({ key: g.key, values: Array.from(g) }))
* // => [{ key: 1, values: ['10', '15'] },
* // { key: 2, values: ['20'] }]
* ```
*/
groupBy<TKey, TProject>(keySelector: (arg: T) => TKey, elementSelector: (arg: T) => TProject): ArraySequence<KeySequence<TKey, TProject>>;
/** Sort the array in ascending order of the selector
*
* ```js
* from([4, 1, 10]).orderBy(x => x)
* // => [1, 4, 10]
* ```
*/
orderBy(keySelector: (arg: T) => string | number): OrderedSequence<T>;
/** Sort the array in ascending order of the selector, with a custom comparer
*
* ```js
* // Sort alphabetically, ignoring case.
* from(['A xylophone', 'a frog', 'a zoo']).orderBy(x => x, new Intl.Collator('en', { sensitivity: 'base' }).compare)
* // => ['a frog', 'A xylophone', 'a zoo']
* ```
*/
orderBy<TKey>(keySelector: (arg: T) => TKey, comparer: ICompare<TKey>): OrderedSequence<T>;
/** Sort the array in descending order of the selector
*
* ```js
* from([4, 1, 10]).orderByDescending(x => x)
* // => [10, 4, 1]
* ```
*/
orderByDescending(keySelector: (arg: T) => string | number): OrderedSequence<T>;
/** Sort the array in descending order of the selector, with a custom comparer
*
* ```js
* // Sort reverse alphabetically, ignoring case.
* from(['A xylophone', 'a frog', 'a zoo']).orderByDescending(x => x, new Intl.Collator('en', { sensitivity: 'base' }).compare)
* // => ['a zoo', 'A xylophone', 'a frog']
* ```
*/
orderByDescending<TKey>(keySelector: (arg: T) => TKey, comparer: ICompare<TKey>): OrderedSequence<T>;
/** Take a maximum amount of elements
*
* ```js
* from([2, 1, 5]).take(2)
* // => [2, 1]
* ```
*/
take(count: number): Sequence<T>;
/** Take elements while the predicate is true, then skips the rest
*
* ```js
* from([2, 3, 1, 5]).takeWhile(x => x >= 2)
* // => [2, 3]
* ```
*/
takeWhile(predicate: (arg: T) => any): Sequence<T>;
/** Skip a number of elements before letting the rest through
*
* ```js
* from([2, 3, 1, 5]).skip(2)
* // => [1, 5]
* ```
*/
skip(count: number): Sequence<T>;
/** Skip elements while the predicate is true, then take the rest
*
* ```js
* from([2, 3, 1, 5]).skipWhile(x => x >= 2)
* // => [1, 5]
* ```
*/
skipWhile(predicate: (arg: T) => any): Sequence<T>;
/** Append another iterable to the end
*
* ```js
* from([1, 2]).append([3, 4])
* // => [1, 2, 3, 4]
* ```
*/
append<TAppend>(iterable: Iterable<TAppend>): Sequence<T | TAppend>;
/** Prepend another iterable to the start
*
* ```js
* from([1, 2]).prepend([3, 4])
* // => [3, 4, 1, 2]
* ```
*/
prepend<TPrepend>(iterable: Iterable<TPrepend>): Sequence<TPrepend | T>;
/** Get all distinct elements of the sequence using strict equality. First value wins.
*
* ```js
* from([1, 2, 2, 3]).distinct()
* // => [1, 2, 3]
* ```
*/
distinct(): Sequence<T>;
/** Get all distinct elements of the sequence, mapping each element to a key that will be used for strict equality. First value wins.
*
* ```js
* from([10, 15, 20, 25, 30]).distinct(x => Math.trunc(x / 10))
* // => [10, 20, 30]
* ```
*/
distinct(keySelector: (arg: T) => unknown): Sequence<T>;
/** Project each element to an iterable/array, then flatten the result
*
* ```js
* from(['1 2', '3 4']).flat(x => x.split(' '))
* // => ['1', '2', '3', '4']
* ```
*/
flat<TProject>(projector: (input: T) => Iterable<TProject>): Sequence<TProject>;
/** Correlates the elements of two sequences based on matching keys. An inner join.
*
* ```js
* const appleTypes = [
* { name: 'green apple', id: 5 },
* { name: 'red apple', id: 2 },
* { name: 'yellow apple', id: 10 }
* ];
* const apples = [
* { name: 'golden delicious', type: 10 },
* { name: 'granny smith', type: 5 },
* { name: 'pink lady', type: 2 },
* { name: 'fuji', type: 2 },
* { name: 'unknown', type: 999 }
* ];
*
* from(apples).join(
* appleTypes,
* apple => apple.type,
* type => type.id,
* (apple, type) => `${apple.name}: ${type.name}`
* )
* // => [ 'golden delicious: yellow apple',
* // 'granny smith: green apple',
* // 'pink lady: red apple',
* // 'fuji: red apple' ]
* ```
*/
join<TInner, TKey, TResult>(innerSequence: Iterable<TInner>, outerKeySelector: (arg: T) => TKey, innerKeySelector: (arg: TInner) => TKey, resultSelector: (outer: T, inner: TInner) => TResult): Sequence<TResult>;
/** Correlates the elements of two sequences based on matching keys, and groups everything in the other table.
*
* ```js
* const appleTypes = [
* { name: 'green apple', id: 5 },
* { name: 'red apple', id: 2 },
* { name: 'yellow apple', id: 10 }
* ];
* const apples = [
* { name: 'golden delicious', type: 10 },
* { name: 'granny smith', type: 5 },
* { name: 'pink lady', type: 2 },
* { name: 'fuji', type: 2 },
* { name: 'unknown', type: 999 }
* ];
*
* from(appleTypes).groupJoin(
* apples,
* type => type.id,
* apple => apple.type,
* (type, apples) => `${type.name}: ${apples.map(a => a.name).joinString(', ')}`
* );
* // => [ 'green apple: granny smith',
* // 'red apple: pink lady, fuji',
* // 'yellow apple: golden delicious' ]
* ```
*/
groupJoin<TInner, TKey, TResult>(innerSequence: Iterable<TInner>, outerKeySelector: (arg: T) => TKey, innerKeySelector: (arg: TInner) => TKey, resultSelector: (outer: T, inner: Sequence<TInner>) => TResult): Sequence<TResult>;
/** Counts the number of elements in the sequence
*
* ```js
* from([2, 1, 5]).count()
* // => 3
* from([]).count()
* // => 0
* ```
*/
count(): number;
/**
* Converts this sequence to an array.
* Note: If you are using this Sequence in a for..of loop, you do _not_ need this --
* you can use the sequence directly.
*
* ```js
* from([2, 1, 5]).toArray()
* // => [2, 1, 5]
* ```
*/
toArray(): T[];
/** Converts this sequence to a Map. First key wins.
*
* ```js
* from([{ k: 'a', v: 123 }, { k: 'b', v: 456 }]).toMap(x => x.k, x => x.v)
* // => new Map([['a', 123], ['b', 456]])
* ```
*/
toMap<TKey, TElement>(keySelector: (arg: T) => TKey, elementSelector: (arg: T) => TElement): Map<TKey, TElement>;
/** Converts this sequence into an object. First key wins.
*
* ```js
* from([{ k: 'a', v: 123 }, { k: 'b', v: 456 }]).toObject(x => x.k, x => x.v)
* // => { a: 123, b: 456 }
* ```
*/
toObject<TKey extends PropertyKey, TElement>(keySelector: (arg: T) => TKey, elementSelector: (arg: T) => TElement): Record<TKey, TElement>;
/** Convert this sequence into a Set
*
* ```js
* from([2, 1, 1, 5]).toSet()
* // => new Set([2, 1, 5])
* ```
*/
toSet(): Set<T>;
/** Map each element and convert the resulting sequence into a set
*
* ```js
* from([2, 1, 1, 5]).toSet(x => x + 1)
* // => new Set([3, 2, 6])
* ```
*/
toSet<TProject>(projector: (arg: T) => TProject): Set<TProject>;
/** Get the first element in the sequence. Will throw if empty! Use firstOrDefault if no throw is wanted.
*
* ```js
* from([2, 1, 5]).first()
* // => 2
* from([]).first()
* // => throws
* ```
*/
first(): T;
/** Get the first element in the sequence that matches a condition. Will throw if empty! Use firstOrDefault if no throw is wanted.
*
* ```js
* from([2, 1, 5]).first(x => x >= 4)
* // => 5
* from([2, 1, 5]).first(x => x < 0)
* // => throws
* ```
*/
first(predicate: (arg: T) => any): T;
/** Get the first element in the sequence. If empty, returns undefined.
*
* ```js
* from([2, 1, 5]).firstOrDefault()
* // => 2
* from([]).firstOrDefault()
* // => undefined
* ```
*/
firstOrDefault(): T | undefined;
/** Get the first element in the sequence that matches a condition. If empty or no matches, returns undefined.
*
* ```js
* from([2, 1, 5]).firstOrDefault(x => x >= 4)
* // => 5
* from([2, 1, 5]).firstOrDefault(x => x < 0)
* // => undefined
* ```
*/
firstOrDefault(predicate: (arg: T) => any): T | undefined;
/** Get the _only_ element in the sequence. Will throw if empty or more than one element! Use singleOrDefault if no throw is wanted.
*
* ```js
* from([2]).single()
* // => 2
* from([2, 1, 5]).single()
* // => throws
* from([]).single()
* // => throws
* ```
*/
single(): T;
/** Get the _only_ element in the sequence that matches a condition. Will throw if empty or more than one element! Use singleOrDefault if no throw is wanted.
*
* ```js
* from([2, 1, 5]).single(x => x >= 4)
* // => 5
* from([2, 1, 5]).single(x => x >= 1)
* // => throws
* ```
*/
single(predicate: (arg: T) => any): T;
/** Get the _only_ element in the sequence. Returns undefined if empty or more than one element.
*
* ```js
* from([2]).singleOrDefault()
* // => 2
* from([2, 1, 5]).singleOrDefault()
* // => undefined
* ```
*/
singleOrDefault(): T | undefined;
/** Get the _only_ element in the sequence that matches a condition. Returns undefined if empty or more than one element.
*
* ```js
* from([2, 1, 5]).singleOrDefault(x => x >= 4)
* // => 5
* from([2, 1, 5]).singleOrDefault(x => x >= 1)
* // => undefined
* ```
*/
singleOrDefault(predicate: (arg: T) => any): T | undefined;
/** Get the last element in the sequence. Will throw if empty! Use lastOrDefault if no throw is wanted.
*
* ```js
* from([2, 1, 5]).last()
* // => 5
* from([]).last()
* // => throws
* ```
*/
last(): T;
/** Get the last element in the sequence that matches a condition. Will throw if empty! Use lastOrDefault if no throw is wanted.
*
* ```js
* from([2, 1, 5]).last(x => x < 4)
* // => 1
* from([]).last(x => x < 0)
* // => throws
* ```
*/
last(predicate: (arg: T) => any): T;
/** Get the last element in the sequence. If empty, returns undefined.
*
* ```js
* from([2, 1, 5]).lastOrDefault()
* // => 5
* from([]).lastOrDefault()
* // => undefined
* ```
*/
lastOrDefault(): T | undefined;
/** Get the last element in the sequence that matches a condition. If empty or no matches, returns undefined.
*
* ```js
* from([2, 1, 5]).lastOrDefault(x => x < 4)
* // => 1
* from([2, 1, 5]).lastOrDefault(x => x < 0)
* // => undefined
* ```
*/
lastOrDefault(predicate: (arg: T) => any): T | undefined;
/** True if all elements pass the predicate
*
* ```js
* from([2, 1, 5]).all(x => x >= 1)
* // => true
* from([2, 1, 5]).all(x => x >= 2)
* // => false
* ```
*/
all(predicate: (arg: T) => any): boolean;
/** True if any elements pass the predicate
*
* ```js
* from([2, 1, 5]).any(x => x >= 4)
* // => true
* from([2, 1, 5]).any(x => x <= 0)
* // => false
* ```
*/
any(predicate: (arg: T) => any): boolean;
/** True if the sequence is not empty
*
* ```js
* from([2, 1, 5]).any()
* // => true
* from([]).any()
* // => false
* ```
*/
any(): boolean;
/** True if no elements pass the predicate
*
* ```js
* from([2, 1, 5]).none(x => x === 0)
* // => true
* from([2, 1, 5]).none(x => x === 1)
* // => false
* ```
*/
none(predicate: (arg: T) => any): boolean;
/** True if the element is in the sequence. Checked with ===.
*
* ```js
* from([2, 1, 5]).contains(1)
* // => true
* from([{ a: '1' }]).contains({ a: '1' })
* // => false (strict equality. use any with a custom search instead.)
* ```
*/
contains(value: T): boolean;
/** Projects each element to a number and sums the sequence. If empty, returns 0.
*
* ```js
* from(['2', '1', '5']).sum(x => parseFloat(x))
* // => 8
* ```
*/
sum(f: (arg: T) => number): number;
/** Projects each element to a number and averages the sequence. If empty, throws.
*
* ```js
* from(['2', '1', '6']).average(x => parseFloat(x))
* // => 3
* ```
*/
average(f: (arg: T) => number): number;
/** Projects each element to a number and finds the max of the sequence. If empty, throws.
*
* ```js
* from(['2', '1', '5']).max(x => parseFloat(x))
* // => 5
* ```
*/
max(f: (arg: T) => number): number;
/** Projects each element to a number and finds the min of the sequence. If empty, throws.
*
* ```js
* from(['2', '1', '5']).min(x => parseFloat(x))
* // => 1
* ```
*/
min(f: (arg: T) => number): number;
/** Finds the minimum element in the sequence according to a selector. Equivalent (but faster) to orderBy(f).first().
*
* ```js
* from([{ key: 'A', value: 2 }, { key: 'B', value: 1 }, { key: 'C', value: 10 }]).minBy(x => x.value)
* // => { key: 'B', value: 1 }
* ```
*/
minBy(f: (arg: T) => number): T;
/** Finds the maximum element in the sequence according to a selector. Equivalent (but faster) to orderByDescending(f).first().
*
* ```js
* from([{ key: 'A', value: 2 }, { key: 'B', value: 1 }, { key: 'C', value: 10 }]).maxBy(x => x.value)
* // => { key: 'C', value: 10 }
* ```
*/
maxBy(f: (arg: T) => number): T;
/** Iterates through this sequence. */
[Symbol.iterator](): Iterator<T>;
}
/** A sequence of numbers */
export interface NumberSequence<T> extends AnySequence<T> {
/** Sums every number in the sequence. If empty, returns 0.
*
* ```js
* from([2, 1, 5]).sum()
* // => 8
* ```
*/
sum(): number;
/** Averages the sequence. If empty, throws.
*
* ```js
* from([2, 1, 6]).average()
* // => 3
* ```
*/
average(): number;
/** Finds the maximum in the sequence. If empty, throws.
*
* ```js
* from([2, 1, 5]).max()
* // => 5
* ```
*/
max(): number;
/** Finds the minimum in the sequence. If empty, throws.
*
* ```js
* from([2, 1, 5]).min()
* // => 1
* ```
*/
min(): number;
}
declare type UnwrapIterable<T> = [T] extends [Iterable<infer U>] ? U : never;
/** A sequence of iterable elements */
export interface ArraySequence<T> extends AnySequence<T> {
/** Project each element to an iterable/array, then flatten the result
*
* ```js
* from([[1, 2], [3, 4]]).flat(x => [...x, 0])
* // => [1, 2, 0, 3, 4, 0]
* ```
*/
flat<TProject>(projector: (input: T) => Iterable<TProject>): Sequence<TProject>;
/** Flatten the sequence
*
* ```js
* from([[1, 2], [3, 4]]).flat()
* // => [1, 2, 3, 4]
* ```
*/
flat(): Sequence<UnwrapIterable<T>>;
}
/** A sequence of strings */
export interface StringSequence<T> extends AnySequence<T> {
/** Joins the elements with an optional separator
*
* ```js
* from(['a', 'b', 'c']).joinString(', ')
* // => 'a, b, c'
* ```
*/
joinString(separator?: string): string;
}
export interface WithKey<TKey> {
/** The key that this set was grouped by */
readonly key: TKey;
}
export interface WithOrderedMethods<T> {
/** Order the sequence by another key, ascending.
*
* ```js
* // Sort by length of the string, then alphabetical order
* from(['two', 'one', 'thirteen', 'five']).orderBy(x => x.length).thenBy(x => x)
* // => ['one', 'two', 'five', 'thirteen']
* ```
*/
thenBy(keySelector: (arg: T) => string | number): OrderedSequence<T>;
/** Order the sequence by another key, ascending, with a custom comparer.
*
* See orderBy for an example.
*/
thenBy<TKey>(keySelector: (arg: T) => TKey, comparer: ICompare<TKey>): OrderedSequence<T>;
/** Order the sequence by another key, descending.
*
* ```js
* // Sort by length of the string, then reverse alphabetical order
* from(['one', 'two', 'thirteen', 'five']).orderBy(x => x.length).thenByDescending(x => x)
* // => ['two', 'one', 'five', 'thirteen']
* ```
*/
thenByDescending(keySelector: (arg: T) => string | number): OrderedSequence<T>;
/** Order the sequence by another key, descending, with a custom comparer.
*
*
* See orderBy for an example.
*/
thenByDescending<TKey>(keySelector: (arg: T) => TKey, comparer: ICompare<TKey>): OrderedSequence<T>;
}
declare type DoesExtend<T, TWant> = [T] extends [TWant] ? T : never;
declare type DoesExtendAny<T> = any extends T ? never : T;
declare type ExtendsCarefully<T, TWant> = DoesExtendAny<DoesExtend<T, TWant>>;
/** A sequence of values. */
export declare type Sequence<T> = ExtendsCarefully<T, number> extends never ? (ExtendsCarefully<T, string> extends never ? (ExtendsCarefully<T, Iterable<unknown>> extends never ? AnySequence<T> : ArraySequence<T>) : StringSequence<T>) : NumberSequence<T>;
/** A sequence with a key. Obtained from groupBy. */
export declare type KeySequence<TKey, TElement> = WithKey<TKey> & Sequence<TElement>;
/** An ordered sequence. Can use thenBy to continue ordering. */
export declare type OrderedSequence<T> = WithOrderedMethods<T> & Sequence<T>;
/** Gets the sequence type.
* ```typescript
* type MySequence = Sequence<string>
* type MySequenceType = SequenceType<MySequence>
* // MySequenceType === string
* ```
*/
export declare type SequenceType<T> = T extends Sequence<infer Y> ? Y : never;
/** Compares two values.
* If a comes before b, the result should be negative.
* If both values are equal, the result should be zero.
* If a comes after b, the result should be positive.
*/
export declare type ICompare<T> = (a: T, b: T) => number;
/** Start the sequence. Can be used with an array or any iterable.
*
* ```js
* // Import me:
* import from from '@adamburgess/linq'
* // Arrays:
* from([1, 2, 3])
* // Objects that support the Iterable protocol:
* from(new Map())
* // Generators:
* from(function*() { yield 'generated values' })
* ```
*/
export declare function from<T>(it: Iterable<T>): Sequence<T>;
export default from;