jsinq Wiki & Documentation Rss Feed

Updated Wiki: Frequently asked questions

kaijaeger — Wed, 04 Aug 2010 06:50:49 GMT

Q: How fast is JSINQ?

A: JSINQ's "Enumerable" implementation is not optimized for speed, but it is still reasonably fast, i.e. for the kind of datasets you deal with in a typical JavaScript application, the performance of JSINQs "Enumerable" implementation should be more than adequate. JSINQs query-compiler on the other hand is relatively slow, but since queries are generally compiled once and then never again, the impact of the query compilation on the overall performance of a JavaScript application should again be negligible. If you run into performance problems when using JSINQ, make sure your queries are defined in a scope where they are not compiled over and over again.

Q: Is JSINQ ready for production use?

A: Yes, for the most part! The "Enumerable" part of JSINQ is reasonably well-tested and is generally considered to be "safe" but the query compiler is still in a rather "experimental" stage. What you should note though is that if the query compiler produces correct output for a specific query, it is very likely to continue to do so in the future. In other words: bugs in the query compiler are likely to show up early and if a query compiles without errors once, it will not fail the second time (barring the influence of cosmic rays).

Q: Is JSINQ prone to "SQL injections"?

A: You mean JSINQ-injections? Yes it is, but only if you are doing it wrong! Since you specify your queries as strings, they are theoretically prone to the same kind of injection-type attacks that you get with SQL, but only if you are piecing together your queries with unvalidated strings that you somehow obtain from the user. Of course that is absolutely not how you should write your queries. If you have to get variables into your query, use placeholders! Placeholders are not replaced textually, i.e. you can't hijack a JSINQ query using a bad string passed in via a placeholder. Also, since JSINQ runs on the client, even if it was prone to injection-type attacks, it wouldn't really matter because you should never trust anything that comes from the client, ever.

Q: Is JSINQ better than jQuery, Prototype,...?

A: No. JSINQ is not a general-purpose JavaScript framework, it is not a widget library, it is not an Ajax framework and it doesn't try to be any of those things. You can easily combine JSINQ with those frameworks though.

Q: Does JSINQ support nested queries?

A: Theoretically: yes. You can assign query objects to placeholders or you can even define nested queries inline using anonymous functions.

Q: What does JSINQ stand for?

A: JavaScript INtegrated Query. And yes, it's a misnomer because JSINQ isn't really integrated into JavaScript at all.

Q: Is there a "JSINQ to XML"?

A: If by that you mean a JavaScript equivalent of LINQ to XML, then no. But there should be and you should probably be the one to write it (let me know if you do).

Q: How do you pronounce JSINQ?

A: I pronounce it Jay-Sink, but you may also pronounce it Jay-Ess-Ink or Ja-Zink (the sound a broken cash register makes).

Updated Wiki: Home

kaijaeger — Wed, 04 Aug 2010 06:49:38 GMT

JSINQ 1.0 out now!

JSINQ 1.0, the first stable release of JSINQ is available for download right now! It is packed with new features such as

Support for all .NET 3.5 query operators
Experimental support for the .NET 4.0 query operator "zip"
100% lazy (uses deferred execution)
Complete, fully tested implementations of System.Collections.Generic.List and System.Collections.Generic.Dictionary
toList, toDictionary and toLookup now available for jsinq.Enumerable
Still only 23 KB when minified

What is JSINQ?

JSINQ is the JavaScript library that allows you to write SQL-like queries against arrays and DOM node lists.
JSINQ is a complete implementation of LINQ to Objects (the .NET 4.0 version) in JavaScript. What that means is that if you know LINQ and you know JavaScript, you know JSINQ. JSINQ is both an API-compatible implementation of System.Linq.Enumerable and a complete query-expression compiler. That's right: you can write LINQ-style queries in JavaScript. And if that isn't enough: JSINQ is also very liberally licensed, well-document, well-tested (the Enumerable-part) and a stable version has just been released. So give it a go!

What does it look like?

Let's say you have a list of customers and you want to assemble a list of your customers' lastnames, ordered by their frequency. With JSINQ, you can write something like this:

var result = 
    customers.groupBy(function(customer) { 
        return customer.lastname; 
    }).
    select(function(g) { 
        return {lastname: g.key, count: g.count()}; 
    }).
    orderByDescending(function(r) { 
        return r.count; 
    });

This will do the job, but it's also rather difficult to read. That's why JSINQ also lets you write the following:

var query = new jsinq.Query('\
    from customer in $0 \
    group customer by customer.lastname into g \
    select {lastname: g.key, count: g.count()} \
    into r \
    orderby r.count descending \
    select r \
');

query.setValue(0, customers);
var result = query.execute();

Confused? What's with all the backslashes? Please read: JSINQ in a nutshell.

What can I do with JSINQ?

Write arbitrarily complex queries against JavaScript arrays, DOM node lists or your own enumerable types
Find elements in the HTML DOM tree using SQL-like queries
Dynamically create HTML elements from JSON you have received via XMLHttpRequest in a declarative manner
Tinker with XML and turn it into something else
Combine it in interesting ways with the JavaScript-/Ajax-frameworks you are already using
Write less code by exploiting the power of declarative programming
And for the ambitious: write raytracers, monadic parser combinators, etc.

Using JSINQ

JSINQ in a nutshell (new to JSINQ?, read this!)
JSINQ Documentation
Frequently asked questions

Previous work

JSINQ isn't the first attempt at implementing LINQ in JavaScript. There is also Chris Pietschmann's LINQ to JavaScript (right here on CodePlex), there is jLINQ and then there is this.

Updated Wiki: Home

kaijaeger — Mon, 24 May 2010 09:06:37 GMT

