array - Documentation

Source:

Extensions/array.js, line 3

the JS native Array class

Methods

clone(a) → {array}

Source:

Extensions/array.js, line 1321

clones an array

Example

eg. usage

var collection = [
  {type: 'a', value: 1}, 
  {type: 'b', value: 8}, 
  {type: 'c', value: 5}, 
  {type: 'd', value: 7}, 
  {type: 'e', value: 9}, 
  {type: 'f', value: 3},
];

var clone = Array.clone(collection); // or var clone = collection.clone();

console.log(collection === clone); // false;

Parameters:

Name	Type	Description
`a`	array	the array

Returns:

Type: array

concat(a, ac) → {array}

Source:

Extensions/array.js, line 58

concatenates two arrays

Example

eg. usage

var arr = ['a', 'e', 'i', 'o', 'u'];

console.log(Array.concat(arr, ['b', 'c', 'd']); // ['a', 'e', 'i', 'o', 'u', 'b', 'c', 'd']
console.log(arr.concat(['b', 'c', 'd']); // ['a', 'e', 'i', 'o', 'u', 'b', 'c', 'd']

Parameters:

Name	Type	Description
`a`	array \| *	the array to be concatenated
`ac`	array \| *	the array to concatenate or the item to concatenate

Returns:

Type: array

contains(a, item, allopt) → {boolean}

Source:

Extensions/array.js, line 28

checks if an Array contains something

Example

eg. usage

var arr = ['a', 'e', 'i', 'o', 'u'];

console.log(Array.contains(arr, 'b')); // false
console.log(Array.contains(arr, 'a')); // true
console.log(Array.contains(arr, ['a', 'b', 'e']); // true
console.log(Array.contains(arr, ['a', 'b', 'e'], true); // false

console.log(arr.contains('b')); // false
console.log(arr.contains('a')); // true
console.log(arr.contains(['a', 'b', 'e']); // true
console.log(arr.contains(['a', 'b', 'e'], true); // false

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array to be checked
`item`	array \| *			can be anything or an array of anything
`all`	boolean	<optional>	`false`	specify to check if the array must contain all items

Returns:

Type: boolean

containsBy(a, propName, propValueopt) → {any|null}

Source:

Extensions/array.js, line 631

checks if an array contains an item by propName/propValue pair or predicate,

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
  {type: 'b', value: 'b-1-1'},
];

console.log(Array.containsBy(collection, 'value', 'a-2-2')); // false
console.log(collection.containsBy('value', 'a-2-2')); // same as above

console.log(Array.containsBy(collection, 'value', 'a-2-1')); // true
console.log(collection.containsBy('value', 'a-2-1')); // same as above

console.log(Array.containsBy(collection, function(item) {
  return item.type === 'c';
})); // true

console.log(collection.containsBy(function(item) {
  return item.type === 'c';
})); // same as above

Parameters:

Name	Type	Attributes	Default
`a`	array
`propName`	string \| function
`propValue`	any	<optional>	`null`

Returns:

Type: any | null

countBy(a, propName, propValueopt, falseValuesopt) → {number}

Source:

Extensions/array.js, line 673

counts items in array that respects propName/propValue pair or predicate,

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
  {type: 'b', value: 'b-1-1'},
];

console.log(Array.countBy(collection, 'type', 'a')); // 4
console.log(collection.countBy('type', 'a')); // same as above

console.log(Array.countBy(collection, 'type', 'a', true)); // 3, it counts false values
console.log(collection.countBy('type', 'a', true)); // same as above

console.log(Array.countBy(collection, function(item) {
  return item.type === 'b';
})); // 2

console.log(collection.countBy(function(item) {
  return item.type === 'b';
})); // same as above

console.log(Array.countBy(collection, function(item) {
  return item.type === 'b';
}, null, true)); // 5, it counts false values

console.log(collection.countBy(function(item) {
  return item.type === 'b';
}, null, true)); // same as above

Parameters:

Name	Type	Attributes	Default
`a`	array
`propName`	string \| function
`propValue`	any \| null	<optional>	`null`
`falseValues`	boolean	<optional>	`false`

Returns:

Type: number

cut(a) → {array}

Source:

Extensions/array.js, line 1300

returns a sliced array with all elements but the last item

Example

eg. usage

var a = [1, 2, 3, 4, 5];

console.log(Array.cut(a)); // [1, 2, 3, 4]
console.log(a.cut()); // same as above

Parameters:

Name	Type	Description
`a`	array	the array

Returns:

Type: array

deepFindBy(a, propName, propValueopt, childrenPropNameopt) → {array}

Source:

Extensions/array.js, line 513

deeply sorts an array

Example

eg. usage

var collection = [
  {type: 'b', value: 'b', items: [
    {type: 'b', value: 'b-1'},
    {type: 'b', value: 'b-5'},
    {type: 'b', value: 'b-2'},
    {type: 'b', value: 'b-4'},
    {type: 'b', value: 'b-3'},
  ]}, 
  {type: 'd', value: 'd'}, 
  {type: 'a', value: 'a', items: [
    {type: 'a', value: 'a-1', items: [
      {type: 'a', value: 'a-1-1'},
      {type: 'a', value: 'a-1-3'},
      {type: 'a', value: 'a-1-2'},
    ]}},
    {type: 'a', value: 'a-5', items: [
      {type: 'a', value: 'a-5-1'},
    ]}},
    {type: 'a', value: 'a-2', items: [
      {type: 'a', value: 'a-2-1'},
      {type: 'a', value: 'a-2-3'},
      {type: 'a', value: 'a-2-2'},
      {type: 'a', value: 'a-2-4'},
    ]}},
    {type: 'a', value: 'a-4', items: [
      {type: 'a', value: 'a-4-1'},
    ]}},
    {type: 'a', value: 'a-3', items: [
      {type: 'a', value: 'a-3-2'},
      {type: 'a', value: 'a-3-1'},
    ]}},
  ]}, 
  {type: 'c', value: 'c', items: []}, 
];

