Jinqu - LINQ for Javascript

Jinqu, based on the LINQ design, is the ultimate querying API for Javscript & Typescript. It provides:

• LINQ syntax
• Lazy (i.e. deferred) Evaluation
• Local and Remote Evaluation w/ provider model for libraries implementing remote evaluation (e.g. jinqu-odata)
• Static Typing (in Typescript)
• Dynamic queries (in strings)
• Even works on IE 11 (with transpilation)

Jinqu works perfectly in both Javascript and Typescript, but is optimized for Typescript. Jinqu is itself written in Typescript.

Installation

npm install jinqu

Code Examples

First, make sure you've imported jinqu. This will add asQueryable method to Array Prototype.

1import 'jinqu'

We need to call asQueryable to create a query for an Array.

1const array = [1,2,3,4,5]
2const query = array.asQueryable().where(c => n % 2 == 0).toArray()
3for (var n of query)
4    console.log (n) // outputs 2,4

If you want to use query methods directly, you need to install and import jinqu-array-extensions package.

npm i jinqu-array-extensions

1import 'jinqu-array-extensions'

You actually only need to do this once, such as in the entry point for your application, to ensure the Array prototype extensions are set up.

Now let's filter an array:

1const array = [1,2,3,4,5]
2const query = array.where(c => n % 2 == 0).toArray()
3for (var n of query)
4    console.log (n) // outputs 2,4

We can chain query operators:

1const array = [1,2,3,4,5]
2const query = array
3    .where(c => n % 2 == 0)
4    .orderByDescending (n => n)
5    .toArray()
6for (var n of query)
7  console.log (n) // outputs 4,2

Importantly, results aren't evaluated until toArray is called.

Dynamic Expressions

1const filtered = orders.where('c => c.id > value', { value: 3 })

The additional argument is a variable scope that lets you pass in variables dynamically.

Supported Query Operators

The full range of LINQ operators are supported:

1where  
2ofType  
3cast  
4select  
5selectMany  
6join  
7groupJoin  
8orderBy  
9orderByDescending  
10thenBy  
11thenByDescending  
12take  
13takeWhile  
14skip  
15skipWhile  
16groupBy  
17distinct  
18concat  
19zip  
20union  
21intersect  
22except  
23defaultIfEmpty  
24reverse  
25first  
26firstOrDefault  
27last  
28lastOrDefault  
29single  
30singleOrDefault  
31elementAt  
32elementAtOrDefault  
33contains  
34sequenceEqual  
35any  
36all  
37count  
38min  
39max  
40sum  
41average  
42aggregate  
43toArray

As well as:

1ofGuardedType

And also:

1range  
2repeat

Remote Query Providers

Jinqu has the following remote providers:

• Jinqu-OData - Query OData endpoints
• Linquest - Query Remote LINQ endpoints

Remote queries always return promises so are awaited. So rather than toArray to obtain the results of the query, you'll call toArrayAsync:

1...
2const result = await remoteQuery.toArrayAsync()
3for (var item of result)
4   ...

Array Prototype Extensions

Jinqu query operators build queries with a simple model: they take a query type as an input, transform it, and output another query type. However, the very first operator in a query needs to take an array type as the original source for the query. To make this work, jinqu extends the Array prototype.

Extending the array prototype is very convenient, but occasionally has conflict issues with Array's built-in prototype or other 3rd party prototype extensions.

To overcome this, you can call asQueryable or the convenience q for short, to ensure you're working with an IQuery<T> type:

1[1,2,3].asQueryable().reverse()
2[1,2,3].q().reverse() // same as above

In addition, the concat, join, and reverse methdos (which are built into the Array prototype), have special support: call concatWith, joinWith, and reverseTo, to start a query with these operators on the array type.

ofType and ofGuardedType

ofType and ofGuardedType filter elements of a specified type. The type arguments you must supply are a little different to what you might expect if you come from a C# background, but will make sense to you when you get a feel for the Typescript type system.

• ofType takes either a:
  • constructor to filter class instances
  • default value to filter primitive types
• ofGuardedType takes a:
  • Typescript type guard (See Typescript Advanced Types) to filter values by a condition indicative of type

Their usage is as follows:

1class Panda {
2    constructor (public id: number) {}
3}
4
5function isNumber(x: any): x is number {
6    return typeof x === "number"
7}
8
9const array = ["1", 2, new Panda(3), "4", 5, new Panda(6)]
10const justPandas = array.ofType(Panda) // panda 3, panda 6 - using constructor type filter
11const justStrings = array.ofType("") // "1", "4" - using default value type filter
12const justNumbers = array.ofGuardedType(isNumber) // 2, 5 - using type guard filter

License

jinqu is licensed with the MIT License.