# Alot
----
[](https://app.travis-ci.com/github/atmajs/alot)
[](http://badge.fury.io/js/alot)
**🌱 Lazy**, **⛓️ Async** and ⚡ Performance-Optimized `Array/Stream` methods
```ts
import alot from 'alot';
const users: IUser[];
// Sync
const userAgeGroups = alot(users)
.distinctBy(x => x.email)
.sortBy(x => x.createdAt)
.groupBy(x => x.age)
.skip(1)
.take(2)
.toArray();
// Async
const userData = await alot(users)
.mapAsync(async user => UserService.loadFooMeta(user.id))
.toArrayAsync({ threads: 4 });
```
----
- [📝 Blog Post 🔗](https://dev.kit.eco/alot-turns-your-arrays-into-lazy-and-async-streams)
- [📚 API Documentation 🔗](https://docs.atma.dev/alot/classes/Alot.html)
----
Methods overview:
### `map`, `mapAsync`
```ts
map (fn: (x: T, i?: number) => TResult): IAlotStream
```
```ts
mapAsync (fn: (x: T, i?: number) => PromiseLike): IAlotStream
```
### `mapMany`, `mapManyAsync`
```ts
map (fn: (x: T, i?: number) => TResult[]): IAlotStream
```
```ts
mapAsync (fn: (x: T, i?: number) => PromiseLike): IAlotStream
```
### `mapFull`, `mapFullAsync`
Transform the complete stream
```ts
mapFull (fn: (arr: T[]) => TResult): IAlotStream
```
```ts
mapFullAsync (fn: (arr: T[]) => PromiseLike): PromiseLike
```
### `filter`, `filterAsync`
```ts
filter (fn: (x: T, i?: number) => boolean): IAlotStream
```
```ts
filterAsync (fn: (x: T, i?: number) => PromiseLike): IAlotStream
```
### `forEach`, `forEachAsync`
```ts
forEach (fn: (x: T, i?: number) => void | any): IAlotStream
```
```ts
forEachAsync (fn: (x: T, i?: number) => void | any): IAlotStream
```
### `take`, `takeWhile`, `takeWhileAsync`
```ts
take (count: number): IAlotStream
```
```ts
takeWhile (fn: (x: T) => boolean): IAlotStream
takeWhileAsync (fn: (x: T) => boolean | Promise): IAlotStream
```
### `skip`, `skipWhile`, `skipWhileAsync`
```ts
skip (count: number): IAlotStream
```
```ts
skipWhile (fn: (x: T, i?: number) => boolean): IAlotStream
skipWhileAsync (fn: (x: T, i?: number) => boolean | Promise): IAlotStream
```
### `groupBy`
```ts
groupBy (fn: (x: T) => TKey): IAlotStream< { key: TKey[], values: T[] } >
```
### `join`
> Join elements from collection `Inner` and collection `Outer` by the matched `Key`. Elements with **no** matches are **skipped**.
```ts
// Inner Left Join
join (
inner: TInner[],
getKeyOuter: (x: TOuter) => string | number,
getKeyInner: (x: TInner) => string | number,
joinFn: (a: TOuter, b: TInner) => TResult
): IAlotStream< TResult >
```
### `joinOuter`
> Join elements from collection `Inner` and collection `Outer` by the matched `Key`. Elements with **no** matches are **included** as is.
```ts
// Outer Full Join
joinOuter (
inner: TInner[],
getKey: (x: TOuter) => string | number,
getForeignKey: (x: TInner) => string | number,
joinFn: (a?: TOuter, b?: TInner) => TResult
): IAlotStream< TResult >
```
### `concat`
> Same as `Array::concat`
```ts
// Outer Full Join
concat (
other: TOther[],
): IAlotStream< (TSource | TOther) >
```
### `distinctBy`
```ts
distinctBy (fn: (x: T, i?: number) => TKey): IAlotStream
```
### `sortBy`, `sortByAsync`, `sortByLocalCompare`
```ts
sortBy (fn: (x: T, i?: number) => string | number, direction: 'asc' | 'desc' = 'asc'): IAlotStream
sortBy (property: string, direction: 'asc' | 'desc' = 'asc'): IAlotStream
// also nested path are supported 'user.foo.username'
```
### `thenBy`
`thenBy()` specifies a secondary sort method that is used to further sort data that has already been sorted with a call to `sortBy()`
```ts
alot(arr).sortBy(x => x.age).thenBy(x => x.name).toArray()
```
# Output Data
### `toArray`
```ts
toArray(): T[]
```
### `toArrayAsync`
```ts
toArrayAsync(options: {
threads?: number
errors?: 'reject' | 'include' | 'ignore'
} = { threads: 4, errors: 'reject' }): Promise
```
> `errors` 'reject' - all iterations will be stopped and the task will reject.
> `errors` 'include' - all iterations will be executed, and any throw or rejection will be in resulted array.
> `errors` 'ignore' - all iterations will be executed, and any throw or rejection are ignored. The resulted array could contain holes.
### `toDictionary` `toDictionaryAsync`
```ts
toDictionary(keyFn: (x: T) => TKey, valFn?: (x: T) => TOut ): { [key: string]: TOut }
toDictionaryAsync(keyFn: (x: T) => TKey | Promise, valFn?: (x: T) => TOut | Promise ): Promise<{ [key: string]: TOut }>
```
### `toMap` `toMapAsync`
```ts
toDictionary(keyFn: (x: T) => TKey, valFn?: (x: T) => TOut ): Map
toDictionaryAsync(keyFn: (x: T) => TKey | Promise, valFn?: (x: T) => TOut | Promise ): Promise>
```
### `first`, `find` (alias), `firstAsync`, `findAsync`
```ts
first(matcher?: (x: T, i?: number) => boolean): T
find(matcher?: (x: T, i?: number) => boolean): T
firstAsync(matcher?: (x: T, i?: number) => boolean | Promise): Promise
find(matcher?: (x: T, i?: number) => boolean | Promise): Promise
```
# Aggregation
### `sum`, `sumAsync`, `sumBigInt`, `sumBigIntAsync`
```ts
sum (fn: (x: T, i?: number) => number): number
sumAsync (fn: (x: T, i?: number) => number | Promise): Promise
```
### `max`, `maxAsync`, `min`, `minAsync`
```ts
max (getVal: (x: T, i?: number) => TNumeric): TNumeric
maxAsync (getVal: (x: T, i?: number) => TNumeric): Promise
min (getVal: (x: T, i?: number) => TOut): TNumeric
minAsync (getVal: (x: T, i?: number) => TOut): Promise
```
# Static Methods
#### `fromObject`
```ts
alot.fromObject(foo: any): Alot<{ key: string, value: string }>
```
#### `fromRange`
```ts
alot.fromRange(start: number, endExcluded: number): Alot
```
Supports ascending, e.g.`[-1..10)`, and descending ranges - `[10..-1)`
----
_Atma.js Project_