@adamburgess/linq v3.0.0

@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

1. Arrays
2. Iterables
3. Generators
4. Infinite Generators*

Transformations

1. Map
2. Where (with narrowing!)
3. Reversing
4. Group By
5. Order By
6. Order By Descending
7. Order By ..., Then By
8. Order By ..., Then By Descending
9. Take
10. Skip
11. Take While
12. Skip While
13. Append
14. Prepend
15. Distinct
16. Flat (with projection to sequence)
17. Join (an inner join)
18. GroupJoin

Outputs

1. Count
2. toArray
3. toMap
4. toObject
5. First (+ or Default)
6. Single (+ or Default)
7. Last (+ or Default)
8. All
9. Any
10. None
11. Contains
12. Sum (with projection to number)
13. Average (with projection to number)
14. Max (with projection to number)
15. Min (with projection to number)
16. Min By
17. Max By

Special additions for number sequences:

1. Sum
2. Average
3. Max
4. Min

Special additions for iterable/array sequences:

1. Flat

Special additions for string sequences:

1. 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

⚠️ Really doesn't have enough methods to be general purpose. It is missing: Group, Order, Count, First, Last, Distinct. Subjectively, I use all of these.
⚠️ Supports ES iterators, but doesn't support repeatable/lazy ES iterators
✔️ Extremely popular.
✔️ 3,818 bytes minified/1,065 bytes brotlied

linq.js (on npm: linq)

✔️ Has everything.
❌ Except iterable support. It supports iterators but not iterables. Most of the time, you use iterables. Arrays are iterables. You use the iterable protocol to convert them to iterators. Technically, it doesn't even support iterators. Only objects that are both iterators and iterables.
✔️ Very popular.
⚠️ Types could be improved: toObject is was not typed
❌ 35KB minified/6.6KB brotlied

fromfrom

✔️ Has nearly everything you'd like.
✔️ Supports ES iterators, including lazy/repeatable. (Nice!)
⚠️ Not very popular, but hey, this library is awesome.
✔️ 4,216 bytes minified/1,330 bytes brotlied
✅ Great name. import { from } from 'fromfrom'

@adamburgess/linq

✔️ Supports ES iterators, including lazy/repeatable.
✔️ Has everything in fromfrom, everything in iterare, but not everything in linq.js. Thinking about adding an "extended" version.
✔️ Excellent typing, if I do say so myself. Has a couple features that other libraries don't have.
❌ 1 user. Hah.
✔️ 4,457 bytes minified/1,251 bytes brotlied

Others not considered:

❌ @siderite/linqer: 5kb brotlied, 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

✔️ - has it
⚠️ - doesn't have it, but has a one liner work around
❌ - have to reimplement yourself, and reimplementing would be annoying if done multiple times

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.