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

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@financial-times/dotcom-server-handlebars",
-  "version": "7.2.7",
+  "version": "7.3.1",
   "description": "",
   "main": "dist/node/index.js",
   "types": "src/index.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "tsc": "../../node_modules/.bin/tsc --incremental",
     "clean": "npm run clean:dist && npm run clean:node_modules",
     "clean:dist": "rm -rf dist",
     "clean:node_modules": "rm -rf node_modules",
-    "build:node": "npm run tsc -- --module commonjs --outDir ./dist/node",
+    "build:node": "tsc",
     "build": "npm run build:node",
     "dev": "npm run build:node -- --watch",
     "preinstall": "[ \"$INIT_CWD\" != \"$PWD\" ] || npm_config_yes=true npx check-engine"
@@ -31,6 +30,9 @@
     "node": ">= 14.0.0",
     "npm": "7.x || 8.x"
   },
+  "files": [
+    "dist/"
+  ],
   "repository": {
     "type": "git",
     "repository": "https://github.com/Financial-Times/dotcom-page-kit.git",
@@ -43,4 +45,4 @@
   "devDependencies": {
     "check-engine": "^1.10.1"
   }
-}
+}

package/src/PageKitHandlebars.ts

@@ -1,142 +0,0 @@
-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/findPartialFiles.ts

@@ -1,25 +0,0 @@
-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

@@ -1,213 +0,0 @@
-# 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

@@ -1,8 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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'