Array

These are extensions to JavaScript's Array. See this documentation for all standard Array methods. All of the methods that Rulecube has added return an array leave the original array intact and return a new array.

// To get the sum of the value of every real estate in London, you might use this:
realEstates
   .where(re => re.City === 'London')
   .sum(re => re.Value)

Methods

where

where(predicate: function) 

Filters based on the given predicate and returns the filtered array. Essentially an alias for filter().

Parameters

predicate function

Predicate function for filtering data. This function is called with 3 parameters: value, index and the array itself.

Return type

array

Examples

persons.where(p => p.City === 'London')        // A new array containing only people who live in London
[1,12,300,6000].where(p => p > 100)            // [300, 6000] - filtered based on the value
[1,12,300,6000].where((p, idx) => idx > 1)     // [300, 6000] - filtered based on the index

whereIn

whereIn(predicate?: function, otherList: array) 

Filters the collection based cross-checking every item using the predicate, with another list. Also known as an Intersect.

Parameters

predicate function

(optional) Predicate for selecting the data. This function is called with 3 parameters: value, index and the array itself.

otherList array

The other list to compare with.

Return type

array

Examples

addresses.whereIn(p => p.City, LIST_OF_CAPITALS)     // Result will only contain addresses that are in capital cities
addresses.intersect(p => p.City, LIST_OF_CAPITALS)   // Same as the previous, intersect is an alias for whereIn
addresses.whereIn('City', LIST_OF_CAPITALS)          // Instead of a predicate you can use a property name string
[1,12,300,6000].whereIn(p => p, [299, 300, 301])     // => [300], as only 300 was present in the other list
[1,12,300,6000].whereIn([299, 300, 301])             // Same as the previous, but demonstrates that the predicate can be skipped if
                                                     // the predicate is an identity predicate (p => p)

whereNotIn

whereNotIn(predicate?: function, otherList: array) 

This is the inverse operation of the whereIn. Also known as an Except.

Parameters

predicate function

(optional) Predicate for selecting the data. This function is called with 3 parameters: value, index and the array itself.

otherList array

The other list to compare with.

Return type

array

Examples

addresses.whereNotIn(p => p.City, LIST_OF_CAPITALS)  // Result will only contain addresses that are NOT in capital cities
addresses.except(p => p.City, LIST_OF_CAPITALS)      // Same as the previous, except is an alias for whereNotIn
[1,12,300,6000].whereNotIn(p => p, [299, 300, 301])  // => [1,12,6000], as only 300 was in the other list
[1,12,300,6000].whereNotIn([299, 300, 301])          // Same as the previous, but demonstrates that the predicate can be skipped if
                                                     // the predicate is an identity predicate (a => a)

ofType

ofType(type: Type) 

Filters based on the given type and returns the filtered typed array.

Parameters

type Type

The type to filter by.

Return type

array

Examples

items.ofType(Mortgage)             // A new array containing only items of type 'Mortgage'
[1,12,'hi'].ofType(Number)         // [ 1, 12 ] 
[1,12,'hi'].ofType(String)         // [ 'hi' ] 

map

map(predicate: function) 

Transforms the collection based on the given predicate. Actually one of the Array standard methods, but included here for reference. See also: map().

Parameters

predicate function

Predicate for transforming/mapping the data. This function is called with 3 parameters: value, index and the array itself.

Return type

array

Examples

[2,3,1].map(i => i + 1)                // [3, 4, 2]
[{val:2}, {val:1}].map(i => i.val)     // [2, 1]

orderBy

orderBy(predicate?: function) 

Sorts the collection in an ascending order.

Parameters

predicate function

(optional) Predicate for ordering data. This function is called with 1 parameter: value.

Return type

array

Examples

[2,3,1].orderBy()                                      // => [1, 2, 3]
[{val:2}, {val:1}].orderBy(i => i.val)                 // => [{val: 1}, {val:2}]

orderByDesc

orderByDesc(predicate?: function) 

Sorts the collection in an descending order.

Parameters

predicate function

(optional) Predicate for ordering data. This function is called with 1 parameter: value.

Return type

array

Examples

[2,3,1].orderByDesc()                          // => [3, 2, 1]
[{val:2}, {val:1}].orderByDesc(i => i.val)     // => [{val: 2}, {val:1}]

copy

copy() 

Create a (shallow) copy of the collection. Note: functions the same as .slice().

Parameters

Return type

array

Examples

[1, 2, 3].copy()                          // => [1, 2, 3] - different array, same values

reverse

reverse() 

Reverses the collection. Actually one of the Array standard methods, but included here for reference. See also: reverse(). Note: this changes the order of the array and does not create a copy! Use .copy().reverse() or .reverseCopy() for that instead.

Parameters

Return type

array

Examples

[1,2,3].reverse()                          // => [3, 2, 1]
[{val:2}, {val:1}].reverse()               // => [{val: 1}, {val: 2}]

reverseCopy

reverseCopy() 