console.log(Array.deepFindBy(collection, 'value', 'a-2-1', 'items')); // {type: 'a', value: 'a-2-1'}
console.log(collection.deepFindBy('value', 'a-2-1', 'items')); // same as above

console.log(Array.deepFindBy(collection, function(item) {
   return item.value.contains('a-2-1');
}, null, 'items')); // {type: 'a', value: 'a-2-1'}

console.log(collection.deepFindBy(function(item) {
   return item.value.contains('a-2-1');
}, null, 'items')); // same as above

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array
`propName`	string \| function			the propName you want to use for the deep find
`propValue`	any	<optional>	`null`	the propValue you want to use for the deep find
`childrenPropName`	string	<optional>	`'children'`	the childrenPropName to be used for the deep find recursion

Returns:

Type: array

deepMap(a, childrenPropNameopt, iteratee)

Source:

Extensions/array.js, line 1102

deeply maps a recursive tree structure with (same structure) childrenPropName or 'children' property

for examples see lodash.deepMap

Parameters:

Name	Type	Attributes	Default	Description
`a`	array \| object			the array to use for the deep mapping
`childrenPropName`	string	<optional>	`'children'`	the property name to use for children collection
`iteratee`	function			the item mapping iteratee

deepSortBy(a, propNames, propDirectionsopt, childrenPropNameopt) → {array}

Source:

Extensions/array.js, line 236

deeply sorts an array

Example

eg. usage

var collection = [
  {type: 'b', value: 'b', items: [
    {type: 'b', value: 'b-1'},
    {type: 'b', value: 'b-5'},
    {type: 'b', value: 'b-2'},
    {type: 'b', value: 'b-4'},
    {type: 'b', value: 'b-3'},
  ]}, 
  {type: 'd', value: 'd'}, 
  {type: 'a', value: 'a', items: [
    {type: 'a', value: 'a-1', items: [
      {type: 'a', value: 'a-1-1'},
      {type: 'a', value: 'a-1-3'},
      {type: 'a', value: 'a-1-2'},
    ]}},
    {type: 'a', value: 'a-5', items: [
      {type: 'a', value: 'a-5-1'},
    ]}},
    {type: 'a', value: 'a-2', items: [
      {type: 'a', value: 'a-2-1'},
      {type: 'a', value: 'a-2-3'},
      {type: 'a', value: 'a-2-2'},
      {type: 'a', value: 'a-2-4'},
    ]}},
    {type: 'a', value: 'a-4', items: [
      {type: 'a', value: 'a-4-1'},
    ]}},
    {type: 'a', value: 'a-3', items: [
      {type: 'a', value: 'a-3-2'},
      {type: 'a', value: 'a-3-1'},
    ]}},
  ]}, 
  {type: 'c', value: 'c', items: []}, 
];