JSINQ 1.0 out now!

JSINQ 1.0, the first stable release of JSINQ is available for download right now! It is packed with new features such as

Support for all .NET 3.5 query operators
Experimental support for the .NET 4.0 query operator "zip"
100% lazy (uses deferred execution)
Complete, fully tested implementations of System.Collections.Generic.List and System.Collections.Generic.Dictionary
toList, toDictionary and toLookup now available for jsinq.Enumerable
Still only 23 KB when minified

What is JSINQ?

What does it look like?

Let's say you have a list of customers and you want to assemble a list of your customers' lastnames, ordered by their frequency. With JSINQ, you can write something like this:

var result = 
    customers.groupBy(function(customer) { 
        return customer.lastname; 
    }).
    select(function(g) { 
        return {lastname: g.key, count: g.count()}; 
    }).
    orderByDescending(function(r) { 
        return r.count; 
    }).
    select(function(r) { 
        return r; 
    });

This will do the job, but it's also rather difficult to read. That's why JSINQ also lets you write the following:

var query = new jsinq.Query('\
    from customer in $0 \
    group customer by customer.lastname into g \
    select {lastname: g.key, count: g.count()} \
    into r \
    orderby r.count descending \
    select r \
');

query.setValue(0, customers);
var result = query.execute();

Confused? What's with all the backslashes? Please read: JSINQ in a nutshell.

What can I do with JSINQ?

Write arbitrarily complex queries against JavaScript arrays, DOM node lists or your own enumerable types
Find elements in the HTML DOM tree using SQL-like queries
Dynamically create HTML elements from JSON you have received via XMLHttpRequest in a declarative manner
Tinker with XML and turn it into something else
Combine it in interesting ways with the JavaScript-/Ajax-frameworks you are already using
Write less code by exploiting the power of declarative programming
And for the ambitious: write raytracers, monadic parser combinators, etc.

Using JSINQ

JSINQ in a nutshell (new to JSINQ?, read this!)
JSING Documentation
Frequently asked questions

Previous work

JSINQ isn't the first attempt at implementing LINQ in JavaScript. There is also Chris Pietschmann's LINQ to JavaScript (right here on CodePlex), there is jLINQ and then there is this.

Updated Wiki: Home

kaijaeger — Thu, 13 May 2010 09:41:26 GMT

JSINQ 1.0 out now!

JSINQ 1.0, the first stable release of JSINQ is available for download right now! It is packed with new features such as

Support for all .NET 3.5 query operators
Experimental support for the .NET 4.0 query operator "zip"
Complete, fully tested implementations of System.Collections.Generic.List and System.Collections.Generic.Dictionary
toList, toDictionary and toLookup now available for jsinq.Enumerable
Still only 23 KB when minified

What is JSINQ?

What does it look like?

Let's say you have a list of customers and you want to assemble a list of your customers' lastnames, ordered by their frequency. With JSINQ, you can write something like this:

var result = 
    customers.groupBy(function(customer) { 
        return customer.lastname; 
    }).
    select(function(g) { 
        return {lastname: g.key, count: g.count()}; 
    }).
    orderByDescending(function(r) { 
        return r.count; 
    }).
    select(function(r) { 
        return r; 
    });

This will do the job, but it's also rather difficult to read. That's why JSINQ also lets you write the following:

var query = new jsinq.Query('\
    from customer in $0 \
    group customer by customer.lastname into g \
    select {lastname: g.key, count: g.count()} \
    into r \
    orderby r.count descending \
    select r \
');

query.setValue(0, customers);
var result = query.execute();

Confused? What's with all the backslashes? Please read: JSINQ in a nutshell.

What can I do with JSINQ?

Write arbitrarily complex queries against JavaScript arrays, DOM node lists or your own enumerable types
Find elements in the HTML DOM tree using SQL-like queries
Dynamically create HTML elements from JSON you have received via XMLHttpRequest in a declarative manner
Tinker with XML and turn it into something else
Combine it in interesting ways with the JavaScript-/Ajax-frameworks you are already using
Write less code by exploiting the power of declarative programming
And for the ambitious: write raytracers, monadic parser combinators, etc.

Using JSINQ

JSINQ in a nutshell (new to JSINQ?, read this!)
JSING Documentation
Frequently asked questions

Previous work

JSINQ isn't the first attempt at implementing LINQ in JavaScript. There is also Chris Pietschmann's LINQ to JavaScript (right here on CodePlex), there is jLINQ and then there is this.

Updated Wiki: JSINQ in a nutshell

kaijaeger — Sat, 27 Mar 2010 14:17:08 GMT

Including the JSINQ files

JSINQ consists of two components, jsinq.Enumerable and jsinq.Query. The "Enumerable" component is a complete, API-compatible implementation of the .NET class System.Linq.Enumerable. To use jsinq.Enumerable, you need to include the "jsinq.js" file in your HTML page like this:

<script type="text/javascript" src="jsinq.js"></script>

It is recommended that you use the file found in the "build" folder as it is substantially smaller than the un-minified file found in the "source" folder.

If you also want to use jsinq.Query (see below), you'll also have to include the file "jsinq-query.js".

Writing queries using query-methods

Once you have included the file(s), you can start to write queries against arrays, DOM node lists or your own enumerable objects. An example:

var names = ['Bob', 'Alice', 'Joe', 'Frank', 'Arthur', 'Marcy'];
var enumerable = new jsinq.Enumerable(names);

var namesThatStartWithAnA = enumerable.where(function(name) { 
	return name.charAt(0) == 'A'; 
});

The variable "namesThatStartWithAnA" now refers to an enumerable that will return all the names in the "names" array that start with a capital "A" when enumerated. To enumerate an enumerable, do the following:

