Have ideas to improve npm?Join in the discussion! Β»

    @adamburgess/linq
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.4Β β€’Β PublicΒ β€’Β Published

    @adamburgess/linq

    A decent linq. With decent types. Less than 2kb gzipped.

    npm version gzipped size brotlied size npm type definitions codecov

    Docs/Usage

    Generated documentation: https://adamburgess-linq.netlify.app/

    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,706 bytes minified/1,047 bytes brotlied

    linq.js (on npm: linq)

    βœ”οΈ Has everything.
    ❌ Except iterator support.
    βœ”οΈ Very popular.
    ⚠️ Types could be improved: toObject is 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,212 bytes minified/1,326 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,447 bytes minified/1,254 bytes brotlied

    Others not considered:

    ❌ @siderite/linqer: 5kb brotlied, and the typings aren't generic. 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

    this one fromfrom iterare linq.js
    Size in bytes (minified) 4,447 4,212 3,725 35,750 (+800% ❌)
    Size in bytes (brotlied) 1,254 1,326 1,058 6,655 (+500% ❌)
    Arrays βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Iterables βœ”οΈ βœ”οΈ βœ”οΈ ❌
    Generators βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Infinite Iterables βœ”οΈ βœ”οΈ βœ”οΈ ❌
    Lazy Iterables βœ”οΈ βœ”οΈ ❌ ❌
    Map βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Where βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Reverse βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Group By βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Order By βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Then By βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Take βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Skip βœ”οΈ βœ”οΈ ⚠️[5] βœ”οΈ
    Take While βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Skip While βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Append βœ”οΈ βœ”οΈ βœ”οΈ ❌
    Prepend βœ”οΈ βœ”οΈ ❌ ❌
    Distinct βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Flat βœ”οΈ ⚠️[1] βœ”οΈ βœ”οΈ
    Join βœ”οΈ ❌ ❌ βœ”οΈ
    Group Join βœ”οΈ ❌ ❌ βœ”οΈ
    Count βœ”οΈ ⚠️[2] ⚠️[2] βœ”οΈ
    to Array βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    To Map βœ”οΈ βœ”οΈ βœ”οΈ ❌
    to Object βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    to Set βœ”οΈ βœ”οΈ βœ”οΈ ⚠️[8]
    First βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Single βœ”οΈ ❌ ❌ βœ”οΈ
    Last βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    All βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    Any βœ”οΈ βœ”οΈ βœ”οΈ βœ”οΈ
    None βœ”οΈ ⚠️[3] ⚠️[3] ⚠️[3]
    Contains βœ”οΈ βœ”οΈ ⚠️[6] βœ”οΈ
    Sum βœ”οΈ βœ”οΈ ❌ βœ”οΈ
    Average βœ”οΈ ❌ ❌ βœ”οΈ
    Max βœ”οΈ ❌ ❌ βœ”οΈ
    Min βœ”οΈ ❌ ❌ βœ”οΈ
    Min By βœ”οΈ ❌ ❌ βœ”οΈ
    Max By βœ”οΈ ❌ ❌ βœ”οΈ
    Sum/Avg/Max/Min fail on non-numbers βœ”οΈ ❌[4] ⁿ/ₐ ❌
    Flatten fails on non-iterables βœ”οΈ ⁿ/ₐ ⚠️[7] ⚠️[7]

    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.

    Keywords

    Install

    npm i @adamburgess/linq

    DownloadsWeekly Downloads

    245

    Version

    1.1.4

    License

    MIT

    Unpacked Size

    69.1 kB

    Total Files

    9

    Last publish

    Collaborators

    • avatar