console.log(Array.deepSortBy(collection, ['type', 'value'], ['asc', 'desc'], 'items')); 
// [
//   {type: 'a', value: 'a', items: [
//     {type: 'a', value: 'a-5', items: [
//       {type: 'a', value: 'a-5-1'},
//     ]}},
//     {type: 'a', value: 'a-4', items: [
//       {type: 'a', value: 'a-4-1'},
//     ]}},
//     {type: 'a', value: 'a-3', items: [
//       {type: 'a', value: 'a-3-2'},
//       {type: 'a', value: 'a-3-1'},
//     ]}},
//     {type: 'a', value: 'a-2', items: [
//       {type: 'a', value: 'a-2-4'},
//       {type: 'a', value: 'a-2-3'},
//       {type: 'a', value: 'a-2-2'},
//       {type: 'a', value: 'a-2-1'},
//     ]}},
//     {type: 'a', value: 'a-1', items: [
//       {type: 'a', value: 'a-1-3'},
//       {type: 'a', value: 'a-1-2'},
//       {type: 'a', value: 'a-1-1'},
//     ]}},
//   ]}, 
//   {type: 'b', value: 'b', items: [
//     {type: 'b', value: 'b-5'},
//     {type: 'b', value: 'b-4'},
//     {type: 'b', value: 'b-3'},
//     {type: 'b', value: 'b-2'},
//     {type: 'b', value: 'b-1'},
//   ]}, 
//   {type: 'c', value: 'c', items: []}, 
//   {type: 'd', value: 'd'}, 
// ]

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array to be sorted
`propNames`	array \| string			the propName(s) you want to use for sorting
`propDirections`	array \| string \| null	<optional>	`null`	the propDirection(s) you want to use for sorting (respect propName(s) order)
`childrenPropName`	string	<optional>	`'children'`	the childrenPropName to be used for sorting

Returns:

Type: array

diff(a, b, fnopt) → {array}

Source:

Extensions/array.js, line 101

creates an array of unique array values not included in the other provided arrays

Example

eg. usage

var arr = ['a', 'e', 'i', 'o', 'u'];
var arr2 = ['a', 'b', 'c', 'd', 'e'];

console.log(Array.diff(arr, arr2)); // ['i', 'o', 'u']
console.log(arr.diff(arr2)); // same as above

console.log(Array.diff(arr2, arr)); // ['b', 'c', 'd']
console.log(arr2.diff(arr)); // same as above

var collection = [{id: 1, type: 'a'}, {id: 2, type: 'e'}, {id: 3, type: 'i'}, {id: 4, type: 'o'}, {id: 5, type: 'u'}];
var collection2 = [{id: 1, type: 'a'}, {id: 2, type: 'b'}, {id: 3, type: 'c'}, {id: 4, type: 'd'}, {id: 5, type: 'e'}];

console.log(Array.diff(collection, collection2)); // [{id: 2, type: 'e'}, {id: 3, type: 'i'}, {id: 4, type: 'o'}, {id: 5, type: 'u'}]
console.log(collection.diff(collection2)); // same as above