var enumerator = namesThatStartWithAnA.getEnumerator();
while (enumerator.moveNext()) {
	var name = enumerator.current();
	document.write(name + '<br />');
}

There is also a convenient helper-method that makes enumerating over the elements in an enumerable much easier:

namesThatStartWithAnA.each(function(name) {
	document.write(name + '<br />');
});

You can create more complex queries by chaining together multiple query-methods like this:

var result = enumerable.where(function(name) { 
	return name.toLowerCase().indexOf('a') > -1; 
}).orderByDescending(function(name) { 
	return name; 
});

When enumerating the enumerator referred to by the variable "result", you will receive a list of all names that contain an "a" in a reverse alphabetical order.

Using this "pattern", you can create arbitrarily complex queries. Unfortunately, the simple query above already looks quite complex and as you keep adding clauses to your query, it will become increasingly difficult to see what the result of a query is going to be.

Writing queries using query expressions

Fortunately, chaining together query-methods is not the only way of defining a query in JSINQ. Instead, you can write your queries in a more natural, SQL-like fashion:

var query = new jsinq.Query(' \
	from name in $0 \
	where name.toLowerCase().indexOf("a") > -1 \
	orderby name descending \
	select name \
');

So what is going on here? The Query constructor provided by JSINQ receives a string containing a LINQ expression and essentially compiles it into JavaScript code. Unsurprisingly, the JavaScript code produced by the query compiler looks exactly like the code in the previous examples. Looking at the code above however, you might notice two things that are weird. For one, what is up with all the backslashes? JavaScript does not officially support multi-line strings which is a bummer, because queries look so much nicer when you put each clause on a separate line. Multi-line strings can however be simulated by placing a backslash at the end of each line. This is slightly evil because it is not in any way mentioned in the JavaScript language specification, but it appears to work in most browsers (read: use with caution and at your own risk). Secondly, what is "$0"? The JSINQ Query object essentially acts like a prepared statement. When you create a new Query object, you invoke the query compiler but the query is not actually executed. That way, you can use the same query many times without having to re-compile it over and over again. What's even better is, that you can apply the same query to different datasets without having to re-compile it. This is where placeholders come into play. You can use placeholders in your query, where you would otherwise use an identifier or an expression. Using the "setValue" method of the Query object, you can then assign a concrete value to each placeholder like this:

query.setValue(0, enumerable);

This assigns our enumerable (the one with the names in it) to placeholder "$0". Once you have assigned a value to each placeholder, you can execute a query by invoking its "execute" method. Our example in its entirety now looks like this:

var query = new jsinq.Query(' \
	from name in $0 \
	where name.toLowerCase().indexOf("a") > -1 \
	orderby name descending \
	select name \
');

query.setValue(0, enumerable);
var result = query.execute();

The variable "result" now contains the enumerable that is the result of applying our query to the enumerable that we have specified using the "setValue" method.

What's next?

Download JSINQ!
Read the documentation

Updated Wiki: jsinq.Dictionary

kaijaeger — Sat, 27 Mar 2010 14:16:27 GMT

jsinq.Dictionary

Since its initial release, JSINQ has been expanded to also contain the two collection classes jsinq.List and jsinq.Dictionary. jsinq.Dictionary is a complete implementation of System.Collections.Generic.Dictionary. Unlike JavaScript's object type, jsinq.Dictionary supports arbitrary values as keys.

var dictionary = new jsinq.Dictionary();
dictionary.set("Hello", "World");
alert(dictionary.item("Hello")); // alerts "World"
var myKey = { foo: 123 };
dictionary.set(myKey, new Date());
alert(dictionary.containsKey(myKey)); // alerts "true"

You can also turn any jsinq.Enumerable into a dictionary by invoking its "toDictionary" method.

Methods

jsinq.Dictionary provides the following methods:

Method	Static	Description
item	no	Retrieves the value associated with the specified key
set	no	Sets the value associated with the specified key. An existing value associated with the key will be replaced.
count	no	Returns the number of key-value pairs in this dictionary
getComparer	no	Retrieves the comparer associated with this dictionary
add	no	Adds the specified key and value to the dictionary
tryAdd	no	Attempts to add the specified key and value to the dictionary. Returns a boolean value indicating whether the operation was successful.
keys	no	Returns an array containing the keys in this dictionary
values	no	Returns an array containing the values in this dictionary
clear	no	Empties the dictionary
containsKey	no	Returns a boolean value indicating whether the specified key is contained within the dictionary.
containsValue	no	Returns a boolean value indicating whether the specified value is contained within the dictionary
getEnumerator	no	Returns an enumerator that iterates over this dictionary
toArray	no	Returns an array containing the keys and values in this dictionary dictionary. Returns a boolean value indicating whether the operation was successful.
isReadOnly	no	Indicates whether this dictionary is read-only
toString	no	Returns a string representing the dictionary

Please check out the official .NET reference for additional information on how to use these methods: http://msdn.microsoft.com/en-us/library/xfhwa508.aspx
Also look at the comments in the source code and of course the examples.

Updated Wiki: jsinq.List

kaijaeger — Sat, 27 Mar 2010 14:16:18 GMT

jsinq.List

As of version 1.0, JSINQ contains a complete implementation of System.Collections.Generic.List that you can use independently of the querying functionality. To use JSINQ's list implementation, all you have to do is include the file "jsinq.js". You can then use jsinq.List like you would System.Collections.Generic.List:

