query-js

1.2.0 • Public • Published

Query-js is a module, that adds sequence operations to javascript. It's inspired by the operations available in LINQ, but is not meant as a port. The methods are generally evaluating lazily when possible.

aggregate

Aggregate is what is also known as a left fold. It applies a function to the element one at a time and passes the result onto the next iteration. If you do not provide a seed undefined is used as seed

Example

var arr = [1,2,3,4,5],
    //will be (0)+1+2+3+4+5 aka 15
    sum = arr.aggregate(function (sum, elem) { return sum + elem; }, 0);

all

Test wheter all elements in a sequence satisfies the given predicate. To be more precise it tests whether there are no elements that doesn't satisfy the predicate (See last example) Example

var arr = [1,2,3,4,5],
    willBeFalse = arr.all(function(e){return e < 5;}),
    willBeTrue = arr.all(function(e){return e < 6;});
    willAlsoBeTrue = [].all(function(e){return false;});

any

Test wheter any elements in a sequence satisfies the given predicate Example

var arr = [2,4,6],
    willBeFalse = arr.any(function(e){return e % 2 !== 0;}),
    willBeTrue = arr.any(function(e){return e === 4;});

any

Computes the aevrage of the elements in the sequence Example

     //will be 4
 var avg = [2,4,6].average();
     //wil also be 4
     avg = [{value : 2},{value : 4},{value : 6}].average(function(e){return e.value;});

count

Returns the count of elements in the sequence

Example

var arr=[1,2,3],
    //there's three numbers in the sequence
    willBeThree = arr.count(),
    //but only two of the numbers are odd
    willBeTwo = arr.count(function(e){return e % 2;});

current

Returns the current element in the sequence. Should generally not be used and might very well be removed from the API in a future release

distinct

Filters out all duplicates, if no comparer is passed then a simple comparison is used. If custom comparison is required a compare can be passed Example

//will be an array [1,2,3,4,5]
var res = [1,1,2,2,3,3,4,4,5,5].distinct();
res = [{index : 1, value : 4}, {index : 4, value : 4},{index : 2, value : 3}].distinct(function(a,b){ return a.index === b.index });

each

Is very similar to select but instead of returning a lazily evaluated sequence it's evaluated upfront and returned in an array Example

   var seq = Sequence([1,2,3,4,5]).where(function(e){return e % 2;}),
       //[1,3,5]
       arr = seq.each();
       //[1,9,25]
       arr = seq.each(function(e){return e * e;});

first

Returns the first element of the sequence or if a predicate is provided the first element that meets the criteria if no elements can be found it will throw an exception (See firstOrDefault if this is not warrented)

Example

    var arr = [2,3,4];
         //simply get the list element in the sequence
         willBeTwo = arr.first();
         //get the first element, that satisfy the predicate
         willBeThree = arr.first(function(e){ return e % 2; });

firstOrDefault

Like first but instead of throwing if no elements are found will return a default value. null is returned as default but a specific value can be passed as a paramter

Example

   var //will be null
       defaultValue = [].firstOrDefault();
       //will be 4
       defaultValueSpecified = [].firstOrDefault(4);
       //With predicate
       defaultValueSpecified = [2,4,6,8].firstOrDefault(function(e){return e % 2;},4);

groupBy

groupBy groups the sequence based on a key for each element. The result can be treated like any other JS object or you can chain additional query operators to the result, treating it as a sequence of key-value pairs Yopu can pass a second function which can be use to project the value of the element into a new element Example

   var arr = [{name:"John", age:"Middel"}, 
              {name:"Peter", age:"young"}, 
              {name:"Jack", age:"Old"},
              {name:"Christine", age:"young"},
              {name."Juliet", age : "Middel"}];
       //{
       //  "Middel" : [{name:"John", age:"Middel"},{name."Juliet", age : "Middel"}],
       //  "young"  : [{name:"Peter", age:"young"},{name:"Christine", age:"young"}],
       //  "Old"    : [{name:"Jack", age:"Old"}]
       //}
       ageGroups = arr.groupBy(function(e){return e.age;})

iterate

Iterate does exactly want the name implies. It iterates over the sequence of elements. Passing each element to the function as a parameter.

Example

   // prints 1 2 3 to the console
   [1,2,3].iterates(console.log);

last

Pick the last element of a sequence. If a predicate is specified, the last element that satisfy the predicate is returned. It will throw if the sequence is empty. If that's not warrented then use lastOrDefault instead

Example

   var arr = [1,2,3,4];
       //simply get the last element of the sequence
       willBeFour = arr.last();
       //get the last element that satisfy the predicate
       wiilBeThree = arr.last(function(e){ return e % 2;});