console.log(Array.diff(collection, collection2, 'type'); // [{id: 3, type: 'i'}, {id: 4, type: 'o'}, {id: 5, type: 'u'}]
console.log(collection.diff(collection2, 'type'); // same as above

console.log(Array.diff(collection, collection2, function(aitem, bitem) {
  return aitem.type === bitem.type;
})); // same as above

console.log(collection.diff(collection2, function(aitem, bitem) {
  return aitem.type === bitem.type;
})); // same as above

Parameters:

Name Type Attributes Default Description

a array the first array to use for the diff

b array the second array to use for the diff

fn

function | string

null

function to use as comparator for the diff or the propname to check for the equality or nothing for standard equality
the function will be invoked with an item from the first array and an item from the second array,
so the function has to look like this

function(aitem, bitem) {}

Properties

Name	Type	Description
`aitem`	object \| any	the item from the first array
`bitem`	object \| any	the item from the second array

Returns:

Type: array

diffBy(a, b, propName) → {array|null}

Source:

Extensions/array.js, line 152

creates an array of unique array values not included in the other provided arrays based on a field equality (aliases Array.diff)

Example

<caption>eg. usage</caption>

Parameters:

Name	Type	Description
`a`	array	the first array to use for the diff
`b`	array	the second array to use for the diff
`propName`	string	the property name to be used in comparator for the diff

Returns:

Type: array | null

distinct(a) → {array}

Source:

Extensions/array.js, line 80

distincts an array

Example

eg. usage

var arr = ['a', 'a', 'e', 'i', 'o', 'u'];

console.log(Array.distinct(arr); // ['a', 'e', 'i', 'o', 'u']
console.log(arr.distinct(]); // ['a', 'e', 'i', 'o', 'u']

Parameters:

Name	Type	Description
`a`	array	the array to be distincted

Returns:

Type: array

each(a, iteratee, reverseopt) → {array}

Source:

Extensions/array.js, line 925

executes an iteratee n times as the array length, the iteratee will be invoked with tree arguments item, index, array

Example

eg. usage

var a = [
  {type: 'a', value: 1},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

Array.each(a, function(item, index) {
  console.log(item.type);
});

// it logs
// 'a'
// 'b'
// 'c'
// 'd'

Array.each(a, function(item, index) {
  console.log(item.type);
}, true);

// it logs
// 'd'
// 'c'
// 'b'
// 'a'

Parameters:

Name	Type	Attributes	Default	Description
`a`	array
`iteratee`	function
`reverse`	boolean	<optional>	`false`	true if you want to do a reverse cycle

Returns:

Type: array

filterBy(a, propName, propValue) → {array}

Source:

Extensions/array.js, line 326

filters an array by propName or predicate

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
];

console.log(Array.filterBy(collection, type, 'a'));
// [
//   {type: 'a', value: 'a'}, 
//   {type: 'a', value: 'a-2-1'}, 
//   {type: 'a', value: 'a-1-3'}, 
//   {type: 'a', value: 'a-1-1'}, 
// ]

console.log(collection.filterBy('type', 'a')); // same as above

console.log(Array.filterBy(collection, function(item) {
  return item.value.contains('1');
}));
// [
//   {type: 'a', value: 'a-2-1'}, 
//   {type: 'a', value: 'a-1-3'}, 
//   {type: 'a', value: 'a-1-1'}, 
// ]

console.log(collection.filterBy(function(item) {
  return item.value.contains('1');
})); // same as above

Parameters:

Name	Type	Description
`a`	array
`propName`	string \| function
`propValue`	any

Returns:

Type: array

findBy(a, propName, propValueopt, reverseopt) → {any|null}

Source:

Extensions/array.js, line 461

finds an item in an array by propName/propValue pair or predicate, returns the first element found respecting the specified predicate

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
];

console.log(Array.findBy(collection, 'type', 'a')); // {type: 'a', value: 'a'} 
console.log(collection.findBy('type', 'a')); // same as above

console.log(Array.findBy(collection, 'type', 'a', true)); // {type: 'a', value: 'a-1-1'} 
console.log(collection.findBy('type', 'a', true)); // same as above

console.log(Array.findBy(collection, function(item, index, collection){
  return item.value.contains('1');
})); // {type: 'a', value: 'a-2-1'} 

console.log(collection.findBy(function(item, index, collection){
  return item.value.contains('1');
})); // same as above

console.log(Array.findBy(collection, function(item, index, collection){
  return item.value.contains('1');
}, true)); // {type: 'a', value: 'a-1-1'} 

console.log(collection.findBy(function(item, index, collection){
  return item.value.contains('1');
}, true)); // same as above

Parameters:

Name	Type	Attributes	Default	Description
`a`	array
`propName`	string \| function
`propValue`	any	<optional>	`null`
`reverse`	boolean	<optional>	`false`	is true specified to search from right to left

Returns:

Type: any | null

first(a, propNameopt, propValueopt) → {any}

Source:

Extensions/array.js, line 970

returns the first item in an array, with optional propName/propValue pair or predicate

Example

eg. usage

var a = [
  {type: 'a', value: 1},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

console.log(Array.first(a)); // {type: 'a', value: 1}
console.log(a.first())); // {type: 'a', value: 1}

var a = [
  {type: 'a', value: 1},
  {type: 'b', value: 1},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

console.log(Array.first(a, 'type', 'b')); // {type: 'b', value: 1}
console.log(a.first('type', 'b'))); // {type: 'b', value: 1}

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array
`propName`	string	<optional>	`null`	optional, combined with propValue filters the array before extracting the first item or you can specify an optional function as predicate to customize the filter
`propValue`	string	<optional>	`null`	optional, combined with propName filters the array before extracting the first item

Returns:

Type: any

flatten(a, deepopt) → {array}

Source:

Extensions/array.js, line 1164

flattens array a single level deep,
or with deep parameter (true boolean) recursively flattens array,
or with deep parameter (number) you specify the recursion depth

Example

eg. usage

var a = [1, [2, [3, [4]], 5]];

console.log(Array.flatten(a)); // [1, 2, [3, [4]], 5]
console.log(Array.flatten(a, 1)); // same as above
console.log(a.flatten()); // same as above
console.log(a.flatten(1)); // same as above

console.log(Array.flatten(a, true)); // [1, 2, 3, 4, 5]
console.log(a.flatten(true)); // same as above

console.log(Array.flatten(a, 2)); // [1, 2, 3, [4], 5]
console.log(a.flatten(2)); // same as above

console.log(Array.flatten(a, 3)); // [1, 2, 3, 4, 5]
console.log(a.flatten(3)); // same as above

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array
`deep`	boolean \| number	<optional>	`false`	the deep (boolean) or depth (number) parameter specifies to do a full recursion or the recursion depth

Returns:

Type: array

indexBy(a, propName, propValueopt, reverseopt) → {any|null}

Source:

Extensions/array.js, line 579

finds the index of an item in an array by propName/propValue pair or predicate, returns the first element found respecting the specified predicate

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
];

console.log(Array.indexBy(collection, 'type', 'a')); // 0
console.log(collection.indexBy('type', 'a')); // same as above

console.log(Array.indexBy(collection, 'type', 'a', true)); // 4
console.log(collection.indexBy('type', 'a', true)); // same as above

console.log(Array.indexBy(collection, function(item, index, collection){
  return item.value.contains('1');
})); // 1

console.log(collection.indexBy(function(item, index, collection){
  return item.value.contains('1');
})); // same as above

console.log(Array.indexBy(collection, function(item, index, collection){
  return item.value.contains('1');
}, true)); // 4

console.log(collection.indexBy(function(item, index, collection){
  return item.value.contains('1');
}, true)); // same as above

Parameters:

Name	Type	Attributes	Default	Description
`a`	array
`propName`	string \| function
`propValue`	any	<optional>	`null`
`reverse`	boolean	<optional>	`false`	is true specified to search from right to left

Returns:

Type: any | null

intersection(a, …arrays) → {any|null}

Source:

Extensions/array.js, line 724

returns a new array with the intersection of passed arrays

Example

eg. usage

var a = [1, 2, 3, 4, 5];
var b = [1, 4, 5, 7, 8];

console.log(Array.intersection(a, b)); // [1, 4, 5]
console.log(a.intersection(b)); // same as above

var a = [
  {type: 1, value: 1},
  {type: 1, value: 2},
  {type: 2, value: 1},
  {type: 2, value: 2},
  {type: 3, value: 1},
];

var b = [
  {type: 1, value: 1},
  {type: 2, value: 1},
  {type: 2, value: 3},
  {type: 3, value: 2},
  {type: 4, value: 1},
  {type: 5, value: 1},
];

console.log(Array.intersection(a, b));
// [
//   {type: 1, value: 1},
//   {type: 2, value: 1},
// ]

console.log(a.intersection(b)); // same as above

var c = [
  {type: 1, value: 1},
  {type: 1, value: 2},
  {type: 2, value: 4},
];

console.log(Array.intersection(a, b, c));
// [
//   {type: 1, value: 1},
// ]

console.log(a.intersection(b, c)); // same as above

Parameters:

Name	Type	Attributes	Description
`a`	array
`arrays`	array	<repeatable>

Returns:

Type: any | null

isArray(a) → {boolean}

Source:

Extensions/array.js, line 9

checks if something is an array

Example

eg. usage

var a = new Array();

console.log(Array.isArray(a)); // true<br>
console.log(Array.isArray(2)); // false<br>
console.log(Array.isArray([])); // true<br>
console.log(Array.isArray(null)); // false

Parameters:

Name	Type	Description
`a`	array	the array to be checked

Returns:

Type: boolean

last(a, propNameopt, propValueopt) → {any}

Source:

Extensions/array.js, line 1010

returns the last item in an array, with optional propName/propValue pair or predicate

Example

eg. usage

var a = [
  {type: 'a', value: 1},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

console.log(Array.last(a)); // {type: 'd', value: 4}
console.log(a.last())); // {type: 'd', value: 4}

var a = [
  {type: 'a', value: 1},
  {type: 'a', value: 2},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

console.log(Array.last(a, 'type', 'a')); // {type: 'a', value: 2}
console.log(a.last('type', 'a'))); // {type: 'a', value: 2}

Parameters:

Name	Type	Attributes	Default	Description
`a`	array
`propName`	string \| function	<optional>	`null`	optional, combined with propValue filters the array before extracting the last item or you can specify an optional function as predicate to customize the filter
`propValue`	string	<optional>	`null`	optional, combined with propName filters the array before extracting the last item

Returns:

Type: any

lorem(items, modelopt) → {array}

Source:

Extensions/array.js, line 1119

loremizes an array

Example

eg. usage

console.log(Array.lorem(5)); // [1, 2, 3, 4, 5];

console.log(Array.lorem(5, 1)); // [1, 1, 1, 1, 1];

console.log(Array.lorem(5, '1')); // ['1', '1', '1', '1', '1'];

console.log(Array.lorem(5, {type: 'a', value: 1})); 
// it logs
[
  {type: 'a', value: 1}, 
  {type: 'a', value: 1}, 
  {type: 'a', value: 1}, 
  {type: 'a', value: 1}, 
  {type: 'a', value: 1} 
];

console.log(Array.lorem(5, function(index) {
  return {
    type: 'a',
    value: index,
  };
});
// it logs
[
  {type: 'a', value: 1}, 
  {type: 'a', value: 2}, 
  {type: 'a', value: 3}, 
  {type: 'a', value: 4}, 
  {type: 'a', value: 5} 
];

Parameters:

Name	Type	Attributes	Default	Description
`items`	number
`model`	function \| object	<optional>	`false`

Returns:

Type: array

maxBy(a, propNameopt) → {object}

Source:

Extensions/array.js, line 1350

finds max value by propName in a collection array

Example

eg. usage

var collection = [
  {type: 'a', value: 1}, 
  {type: 'b', value: 8}, 
  {type: 'c', value: 5}, 
  {type: 'd', value: 7}, 
  {type: 'e', value: 9}, 
  {type: 'f', value: 3},
];

console.log(Array.maxBy(a, 'value')); // {type:'e', value: 9}
console.log(Array.maxBy(a, 'type')); // {type:'f', value: 3}

console.log(a.maxBy('value')); // {type:'e', value: 9}
console.log(a.maxBy('type')); // {type:'f', value: 3}

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array to check for max value
`propName`	string	<optional>	`null`	the property name to use for comparation

Returns:

Type: object

pull(a, any) → {array}

Source:

Extensions/array.js, line 376

removes an item from an array

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
];

console.log(Array.pull(collection, {type: 'a', value: 'a'}));
// [
//   {type: 'a', value: 'a-2-1'}, 
//   {type: 'a', value: 'a-1-3'}, 
//   {type: 'c', value: 'c'}, 
//   {type: 'a', value: 'a-1-1'}, 
//   {type: 'b', value: 'b'},
// ]

console.log(collection.pull({type: 'a', value: 'a'})); // same as above

Parameters:

Name	Type	Description
`a`	array
`any`	any

Returns:

Type: array

pullBy(a, propName, propValue) → {array}

Source:

Extensions/array.js, line 413

removes an item from an array by propName/propValue pair or predicate

Example

eg. usage

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
];

