@adamburgess/linq
A decent linq. With decent types. Less than 2kb gzipped.
Docs/Usage
Generated documentation: https://linq.adam.id.au/
import from from '@adamburgess/linq'
const sequence = from(['an', 'iterable', 'here']);
// now use any methods on sequence!
// e.g. mapping:
const uppercases = sequence.map(x => x.toUpperCase());
// note: the sequence hasn't been mapped yet! toUpperCase hasn't been called!
// you must _run_ the sequence (see Outputs below)
Array.from(uppercases); // or uppercases.toArray()
// => ['AN', 'ITERABLE', 'HERE']
// You can extend already existing transforms:
const reversed = uppercases.reverse();
// still! The sequence hasn't been reversed!
// Again you must run it:
Array.from(reversed);
// => ['HERE', 'ITERABLE', 'AN']
// note! When this reversed array was created, it ran:
// 1. the uppercase sequence (yes, again!)
// 2. the reverse method
// _ALL_ operations are deferred until outputting the sequence!Features
Completely lazy evaluation.
Inputs
- Arrays
- Iterables
- Generators
- Infinite Generators*
Transformations
- Map
- Where (with narrowing!)
- Reversing
- Group By
- Order By
- Order By Descending
- Order By ..., Then By
- Order By ..., Then By Descending
- Take
- Skip
- Take While
- Skip While
- Append
- Prepend
- Distinct
- Flat (with projection to sequence)
- Join (an inner join)
- GroupJoin
Outputs
- Count
- toArray
- toMap
- toObject
- First (+ or Default)
- Single (+ or Default)
- Last (+ or Default)
- All
- Any
- None
- Contains
- Sum (with projection to number)
- Average (with projection to number)
- Max (with projection to number)
- Min (with projection to number)
- Min By
- Max By
Special additions for number sequences:
- Sum
- Average
- Max
- Min
Special additions for iterable/array sequences:
- Flat
Special additions for string sequences:
- JoinString
* Note: Some transformations/most outputs do not work with infinite sequences, such as Group By and Order By.
Other libraries
or: why use this one?
iterare
linq.js (on npm: linq)
is was not typed
fromfrom
import { from } from 'fromfrom'
@adamburgess/linq
Others not considered:
and the typings aren't generic. It now has a typescript version. Yet, they've borked the packaging -- I can't import the module without changing their package.json and importing the direct path. For that reason, useless. Has similar features to fromfrom.
Table comparison to other libraries
| this one | fromfrom | iterare | linq.js | |
|---|---|---|---|---|
| Size in bytes (minified) | 4,457 | 4,216 | 3,818 | 35,451 (+800% |
| Size in bytes (brotlied) | 1,251 | 1,330 | 1,065 | 6,516 (+500% |
| Arrays | ||||
| Iterables | ||||
| Generators | ||||
| Infinite Iterables | ||||
| Lazy Iterables | ||||
| Map | ||||
| Where | ||||
| Reverse | ||||
| Group By | ||||
| Order By | ||||
| Then By | ||||
| Take | ||||
| Skip |
|
|||
| Take While | ||||
| Skip While | ||||
| Append | ||||
| Prepend | ||||
| Distinct | ||||
| Flat |
|
|||
| Join | ||||
| Group Join | ||||
| Count |
|
|
||
| to Array | ||||
| To Map | ||||
| to Object | ||||
| to Set |
|
|||
| First | ||||
| Single | ||||
| Last | ||||
| All | ||||
| Any | ||||
| None |
|
|
|
|
| Contains |
|
|||
| Sum | ||||
| Average | ||||
| Max | ||||
| Min | ||||
| Min By | ||||
| Max By | ||||
| Sum/Avg/Max/Min fail on non-numbers |
|
ⁿ/ₐ | ||
| Flatten fails on non-iterables | ⁿ/ₐ |
|
|
|
notes:
1. Use flatmap with identity.
2. Use forEach with a count.
3. Use !any
4. There is some typing to prevent Sum on non-numbers, but it actually has no effect.
5. Use slice
6. Use find, check for !== undefined
7. If used on non-iterables, it returns the element unchanged. This follows how JS's .flat() works. My opinion: Why are you flattening an array of things that aren't arrays? Don't.
8. It's untyped!
Performance
It's probably slow.
It uses iterators for everything.
If you want performance, maybe use iterare. Their readme puts performance front and center.