Reverses a copy of the collection, leaves the original intact. Note: This is different from the native: reverse().

Parameters

Return type

array

Examples

[1,2,3].reverseCopy()                          // => [3, 2, 1]
[{val:2}, {val:1}].reverseCopy()               // => [{val: 1}, {val: 2}]

take

take(num: number) 

Reduces the collection to the given amount of items from the start.

Parameters

num number

The number of items to take.

Return type

array

Examples

[5, 6, 7, 8, 9].take(3)    // [5, 6, 7]

skip

skip(num: number) 

Reduces the collection by removing the given amount of items.

Parameters

num number

The number of items to skip.

Return type

array

Examples

[5, 6, 7, 8, 9].skip(3)            // [8, 9]
[5, 6, 7, 8, 9].skip(1).take(3)    // [6, 7, 8]

distinct

distinct(predicate?: function) 

Reduces the collection to contain only unique values.

Parameters

predicate function

(optional) Predicate for comparing the data.

Return type

array

Examples

[ 1, 2, 3, 3, 2, 1  ].distinct()                          // [1, 2, 3]
[ 'a', 'A', 'b', 'a'].distinct()                          // ['a', 'A', 'b']
[ 'a', 'A', 'b', 'a'].distinct(s => s.toLowerCase())      // ['a', 'b']
[ {name: 'Joe' }, {name: 'Joe' }].distinct(s => s.name)   // [{ name: 'Joe' }]

groupBy

groupBy(predicate: function) 

Groups the collection based on the given predicate.

Parameters

predicate function

Predicate for grouping the data.

Return type

array

Examples

// Example 1:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd') 
// => [ [ 1, 3 ], [ 2, 4 ] ]

// Example 1b:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd').keys
// => { 'even': [ 2, 4 ], 'odd': [ 1, 3 ] }

// Example 2:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd')   // [ [ 1, 3 ], [ 2, 4 ] ]
            .map(b => b.sum())                            // [ 4, 6 ] - Sommated each sub-collection

// Example 3:
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd')   // [ [ 1, 3 ], [ 2, 4 ] ]
            .map(b => b.key)                              // [ 'odd', 'even' ]

// Example 4: for demonstration purposes, do not use this code block literally in a Ruleset.
// For use in Rulesets, imagine using a rule with the name 'group' having this groupBy expression,
// and every line after that as separate rules.
[1, 2, 3, 4].groupBy(a => a % 2 === 0 ? 'even' : 'odd')   // Same as in Example 1
group[0].key                                              // => 'odd' - the key of the first group
group[1].key                                              // => 'even' - the key of the second group
group[0]                                                  // => [1, 3] - the values of the first group
group[1]                                                  // => [2, 4] - the values of the second group
group.keys['odd']                                         // => [1, 3] - an alternative way to get the data
group.keys['even']                                        // => [2, 4] - an alternative way to get the data

groupMap

groupMap(groupPredicate: function, mapPredicate: function) 

Groups and maps the collection based on the given predicates.

Parameters

groupPredicate function

Predicate for grouping the data.

mapPredicate function

Predicate for transforming/mapping the data.

Return type

array

Examples

[1, 2, 3, 4].groupMap(a => a % 2, b => b.sum())    // [ 4, 6 ] - Group by even/odd numbers and sum the collection

find

find(predicate: function) 

Finds an item in the collection based on the given predicate and returns the first item that matches. Actually one of the Array standard methods, but included here for reference. See also: find().

Parameters

predicate function

Predicate for finding the item. This function is called with 3 parameters: value, index and the array itself.

Return type

any

Examples

[1,12,300,6000].find(p => p > 100)         // => 300
persons.find(p => AGE(p.Birthdate) > 50)   // Finds and returns the first person with an age over 50

findMin

findMin(predicate?: function) 

Returns the item with the lowest-valued numeric value in the collection. A predicate may be used to transform/map the data. Note: This is similar to min() but returns the item instead of the value. See also:

• Array.min

Parameters

predicate function

(optional) Predicate for transforming/mapping the data.

Return type

T

Examples

[2, 1, 3].findMin()                          // => 1
[{val:2}, {val:1}].findMin(i => i.val)       // => {val:1}

// Compared with min():
[{val:2}, {val:1}].min(i => i.val)           // => 1

findMax

findMax(predicate?: function) 

Returns the item with the highest-valued numeric value in the collection. A predicate may be used to transform/map the data. Note: This is similar to max() but returns the item instead of the value. See also:

• Array.max

Parameters

predicate function

(optional) Predicate for transforming/mapping data.

Return type

T

Examples

[2, 3, 1].findMax()                          // => 3
[{val:2}, {val:3}].findMax(i => i.val)       // => { val:3 }

// Compared with max():
[{val:2}, {val:3}].max(i => i.val)           // => 3

first

first(predicate?: function) 

Returns the first item in the collection. When given a predicate, finds and returns the first item that matches, similar to find().