console.log(Array.pullBy(collection, 'type', 'a'));
// [
//   {type: 'c', value: 'c'}, 
//   {type: 'b', value: 'b'},
// ]

console.log(collection.pullBy('type', 'a')); // same as above

console.log(Array.pullBy(collection, function(item) {
  return item.value.contains('1');
}));
// [
//   {type: 'a', value: 'a'}, 
//   {type: 'c', value: 'c'}, 
//   {type: 'b', value: 'b'},
// ]

console.log(collection.pullBy(function(item) {
  return item.value.contains('1');
})); // same as above

Parameters:

Name	Type	Description
`a`	array
`propName`	string \| function
`propValue`	any

Returns:

Type: array

random(a, weightFieldopt, valueFieldopt) → {any|null}

Source:

Extensions/array.js, line 879

randomizes an item from an array, with optional weight parameters

Example

eg. usage

var a = [1, 2, 3, 4, 5];

console.log(Array.random(a)); // eg. 3
console.log(a.random()); // same as above

var a = [
  {type: 'a', value: 1},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

console.log(Array.random(a)); // eg. {type: 'a', value: 1}
console.log(a.random()); // same as above

var a = [
  {type: 'a', value: 1, weight: 3},
  {type: 'b', value: 2, weight: 5},
  {type: 'c', value: 3, weight: 1},
  {type: 'd', value: 4, weight: 1},
];

console.log(Array.random(a, 'weight')); // eg. {type: 'b', value: 2}
console.log(a.random('weight')); // same as above

console.log(Array.random(a, 'weight', 'value')); // eg. 2
console.log(a.random('weight', 'value')); // same as above

Parameters:

Name	Type	Attributes	Default
`a`	array
`weightField`	string	<optional>	`null`
`valueField`	string	<optional>	`null`

Returns:

Type: any | null

removeBy(a, propName, propValueopt) → {array}

Source:

Extensions/array.js, line 861

Parameters:

Name	Type	Attributes	Default
`a`	array
`propName`	string \| function
`propValue`	any	<optional>	`null`

Returns:

Type: array

shuffle(a) → {array}

Source:

Extensions/array.js, line 1198

creates an array of shuffled values, using a version of the Fisher-Yates shuffle. (from lodash documentation)

Example

eg. usage

var a = [1, 2, 3, 4, 5];

console.log(Array.shuffle(a)); // [4, 3, 5, 1, 2]
console.log(a.shuffle()); // same as above (or another randomization ;-)

Parameters:

Name	Type	Description
`a`	array	the array

Returns:

Type: array

sortBy(a, propNames, propDirectionsopt) → {array}

Source:

Extensions/array.js, line 171

sorts an array

Example

eg. usage

var collection = [
  {id: 1, type: 'a'}, 
  {id: 3, type: 'i'}, 
  {id: 5, type: 'u'}, 
  {id: 4, type: 'o'}, 
  {id: 2, type: 'e'}
];

console.log(Array.sortBy(collection, 'type')); // [{id: 1, type: 'a'}, {id: 2, type: 'e'}, {id: 3, type: 'i'}, {id: 4, type: 'o'}, {id: 5, type: 'u'}] 
console.log(collection.sortBy('type')); // same as above

console.log(Array.sortBy(collection, 'id', 'desc')); // [{id: 5, type: 'u'}, {id: 4, type: 'o'}, {id: 3, type: 'i'}, {id: 2, type: 'e'}, {id: 1, type: 'a'}] 
console.log(collection.softBy('id', 'desc')); // same as above

var collection = [
  {type: 'a', value: 'a'}, 
  {type: 'a', value: 'a-2-1'}, 
  {type: 'a', value: 'a-1-3'}, 
  {type: 'c', value: 'c'}, 
  {type: 'a', value: 'a-1-1'}, 
  {type: 'b', value: 'b'},
];

console.log(Array.sortBy(collection, ['type', 'value'])); 
// [
//   {type: 'a', value: 'a'}, 
//   {type: 'a', value: 'a-1-1'}, 
//   {type: 'a', value: 'a-1-3'}, 
//   {type: 'a', value: 'a-2-1'}, 
//   {type: 'b', value: 'b'},
//   {type: 'c', value: 'c'}, 
// ];

console.log(collection.sortBy(['type', 'value'])); // same as above

console.log(Array.sortBy(collection, ['type', 'value'], ['asc', 'desc'])); 
// [
//   {type: 'a', value: 'a'}, 
//   {type: 'a', value: 'a-2-1'}, 
//   {type: 'a', value: 'a-1-3'}, 
//   {type: 'a', value: 'a-1-1'}, 
//   {type: 'b', value: 'b'},
//   {type: 'c', value: 'c'}, 
// ];

console.log(collection.sortBy(['type', 'value'], ['asc', 'desc'])); // same as above

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array to be sorted
`propNames`	array \| string			the propName(s) you want to use for sorting
`propDirections`	array \| string \| null	<optional>	`null`	the propDirection(s) you want to use for sorting (respect propName(s) order)

Returns:

Type: array

split(a, nopt) → {array}

Source:

Extensions/array.js, line 1219

splits an array in n-pieces chunks

Example

eg. usage

var a = [1, 2, 3, 4, 5];

console.log(Array.split(a)); // []
console.log(a.split()); // same as above

console.log(Array.split(a, 1)); // [[1], [2], [3], [4], [5]]
console.log(a.split(1)); // same as above

console.log(Array.split(a, 2)); // [[1, 2], [3, 4], [5]]
console.log(a.split(2)); // same as above

console.log(Array.split(a, 3)); // [[1, 2, 3], [4, 5]]
console.log(a.split(3)); // same as above

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array
`n`	number	<optional>	`0`	the n pieces of chunks you want

Returns:

Type: array

sum(a, predicate, startValueopt) → {any}

Source:

Extensions/array.js, line 1050

sums a collection by predicate or propName

Example

eg. usage

var a = [
  {type: 'a', value: 1},
  {type: 'b', value: 2},
  {type: 'c', value: 3},
  {type: 'd', value: 4},
];

console.log(Array.sum(a, 'value', 0)); // 4 + 3 + 2 + 1 = 10
console.log(a.sum('value', 0))); // same as above

