hbl-arrays

A helper for Handlebars that adds array manipulation. Meant to supercede helpers/handlebars-helpers' array helpers.

This is not a drop-in replacement for the following helpers :

• {{ before arr 1 }}
• {{ join arr }} (usage with a separator, that is to say {{ join arr "-" }}, is drop-in)
• {{# withBefore arr 1 }}

These helpers are/were broken in the original package. The documented usage (within the JSDoc) were different from the actual (and tested for) results. If you would rather not use the documented methods, you will need to still use helpers/handlebars-helpers or a different helper package.

const Handlebars = require('handlebars');
require('hbl-arrays').default(Handlebars);

const tpl = Handlebars.compile('{{before x 2}}');
console.log(tpl({x: ['a', 'b', 'c']})) // result : 'a,b'

Get all items in array arr after index index.

Usage : {{ after ['a', 'b', 'c'] 2 }}

Result : c

Casts a value val as an array.

Usage : {{ arrayify "foo" }}

Result : foo,bar,12

Get all items in array arr before index index.

Usage : {{ before ['a', 'b', 'c'] 2 }}

Result : a

Usage : {{#eachIndex ['a', 'b', 'c', 'd']}}{{item}} is {{index}}<br>{{/eachIndex}}

Result : a is 0<br>b is 1<br>c is 2<br>d is 3<br>

Check if an array val or string val is of length len. Aliased as {{lengthEqual}}

Usage : {{ equalsLength "val" 3 }}

Result : true

Usage : {{#filter ['a', 'b', 'c'] "a"}}AAA{{else}}BBB{{/filter}}

Result : AAA

Get first item in an array arr.

Usage : {{ first ['a', 'b', 'c'] }}

Result : a

Get first X items from an array arr.

Usage : {{ first ['a', 'b', 'c'] 2 }}

Result : a,b

Iterate over an array. Exposes :

• index — the iterator's index
• total — the total items within the iterator (length of the array)
• isFirst — if the curent item is the first in the array
• isLast — if the current item is the last in the array

Usage : {{#forEach [{name: 'a'}, {name: 'b'}]}}{{name}}{{/forEach}}

Result : ab

Check if a value val is within an array arr.

Usage : {{#inArray ['a', 'b', 'c'] "a"}}foo{{else}}bar{{/inArray}}

Result : foo

Get the item at index within an array arr.

Usage : {{ itemAt ['a', 'b', 'c'] 2 }}

Result : c

Join an array arr into a string.

Usage : {{ join ['a', 'b', 'c'] }}

Result : a,b,c

Join an array arr into a string, seperating each item with str.

Usage : {{ join ['a', 'b', 'c'] '*' }}

Result : a*b*c

Get last item in an array arr.

Usage : {{ last ['a', 'b', 'c'] }}

Result : c

Get last X items in an array arr.

Usage : {{ last ['a', 'b', 'c'] 2 }}

Result : b,c

Get the length of a value val.

Usage : {{ length {'a': 'a', 'b': 'b'} }}

Result : 2

Check if an array val or string val is of length len. Aliased as {{lengthEqual}}

Usage : {{ equalsLength "val" 3 }}

Result : true

Create an array by calling a function fn on each element of an array arr.

Usage :

const tpl = Handlebars.compile('{{ map arr double }}');
tpl({
      arr: ['a', 2, 'c'],
      double: function (v) { return v+v; } 
});

Result : aa,4,cc

Create an array by mapping over an array arr of objects and plucking prop from each object.

Usage : {{ pluck [{a: 'x'}, {a: 'y'}, {a: 'z'}] "a" }}

Result : x,y,z

Reverse the elements within an array arr.

Usage : {{ reverse ['a', 'b', 'c', 'd'] }}

Result : d,c,b,a

Reverese a string str.

Usage : {{ reverse 'abcd' }}

Result : dcba

Checks if any item within an array arr returns true for a function fn.

Usage :

const tpl = Handlebars.compile('{{#some val isString}}yay{{else}}nay{{/some}}');
tpl({
  val: ['wow', 1, ['wow']],
  isString: function(v) { return typeof v === 'string'; }
});

Result : yay

Sorts an array arr. You can reverse sort using {{ sort arr reverse=true }}.

Usage : {{ sort ['b', 'a', 'c'] reverse=true }}

Result : c,b,a

Sorts an array arr using a function fn.

Usage :

const tpl = Handlebars.compile('{{ sortBy arr compare }}');
tpl({
  arr: ['b', 'a', 'c'],
  compare: function(a,b) { return b.localeCompare(a, 'en', { sensitivity: 'base' }); }
})

Result : c,b,a

Sorts an array arr (of objects) based on a property prop.

Usage : {{{ stringify (sortBy [{a: 'zzz'}, {a: 'aaa'}] "a") 0 }}}

Result : [{"a":"aaa"},{"a":"zzz"}]

Get the first item of an array arr and use within a block.

Usage : {{#withFirst ['a', 'b', 'c']}}{{this}} is first{{/withFirst}}

Result : a is first

Get first X items of an array arr and use within a block.

Usage : {{#withFirst ['a', 'b', 'c'] 2 }}{{this}}{{/withFirst}}

Result : ab

Get all items before index index of an array arr and use within a block.

Usage : {{#withBefore ['a', 'b', 'c'] 2}}{{this}} is first{{/withBefore}}

Result : a

Split an array arr into arrays of size size and use within a block.

Usage : {{#withGroup ['a','b','c','d','e','f','g','h'] 4}}{{#each this}}{{.}}<br>{{/each}}{{/withGroup}}

Result : a,b,c,d<br>e,f,g,h<br>

Get all items after index index of an array arr and use within a block.

Usage : {{#withAfter ['a', 'b', 'c'] 2}}{{this}}{{/withAfter}}

Result : bc

Get last item of an array arr and use within a block.

Usage : {{#withLast ['a', 'b', 'c' }}{{this}}{{/withLast}}

Result : c

Get last X items of an array arr and use within a block.

Usage : {{#withLast ['a', 'b', 'c'] 2}}{{this}} is last<br>{{/withLast}}

Result : b is last<br>c is last<br>

Sort an array arr and use it within a block. You can reverse sort using {{# withSort arr prop reverse=true }}.

Usage : {{#withSort ['b', 'a', 'c'] reverse="true"}}{{this}}{{/withSort}}

Result : cba

Sort an array arr of objects based on a property prop and use it within a block. You can reverse sort using {{# withSort arr prop reverse=true }}.

Usage : {{#withSort arr "name" reverse="true"}}{{name}}<br>{{/withSort}}

• arr is defined as :

  arr: [
      {name: 'esbuild'},
      {name: 'expect'},
      {name: 'handlebars'},
      {name: 'hbl-object'}
    ]

Result : hbl-object<br>handlebars<br>expect<br>esbuild<br>

Remove all duplicate values from an array arr.

Usage : {{ unique ['a', 'a', 'c', 'b', 'e', 'e'] }}

Result : a,c,b,e

This package is licensed under the 3-Clause BSD licence. A copy of it can be found in the LICENSE file in the root of the source repository and in the root of the package directory.