Skip to content

arogozine/LinqToTypeScript

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

LINQ To TypeScript

  • Implementation of LINQ for TypeScript
  • Targets TypeScript 4.7.X and ES 2022
await from([bing, google, quackQuackGo])
    .asParallel()
    .selectAsync(downloadHtml)
    .select(getTitle)
    .toArray()

Getting Started

npm i linq-to-typescript

npm npm bundle size License npm

tsconfig.json

"compilerOptions": {
    "target": "es2022",
    "lib": [
      "es2022"
    ]
}
  • The strict TS option is recommended.

Using the Library

With Wrappers

// 0. Import Module
import { from } from "linq-to-typescript"

// To Use With Wrappers
const evenNumbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9]).where((x) => x % 2 === 0).toArray()

Without Wrappers

// 0. Import Module
import { initializeLinq, IEnumerable } from "linq-to-typescript"
// 1. Declare that the JS types implement the IEnumerable interface
declare global {
    interface Array<T> extends IEnumerable<T> { }
    interface Uint8Array extends IEnumerable<number> { }
    interface Uint8ClampedArray extends IEnumerable<number> { }
    interface Uint16Array extends IEnumerable<number> { }
    interface Uint32Array extends IEnumerable<number> { }
    interface Int8Array extends IEnumerable<number> { }
    interface Int16Array extends IEnumerable<number> { }
    interface Int32Array extends IEnumerable<number> { }
    interface Float32Array extends IEnumerable<number> { }
    interface Float64Array extends IEnumerable<number> { }
    interface Map<K, V> extends IEnumerable<[K, V]> { }
    interface Set<T> extends IEnumerable<T> { }
    interface String extends IEnumerable<string> { }
}
// 2. Bind Linq Functions to Array, Map, etc
initializeLinq()
// 3. Use without a wrapper type
const evenNumbers = [1, 2, 3, 4, 5, 6, 7, 8, 9].where((x) => x % 2 === 0).toArray()

Examples

Please refer to the examples folder

ES6 Modules (ESM)

To use library with ES6 modules make sure that you specify "type": "module" in package.json

API

TypeDoc API Surface Documentation

LinqToTypeScript implements the functionality of the IEnumerable interface

  • IEnumerable, IAsyncEnumerable, and IParallelEnumerable interfaces are based on,
  • IEnumerable<T> Interface
  • Some changes made due to conflics with existing method names
  • Some changes made due to limitations of JavaScript

IEnumerable

  • Inspired by LINQ API Surface
  • Has Async methods that return Promise or IAsyncEnumerable
  • Implements Iterable<T>
  • Use from to wrap your arrays

IAsyncEnumerable

  • Inspired by LINQ API Surface
  • Has Async methods that return Promise or IAsyncEnumerable
  • For asynchronous iteration
  • Implements AsyncIterable<T> interface
  • Use fromAsync to wrap your AsyncIterable type

IParallelEnumerable

  • Inspired by LINQ API Surface
  • Has Async methods that return Promise or IParallelEnumerable
  • For asynchronous iteration in parallel (where possible)
  • Implements AsyncIterable<T> interface
  • Use fromParallel to create a parallel enumeration

Shared Instance Methods

Method Async* Tests Coverage Notes
aggregate No Sync
all Yes Sync, Async
any Yes Sync, Async
append No Sync
average Yes Sync, Async
chunk No Sync
concatenate No Sync Equivalent to .Concat but renamed to avoid conflict with JS
contains Yes Sync, Async
count Yes Sync, Async
defaultIfEmpty No Sync
distinct Yes Sync, Async
elementAt No Sync
elementAtOrDefault No Sync
except Yes Sync, Async
first Yes Sync, Async
firstOrDefault Yes Sync, Async
each Yes Sync, Async From List<T>.ForEach
groupBy Yes Sync, Async
groupByWithSel No Sync
groupJoin Yes Sync, Async
intersect Yes Sync, Async
joinByKey No Sync
last Yes Sync, Async
lastOrDefault Yes Sync, Async
max Yes Sync, Async
min Yes Sync, Async
ofType No Sync
order No Sync
orderBy Yes Sync, Async
orderByDescending Yes Sync, Async
orderDescending No Sync
partition Yes Sync, Async
prepend No Sync
reverse No Sync
select Yes Sync, Async
selectMany Yes Sync, Async
sequenceEquals Yes Sync, Async
single Yes Sync, Async
singleOrDefault Yes Sync, Async
skip No Sync
skipWhile Yes Sync, Async
sum Yes Sync, Async
take No Sync
takeWhile Yes Sync, Async
toArray No Sync
toMap Yes Sync, Async Equivalent to ToDictionary
toObject Yes Sync, Async
toSet No Sync Equivalent to ToHashSet. No comparer overload for JS.
union Yes Sync
where Yes Sync, Async
zip Yes Sync, Async

* Async methods take an async function

Static Methods

Method Async Parallel Tests Coverage
empty emptyAsync emptyParallel Test
enumerateObject enumerateObjectAsync N/A Test
flatten flattenAsync flattenParallel Test
range rangeAsync rangeParallel Test
repeat repeatAsync repeatParallel Test

Index Methods

Method Notes
bindArray Binds IEnumerable methods to an ArrayLike Iterable type
bindLinq Binds IEnumerable methods to an Interable type
bindLinqAsync Binds IAsyncEnumerable methods to an AsyncIterable type
isEnumerable Determines if source implements IEnumerable
isAsyncEnumerable Determines if source implements IAsyncEnumerable
isParallelEnumerable Determines if source implements IParallelEnumerable
initializeLinq Binds to IEnumerable to Array Types, Map, Set, & String

Exception Types

Exception Notes
ArgumentOutOfRangeException Thrown when a passed in argument is invalid
InvalidOperationException Thrown when no elements or no predicate match

Design

Binding new APIs to Array Types

JavaScript doesn't have extension methods like in C#, therefore we extend the class itself with new methods. Call initializeLinq to bind library functions to default Array methods,

The following collections support IEnumerable,

  • Array
  • Map
  • Set
  • String
  • Int8Array
  • Int16Array
  • Int32Array
  • Uint8Array
  • Uint8ClampedArray
  • Uint16Array
  • Uint32Array
  • Float32Array
  • Float64Array

Using Wrappers

NOTE: Wrappers are safer as they won't interfere with other libraries.

// To Create an IEnumerable<T>
import { from } from "linq-to-typescript"
from(iterableIteratorOrArray)

// To Create an IAsyncEnumerable<T>
import { fromAsync } from "linq-to-typescript"
fromAsync(asyncIterableIteratorOrPromiseArray)

// To Create an IParallelEnumerable<T>
// You have to specify the parallel generator function type
import { fromParallel, ParallelGeneratorType } from "linq-to-typescript"
fromParallel(ParallelGeneratorType.PromiseToArray, asyncFuncThatReturnsAnArray)

Issues and Questions

Q1: How does this compare to other LINQ libraries?

Other libraries tend to use eager evaluation and work with arrays instead of iterables.

Q2: Can I use your code?

With attribution; the code is licensed under MIT.

Q3: Why should I use this instead of lodash or something similar?

The whole library is written in TypeScript first and avoids typechecking done by TypeScript Language Service.

Lazy evaluation. Not much happens until you iterate over the enumerable or conver it to an Array, Map, etc.

Q4: Is IE11 supported?

No.

Q5: Can I contribute?

Please do!