lastOrDefault

Works like last except that it will return a default value if there are no elements in the sequence that satisfy the predicate

Example

   var arr = [1,2,3,4];
       //simply get the last element of the sequence
       willBeFour = arr.last();
       //get the last element that satisfy the predicate
       wiilBeThree = arr.last(function(e){ return e % 2;});

max

Returns the maximal value of the sequence. The method accepts a function as the only argument. If a projection is provided the elements will be projected before compared Example

var arr = [{index : 1, value 4},{index : 2, value : 3}];
    //will be {index : 1, value 4}
    max = arr.max(function(e){return e.value;});
    //will be 5
    max = [1,3,5,4,2].max();

min

Returns the minimal value of the sequence. The method accepts a function for projection of the elements, as the only argument. If a projection is provided the elements will be projected before compared Example

var arr = [{index : 1, value 4},{index : 2, value : 3}];
    //will be {index : 2, value 3}
    min = arr.min(function(e){return e.value;});
    //will be 1
    max = [1,3,5,4,2].min();

next

Move the iteration to the next ele in the sequence. This is meant for internal use and should generally not be used

orderBy

orderBy sorts the sequence of elements. If no projection is provided then simple comparison of the individual elements is used. Example

   var arr = [1,4,2,5,3],
       //will be [1,2,3,4,5]
       res = arr.orderBy()
       //will be [{index:0,count: 4},{index : 1, count : 3},{index : 2, count : 2}]
       res = [{index:1,count: 3},{index : 0, count : 4},{index : 2, count : 2}].orderBy(function(e){return e.index;});

product

Will take the product of all the elements Example

   var arr [1,2,3,4,5]
       //will be 120 (1*2*3*4*5)
       res = arr.product();
       //will also be 120
       res = [{value : 1},{value : 2},{value : 3},{value : 4},{value : 5}].product(function(e){return e.value;});

reset

Will restart the iteration of the sequence. Is meant for internal use an should generally not be used

reverse

Reverses the sequence Example

   var arr = [1,2,3,4],
       //will be [4,3,2,1]
       res = arr.reverse();

select

This method lets you project the elements of sequence into a sequence of new values Example

   var arr = [{value : 1},{value : 2},{value : 3},{value : 4},{value : 5}],
       //will be [1,2,3,4,5]
       res = arr.select(function(e){return e.value;})

single

Works pretty much the same way as first. However if more than one elements are present it will throw an exception. To be able to know whether or not multiple elements satifying the predicate are present it will have to iterate the entire collection

Example

var arr = [1,2,3];
    //will fail because multiple valid elements exists
    error = arr.single();
    //will return because only one element satisfy the predicate
    willBeTwo = arr.single(function(e){return e % 2 === 0;});

singleOrDefault

Where single works similar to first. This works similar to firstOrDefault. If no elements are present it will return a default value. Just like single, if multiple elements are present an exception will be thrown

Example

 var arr = [1,2,3];
    //will fail because multiple valid elements exists
    error = arr.singleOrDefault();
    //will return because only one element satisfy the predicate
    willBeTwo = arr.singleOrDefault(function(e){return e % 2 === 0;});
    //will return null because no default are specified
    willBeNull = arr.singleOrDefault(function(e){ return e > 3;});
    //will return null because no default are specified
    willReturnTheDefaultOfFour = arr.singleOrDefault(function(e){ return e > 3;},4);

skip

Skip a number of elements Example

    var arr = [1,2,3,4,5],
        //we be [2,3,4,5]
        res = arr.skip(1).each();

sum

Sums up the elements of the sequence Example

    var arr = [1,2,3,4,5]
        //will be 15
        res = arr.sum();
        //will also be 15
        res = [{value : 1},{value : 2},{value : 3},{value : 4},{value : 5}].sum(function(e){return e.value;});

take

Takes a number of elements

Example

    var arr = [1,2,3,4,5],
        //will be [1,2,3]
        res = arr.take(3).each();

where

Takes elements from the sequence as long as the predicate is satisfied Example

    var arr = [1,2,3,4,5],
        //will be [1,3,5]
        res = arr.where(function(e){ return e < 4; });

where

Filters the sequence based on a predicate Example

    var arr = [1,2,3,4,5],
        //will be [1,3,5]
        res = arr.where(function(e){ return e % 2; });

Package Sidebar

Install

npm i query-js

Weekly Downloads

0

Version

1.2.0

License

ISC

Last publish

Collaborators

  • runefs