ltt

linq-to-typescript

LINQ to TypeScript

Showing:

Popularity

Downloads/wk

630

GitHub Stars

53

Maintenance

Last Commit

2mos ago

Contributors

1

Package

Dependencies

0

License

MIT

Type Definitions

Built-In

Tree-Shakeable

Yes?

Categories

Readme

LINQ To TypeScript

  • Implementation of LINQ for TypeScript
  • Targets TypeScript 3.9.X and ES 2018
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": "es2018",
    "lib": [
      "dom",
      "es2018"
    ],
    "importHelpers": true
}
  • The strict TS option is recommended.
  • Library is dependent on tslib for async iteration polyfills.

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 and Map
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

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

MethodAsync*Tests CoverageNotes
aggregateNoSync
allYesSync, Async
anyYesSync, Async
averageYesSync, Async
concatenateNoSyncEquivalent to .Concat but renamed to avoid conflict with JS
containsYesSync, Async
countYesSync, Async
distinctYesSync, Async
elementAtNoSync
elementAtOrDefaultNoSync
exceptYesSync, Async
firstYesSync, Async
firstOrDefaultYesSync, Async
eachYesSync, AsyncFrom List<T>.ForEach
groupByYesSync, Async
groupByWithSelNoSync
intersectYesSync, Async
joinByKeyNoSync
lastYesSync, Async
lastOrDefaultYesSync, Async
maxYesSync, Async
minYesSync, Async
ofTypeNoSync
orderByYesSync, Async
orderByDescendingYesSync, Async
reverseNoSync
selectYesSync, Async
selectManyYesSync, Async
sequenceEqualsYesSync, Async
singleYesSync, Async
singleOrDefaultYesSync, Async
skipNoSync
skipWhileYesSync, Async
sumYesSync, Async
takeNoSync
takeWhileYesSync, Async
toArrayNoSync
toMapYesSync, AsyncEquivalent to ToDictionary
toSetNoSyncEquivalent to ToHashSet. No comparer overload for JS.
unionYesSync
whereYesSync, Async
zipYesSync, Async

* Async methods take an async function

Static Methods

MethodAsyncParallelTests Coverage
emptyemptyAsyncemptyParallelTest
enumerateObjectenumerateObjectAsyncN/ATest
flattenflattenAsyncflattenParallelTest
partitionpartitionAsyncpartitionParallelTest
rangerangeAsyncrangeParallelTest
repeatrepeatAsyncrepeatParallelTest

Index Methods

MethodNotes
bindArrayBinds IEnumerable methods to an ArrayLike Iterable type
bindLinqBinds IEnumerable methods to an Interable type
bindLinqAsyncBinds IAsyncEnumerable methods to an AsyncIterable type
isEnumerableDetermines if source implements IEnumerable
isAsyncEnumerableDetermines if source implements IAsyncEnumerable
isParallelEnumerableDetermines if source implements IParallelEnumerable
initializeLinqBinds to IEnumerable to Array Types, Map, Set, & String

Exception Types

ExceptionNotes
ArgumentOutOfRangeExceptionThrown when a passed in argument is invalid
InvalidOperationExceptionThrown 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)

F.A.Q.

Q I am getting a Error: Cannot find module 'tslib' error.

A This library depends on tslib. Run npm i tslib to solve the error.

Q Why did you create this?

A For fun and to gain understanding of TypeScript and Node Package Manager.

Q What's needed to target ES2018?

A This library uses iteration and async iteration. You may need polyfills for Iterator and AsyncIterator. Libraries such as core js have this.

Q Can this run in an ES5 browser like Internet Explorer.

A With the right transpiler, polyfills, and bundler. Its not recommended due to the size and most likely major performance impact.

Q How does this compare to other LINQ libraries?

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

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

A

  • TypeScript first. Libraries which target JavaScript first do additional type checking which can have a negative impact on performance.
  • This library uses iterators and generators. Evaluation is lazy, not eager like JS array operations. These are new language features which have no support in legacy browsers like IE11.

Q Which browsers are supported?

A

  • Firefox, Chrome, and Edge. IE is not supported.
  • A good bundler targeting ES5 should allow IE support (with proper ES6/ES7 polyfils).

Q Can I contribute?

A Please do!

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100