amphora-html 6.0.0 → 7.0.0

package/README.md

@@ -5,6 +5,8 @@ The HTML renderer for Clay components that use [Handlebars](http://handlebarsjs.
 ## Install
 `$ npm install --save amphora-html`
 
+Requires Node 26.12.1 or later. Templates are rendered with [clayhandlebars](https://github.com/clay/handlebars) 6, which comes with amphora-html: you don't need to install it or Handlebars yourself.
+
 ## The Why
 
 HTML rendering was controlled entirely by [Amphora](https://github.com/nymag/amphora) in v2.x, which meant that Amphora was responsible for a lot of heavy lifting. Furthermore, rendering was handled by a module called [Multiplex Templates](https://www.npmjs.com/package/multiplex-templates) which did some :crystal_ball: dark magic :sparkles: to synchronously render component templates. This required some affordances from Amphora which added to the weight of the middleware. By separating renderers out into separate modules which can be plugged into Amphora >v2.x we can create renderers for specific requirements (XML, Amp, etc.) _and_ the rendering process can be moved to separate machines to create more maintainable systems.
@@ -45,6 +47,21 @@ const helpers = {
 amphoraHtml.addHelpers(helpers);
 ```
 
+### The Handlebars environment
+
+`amphoraHtml.handlebars` is the Handlebars environment amphora-html renders with: clayhandlebars' helpers and partials, the helpers given to `addHelpers`, and a partial for every component and layout (registered when amphora-html is first required). `amphoraHtml.wrapPartial(name, template)` is what each component and layout template is wrapped in before it is registered.
+
+Use them when you compile templates outside of a page render, in a test for instance, so that they run with exactly the helpers the pages get, instead of requiring your own copy of clayhandlebars:
+
+```javascript
+const { handlebars, wrapPartial } = require('amphora-html');
+
+handlebars.registerPartial('my-partial', handlebars.compile(wrapPartial('my-partial', source), { preventIndent: true }));
+const html = handlebars.compile(template, { preventIndent: true })(data);
+```
+
+It is the `handlebars` module that clayhandlebars requires, so whatever you register on it is seen by the pages too.
+
 ### Amphora HTML Plugins
 
 

package/index.js

@@ -9,3 +9,5 @@ module.exports.addResolveMedia = setup.addResolveMedia;
 module.exports.addHelpers = setup.addHelpers;
 module.exports.addPlugins = setup.addPlugins;
 module.exports.configureRender = setup.configureRender;
+module.exports.handlebars = setup.handlebars;
+module.exports.wrapPartial = setup.wrapPartial;

package/lib/clone-deep.js

@@ -0,0 +1,181 @@
+'use strict';
+
+const { types } = require('util'),
+  { isObject, assignValue } = require('./utils'),
+  toString = Object.prototype.toString,
+  // what gets copied; anything else (functions, errors, promises, weak maps...)
+  // stays the same object, or becomes {} when it is the value given
+  CLONEABLE = new Set([
+    '[object Arguments]', '[object Array]', '[object ArrayBuffer]', '[object Boolean]',
+    '[object DataView]', '[object Date]', '[object Float32Array]', '[object Float64Array]',
+    '[object Int8Array]', '[object Int16Array]', '[object Int32Array]', '[object Map]',
+    '[object Number]', '[object Object]', '[object RegExp]', '[object Set]', '[object String]',
+    '[object Symbol]', '[object Uint8Array]', '[object Uint8ClampedArray]', '[object Uint16Array]',
+    '[object Uint32Array]'
+  ]);
+
+/**
+ * @param {ArrayBuffer} buffer
+ * @returns {ArrayBuffer}
+ */
+function cloneArrayBuffer(buffer) {
+  const result = new buffer.constructor(buffer.byteLength);
+
+  new Uint8Array(result).set(new Uint8Array(buffer));
+  return result;
+}
+
+/**
+ * An empty object of the same kind, for the kinds that are not plain objects or arrays
+ *
+ * @param {Object} value
+ * @param {string} tag
+ * @returns {Object}
+ */
+function initCloneByTag(value, tag) { // eslint-disable-line complexity
+  const Ctor = value.constructor;
+
+  switch (tag) {
+    case '[object ArrayBuffer]':
+      return cloneArrayBuffer(value);
+    case '[object Boolean]':
+    case '[object Date]':
+      return new Ctor(+value);
+    case '[object DataView]':
+      return new Ctor(cloneArrayBuffer(value.buffer), value.byteOffset, value.byteLength);
+    case '[object Number]':
+    case '[object String]':
+      return new Ctor(value);
+    case '[object RegExp]': {
+      const result = new Ctor(value.source, /\w*$/.exec(value));
+
+      result.lastIndex = value.lastIndex;
+      return result;
+    }
+    case '[object Map]':
+    case '[object Set]':
+      return new Ctor();
+    case '[object Symbol]':
+      return Object(Symbol.prototype.valueOf.call(value));
+    default:
+      // typed arrays
+      return new Ctor(cloneArrayBuffer(value.buffer), value.byteOffset, value.length);
+  }
+}
+
+/**
+ * An empty object with the prototype of `value`, unless `value` is a prototype
+ * itself or its constructor is not a function
+ *
+ * @param {Object} value
+ * @returns {Object}
+ */
+function initCloneObject(value) {
+  const Ctor = value.constructor,
+    proto = Object.getPrototypeOf(value),
+    isPrototype = value === (typeof Ctor === 'function' && Ctor.prototype || Object.prototype);
+
+  return typeof Ctor === 'function' && !isPrototype && isObject(proto) ? Object.create(proto) : {};
+}
+
+/**
+ * An array of the same kind and length, with what RegExp#exec adds to its results
+ *
+ * @param {Array} array
+ * @returns {Array}
+ */
+function initCloneArray(array) {
+  const result = new array.constructor(array.length);
+
+  if (array.length && typeof array[0] === 'string' && Object.hasOwn(array, 'index')) {
+    result.index = array.index;
+    result.input = array.input;
+  }
+
+  return result;
+}
+
+/**
+ * Own enumerable keys, symbols included
+ *
+ * @param {Object} value
+ * @returns {Array}
+ */
+function ownKeys(value) {
+  return Object.keys(value).concat(Object.getOwnPropertySymbols(value).filter((symbol) => Object.prototype.propertyIsEnumerable.call(value, symbol)));
+}
+
+/**
+ * @param {*} value
+ * @param {Object} [parent]  the object `value` was read from
+ * @param {Map} copies  the copy of every object copied so far
+ * @returns {*}
+ */
+function baseClone(value, parent, copies) { // eslint-disable-line complexity
+  if (!isObject(value)) {
+    return value;
+  }
+
+  const isArray = Array.isArray(value);
+  let result;
+
+  if (isArray) {
+    result = initCloneArray(value);
+  } else {
+    const tag = toString.call(value),
+      isFunction = tag === '[object Function]' || tag === '[object GeneratorFunction]';
+
+    if (Buffer.isBuffer(value)) {
+      // a view of the same memory, as lodash's cloneDeep gave
+      return value.subarray();
+    }
+
+    if (tag === '[object Object]' || tag === '[object Arguments]' || isFunction && !parent) {
+      result = isFunction ? {} : initCloneObject(value);
+    } else if (CLONEABLE.has(tag)) {
+      result = initCloneByTag(value, tag);
+    } else {
+      return parent ? value : {};
+    }
+  }
+
+  // an object met before (shared or circular) gets the same copy
+  if (copies.has(value)) {
+    return copies.get(value);
+  }
+  copies.set(value, result);
+
+  if (types.isSet(value)) {
+    value.forEach((item) => result.add(baseClone(item, value, copies)));
+  } else if (types.isMap(value)) {
+    value.forEach((item, key) => result.set(key, baseClone(item, value, copies)));
+  }
+
+  if (isArray) {
+    // every index, holes included
+    for (let index = 0; index < value.length; index++) {
+      assignValue(result, index, baseClone(value[index], value, copies));
+    }
+  } else {
+    for (const key of ownKeys(value)) {
+      assignValue(result, key, baseClone(value[key], value, copies));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * A deep copy, made the way lodash's cloneDeep made it: objects keep their
+ * prototype, a shared or circular object is copied once, Dates, RegExps, Maps,
+ * Sets, typed arrays and boxed values are copied, and functions, errors and
+ * other objects that can't be copied are kept as they are.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function cloneDeep(value) {
+  return baseClone(value, undefined, new Map());
+}
+
+module.exports = cloneDeep;

package/lib/files.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// What the renderer asks the file system. Every answer is remembered for the
+// life of the process, as with nymag-fs: a file added later is not seen, and
+// each file is read once.
+
+const fs = require('fs'),
+  path = require('path'),
+  { memoize } = require('./utils');
+
+/**
+ * @param {string} filename
+ * @returns {boolean}
+ */
+function fileExists(filename) {
+  try {
+    return !!fs.statSync(filename);
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * @param {string} file
+ * @returns {boolean}
+ */
+function isDirectory(file) {
+  try {
+    return fs.statSync(file).isDirectory();
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * The files of a folder, without folders, tests and documentation
+ *
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function getFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .filter((file) => !isDirectory(path.join(dir, file)) &&
+        file.indexOf('.test.') === -1 && // ignore test files
+        file.indexOf('.md') === -1); // ignore documentation files
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * The contents of a file
+ *
+ * @param {string} file
+ * @returns {Promise<string>}
+ */
+function readFilePromise(file) {
+  return new Promise((resolve, reject) => {
+    fs.readFile(file, 'utf8', (err, data) => err ? reject(err) : resolve(data));
+  });
+}
+
+module.exports.fileExists = memoize(fileExists);
+module.exports.getFiles = memoize(getFiles);
+module.exports.readFilePromise = memoize(readFilePromise);

package/lib/media.js

@@ -1,11 +1,10 @@
 'use strict';
 
-const _ = require('lodash'),
-  path = require('path'),
-  files = require('nymag-fs'),
-  bluebird = require('bluebird'),
+const path = require('path'),
+  files = require('./files'),
   setup = require('./setup'),
   styleguide = require('./styleguide'),
+  { isObject, toList } = require('./utils'),
   STYLE_TAG = 'style',
   SCRIPT_TAG = 'scripts',
   MODULE_SCRIPT_TAG = 'module',
@@ -164,7 +163,7 @@ function injectTags(fileArray, tag) {
   // Defaults to false so existing deployments are unaffected.
   var moduleBuster = module.exports.omitCacheBusterOnModules ? '' : buster;
 
-  return bluebird.resolve(_.map(fileArray, function (file) {
+  return Promise.resolve(toList(fileArray).map(function (file) {
     if (tag === STYLE_TAG) {
       return `<link rel="stylesheet" type="text/css" href="${file}${buster}">`;
     } else if (tag === MODULE_SCRIPT_TAG) {
@@ -180,6 +179,19 @@ function injectTags(fileArray, tag) {
   }).join('\n'));
 }
 
+/**
+ * Wait for the values of an object, the way Bluebird's props did
+ *
+ * @param {Object} obj  values or promises for them
+ * @returns {Promise<Object>}  the same keys with the values
+ */
+function props(obj) {
+  const keys = Object.keys(obj);
+
+  return Promise.all(keys.map((key) => obj[key]))
+    .then((values) => Object.fromEntries(keys.map((key, i) => [key, values[i]])));
+}
+
 /**
  * Gets a list of all css and js needed for the components listed.
  * @param {Object} state
@@ -206,7 +218,7 @@ function getStyleFiles(state) {
     assetPath = site && site.assetPath || '',
     assetHost = site && site.assetHost || '',
     siteStyleguide = site && site.styleguide,
-    layoutName = _.get(state, '_layoutData.name');
+    layoutName = state._layoutData?.name;
   let cssFilePaths = [], layoutBasePath;
 
   // legacy behavior: load <component>.css and <component>.<site>.css
@@ -331,7 +343,7 @@ function pathJoin(assetHost, assetPath, assetDir) {
  * @param {string} [cacheBuster]
  */
 function configure(options, cacheBuster = '') {
-  if (options && _.isObject(options)) {
+  if (options && isObject(options)) {
     module.exports.editStylesTags = options.styles || false;
     module.exports.editScriptsTags = options.scripts || false;
     // modulepreload: when true, <link rel="modulepreload"> hints are injected
@@ -366,7 +378,7 @@ function injectScriptsAndStyles(state) {
   const { locals } = state;
 
   return function (html) {
-    var mediaMap = {};
+    var mediaMap;
 
     // Check that HTML is string
     if (typeof html !== 'string') {
@@ -387,7 +399,7 @@ function injectScriptsAndStyles(state) {
 
     mediaMap.moduleScripts = moduleScriptFiles.length
       ? injectTags(moduleScriptFiles, MODULE_SCRIPT_TAG)
-      : bluebird.resolve(false);
+      : Promise.resolve(false);
 
     // modulePreloads: <link rel="modulepreload"> hints for <head>.
     // Only active when configure({ modulepreload: true }) has been called — opt-in so
@@ -398,7 +410,7 @@ function injectScriptsAndStyles(state) {
 
     mediaMap.modulePreloads = modulePreloadFiles.length
       ? injectTags(modulePreloadFiles, MODULEPRELOAD_TAG)
-      : bluebird.resolve(false);
+      : Promise.resolve(false);
 
     if (!locals.edit) {
       mediaMap.styles = combineFileContents(mediaMap.styles, 'public/css', '/css/', STYLE_TAG);
@@ -408,7 +420,7 @@ function injectScriptsAndStyles(state) {
       mediaMap.scripts = module.exports.editScriptsTags ? injectTags(mediaMap.scripts, SCRIPT_TAG) : combineFileContents(mediaMap.scripts, 'public/js', '/js/', SCRIPT_TAG);
     }
 
-    return bluebird.props(mediaMap)
+    return props(mediaMap)
       .then(combinedFiles => {
         // modulepreload hints go first in <head>, before CSS, so the browser can
         // start fetching ESM scripts at the earliest possible moment.

package/lib/render.js

@@ -1,11 +1,11 @@
 'use strict';
 
-const _ = require('lodash'),
-  mediaService = require('./media'),
+const mediaService = require('./media'),
   clayUtils = require('clayutils'),
-  bluebird = require('bluebird'),
   styleguide = require('./styleguide'),
-  setup = require('./setup');
+  setup = require('./setup'),
+  cloneDeep = require('./clone-deep'),
+  { assign, pick, toList } = require('./utils');
 
 let { getIndices, getSchemaPath, getComponentPath, getLayoutPath } = require('amphora-fs'),
   log = require('./log').setup({ file: __filename }),
@@ -18,18 +18,24 @@ let { getIndices, getSchemaPath, getComponentPath, getLayoutPath } = require('am
  * @param {String} ref
  * @param {Object} data
  * @param {Object} locals
- * @returns {Object} data
+ * @returns {Promise<Object>} data
  */
-function applyRenderHooks(ref, data, locals) {
+async function applyRenderHooks(ref, data, locals) {
   // skip render hooks in edit mode
   if (locals.edit) {
-    return bluebird.resolve(data);
+    return data;
   }
 
-  return bluebird.filter(setup.plugins, (plugin) => plugin.render)
-    .reduce((val, plugin) => {
-      return plugin.render(ref, val, locals);
-    }, data);
+  const plugins = setup.plugins.filter((plugin) => plugin.render);
+  // with no data, the first plugin stands in for it and its hook is skipped,
+  // as Bluebird's reduce did (a model.js `render` that returns nothing gets here)
+  let val = data === undefined ? await plugins.shift() : await data;
+
+  for (const plugin of plugins) {
+    val = await plugin.render(ref, val, locals);
+  }
+
+  return val;
 }
 
 /**
@@ -79,17 +85,29 @@ function makeHtml(state) {
 
     // At the final stage of rendering we need to smoosh
     // all the data together with the state.
-    _.assign(state, _data);
+    assign(state, _data);
 
     // send clone of state/data to be used by kiln so kiln doesn't load component data that was mutated by hbs templates
     if (state.locals.edit) {
-      _.assign(state, { _componentData: _.cloneDeep(_data) });
+      state._componentData = cloneDeep(_data);
     }
 
     return rootPartial(state);
   };
 }
 
+/**
+ * The styleguide of the site, `_default` when it has none
+ *
+ * @param  {Object} meta
+ * @return {String}
+ */
+function getStyleguideName(meta) {
+  const name = meta.locals?.site?.styleguide;
+
+  return name === undefined ? '_default' : name;
+}
+
 /**
  * Construct the object that is needed by Kiln for rendering in
  * edit mode. Requires reading from the file system.
@@ -120,16 +138,16 @@ function makeState(data, meta) {
 
   // grab the component variations and make available via the state
   // note: if styleguide isn't set, this gets variations from the '_default' styleguide
-  initialState._componentVariations = styleguide.getVariations(_.get(meta, 'locals.site.styleguide', '_default'));
+  initialState._componentVariations = styleguide.getVariations(getStyleguideName(meta));
 
   if (meta.locals.edit) {
     initialState._envVars = ENV_VARS;
-    initialState._componentSchemas = _.map(componentList, (name) => {
+    initialState._componentSchemas = toList(componentList).map((name) => {
       return { name, schema: getSchemaPath(getComponentPath(name)) };
     });
   }
 
-  return  _.assign(initialState, _.pick(meta, ['locals', '_layoutRef']));
+  return Object.assign(initialState, pick(meta, ['locals', '_layoutRef']));
 }
 
 /**
@@ -200,7 +218,7 @@ function configure({ editAssetTags, cacheBuster, modulepreload }) {
  * @param {Array} vars
  */
 function addEnvVars(vars) {
-  ENV_VARS = _.pick(process.env, vars);
+  ENV_VARS = pick(process.env, vars);
   log('info', 'env vars registered with amphora html');
 }
 

package/lib/setup.js

@@ -1,10 +1,9 @@
 'use strict';
 
 const path = require('path'),
-  _ = require('lodash'),
-  glob = require('glob'),
   fs = require('fs'),
   render = require('./render'),
+  { toList } = require('./utils'),
   nymagHbs = require('clayhandlebars'),
   hbs = nymagHbs(),
   TEMPLATE_NAME = 'template';
@@ -24,19 +23,19 @@ function init() {
 function getRenderableItems() {
   const items = [];
 
-  _.each(getComponents(), function (cmpt) {
+  for (const cmpt of toList(getComponents())) {
     items.push({
       name: cmpt,
       path: getComponentPath(cmpt)
     });
-  });
+  }
 
-  _.each(getLayouts(), function (layout) {
+  for (const layout of toList(getLayouts())) {
     items.push({
       name: layout,
       path: getLayoutPath(layout)
     });
-  });
+  }
 
   return items;
 }
@@ -47,47 +46,56 @@ function getRenderableItems() {
  * @param {Array} items
  */
 function registerPartials(items) {
-  _.each(items, function (item) {
-    var templateFile = getPossibleTemplates(item.path, TEMPLATE_NAME),
-      isHandlebars = _.includes(templateFile, '.handlebars') || _.includes(templateFile, '.hbs'),
-      templateFileContents,
-      modifiedTemplateFile;
+  for (const item of items) {
+    const templateFile = getPossibleTemplates(item.path, TEMPLATE_NAME),
+      isHandlebars = typeof templateFile === 'string' && (templateFile.includes('.handlebars') || templateFile.includes('.hbs'));
 
     if (isHandlebars) {
-      templateFileContents = fs.readFileSync(templateFile, 'utf8');
-      // this wrapper guarantees we'll never render a component in a partial if it doesn't have a _ref
-      modifiedTemplateFile = nymagHbs.wrapPartial(item.name, templateFileContents);
+      const templateFileContents = fs.readFileSync(templateFile, 'utf8'),
+        // this wrapper guarantees we'll never render a component in a partial if it doesn't have a _ref
+        modifiedTemplateFile = nymagHbs.wrapPartial(item.name, templateFileContents);
 
       hbs.registerPartial(item.name, modifiedTemplateFile);
     }
-  });
+  }
 
-  // Compile all the loaded partials
-  _.forIn(hbs.partials, function (value, key) {
-    if (_.isString(value)) {
+  // Compile all the loaded partials (inherited ones too, as lodash's forIn did)
+  for (const key in hbs.partials) {
+    if (typeof hbs.partials[key] === 'string') {
       // preventIndent:true solve issue with  <pre> tag/white-space: pre
       // see http://handlebarsjs.com/reference.html compile() options
-      hbs.partials[key] = hbs.compile(value, { preventIndent: true });
+      hbs.partials[key] = hbs.compile(hbs.partials[key], { preventIndent: true });
     }
-  });
+  }
 
   module.exports.hbs = hbs;
 }
 
 /**
  * Grab the possible template files based on the name.
- * Returns a path to the file so that it can be read.
+ * Returns a path to the file so that it can be read: the first
+ * `<templateName>.*` file, in the order glob used to sort them.
  *
  * @param  {String} filePath
  * @param  {String} templateName
  * @return {String}
  */
 function getPossibleTemplates(filePath, templateName) {
-  if (_.isString(filePath)) {
-    return glob.sync(path.join(filePath, `${templateName}.*`))[0];
-  }
+  if (typeof filePath === 'string') {
+    const dir = path.dirname(path.join(filePath, `${templateName}.*`));
+    let names;
+
+    try {
+      names = fs.readdirSync(dir);
+    } catch (e) {
+      return;
+    }
 
-  return [];
+    return names
+      .filter((name) => name.startsWith(`${templateName}.`))
+      .map((name) => path.join(dir, name))
+      .sort((a, b) => a.localeCompare(b, 'en'))[0];
+  }
 }
 
 /**
@@ -96,10 +104,11 @@ function getPossibleTemplates(filePath, templateName) {
  * @param {Object} payload
  */
 function addHelpers(payload) {
-  _.forIn(payload, function (value, key) {
+  // inherited helpers too, as lodash's forIn did
+  for (const key in payload) { // eslint-disable-line guard-for-in
     // set up handlebars helpers that rely on internal services
-    hbs.registerHelper(`${key}`, value);
-  });
+    hbs.registerHelper(`${key}`, payload[key]);
+  }
 }
 
 /**
@@ -143,6 +152,24 @@ module.exports.renderSettings = undefined;
 module.exports.resolveMedia = undefined;
 module.exports.plugins = [];
 
+/**
+ * The Handlebars environment amphora-html renders with: clayhandlebars' helpers and
+ * partials, the helpers given to `addHelpers`, and a partial for each component and
+ * layout. It is the `handlebars` module clayhandlebars itself requires, so it is
+ * shared with anything else in the process that uses that module.
+ *
+ * @type {Object}
+ */
+module.exports.handlebars = hbs;
+
+/**
+ * What every component and layout template is wrapped in before it is registered
+ * as a partial: clayhandlebars' `wrapPartial(name, template)`.
+ *
+ * @type {Function}
+ */
+module.exports.wrapPartial = nymagHbs.wrapPartial;
+
 // Setup functions
 module.exports.init = init;
 module.exports.addHelpers = addHelpers;