Parameters

predicate function

(optional) Predicate for finding the item. When not provided, this method will return the first item in the collection.

Return type

T

Examples

[1,12,300,6000].first()                    // => 1
[1,12,300,6000].first(p => p > 100)        // => 300
persons.first()                            // Returns the first item in the collection
persons.first(p => AGE(p.Birthdate) > 50)  // Finds and returns the first person with an age over 50

last

last(predicate?: function) 

Returns the last item in the collection. When given a predicate, finds and returns the last item that matches.

Parameters

predicate function

(optional) Predicate for finding the item. When not provided, this method will return the last item in the collection.

Return type

T

Examples

[1,12,300,6000].last()                     // => 6000
[1,12,300,6000].last(p => p < 1000)        // => 300
persons.last()                             // Returns the last person in the collection
persons.last(p => AGE(p.Birthdate) > 50)   // Finds and returns the last person with an age over 50

sum

sum(predicate?: function) 

Computes the sum of the collection based on the given predicate.

Parameters

predicate function

(optional) Predicate for selecting data.

Return type

number

Examples

[1,2,3].sum()                          // => 6
[{val:10}, {val:20}].sum(i => i.val)   // => 30

min

min(predicate?: function) 

Returns the lowest-valued numeric value in the collection. A predicate may be used to transform/map the data. See also:

• Array.findMin

Parameters

predicate function

(optional) Predicate for transforming/mapping the data.

Return type

number

Examples

[2, 1, 3].min()                          // => 1
[{val:2}, {val:1}].min(i => i.val)       // => 1

max

max(predicate?: function) 

Returns the highest-valued numeric value in the collection. A predicate may be used to transform/map the data. See also:

• Array.findMax

Parameters

predicate function

(optional) Predicate for transforming/mapping data.

Return type

number

Examples

[2, 3, 1].max()                          // => 3
[{val:2}, {val:1}].max(i => i.val)       // => 2

avg

avg(predicate?: function) 

Computes the average value of the collection based on the given predicate.

Parameters

predicate function

(optional) Predicate for selecting data.

Return type

number

Examples

[1,2,3].avg()                          // => 2
[{val:10}, {val:20}].avg(i => i.val)   // => 15

any

any(predicate?: function) 

Returns whether any item in the collection matches the given predicate. Essentially an alias for some().

Parameters

predicate function

(optional) Predicate function for evaluating data. This function is called with 3 parameters: value, index and the array itself.

Return type

boolean

Examples

[false, true, false].any()                     // => true
[false, false, false].any()                    // => false
[].any()                                       // => false
[1,2,3].any(i => i > 2)                        // => true - 3 is greater than 2
[1,2,3].any(i => i > 3)                        // => false - nothing in the collection is > 3
[{val:10}, {val:20}].any(i => i.val === 10)    // => true
[1,2,3].any((i, idx) => idx > 2)               // => false - no index higher than 2 exists (index starts at 0)

all

all(predicate?: function) 

Returns whether every item in the collection matches the given predicate. Essentially an alias for every().

Parameters

predicate function

(optional) Predicate for matching data.

Return type

boolean

Examples

[true, true, true].all()                       // => true
[true, false, true].all()                      // => false
[].all()                                       // => true
[1,2,3].all(i => i > 2)                        // => false - not every item is greater than 2
[1,2,3].all(i => i > 0)                        // => true - every item is greater than 3
[{val:10}, {val:20}].all(i => i.val === 10)    // => false

none

none(predicate?: function) 

Returns whether none of the items in the collection matches the given predicate. The inverse of any().

Parameters

predicate function

(optional) Predicate function for evaluating data. This function is called with 3 parameters: value, index and the array itself.

Return type

boolean

Examples

[false, true, false].none()                     // => false
[false, false, false].none()                    // => true
[].none()                                       // => true
[1,2,3].none(i => i > 2)                        // => false - 3 is greater than 2
[1,2,3].none(i => i > 3)                        // => true - nothing in the collection is > 3
[{val:10}, {val:20}].none(i => i.val === 10)    // => false
[1,2,3].none((i, idx) => idx > 2)               // => true - no index higher than 2 exists (index starts at 0)

contains

contains(item: any) 

Returns whether the given item is included in the collection. Essentially an alias for includes().

Parameters

item any

The item to look for in the collection.

Return type

number

Examples

[1,12,300,6000].contains(12)         // => true
[1,12,300,6000].contains(123)        // => false

count

count(predicate?: function) 

Filters the collection based on the given predicate and returns the number of items left.

Parameters

predicate function

(optional) Predicate for filtering data.

Return type

number

Examples

[1,12,300,6000].count()                    // => 4
[1,12,300,6000].count(p => p > 100)        // => 2

to

to(otherType: any) 

Casts collection to a different type. Has no effect during run-time, but helps with autocompletion.

Parameters

otherType any

Type to cast to.

Return type

array

Examples

[0,0,1,0,1].to(Boolean)