@financial-times/dotcom-server-handlebars 7.3.1 → 7.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@financial-times/dotcom-server-handlebars",
-  "version": "7.3.1",
+  "version": "7.3.2",
   "description": "",
   "main": "dist/node/index.js",
   "types": "src/index.ts",
@@ -31,7 +31,8 @@
     "npm": "7.x || 8.x"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "src/"
   ],
   "repository": {
     "type": "git",

package/src/PageKitHandlebars.ts

@@ -0,0 +1,142 @@
+import path from 'path'
+import mixinDeep from 'mixin-deep'
+import Handlebars, { HelperDelegate, TemplateDelegate } from 'handlebars'
+import findPartialFiles from './findPartialFiles'
+import loadFileContents from './loadFileContents'
+import { TRenderCallback, TPartialTemplates, TFilePaths } from './types'
+
+export type TPageKitHandlebarsOptions = {
+  /**
+   * An instance of Handlebars to use.
+   * @default require('handlebars')
+   */
+  handlebars?: typeof Handlebars
+
+  /**
+   * Current working directory.
+   * @default process.cwd()
+   */
+  rootDirectory?: string
+
+  /**
+   * Additional helper functions to register with Handlebars.
+   * @default {}
+   */
+  helpers?: {
+    [key: string]: HelperDelegate
+  }
+
+  /**
+   * Partial templates to register with Handlebars.
+   * @default {}
+   */
+  partials?: TPartialTemplates
+
+  /**
+   * A list of directories and patterns used to dynamically find and load partial template files.
+   * @default { './views/partials': '**\/*.{hbs,html}' }
+   */
+  partialPaths?: TFilePaths
+
+  /**
+   * Enable caching of template files to reduce filesystem I/O
+   * @default process.env.NODE_ENV !== 'development
+   */
+  cache?: boolean
+}
+
+// By default NODE_ENV will be undefined so be explicit
+const nodeEnv = process.env.NODE_ENV || 'development'
+
+const defaultOptions: TPageKitHandlebarsOptions = {
+  cache: nodeEnv !== 'development',
+  rootDirectory: process.cwd(),
+  helpers: {},
+  partials: {},
+  partialPaths: {
+    './views/partials': '**/*.{hbs,html}',
+    './bower_components': '*/{templates,server/templates,components,partials,views}/**/*.{hbs,html}',
+    './node_modules/@financial-times':
+      '*/{templates,server/templates,components,partials,views}/**/*.{hbs,html}'
+  }
+}
+
+export class PageKitHandlebars {
+  public options: TPageKitHandlebarsOptions
+  public engine: this['renderView']
+
+  private cache: Map<string, any> = new Map()
+
+  constructor(userOptions: TPageKitHandlebarsOptions = {}) {
+    this.options = mixinDeep({}, defaultOptions, userOptions)
+
+    // Create a point for Express to mount as a view engine
+    this.engine = this.renderView.bind(this)
+  }
+
+  loadPartials(): TPartialTemplates {
+    let partials: TFilePaths = this.cache.get('__partials__')
+
+    if (partials === undefined) {
+      partials = findPartialFiles(this.options.rootDirectory, this.options.partialPaths)
+
+      if (this.options.cache) {
+        this.cache.set('__partials__', partials)
+      }
+    }
+
+    const templates = {}
+
+    Object.keys(partials).forEach((name) => {
+      const filePath = partials[name]
+      templates[name] = this.loadTemplate(filePath)
+    })
+
+    return templates
+  }
+
+  loadTemplate(filePath: string): TemplateDelegate {
+    if (path.isAbsolute(filePath) === false) {
+      filePath = path.resolve(this.options.rootDirectory, filePath)
+    }
+
+    let template: TemplateDelegate = this.cache.get(filePath)
+
+    if (template === undefined) {
+      const contents = loadFileContents(filePath)
+      const hbs = this.options.handlebars || Handlebars
+
+      template = hbs.compile(contents)
+
+      if (this.options.cache) {
+        this.cache.set(filePath, template)
+      }
+    }
+
+    return template
+  }
+
+  render(template: string | TemplateDelegate, templateContext: any): string {
+    if (typeof template === 'string') {
+      template = this.loadTemplate(template)
+    }
+
+    const html = template(templateContext, {
+      helpers: this.options.helpers,
+      partials: { ...this.options.partials, ...this.loadPartials() }
+    })
+
+    return html.trim()
+  }
+
+  // This method is intended to be mounted by Express and used as a view engine.
+  // <https://expressjs.com/en/guide/using-template-engines.html>
+  renderView(templatePath: string, templateContext: any, callback: TRenderCallback): void {
+    try {
+      const html = this.render(templatePath, templateContext)
+      callback(null, html)
+    } catch (error) {
+      callback(error)
+    }
+  }
+}

package/src/__test__/HandlebarsRenderer.spec.ts

@@ -0,0 +1,99 @@
+import path from 'path'
+import { PageKitHandlebars as Subject } from '../PageKitHandlebars'
+
+// NOTE: Tests are run from the repository root directory so we need to set the CWD
+const root = path.join(__dirname, '__fixtures__')
+const view = path.resolve(root, 'views/view.hbs')
+
+describe('dotcom-server-handlebars/src/PageKitHandlebars', () => {
+  let instance
+
+  beforeEach(() => {
+    instance = new Subject({
+      rootDirectory: root,
+      cache: true
+    })
+  })
+
+  describe('.loadPartials()', () => {
+    let result
+
+    beforeEach(() => {
+      result = instance.loadPartials()
+    })
+
+    it('loads and compiles partial templates from disk', () => {
+      const values = Object.values(result)
+
+      expect(values.length).toBe(3)
+
+      values.forEach((template) => {
+        expect(template).toEqual(expect.any(Function))
+      })
+    })
+
+    it('caches each compiled partial template', () => {
+      const keys = Object.keys(result)
+
+      keys.forEach((key) => {
+        const filename = path.join(root, `views/partials/${key}.hbs`)
+        expect(instance.cache.has(filename)).toBe(true)
+      })
+    })
+  })
+
+  describe('.loadTemplate()', () => {
+    let result
+
+    beforeEach(() => {
+      result = instance.loadTemplate(view)
+    })
+
+    it('loads and compiles a template from disk', () => {
+      expect(result).toEqual(expect.any(Function))
+    })
+
+    it('caches the compiled template', () => {
+      expect(instance.cache.has(view)).toBe(true)
+    })
+  })
+
+  describe('.render()', () => {
+    const templateContext = { title: 'Hello World', aside: 'Lorem ipsum' }
+
+    it('can render a template from disk', () => {
+      const result = instance.render(view, templateContext)
+
+      expect(result).toContain('<h1>Hello World</h1>')
+      expect(result).toContain('<aside>Lorem ipsum</aside>')
+      expect(result).toMatch(/<main>.+<\/main>/s)
+    })
+
+    it('can render a given template function', () => {
+      const template = instance.loadTemplate(view)
+      const result = instance.render(template, templateContext)
+
+      expect(result).toContain('<h1>Hello World</h1>')
+      expect(result).toContain('<aside>Lorem ipsum</aside>')
+      expect(result).toMatch(/<main>.+<\/main>/s)
+    })
+  })
+
+  describe('.renderView()', () => {
+    it('can render a template and fire a callback with the result', () => {
+      return new Promise((done) => {
+        const templateContext = { title: 'Hello World', aside: 'Lorem ipsum' }
+
+        instance.renderView(view, templateContext, (error, result) => {
+          expect(error).toBeNull()
+
+          expect(result).toContain('<h1>Hello World</h1>')
+          expect(result).toContain('<aside>Lorem ipsum</aside>')
+          expect(result).toMatch(/<main>.+<\/main>/s)
+
+          done()
+        })
+      })
+    })
+  })
+})

package/src/__test__/__fixtures__/components/DefaultExportComponentCJS.js

@@ -0,0 +1,5 @@
+const React = require('react')
+
+module.exports = function ({ text }) {
+  return React.createElement('div', null, text)
+}

package/src/__test__/__fixtures__/components/DefaultExportComponentES.tsx

@@ -0,0 +1,5 @@
+import React from 'react'
+
+export default function ({ text }) {
+  return <div>{text}</div>
+}

package/src/__test__/__fixtures__/components/NamedExportComponentCJS.js

@@ -0,0 +1,5 @@
+const React = require('react')
+
+exports.Component = function ({ text }) {
+  return React.createElement('div', null, text)
+}

package/src/__test__/__fixtures__/components/NamedExportComponentES.tsx

@@ -0,0 +1,5 @@
+import React from 'react'
+
+export function Component({ text }) {
+  return <div>{text}</div>
+}

package/src/__test__/__fixtures__/views/partials/content.hbs

@@ -0,0 +1 @@
+<h1>{{title}}</h1>

package/src/__test__/__fixtures__/views/partials/partial.hbs

@@ -0,0 +1 @@
+<aside>{{aside}}</aside>

package/src/__test__/__fixtures__/views/partials/wrapper.hbs

@@ -0,0 +1,3 @@
+<main>
+  {{> @partial-block }}
+</main>

package/src/__test__/__fixtures__/views/view.hbs

@@ -0,0 +1,4 @@
+{{#> wrapper }}
+  {{>content}}
+  {{>partial}}
+{{/wrapper}}

package/src/__test__/helpers.spec.ts

@@ -0,0 +1,341 @@
+import { compile } from 'handlebars'
+import * as helpers from '../helpers'
+
+describe('dotcom-server-handlebars/src/helpers', () => {
+  describe('block helpers', () => {
+    describe('#capture', () => {
+      it('captures the string and assigns it to a variable', () => {
+        const template = compile('{{#capture "myOutput"}}Hello, World!{{/capture}}')
+        const templateData = {} as { [key: string]: any }
+        const result = template(templateData, { helpers })
+
+        expect(templateData.myOutput).toBe('Hello, World!')
+        expect(result).toBe('')
+      })
+    })
+
+    describe('#dateformat', () => {
+      const date = new Date('2019-04-10 13:40:21 GMT+0100 (BST)')
+
+      it('formats as ISO date time by default', () => {
+        const template = compile('{{#dateformat}}{{date}}{{/dateformat}}')
+        const result = template({ date }, { helpers })
+
+        expect(result).toBe('2019-04-10T12:40:21Z')
+      })
+
+      it('formats using the given format', () => {
+        const template = compile('{{#dateformat "dddd, mmmm d, yyyy"}}{{date}}{{/dateformat}}')
+        const result = template({ date }, { helpers })
+
+        expect(result).toBe('Wednesday, April 10, 2019')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#dateformat "" ""}}{{date}}{{/dateformat}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifAll', () => {
+      const template = compile('{{#ifAll foo bar baz}}yes{{else}}no{{/ifAll}}')
+
+      it('outputs the contents when all parameters are truthy', () => {
+        const result = template({ foo: 123, bar: 'abc', baz: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameters are falsy', () => {
+        const result = template({ foo: 123, bar: 'abc', baz: false }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifSome}}yes{{/ifSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifEquals', () => {
+      const template = compile('{{#ifEquals foo bar}}yes{{else}}no{{/ifEquals}}')
+
+      it('outputs the contents parameters are strictly equal', () => {
+        const result = template({ foo: true, bar: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameter is not strictly equal', () => {
+        const result = template({ foo: true, bar: null }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifEquals}}yes{{/ifEquals}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifEqualsSome', () => {
+      const template = compile('{{#ifEqualsSome foo bar baz}}yes{{else}}no{{/ifEqualsSome}}')
+
+      it('outputs the contents if parameters are strictly equal', () => {
+        const result = template({ foo: true, bar: true, baz: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('outputs true if first parameter is equal', () => {
+        const result = template({ foo: true, bar: false, baz: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('outputs true if second parameter is equal', () => {
+        const result = template({ foo: true, bar: true, baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('outputs false if neither parameter is equal', () => {
+        const result = template({ foo: true, bar: false, baz: false }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifEqualsSome}}yes{{/ifEqualsSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifSome', () => {
+      const template = compile('{{#ifSome foo bar baz}}yes{{else}}no{{/ifSome}}')
+
+      it('outputs the contents if at least one parameter is truthy', () => {
+        const result = template({ foo: 123, bar: '', baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if all parameters are falsy', () => {
+        const result = template({ foo: 0, bar: '', baz: false }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifSome}}yes{{/ifSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#renderReactComponent', () => {
+      it('renders the specified component (exported as a default CJS Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/DefaultExportComponentCJS"
+          text="foo"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>foo</div>')
+      })
+
+      it('renders the specified component (exported as a default ES Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/DefaultExportComponentES"
+          text="bar"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>bar</div>')
+      })
+
+      it('renders the specified component (exported as a named CJS Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/NamedExportComponentCJS"
+          namedExport="Component"
+          text="baz"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>baz</div>')
+      })
+
+      it('renders the specified component (exported as a named ES Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/NamedExportComponentES"
+          namedExport="Component"
+          text="qux"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>qux</div>')
+      })
+
+      it('throws if mandatory parameters are not provided', () => {
+        const template = compile('{{{renderReactComponent}}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#resize', () => {
+      it('formats the image as an image service URL', () => {
+        const template = compile('{{#resize 640}}http://website.com/picture.jpg{{/resize}}')
+        const result = template({}, { helpers })
+
+        expect(result).toBe(
+          'https://www.ft.com/__origami/service/image/v2/images/raw/http%3A%2F%2Fwebsite.com%2Fpicture.jpg?width=640&source=next&fit=scale-down'
+        )
+      })
+
+      it('accepts named parameters', () => {
+        const template = compile('{{#resize 640 fit="contain"}}http://website.com/picture.jpg{{/resize}}')
+        const result = template({}, { helpers })
+
+        expect(result).toBe(
+          'https://www.ft.com/__origami/service/image/v2/images/raw/http%3A%2F%2Fwebsite.com%2Fpicture.jpg?width=640&source=next&fit=contain'
+        )
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#resize}}http://website.com/picture.jpg{{/resize}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#slice', () => {
+      it('slices a given array and iterates over the new array', () => {
+        const template = compile('{{#slice items offset="2" limit="3"}}{{this}}{{/slice}}')
+        const result = template({ items: [1, 2, 3, 4, 5, 6] }, { helpers })
+
+        expect(result).toBe('345')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#slice offset="2" limit="3"}}{{this}}{{/slice}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#unlessAll', () => {
+      const template = compile('{{#unlessAll foo bar baz}}yes{{else}}no{{/unlessAll}}')
+
+      it('outputs the contents if all parameters are falsy', () => {
+        const result = template({ foo: 0, bar: '', baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameters are truthy', () => {
+        const result = template({ foo: 0, bar: '', baz: true }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#unlessAll}}yes{{/unlessAll}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#unlessEquals', () => {
+      const template = compile('{{#unlessEquals foo bar}}yes{{else}}no{{/unlessEquals}}')
+
+      it('outputs the contents if all parameters are falsy', () => {
+        const result = template({ foo: true, bar: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameters are truthy', () => {
+        const result = template({ foo: true, bar: true }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#unlessEquals}}yes{{/unlessEquals}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#unlessSome', () => {
+      const template = compile('{{#unlessSome foo bar baz}}yes{{else}}no{{/unlessSome}}')
+
+      it('outputs the contents if any parameters are falsy', () => {
+        const result = template({ foo: 1, bar: 'abc', baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if all parameters are truthy', () => {
+        const result = template({ foo: 1, bar: 'abc', baz: true }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#unlessSome}}yes{{/unlessSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+  })
+
+  describe('inline helpers', () => {
+    describe('array', () => {
+      it('converts all parameters into one array', () => {
+        const template = compile('{{array foo bar baz}}')
+        const result = template({ foo: 1, bar: 2, baz: 3 }, { helpers })
+
+        expect(result).toBe('1,2,3')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{array}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('concat', () => {
+      it('concatenates all parameters into one string', () => {
+        const template = compile('{{concat "Welcome to " place ", " name}}')
+        const result = template({ place: 'Hell', name: 'human' }, { helpers })
+
+        expect(result).toBe('Welcome to Hell, human')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{concat}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('encode', () => {
+      it('encodes the parameter as a URI component', () => {
+        const template = compile('{{{encode title}}}')
+        const result = template({ title: 'http://www.foo.com?bar=baz&qux=«»' }, { helpers })
+
+        expect(result).toBe('http%3A%2F%2Fwww.foo.com%3Fbar%3Dbaz%26qux%3D%C2%AB%C2%BB')
+      })
+
+      it('encodes the parameter as a complete URI', () => {
+        const template = compile('{{{encode title mode="uri"}}}')
+        const result = template({ title: 'http://www.foo.com?bar=baz&qux=«»' }, { helpers })
+
+        expect(result).toBe('http://www.foo.com?bar=baz&qux=%C2%AB%C2%BB')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{encode}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('json', () => {
+      it('stringifies the parameter', () => {
+        const template = compile('{{{json data}}}')
+        const result = template({ data: { foo: 'bar', baz: 123, qux: true } }, { helpers })
+
+        expect(result).toBe('{"foo":"bar","baz":123,"qux":true}')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{json}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+
+      it('throws if the user tries to output the @root context', () => {
+        const template = compile('{{json data}}')
+        expect(() => template({ data: { _locals: true } }, { helpers })).toThrow()
+      })
+    })
+  })
+})

package/src/findPartialFiles.ts

@@ -0,0 +1,25 @@
+import path from 'path'
+import glob from 'glob'
+import { TFilePaths } from './types'
+
+export default function loadPartialFiles(cwd: string, partialPaths: TFilePaths): TFilePaths {
+  const partialFiles = {}
+
+  Object.keys(partialPaths).forEach((partialPath) => {
+    const globPattern = partialPaths[partialPath]
+    const baseDirectory = path.resolve(cwd, partialPath)
+
+    const matchingFiles = glob.sync(globPattern, {
+      cwd: baseDirectory
+    })
+
+    matchingFiles.forEach((file) => {
+      const extension = path.extname(file)
+      const name = file.replace(extension, '')
+
+      partialFiles[name] = path.join(baseDirectory, file)
+    })
+  })
+
+  return partialFiles
+}

package/src/helpers/README.md

@@ -0,0 +1,213 @@
+# Handlebars Helpers
+
+This package contains a suite of helpers to enable the migration of applications from [n-handlebars] to Page Kit. Not every helper provided by n-handlebars has been ported over; any helpers we could not find usage of, are used only within [n-ui], or have dependencies on other Handlebars components have not been included.
+
+[n-ui]: https://github.com/Financial-Times/n-ui/
+[n-handlebars]: https://github.com/Financial-Times/n-handlebars
+
+
+## Usage
+
+When using this package you can import the `helpers` property and provide it as an option when creating a new `PageKitHandlebars` instance. Please note that helpers will not be appended to the global Handlebars instance.
+
+```js
+const { PageKitHandlebars, helpers } = require('@financial-times/dotcom-server-handlebars')
+const renderer = new PageKitHandlebars({ helpers })
+```
+
+Alternatively if you want to use the helpers with an existing Handlebars instance:
+
+```js
+const Handlebars = require('handlebars')
+const { helpers } = require('@financial-times/dotcom-server-handlebars')
+
+Handlebars.registerHelper(helpers)
+```
+
+
+## Block helpers
+
+### capture
+
+Captures the string inside of the opening and closing tags and assigns it to a variable.
+
+Example:
+
+```hbs
+{{#capture "myOutput"}}I am being captured.{{/capture}}
+
+{{myOutput}}
+```
+
+### dateformat
+
+Formats a [date object] using the [dateformat] library. If no format is specified it will default to the `isoUtcDateTime` format.
+
+Example:
+
+```hbs
+{{#dateformat}}{{date}}{{/dateformat}}
+{{#dateformat "fullDate"}}{{ date }}{{/dateformat}}
+{{#dateformat "dddd, d mmmm, yyyy"}}{{ date }}{{/dateformat}}
+```
+
+[date object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
+[dateformat]: https://www.npmjs.com/package/dateformat
+
+### ifAll
+
+Outputs the content if all of the parameters are [truthy].
+
+Example:
+
+```hbs
+{{#ifAll foo bar baz}}All parameters are truthy{{else}}A parameter is falsy{{/ifAll}}
+```
+
+[truthy]: https://developer.mozilla.org/en-US/docs/Glossary/Truthy
+
+### ifEquals
+
+Outputs the content if all of the parameters are [strictly equal]. The first parameter is used as the control and all parameters are tested against it.
+
+Example:
+
+```hbs
+{{#ifEquals foo bar}}Parameters are all equal{{else}}A parameter does not match{{/ifEquals}}
+```
+
+[strictly equal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness
+
+### ifEqualsSome
+
+Outputs the content if some of the parameters are [strictly equal]. The first parameter is used as the control and all parameters are tested against it.
+
+Example:
+
+```hbs
+{{#ifEqualsSome foo bar baz}}Some parameters are all equal{{else}}No parameters match{{/ifEqualsSome}}
+```
+
+### ifSome
+
+Outputs the content if at least one of the parameters is [truthy].
+
+Example:
+
+```hbs
+{{#ifSome foo bar baz}}A parameter is truthy{{else}}All parameters are falsy{{/ifSome}}
+```
+
+### renderReactComponent
+
+Outputs a JSX component specified by its local path (relative to the root of the app consuming `dotcom-server-handlebars`) or the package name of the node module, with specification of a named export if required, as well as any other props.
+
+Example:
+
+```hbs
+{{{renderReactComponent localPath="views/components/ComponentWithHbsOutput" title="This is a React component"}}}
+
+{{{renderReactComponent package="@financial-times/dotcom-ui-header" namedExport="LogoOnly" variant="large-logo"}}}
+```
+
+### resize
+
+Deliver an image via the [Origami Image Service] and resize it to the specified width. Additional named parameters will be appended to the URL query string.
+
+Example:
+
+```hbs
+<img src="{{#resize 640}}{{image}}{{/resize}}" />
+<img src="{{#resize 640 fit="contain"}}{{image}}{{/resize}}" />
+```
+
+[Origami Image Service]: https://www.ft.com/__origami/service/image/v2/
+
+### slice
+
+Iterate over a subset of items. Accepts an `offset` and `limit` parameter.
+
+Example:
+
+```hbs
+{{#slice iterable offset="2"}}{{this}}{{/slice}}
+{{#slice iterable offset="4" limit="2"}}{{this}}{{/slice}}
+```
+
+### unlessAll
+
+Outputs the content if all of the parameters are [falsy].
+
+Example:
+
+```hbs
+{{#unlessAll foo bar baz}}All parameters are falsy{{else}}A parameter is truthy{{/unlessAll}}
+```
+
+[falsy]: https://developer.mozilla.org/en-US/docs/Glossary/Falsy
+
+### unlessEquals
+
+Outputs the content if any parameters are _not_ [strictly equal].
+
+Example:
+
+```hbs
+{{#unlessEquals foo bar}}Parameters are not equal{{else}}All parameters match{{/unlessEquals}}
+```
+
+### unlessSome
+
+Outputs the content if any of the parameters are [falsy].
+
+Example:
+
+```hbs
+{{#unlessSome foo bar baz}}A parameter is falsy{{else}}All parameters are truthy{{/unlessSome}}
+```
+
+
+## Inline helpers
+
+### array
+
+Converts the given parameters into a single array.
+
+Example:
+
+```hbs
+{{array foo bar baz}}
+{{>partial parameter=(array foo bar baz)}}
+```
+
+### concat
+
+Concatenates multiple parameters into a single string.
+
+Example:
+
+```hbs
+{{concat "Welcome to " name}}
+{{>partial parameter=(concat "Welcome to " name)}}
+```
+
+### encode
+
+Encodes a uniform resource identifer (URI) using [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) or [`encodeURI()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI).
+
+Example:
+
+```hbs
+{{encode text}}
+{{encode text mode="uri"}}
+```
+
+### json
+
+JSON stringifies the given parameter. Please note that this will error if you try to output the `@root` context when used in an Express application as this may contain secret information.
+
+Example:
+
+```hbs
+{{{json data}}}
+```

package/src/helpers/array.ts

@@ -0,0 +1,8 @@
+export default function array(...args) {
+  if (args.length < 2) {
+    throw Error('At least one parameter must be provided')
+  }
+
+  // The final parameter will always be an instance of HelperOptions
+  return args.slice(0, -1)
+}

package/src/helpers/capture.ts

@@ -0,0 +1,9 @@
+import { HelperOptions } from 'handlebars'
+
+export default function capture(name: string, options: HelperOptions) {
+  if (this.hasOwnProperty(name)) {
+    throw Error(`Template data property "${name}" has already been declared.`)
+  } else {
+    this[name] = options.fn(this)
+  }
+}

package/src/helpers/concat.ts

@@ -0,0 +1,8 @@
+export default function concat(...args) {
+  if (args.length < 3) {
+    throw Error('At least two parameters must be provided')
+  }
+
+  // The final parameter will always be an intance of HelperOptions
+  return args.slice(0, -1).join('')
+}

package/src/helpers/dateformat.ts

@@ -0,0 +1,13 @@
+import formatter from 'dateformat'
+import { HelperOptions } from 'handlebars'
+
+export default function dateformat(...args) {
+  if (args.length > 2) {
+    throw Error('Incorrect number of parameters provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const format = args[0] || 'isoUtcDateTime'
+
+  return formatter(options.fn(this), format)
+}

package/src/helpers/encode.ts

@@ -0,0 +1,15 @@
+import { HelperOptions } from 'handlebars'
+
+export default function encode(...args) {
+  if (args.length !== 2) {
+    throw Error('Incorrect number of parameters provided')
+  }
+
+  const options = args.pop() as HelperOptions
+
+  if (options.hash.mode === 'uri') {
+    return encodeURI(args[0])
+  } else {
+    return encodeURIComponent(args[0])
+  }
+}

package/src/helpers/ifAll.ts

@@ -0,0 +1,12 @@
+import { HelperOptions } from 'handlebars'
+
+export default function ifAll(...args) {
+  if (args.length < 2) {
+    throw Error('At least one parameter must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const condition = args.every(Boolean)
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers/ifEquals.ts

@@ -0,0 +1,12 @@
+import { HelperOptions } from 'handlebars'
+
+export default function ifEquals(...args) {
+  if (args.length < 3) {
+    throw Error('At least two parameters must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const condition = args.every((item) => item === args[0])
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers/ifEqualsSome.ts

@@ -0,0 +1,13 @@
+import { HelperOptions } from 'handlebars'
+
+export default function ifEqualsSome(...args) {
+  if (args.length < 4) {
+    throw Error('At least three parameters must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const control = args.shift()
+  const condition = args.some((item) => item === control)
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers/ifSome.ts

@@ -0,0 +1,12 @@
+import { HelperOptions } from 'handlebars'
+
+export default function ifSome(...args) {
+  if (args.length < 2) {
+    throw Error('At least one parameter must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const condition = args.some(Boolean)
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers/json.ts

@@ -0,0 +1,16 @@
+export default function json(...args) {
+  if (args.length !== 2) {
+    throw Error('Incorrect number of parameters provided')
+  }
+
+  // The second parameter will always be an instance of HelperOptions
+  const target = args[0]
+
+  // Do not allow users to output the whole @root context
+  // <https://github.com/Financial-Times/n-handlebars/pull/65>
+  if (target && target.hasOwnProperty('_locals')) {
+    throw Error('For security reasons you may not use the JSON helper to output the entire view context')
+  }
+
+  return JSON.stringify(target)
+}

package/src/helpers/renderReactComponent.ts

@@ -0,0 +1,34 @@
+import path from 'path'
+import React from 'react'
+import ReactDOMServer from 'react-dom/server'
+
+export default function renderReactComponent({ hash }) {
+  let modulePath
+
+  if (hash.hasOwnProperty('package')) {
+    // `paths` argument provided to ensure package lookup is made
+    // within context of consuming app rather than dependency.
+    modulePath = require.resolve(hash.package, { paths: [process.cwd()] })
+  }
+
+  if (hash.hasOwnProperty('localPath')) {
+    // localPath is relative to root of app consuming dotcom-server-handlebars.
+    modulePath = path.resolve(hash.localPath)
+  }
+
+  if (!modulePath) {
+    throw new Error('You must specify a "package" or "localPath" argument to load a module')
+  }
+
+  const importedModule = require(modulePath)
+
+  const Component = hash.hasOwnProperty('namedExport')
+    ? importedModule[hash.namedExport]
+    : importedModule.__esModule
+    ? importedModule.default
+    : importedModule
+
+  const props = { ...this, ...hash }
+
+  return ReactDOMServer.renderToStaticMarkup(React.createElement(Component, props))
+}

package/src/helpers/resize.ts

@@ -0,0 +1,20 @@
+import { HelperOptions } from 'handlebars'
+import querystring from 'querystring'
+
+const host = 'https://www.ft.com/__origami/service/image/v2/images/raw'
+
+const defaults = { source: 'next', fit: 'scale-down' }
+
+export default function resize(...args) {
+  if (args.length !== 2) {
+    throw Error('Incorrect number of parameters provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const image = options.fn(this)
+  const width = args[0]
+
+  const query = querystring.stringify({ width, ...defaults, ...options.hash })
+
+  return `${host}/${encodeURIComponent(image)}?${query}`
+}

package/src/helpers/slice.ts

@@ -0,0 +1,22 @@
+import { HelperOptions } from 'handlebars'
+
+export default function slice(...args) {
+  if (args.length !== 2) {
+    throw Error('Incorrect number of parameters provided')
+  }
+
+  const options = args.pop() as HelperOptions
+
+  const offset = parseInt(options.hash.offset, 10) || 0
+  const limit = parseInt(options.hash.limit, 10) || 1
+
+  const slicedItems = Array.from(args[0]).slice(offset, offset + limit)
+
+  let contents = ''
+
+  slicedItems.forEach((item) => {
+    contents += options.fn(item)
+  })
+
+  return contents
+}

package/src/helpers/unlessAll.ts

@@ -0,0 +1,12 @@
+import { HelperOptions } from 'handlebars'
+
+export default function unlessAll(...args) {
+  if (args.length < 2) {
+    throw Error('At least one parameter must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const condition = args.some(Boolean) === false
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers/unlessEquals.ts

@@ -0,0 +1,12 @@
+import { HelperOptions } from 'handlebars'
+
+export default function unlessEquals(...args) {
+  if (args.length < 3) {
+    throw Error('At least two parameters must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const condition = args.every((item) => item === args[0]) === false
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers/unlessSome.ts

@@ -0,0 +1,12 @@
+import { HelperOptions } from 'handlebars'
+
+export default function unlessSome(...args) {
+  if (args.length < 2) {
+    throw Error('At least one parameter must be provided')
+  }
+
+  const options = args.pop() as HelperOptions
+  const condition = args.every(Boolean) === false
+
+  return condition ? options.fn(this) : options.inverse(this)
+}

package/src/helpers.ts

@@ -0,0 +1,16 @@
+export { default as array } from './helpers/array'
+export { default as capture } from './helpers/capture'
+export { default as concat } from './helpers/concat'
+export { default as dateformat } from './helpers/dateformat'
+export { default as encode } from './helpers/encode'
+export { default as ifAll } from './helpers/ifAll'
+export { default as ifEquals } from './helpers/ifEquals'
+export { default as ifEqualsSome } from './helpers/ifEqualsSome'
+export { default as ifSome } from './helpers/ifSome'
+export { default as json } from './helpers/json'
+export { default as renderReactComponent } from './helpers/renderReactComponent'
+export { default as resize } from './helpers/resize'
+export { default as slice } from './helpers/slice'
+export { default as unlessAll } from './helpers/unlessAll'
+export { default as unlessEquals } from './helpers/unlessEquals'
+export { default as unlessSome } from './helpers/unlessSome'

package/src/index.ts

@@ -0,0 +1,3 @@
+import * as helpers from './helpers'
+export * from './PageKitHandlebars'
+export { helpers }

package/src/loadFileContents.ts

@@ -0,0 +1,5 @@
+import fs from 'fs'
+
+export default function loadFileContents(filePath: string): string {
+  return fs.readFileSync(filePath).toString()
+}

package/src/types.d.ts

@@ -0,0 +1,11 @@
+import { TemplateDelegate } from 'handlebars'
+
+export type TRenderCallback = (error?: Error, output?: string) => any
+
+export type TFilePaths = {
+  [key: string]: string
+}
+
+export type TPartialTemplates = {
+  [key: string]: TemplateDelegate
+}