benchpressjs

Benchpress is an ultralight (1.3kb minified + gzipped) and super fast templating framework for Javascript and node.js.

It has express support out-of-the-box, and requires zero client-side dependencies.

Installation

Benchpress is available as an npm module:

npm i benchpressjs

API

The following is a quick rundown of the API. See the full docs

Benchpress uses an ahead of time (AOT) compilation model. It requires that you precompile templates into Javascript modules before using them.

.precompile(source, { filename }): Promise<string>

This method compiles a template source into Javascript code.

const benchpress = require('benchpressjs');
const template = 'My favourite forum software is {forum}. This templating engine is written in {language}.';
benchpress.precompile(template, { filename: "your-file.tpl" }).then((precompiled) => {
  // store it somewhere
});

// precompiled output
(function (factory) {
  if (typeof module === 'object' && module.exports) {
    module.exports = factory();
  } else if (typeof define === 'function' && define.amd) {
    define(factory);
  }
})(function () {
  function compiled(helpers, context, get, iter, helper) {
    return 'My favourite forum software is ' + get(context && context['forum']) + '. This templating engine is written in ' + get(context && context['language']) + '.';
  }

  return compiled;
});

.__express

This method provides an express engine API.

const express = require('express');
const app = express();
const benchpress = require('benchpressjs');

const data = {
  foo: 'bar',
};

app.configure(function() {
  app.engine('jst', benchpress.__express);
  app.set('view engine', 'jst');
  app.set('views', 'path/to/compiled/templates');
});

app.render('myview', data, function(err, html) {
  console.log(html);
});

app.get('/myroute', function(res, req, next) {
  res.render('myview', data);
});

.render(template, data): Promise<string> (alias: .parse(template, data, callback(string)))

This method is used mainly to parse templates on the client-side. To use it, .registerLoader(loader) must be used to set the callback for fetching compiled template modules.

require(['benchpress'], (benchpress) => {
  benchpress.registerLoader((name, callback) => {
    // fetch `name` template module
  });

  benchpress.render('basic', {
    forum: 'NodeBB',
    language: 'Javascript',
  }).then((output) => {
    // do something with output
  });
});

Template Syntax

Sample data, see test cases for more:

{
  "animals": [
    {
      "name": "Cat",
      "species": "Felis silvestris catus",
      "isHuman": false,
    },
    {
      "name": "Dog",
      "species": "Canis lupus familiaris",
      "isHuman": false,
    },
    {
      "name": "Human",
      "species": "Homo sapiens",
      "isHuman": true
    }
  ],
  "package": {
    "name": "benchpressjs",
    "author": "psychobunny",
    "url": "http://www.github.com/benchpressjs/benchpress"
  },
  "website": "http://burnaftercompiling.com",
  "sayHello": true
}

Simple key/value

My blog URL is {website}. The URL for this library is {{package.url}}

Conditionals

{{{ if sayHello }}}
  Hello world!
{{{ end }}}

{{{ if !somethingFalse }}}
  somethingFalse doesn't exist
{{{ end }}}

Benchpress supports several syntaxes for conditionals in order to be backwards compatible with templates.js. <!-- ENDIF abcd -->, <!-- END abcd -->, <!-- ENDIF !foobar -->, and <!-- END --> are all equivalent tokens as far as Benchpress is concerned.

Iteration

Repeat blocks of HTML. The two special keys @first and @last are available as booleans, and the @index, @key, and @value special keys are also available. Benchpress supports iterating over objects, in which case @index will be the current loop number and @key will be the key of the current item. For normal arrays, @key == @index.

{{{ each animals }}}
  {animals.name} is from the species {animals.species}.
  {{{ if !animals.isHuman }}}
    - This could be a pet.
  {{{ end }}}
{{{ end }}}

prints out:

Cat is from the species Felis silvestris catus.
- This could be a pet.
Dog is from the Canis lupus familiaris.
- This could be a pet.
Human is from the species Homo sapiens.

Benchpress supports several syntaxes for iteration in order to be backwards compatible with templates.js:

• <!-- END abcd --> == <!-- END foo --> == <!-- END -->
• <!-- BEGIN abc --> {abc.def} <!-- END --> == <!-- BEGIN abc --> {../def} <!-- END --> which will print the def key of every item in abc.