console.log(Array.sum(a, 'type', '')); // abcd
console.log(a.sum('type', ''))); // same as above

console.log(Array.sum(a, function(acc, item) {
  return acc + item.value;
}, 0)); // 4 + 3 + 2 + 1 = 10

console.log(a.sum(function(acc, item) {
  return acc + item.value;
}, 0)); // same as above

Parameters:

Name Type Attributes Default Description

a array

predicate

function | string

the predicate should look like this in ES5

function(acc, item) {
  return acc + item[propName];
}

or in ES6

(acc, item) => {
  return acc + item[propName];
}

this kind of predicate will be implemented automatically if you specify a propName instead the predicate

Properties

Name	Type	Description
`acc`	object \| any	the accumulator variable used for the sum
`item`	object \| any	the iterating item

startValue any <optional> 0

Returns:

Type: any

tail(a, cloneopt) → {array}

Source:

Extensions/array.js, line 1250

reverses an array, with optional clone parameter to avoid original array mutation

Example

eg. usage

var a = [1, 2, 3, 4, 5];

console.log(Array.reverse(a)); // [5, 4, 3, 2, 1]
console.log(a.reverse()); // same as above

console.log(a === [5, 4, 3, 2, 1]); // true

var b = Array.reverse(a, true); // or var b = a.reverse(true);

