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.

Usage

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'

Package documentation

{{ after arr index }}

Get all items in array arr after index index.

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

Result : c

{{ arrayify val }}

Casts a value val as an array.

Usage : {{ arrayify "foo" }}

Result : foo,bar,12

{{ before arr index }}

Get all items in array arr before index index.

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

Result : a

{{# eachIndex arr }}

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>

{{ equalsLength val len }}

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

Usage : {{ equalsLength "val" 3 }}

Result : true

{{# filter arr val }}

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

Result : AAA

{{ first arr }}

Get first item in an array arr.

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

Result : a

{{ first arr X }}

Get first X items from an array arr.

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

Result : a,b

{{# forEach arr }}

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

{{#inArray arr val }}

Check if a value val is within an array arr.

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

Result : foo

{{ itemAt arr index }}

Get the item at index within an array arr.

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

Result : c

{{ join arr }}

Join an array arr into a string.

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

Result : a,b,c

{{ join arr sep }}

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

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

Result : a*b*c

{{ last arr }}

Get last item in an array arr.

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

Result : c

{{ last arr X }}

Get last X items in an array arr.

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

Result : b,c

{{ length val }}

Get the length of a value val.

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

Result : 2

{{ lengthEqual val len }}

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

Usage : {{ equalsLength "val" 3 }}

Result : true

{{ map arr fn }}

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

{{ pluck arr prop }}

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 arr }}

Reverse the elements within an array arr.

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

Result : d,c,b,a

{{ reverse str }}

Reverese a string str.

Usage : {{ reverse 'abcd' }}

Result : dcba

{{#some arr fn }}

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

{{ sort arr }}

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

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

Result : c,b,a

{{ sortBy arr fn }}

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

{{ sortBy arr prop }}

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"}]

{{# withFirst arr }}

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

{{# withFirst arr x }}

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

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

Result : ab

{{# withBefore arr index }}

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

{{# withGroup arr size }}

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>

{{# withAfter arr index }}

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

{{# withLast arr }}

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

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

Result : c

{{# withLast arr X }}

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>

{{# withSort arr }}

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

{{# withSort arr prop }}

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>

{{ unique arr }}

Remove all duplicate values from an array arr.

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

Result : a,c,b,e

Acknowledgements

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.