There is a grey zone where if you wish to print a field of the object you are iterating over, you can't directly. This is a breaking change from templates.js. To fix this, change {abc.def} to {../../abc.def}.

Helpers

Helpers are JavaScript methods for advanced logic in templates. This example shows a really simple example of a function called print_is_human which will render text depending on the current block's data.

benchpress.registerHelper('print_is_human', function (data) {
  return (data.isHuman) ? "Is human" : "Isn't human";
});

{{{ each animals }}}
{print_is_human(@value)}
{{{ end }}}

prints out:

Isn't human
Isn't human
Is human

Testing

npm install
npm test

Projects using Benchpress

NodeBB

Add yours here by submitting a PR :)

Changelog

Version 2.2.0 (2020-11-15)

New: Compiler Rewrite

This release includes a rewrite of the compiler, using the parser combinator library nom.

This rewrite has drastically improved code quality and extensibility. As part of the rewrite, structures include information about source location, so warnings now display file (assuming file name was passed to precompile), line, and column.

Also a performance win: the new compiler is about 4.4 times as fast.

Deprecations

The following features are deprecated, to become errors in v3.0.0:

Keyword outside an interpolation token

You may see a warning like the following:

[benchpress] warning: keyword outside an interpolation token is deprecated
     --> tests/templates/source/loop-tokens-conditional.tpl:4:65
      |
    4 |     <!-- IF @value --> &rarr; <span class="label label-default">@value</span><!-- ENDIF @value -->
      |                                                                 ^^^^^^ help: wrap this in curly braces: `{@value}`
      | note: This will become an error in the v3.0.0

This is a legacy of backwards compatibility with templates.js, where this was supported for @key, @value, and @index.

Mixing token types

You may see a warning like the following:

[benchpress] warning: mixing token types is deprecated
     --> tests/templates/source/mixed-syntax.tpl:20:1
      |
   20 | {{{if rooms.length}}}
      | ^^^^^^^^^^^^^^^^^^^^^ `if` started with modern syntax
     ::: tests/templates/source/mixed-syntax.tpl:34:1
      |
   34 | <!-- ENDIF rooms.length -->
      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ but legacy syntax used for `ENDIF`
      | note: Migrate all to modern syntax. This will become an error in v3.0.0

New Warnings

We added some new warnings to help you avoid common issues:

Output bloat due to ambiguous inner BEGIN

[benchpress] warning: output bloat due to ambiguous inner BEGIN
     --> tests/templates/source/nested-loop.tpl:1:37
      |
    1 | <!-- BEGIN animals -->{animals.name}<!-- BEGIN hobbies -->{animals.hobbies.name}<!-- END hobbies --><!-- END animals -->
      |                                     ^^^^^^^^^^^^^^^^^^^^^^ `hobbies` could refer to the top-level value `hobbies` or 
the `.hobbies` property of the current element, so compiler must emit code for both cases
      | note: Migrate to modern syntax to avoid the ambiguity. This will become an error in the future.

This exists to support backwards compatibility with templates.js, which supported this behavior. Switching to modern syntax will allow you to avoid this ambiguity, resulting in faster templates (and faster compiles).

Extra Tokens

This warning isn't actually new, just improved.

[benchpress] warning: found extra tokens
     --> tests/templates/source/extra-tokens.tpl:17:7 
      |
   17 | </div><!-- END container -->
      |       ^^^^^^^^^^^^^^^^^^^^^^ help: remove the token or make it an unambiguous comment
     --> tests/templates/source/extra-tokens.tpl:25:64 
      |
   25 |         <p class="list-group-item-text">{rooms.description}</p><!-- END description -->
      |                                                                ^^^^^^^^^^^^^^^^^^^^^^^^ help: remove the token or make it an unambiguous comment
     --> tests/templates/source/extra-tokens.tpl:32:66 
      |
   32 |     <p class="list-group-item-text">Click here to create one!</p><!-- END -->
      |                                                                  ^^^^^^^^^^^^ help: remove the token or make it an unambiguous comment
      = note: These tokens will be passed through as text, but this will become an error in the future.

Another legacy of backwards compatibility with templates.js, which would ignore these cases due to how it worked.