console.log(a); // [1, 2, 3, 4, 5]
console.log(b); // [5, 4, 3, 2, 1]

Parameters:

Name	Type	Attributes	Default	Description
`a`	array			the array
`clone`	boolean	<optional>	`false`

Returns:

Type: array

tail(a) → {array}

Source:

Extensions/array.js, line 1279

returns a sliced array with all elements but the first item

Example

eg. usage

var a = [1, 2, 3, 4, 5];

console.log(Array.tail(a)); // [2, 3, 4, 5]
console.log(a.tail()); // same as above

Parameters:

Name	Type	Description
`a`	array	the array

Returns:

Type: array

union(a, …arrays) → {any|null}

Source:

Extensions/array.js, line 786

returns a new array with the union of passed arrays

Example

eg. usage

var a = [1, 2, 3, 4, 5];
var b = [1, 4, 5, 7, 8];

console.log(Array.union(a, b)); // [1, 2, 3, 4, 5, 7, 8]
console.log(a.union(b)); // same as above

var a = [
  {type: 1, value: 1},
  {type: 1, value: 2},
  {type: 2, value: 1},
  {type: 2, value: 2},
  {type: 3, value: 1},
];

var b = [
  {type: 1, value: 1},
  {type: 2, value: 1},
  {type: 2, value: 3},
  {type: 3, value: 2},
  {type: 4, value: 1},
  {type: 5, value: 1},
];

console.log(Array.union(a, b));
// [
//   {type: 1, value: 1},
//   {type: 1, value: 2},
//   {type: 2, value: 1},
//   {type: 2, value: 2},
//   {type: 3, value: 1},
//   {type: 2, value: 3},
//   {type: 4, value: 1},
//   {type: 5, value: 1},
// ]

console.log(a.union(b)); // same as above

var c = [
  {type: 1, value: 1},
  {type: 1, value: 2},
  {type: 2, value: 4},
];

console.log(Array.union(a, b, c));
// [
//   {type: 1, value: 1},
//   {type: 1, value: 2},
//   {type: 2, value: 1},
//   {type: 2, value: 2},
//   {type: 3, value: 1},
//   {type: 2, value: 3},
//   {type: 4, value: 1},
//   {type: 5, value: 1},
//   {type: 2, value: 4},
// ]

console.log(a.union(b, c)); // same as above

Parameters:

Name	Type	Attributes	Description
`a`	array
`arrays`	array	<repeatable>

Returns:

Type: any | null