var list = new jsinq.List();
list.add("JSINQ");
list.insert(0, "Hello");
list.removeAt(1);
alert(list.item(0);
list.set(0, "Test");

You can also turn any jsinq.Enumerable into a list by invoking its "toList" method.

Methods

jsinq.List provides the following methods:

Method	Static	Description
add	no	Adds the specified item to the end of the list
item	no	Retrieves the element at the specified index
set	no	Sets the element at the specified index
addRange	no	Adds the elements of the specified collection to the end of the list
asReadOnly	no	Return a read-only list wrapper for the current collection
binarySearch	no	Searches a sorted list for the given element
clear	no	Empties the list
copyTo	no	Copies a range of elements from the list to the specified array
exists	no	Returns a boolean value indicating whether the list contains any elements satisfying the condition defined by the given predicate function
find	no	Returns the first occurrence of an element that satisfies the condition defined by the given predicate
findAll	no	Retrieves all the elements from the list that satisfy the condtion defined by the given predicate
findIndex	no	Returns the index of the first element in the list that satisfies the condition defined by the given predicate
findLast	no	Returns the last occurrence of an element that satisfies the condition defined by the given predicate
findLastIndex	no	Returns the index of the last element in the list that satisfies the condition defined by the given predicate
forEach	no	Performs the specified action for each element in the list
getEnumerator	no	Returns an enumerator that iterates through the list
getRange	no	Extracts a range of elements from the list. The operation performs a shallow copy of the extracted elements, i.e. reference types are not cloned.
indexOf	no	Returns the index of the first occurrence of the specified item in the list or a part thereof
insert	no	Inserts the specified element into the list at the specified position
insertRange	no	Inserts the elements in the specified collection into the list at the specified position
lastIndexOf	no	Returns the index of the last occurrence of the specified item in the list or a part thereof
remove	no	Removes the specified item from the list. Returns a boolean value indicating whether the operation was successful
removeAll	no	Removes all the elements from the list that satisfy the condition defined by the given predicate
removeAt	no	Removes the element at the given index from the list
removeRange	no	Removes a range of elements from the list
reverse	no	Reverses the order of the elements in the list
sort	no	Sorts the elements in the list or a portion thereof
toArray	no	Returns an array containing the elements in the list
toString	no	Returns a string representing the list
isReadOnly	no	Indicates whether this list is read-only
trueForAll	no	Returns true if all elements in the list satisfy the condition defined by the given predicate

Please check out the official .NET reference for additional information on how to use these methods: http://msdn.microsoft.com/en-us/library/6sh2ey19.aspx
Also look at the comments in the source code and of course the examples.

Updated Wiki: jsinq.Query

kaijaeger — Sat, 27 Mar 2010 14:16:09 GMT

jsinq.Query

jsinq.Query is where the magic happens, that is where LINQ-style queries are turned into JavaScript code. jsinq.Query depends on jsinq.Enumerable, so make sure you include both files when using the query-expression capabilities of JSINQ.

var query = new jsinq.Query("from customer in $0 where customer.lastname.charAt('0') == 'S' select customer.lastname");

This is how you create a new Query. The Query constructor receives the string that contains the query, leaving you with a Query object that is (almost) ready to use. If there is a syntactical error in your query, the query compiler will catch it and throw a QueryTranslationException. Inspect the exception object to see the error message, line number and character offset at which the error occurred. Note that (for now), the error messages produced by the query compiler are pretty bad and the line number given in the exception object is often nowhere near where the actual error occurred. Also note that the query compiler will catch errors in expressions that may be part of the query, so make sure you check those as well.

A query object essentially is a prepared statement, similar to those you might know from writing database applications. That means that a query object is a query waiting to be executed. Before you can do that however, you have to assign values to all placeholders that may exist in your query. Since queries are specified as strings, they are slightly detached from their surroundings and they cannot access variables from "the outside world". This may seem like a problem, but it really isn't. Where you would normally use variables, you can instead use placeholders. These are composed of a dollar sign and a number (like this: $0) which makes them easy to distinguish from "real" variables. To assign a value to a placeholder, you use the setValue method like so:

var query = new jsinq.Query("from customer in $0 where customer.lastname.charAt('0') == 'S' select customer.lastname");
query.setValue(0, myCustomers);

The nice thing about placeholders is that you can keep assigning different values to them as often as you like. So you can use the same query over and over again but have it work on different datasets, with different constraints and so forth.

After you have assigned values to all placeholders, you call the execute method. The execute method executes the query and returns its result (which generally is an Enumerable):

var query = new jsinq.Query('from customer in $0 where customer.lastname.charAt('0') == 'S' select customer.lastname');
query.setValue(0, myCustomers);
var filterCustomers = query.execute();

And that is all there is to writing queries! If you are new to LINQ and are not familiar with the query expression syntax, check out these examples: http://msdn.microsoft.com/en-us/vcsharp/aa336746.aspx (note that some of these are a little outdated and the syntax has since changed a little).

Spanning queries across multiple lines

The most common way of formatting a LINQ query is to put each clause on its own line like this:

from c in customers
join o in orders on c.id equals o.customerId
where o.items > 10
orderby c.lastname
select {lastname: c.lastname, items: o.items}

Unfortunately, JavaScript does not natively support multi-line strings. So you're stuck with writing something like this:

var query = "from c in customers" +
    "join o in orders on c.id equals o.customerId" +
    "where o.items > 10" +
    "orderby c.lastname" +
    "select {lastname: c.lastname, items: o.items}",

Unless you are willing to let language specifications be language specifications and exploit a bug/feature found in pretty much all JavaScript implementations:

var query = "from c in customers \
    join o in orders on c.id equals o.customerId \
    where o.items > 10 \
    orderby c.lastname \
    select {lastname: c.lastname, items: o.items}",

Yes, it's still ugly, but less so. Note that there cannot be any whitespace after the backslash at the end of each line. If you choose to use this "feature", make sure you thoroughly test your application in all browsers that you are targeting.

Methods

jsinq.Query provides the following methods:

Method	Static	Description
setValue	no	Binds a specified value to a placeholder
execute	no	Executes the query and returns the result
getQueryFunction	no	Returns the anonymous function that executes the query

Updated Wiki: jsinq.Enumerable

kaijaeger — Sat, 27 Mar 2010 14:15:57 GMT

From LINQ to JSINQ

The heart of JSINQ is jsinq.Enumerable which is a faithful implementation of System.Linq.Enumerable in JavaScript. It differs from its .NET counterpart in that it uses JavaScript naming conventions, lacks types and has a few subtle differences in how it handles overloads. In general though, it is API-compatible with the .NET implementation. What that means is that you can use the .NET documentation for reference: http://msdn.microsoft.com/en-us/library/system.linq.enumerable_members.aspx

jsinq.Enumerable

jsinq.Enumerable unlike its .NET counterpart is an actual constructor that you can use to create enumerables from arrays or DOM node lists. Let's look at an example:

var nodes = document.getElementsByTagName('*');
var enumerable = new jsinq.Enumerable(nodes);

The variable "enumerable" now holds a new enumerable that can be used to enumerate over the elements of the node list. To do so, simply write:

var enumerator = enumerable.getEnumerator();
while (enumerator.moveNext()) {
    var current = enumerator.next();
    // do something with "current" here
}

You can also write your own enumerables; all you have to do is implement the method getEnumerator and then return an object that supports the three methods current, moveNext and reset. The signatures and semantics of these methods are described here: http://msdn.microsoft.com/en-us/library/system.collections.ienumerator_members.aspx. Also check out the implementation of Enumerable.range in the file "jsinq.js". If you set the prototype of your enumerable to jsinq.Enumerable.prototype, you get all of its querying-goodness for free.

Methods

jsinq.Enumerable provides the following methods:

Method	Static	Description
aggregate	no	Accumulates the elements of an Enumerable using an accumulator function.
all	no	Returns true if all elements in the Enumerable satisfy the specified condition.
any	no	Returns true if the Enumerable contains any elements or if at least one of the elements in the Enumerable satisfy a specified condition.
average	no	Returns the average of the elements in the Enumerable, optionally using the specified selector function.
concat	no	Creates a new Enumerable that is the result of the concatenation of two Enumerables.
contains	no	Returns true if the Enumerable contains the specified element. Optionally uses the specified comparer.
count	no	Returns the number of elements in the Enumerable. If a predicate function is specified, only those elements will be counted that satisfy the given condition.
defaultIfEmpty	no	Returns the Enumerable or a new Enumerable containing only the specified default value, should the Enumerable be empty.
distinct	no	Returns a new Enumerable that contains only distinct elements. Optionally uses a specified comparer.
elementAt	no	Returns the element at the specified offset or throws an exception if the index is out of bounds.
elementAtOrDefault	no	Same as elementAt, except it returns the specified defaultValue if the given index is out of bounds. This differs from the LINQ implementation in that the default value needs to be specified explicitly.
empty	yes	Returns an empty Enumerable
except	no	Returns a new Enumerable containing all elements from this Enumerable except those contained in a second Enumerable (i.e. the set difference between two enumerables). Optionally uses the specified comparer.
first	no	Returns the first element in the Enumerable or throws an exception if the Enumerable is empty. If a predicate function is specified, the method returns the first element that satisfies the given condition. If the Enumerable is empty or no element satisfies the specified condition, an exception is thrown.
firstOrDefault	no	Same as first, except it returns a specified defaultValue if the Enumerable is empty or no element satisfies the specified condition. This method is different from its LINQ counterpart in that it requires the default value to be specified explicitly.
groupBy	no	Groups the elements in the Enumerable. Note that this method resolves overloads based on function arity. Result selectors are expected to have two or more formal parameters while element- and key-selectors are expected to have just one.
groupJoin	no	Correlates the elements in two Enumerables based on their keys and groups the results.
intersect	no	Returns a new Enumerable that is the result of the intersection of two Enumerables. Optionally uses the specified comparer.
join	no	Correlates the elements in two Enumerables based on their keys.
last	no	Returns the last element in the Enumerable or throws an exception, if the Enumerable is empty. If a predicate function is specified, the method returns the last element that satisfies the given condition. If no element satisfies the specified condition, an exception is thrown.
lastOrDefault	no	Same as last, except it returns a specified defaultValue if the Enumerable is empty or not element satisfies the specified condition. This method is different from its LINQ counterpart in that it requires the default value to be specified explicitly.
max	no	Returns the maximum value in the Enumerable.
min	no	Returns the minimum value in the Enumerable.
orderBy	no	Sorts the elements in the Enumerable in ascending order.
orderByDescending	no	Sorts the elements in the Enumerable in descending order.
repeat	yes	Returns an Enumerable that contains the specified element "count" times
reverse	no	Reverses the order of the elements in the Enumerable.
select	no	Projects each of the elements in the Enumerable into a new form. This differes from its LINQ counterpart in that the selector function always receives the index of the current element as its second parameter.
selectMany	no	Projects each of the elements in the Enumerable into a new Enumerable and then flattens the result into a single Enumerable again. This differes from its LINQ counterpart in that the collection selector function always receives the index of the current element as its second parameter.
sequenceEqual	no	Returns true if the Enumerable is identical to another Enumerable by comparing the elements using an optional comparer.
single	no	Returns the only element in the Enumerable or throws an exception either if the Enumerable is empty or if there is more than one element in the Enumerable. Optionally tests the returned element against a predicate function and throws an exception if the element does not satisfy its condition.
singleOrDefault	no	Same as single, except that a specified default value is returned if the Enumerable is empty, contains more than one element or if the element does not satisfy the specified condition. This method differs from its LINQ counterpart in that it requires the default value to be specified explicitly.
skip	no	Returns a new Enumerable that is the result of skipping the first "count" elements of the Enumerable.
skipWhile	no	Returns a new Enumerable that is the result of skipping all elements from the beginning of the Enumerable that satisfy a specified condition.
sum	no	Returns the sum of the elements in the Enumerable, optionally using a specified selector.
take	no	Returns a new Enumerable that is the result of extracting the first "count" elements from the Enumerable.
takeWhile	no	Returns a new Enumerable that is the result of extracting all elements from the beginning of the Enumerable that satisfy the specified condition.
toArray	no	Returns an array containg all the elements in Enumerable.
toList	no	Returns a jsinq.List containg all the elements in Enumerable.
toDictionary	no	Returns a jsinq.Dictionary containg all the elements in Enumerable. A key selector is used to determine the key for each element.
toLookup	no	Returns a jsinq.Lookup containg all the elements in Enumerable. A key selector ise used to determine the key for each element.
union	no	Returns a new Enumerable that is the union of two Enumerables. Optionally uses the specified comparer.
where	no	Returns a new Enumerable that contains only the elements of the Enumerable that satisfy the specified condition.
zip	no	Returns a new Enumerable that is the result of merging two Enumerables using a specified result selector.

Please check out the official .NET reference for additional information on how to use these methods: http://msdn.microsoft.com/en-us/library/system.linq.enumerable_members.aspx
Also look at the comments in the source code and of course the examples.

Updated Wiki: Documentation

kaijaeger — Sat, 27 Mar 2010 14:15:44 GMT

JSINQs architecture

JSINQ is split-up into two parts. jsinq.Enumerable is JSINQ's implementation of System.Linq.Enumerable and jsinq.Query is JSINQ's query-expression compiler. This separation was done quite consciously for two reasons: for one, the query-expression compiler is big and you shouldn't have to carry around its weight when you're not actually using it and secondly, the query-expression compiler is in a reather experimental state while the "Enumerable" implementation is actually quite solid.

Get Started

JSINQ in a nutshell

JSINQ Reference

Types

Updated Wiki: Documentation

kaijaeger — Sat, 27 Mar 2010 14:15:31 GMT

JSINQs architecture

Get Started

JSINQ in a nutshell

JSINQ Reference

Types

Updated Wiki: JSINQ in a nutshell

kaijaeger — Sat, 27 Mar 2010 14:14:57 GMT

Including the JSINQ files

<script type="text/javascript" src="jsinq.js"></script>

Writing queries using query-methods

Once you have included the file(s), you can start to write queries against arrays, DOM node lists or your own enumerable objects. An example:

var names = ['Bob', 'Alice', 'Joe', 'Frank', 'Arthur', 'Marcy'];
var enumerable = new jsinq.Enumerable(names);

var namesThatStartWithAnA = enumerable.where(function(name) { 
	return name.charAt(0) == 'A'; 
});

var enumerator = namesThatStartWithAnA.getEnumerator();
while (enumerator.moveNext()) {
	var name = enumerator.current();
	document.write(name + '<br />');
}

There is also a convenient helper-method that makes enumerating over the elements in an enumerable much easier:

namesThatStartWithAnA.each(function(name) {
	document.write(name + '<br />');
});

You can create more complex queries by chaining together multiple query-methods like this:

var result = enumerable.where(function(name) { 
	return name.toLowerCase().indexOf('a') > -1; 
}).orderByDescending(function(name) { 
	return name; 
});

Writing queries using query expressions

Fortunately, chaining together query-methods is not the only way of defining a query in JSINQ. Instead, you can write your queries in a more natural, SQL-like fashion:

var query = new jsinq.Query(' \
	from name in $0 \
	where name.toLowerCase().indexOf("a") > -1 \
	orderby name descending \
	select name \
');

query.setValue(0, enumerable);

var query = new jsinq.Query(' \
	from name in $0 \
	where name.toLowerCase().indexOf("a") > -1 \
	orderby name descending \
	select name \
');

query.setValue(0, enumerable);
var result = query.execute();

The variable "result" now contains the enumerable that is the result of applying our query to the enumerable that we have specified using the "setValue" method.

What's next?

Download JSINQ!
Read the JSINQ reference

Updated Wiki: Home

kaijaeger — Sat, 27 Mar 2010 14:14:31 GMT

JSINQ 1.0 out now!

JSINQ 1.0, the first stable release of JSINQ is available for download right now! It is packed with new features such as

Support for all .NET 3.5 query operators
Experimental support for the .NET 4.0 query operator "zip"
Complete, fully tested implementations of System.Collections.Generic.List and System.Collections.Generic.Dictionary
toList, toDictionary and toLookup now available for jsinq.Enumerable
Still only 23 KB when minified

What is JSINQ?

What does it look like?

Let's say you have an array of customers and an array of orders and you want to assemble a list of top customers, that is a list of customers who have in total ordered more than ten items. With JSINQ, you might write something like this:

var query = new jsinq.Query('\
    from order in $1 \
    group order by order.customerId into g \
    select {customerId: g.getKey(), items: g.sum(function(g) { return g.items; })} \
    into h \
    join customer in $0 on h.customerId equals customer.id \
    where h.items > 10 \
    orderby h.items descending \
    select {lastname: customer.lastname, items: h.items} \
');

query.setValue(0, customers);
query.setValue(1, orders);
var result = query.execute();

Confused? What's with all the backslashes? Please read: JSINQ in a nutshell.

What can I do with JSINQ?

Write arbitrarily complex queries against JavaScript arrays, DOM node lists or your own enumerable types
Find elements in the HTML DOM tree using SQL-like queries
Dynamically create HTML elements from JSON you have received via XMLHttpRequest in a declarative manner
Tinker with XML and turn it into something else
Combine it in interesting ways with the JavaScript-/Ajax-frameworks you are already using
Write less code by exploiting the power of declarative programming
And for the ambitious: write raytracers, monadic parser combinators, etc.

Using JSINQ

JSINQ in a nutshell (new to JSINQ?, read this!)
JSING Documentation
Frequently asked questions

Previous work

JSINQ isn't the first attempt at implementing LINQ in JavaScript. There is also Chris Pietschmann's LINQ to JavaScript (right here on CodePlex), there is jLINQ and then there is this.

Updated Wiki: Documentation

kaijaeger — Sat, 27 Mar 2010 14:13:41 GMT

JSINQs architecture

JSINQ Reference

Types

Updated Wiki: Home

kaijaeger — Sat, 27 Mar 2010 14:11:31 GMT

JSINQ 1.0 out now!

JSINQ 1.0, the first stable release of JSINQ is available for download right now! It is packed with new features such as

Support for all .NET 3.5 query operators
Experimental support for the .NET 4.0 query operator "zip"
Complete, fully tested implementations of System.Collections.Generic.List and System.Collections.Generic.Dictionary
toList, toDictionary and toLookup now available for jsinq.Enumerable
Still only 23 KB when minified

What is JSINQ?

What does it look like?

var query = new jsinq.Query('\
    from order in $1 \
    group order by order.customerId into g \
    select {customerId: g.getKey(), items: g.sum(function(g) { return g.items; })} \
    into h \
    join customer in $0 on h.customerId equals customer.id \
    where h.items > 10 \
    orderby h.items descending \
    select {lastname: customer.lastname, items: h.items} \
');

query.setValue(0, customers);
query.setValue(1, orders);
var result = query.execute();

Confused? What's with all the backslashes? Please read: JSINQ in a nutshell.

What can I do with JSINQ?

Write arbitrarily complex queries against JavaScript arrays, DOM node lists or your own enumerable types
Find elements in the HTML DOM tree using SQL-like queries
Dynamically create HTML elements from JSON you have received via XMLHttpRequest in a declarative manner
Tinker with XML and turn it into something else
Combine it in interesting ways with the JavaScript-/Ajax-frameworks you are already using
Write less code by exploiting the power of declarative programming
And for the ambitious: write raytracers, monadic parser combinators, etc.

Using JSINQ

JSINQ in a nutshell (new to JSINQ?, read this!)
JSINQ reference
Frequently asked questions

Previous work

JSINQ isn't the first attempt at implementing LINQ in JavaScript. There is also Chris Pietschmann's LINQ to JavaScript (right here on CodePlex), there is jLINQ and then there is this.

Updated Wiki: jsinq.List

kaijaeger — Sat, 27 Mar 2010 14:10:42 GMT

jsinq.List

var list = new jsinq.List();
list.add("JSINQ");
list.insert(0, "Hello");
list.removeAt(1);
alert(list.item(0);
list.set(0, "Test");

You can also turn any jsinq.Enumerable into a list by invoking its "toList" method.

Methods

jsinq.List provides the following methods:

Method	Static	Description
add	no	Adds the specified item to the end of the list
item	no	Retrieves the element at the specified index
set	no	Sets the element at the specified index
addRange	no	Adds the elements of the specified collection to the end of the list
asReadOnly	no	Return a read-only list wrapper for the current collection
binarySearch	no	Searches a sorted list for the given element
clear	no	Empties the list
copyTo	no	Copies a range of elements from the list to the specified array
exists	no	Returns a boolean value indicating whether the list contains any elements satisfying the condition defined by the given predicate function
find	no	Returns the first occurrence of an element that satisfies the condition defined by the given predicate
findAll	no	Retrieves all the elements from the list that satisfy the condtion defined by the given predicate
findIndex	no	Returns the index of the first element in the list that satisfies the condition defined by the given predicate
findLast	no	Returns the last occurrence of an element that satisfies the condition defined by the given predicate
findLastIndex	no	Returns the index of the last element in the list that satisfies the condition defined by the given predicate
forEach	no	Performs the specified action for each element in the list
getEnumerator	no	Returns an enumerator that iterates through the list
getRange	no	Extracts a range of elements from the list. The operation performs a shallow copy of the extracted elements, i.e. reference types are not cloned.
indexOf	no	Returns the index of the first occurrence of the specified item in the list or a part thereof
insert	no	Inserts the specified element into the list at the specified position
insertRange	no	Inserts the elements in the specified collection into the list at the specified position
lastIndexOf	no	Returns the index of the last occurrence of the specified item in the list or a part thereof
remove	no	Removes the specified item from the list. Returns a boolean value indicating whether the operation was successful
removeAll	no	Removes all the elements from the list that satisfy the condition defined by the given predicate
removeAt	no	Removes the element at the given index from the list
removeRange	no	Removes a range of elements from the list
reverse	no	Reverses the order of the elements in the list
sort	no	Sorts the elements in the list or a portion thereof
toArray	no	Returns an array containing the elements in the list
toString	no	Returns a string representing the list
isReadOnly	no	Indicates whether this list is read-only
trueForAll	no	Returns true if all elements in the list satisfy the condition defined by the given predicate

Updated Wiki: jsinq.Dictionary

kaijaeger — Sat, 27 Mar 2010 14:09:52 GMT

jsinq.Dictionary

var dictionary = new jsinq.Dictionary();
dictionary.set("Hello", "World");
alert(dictionary.item("Hello")); // alerts "World"
var myKey = { foo: 123 };
dictionary.set(myKey, new Date());
alert(dictionary.containsKey(myKey)); // alerts "true"

You can also turn any jsinq.Enumerable into a dictionary by invoking its "toDictionary" method.

Methods

jsinq.Dictionary provides the following methods:

Method	Static	Description
item	no	Retrieves the value associated with the specified key
set	no	Sets the value associated with the specified key. An existing value associated with the key will be replaced.
count	no	Returns the number of key-value pairs in this dictionary
getComparer	no	Retrieves the comparer associated with this dictionary
add	no	Adds the specified key and value to the dictionary
tryAdd	no	Attempts to add the specified key and value to the dictionary. Returns a boolean value indicating whether the operation was successful.
keys	no	Returns an array containing the keys in this dictionary
values	no	Returns an array containing the values in this dictionary
clear	no	Empties the dictionary
containsKey	no	Returns a boolean value indicating whether the specified key is contained within the dictionary.
containsValue	no	Returns a boolean value indicating whether the specified value is contained within the dictionary
getEnumerator	no	Returns an enumerator that iterates over this dictionary
toArray	no	Returns an array containing the keys and values in this dictionary dictionary. Returns a boolean value indicating whether the operation was successful.
isReadOnly	no	Indicates whether this dictionary is read-only
toString	no	Returns a string representing the dictionary

Updated Wiki: JSINQ reference

kaijaeger — Sat, 27 Mar 2010 13:57:59 GMT

JSINQs architecture

JSINQ Reference

Types

Updated Wiki: jsinq.List

kaijaeger — Sat, 27 Mar 2010 13:57:56 GMT

jsinq.List

var list = new jsinq.List();
list.add("JSINQ");
list.insert(0, "Hello");
list.removeAt(1);
alert(list.item(0);
list.set(0, "Test");

You can also turn any jsinq.Enumerable into a list by invoking its "toList" method.

Methods

jsinq.List provides the following methods:

Method	Static	Description
add	no	Adds the specified item to the end of the list
item	no	Retrieves the element at the specified index
set	no	Sets the element at the specified index
addRange	no	Adds the elements of the specified collection to the end of the list
asReadOnly	no	Return a read-only list wrapper for the current collection
binarySearch	no	Searches a sorted list for the given element
clear	no	Empties the list
copyTo	no	Copies a range of elements from the list to the specified array
exists	no	eturns a boolean value indicating whether the list contains any elements satisfying the condition defined by the given predicate function
find	no	Returns the first occurrence of an element that satisfies the condition defined by the given predicate
findAll	no	etrieves all the elements from the list that satisfy the condtion defined by the given predicate
findIndex	no	Returns the index of the first element in the list that satisfies the condition defined by the given predicate
findLast	no	Returns the last occurrence of an element that satisfies the condition defined by the given predicate
findLastIndex	no	Returns the index of the last element in the list that satisfies the condition defined by the given predicate
forEach	no	Performs the specified action for each element in the list
getEnumerator	no	Returns an enumerator that iterates through the list
getRange	no	Extracts a range of elements from the list. The operation performs a shallow copy of the extracted elements, i.e. reference types are not cloned.
indexOf	no	Returns the index of the first occurrence of the specified item in the list or a part thereof
insert	no	Inserts the specified element into the list at the specified position
insertRange	no	Inserts the elements in the specified collection into the list at the specified position
lastIndexOf	no	Returns the index of the last occurrence of the specified item in the list or a part thereof
remove	no	Removes the specified item from the list. Returns a boolean value indicating whether the operation was successful
removeAll	no	Removes all the elements from the list that satisfy the condition defined by the given predicate
removeAt	no	Removes the element at the given index from the list
removeRange	no	Removes a range of elements from the list
reverse	no	Reverses the order of the elements in the list
sort	no	Sorts the elements in the list or a portion thereof
toArray	no	Returns an array containing the elements in the list
toString	no	Returns a string representing the list
isReadOnly	no	Indicates whether this list is read-only
trueForAll	no	Returns true if all elements in the list satisfy the condition defined by the given predicate

Updated Wiki: jsinq.Query

kaijaeger — Sat, 27 Mar 2010 13:57:36 GMT

jsinq.Query

var query = new jsinq.Query("from customer in $0 where customer.lastname.charAt('0') == 'S' select customer.lastname");

var query = new jsinq.Query("from customer in $0 where customer.lastname.charAt('0') == 'S' select customer.lastname");
query.setValue(0, myCustomers);

var query = new jsinq.Query('from customer in $0 where customer.lastname.charAt('0') == 'S' select customer.lastname');
query.setValue(0, myCustomers);
var filterCustomers = query.execute();

Spanning queries across multiple lines

The most common way of formatting a LINQ query is to put each clause on its own line like this:

from c in customers
join o in orders on c.id equals o.customerId
where o.items > 10
orderby c.lastname
select {lastname: c.lastname, items: o.items}

Unfortunately, JavaScript does not natively support multi-line strings. So you're stuck with writing something like this:

var query = "from c in customers" +
    "join o in orders on c.id equals o.customerId" +
    "where o.items > 10" +
    "orderby c.lastname" +
    "select {lastname: c.lastname, items: o.items}",

Unless you are willing to let language specifications be language specifications and exploit a bug/feature found in pretty much all JavaScript implementations:

var query = "from c in customers \
    join o in orders on c.id equals o.customerId \
    where o.items > 10 \
    orderby c.lastname \
    select {lastname: c.lastname, items: o.items}",

Methods

jsinq.Query provides the following methods:

Method	Static	Description
setValue	no	Binds a specified value to a placeholder
execute	no	Executes the query and returns the result
getQueryFunction	no	Returns the anonymous function that executes the query