amphora-html 6.0.0 → 7.0.0

package/lib/styleguide.js

@@ -1,10 +1,9 @@
 'use strict';
 
-const _ = require('lodash'),
-  clayUtils = require('clayutils'),
-  files = require('nymag-fs'),
+const clayUtils = require('clayutils'),
+  files = require('./files'),
   path = require('path'),
-  traverse = require('traverse');
+  { isObject, assignValue, memoize } = require('./utils');
 
 /**
  * Looks for CSS files associated with a component's variation
@@ -15,7 +14,7 @@ const _ = require('lodash'),
 function findVariationFiles(styleguide) {
   const stylePath = `styleguides/${styleguide}/components`,
     stylesheets = files.getFiles(stylePath),
-    variations = _.filter(stylesheets, function (file) {
+    variations = stylesheets.filter(function (file) {
       // checks for underscores which denotes variations and make sure it's a
       // css file
       return file.includes('_') && file.includes('.css');
@@ -37,20 +36,45 @@ function findVariationFiles(styleguide) {
 * component and its variations
 */
 function getVariations(styleguide = '_default') {
-  const foundVariations = styleguide !== '_default' ? _.uniq(findVariationFiles(styleguide).concat(findVariationFiles('_default'))) : findVariationFiles('_default'),
+  const foundVariations = styleguide !== '_default' ? [...new Set(findVariationFiles(styleguide).concat(findVariationFiles('_default')))] : findVariationFiles('_default'),
     componentVariations = {};
 
   if (foundVariations.length) {
-    _.forEach(foundVariations, function (variant) {
+    for (const variant of foundVariations) {
       let component = variant.split('_')[0],
         variantName = path.basename(variant, '.css');
 
       (componentVariations[component] || (componentVariations[component] = [])).push(variantName);
-    });
+    }
   }
   return componentVariations;
 }
 
+/**
+ * Call `visit` with every value in `node`, depth first, as traverse's forEach did:
+ * an object's keys are read before it is visited (so keys `visit` adds are not
+ * walked), functions are not walked, and an object found inside itself is
+ * visited but not walked again.
+ *
+ * @param {*} node
+ * @param {Function} visit
+ * @param {Object[]} [parents]  the objects being walked
+ */
+function walk(node, visit, parents = []) {
+  const isWalked = typeof node === 'object' && node !== null,
+    keys = isWalked ? Object.keys(node) : [];
+
+  visit(node);
+
+  if (isWalked && !parents.includes(node)) {
+    parents.push(node);
+    for (const key of keys) {
+      walk(node[key], visit, parents);
+    }
+    parents.pop();
+  }
+}
+
 /**
 * Goes through page data and sets a default for components
 *
@@ -71,25 +95,26 @@ function setDefaultVariations(_data, state) {
       [topLevelVariation || layoutOrSelf]: true
     };
 
-  traverse(_data).forEach(function (val) {
+  walk(_data, function (val) {
     let componentName, componentVariations;
 
-    if (!_.isObject(val) || !val._ref) {
+    if (!isObject(val) || !val._ref) {
       return; // we only care about components' root data
     }
 
     componentName = clayUtils.getComponentName(val._ref);
-    componentVariations = variations[componentName] || [];
+    // a name like `constructor` finds what the object inherits, which is not a list
+    componentVariations = Array.isArray(variations[componentName]) ? variations[componentName] : [];
 
-    if (val.componentVariation && !_.includes(componentVariations, val.componentVariation)) {
+    if (val.componentVariation && !componentVariations.includes(val.componentVariation)) {
       // component has a variation set, but it doesn't exist in the site's styleguide or the default styleguide!
       // render the component with the default variation
-      _.set(val, 'componentVariation', componentName);
+      assignValue(val, 'componentVariation', componentName);
       usedVariations[`${componentName}`] = true;
     } else if (!val.componentVariation) {
       // component has no variation set!
       // render the component with the default variation
-      _.set(val, 'componentVariation', componentName);
+      assignValue(val, 'componentVariation', componentName);
       usedVariations[`${componentName}`] = true;
     } else {
       usedVariations[`${val.componentVariation}`] = true;
@@ -98,5 +123,5 @@ function setDefaultVariations(_data, state) {
   state._usedVariations = Object.keys(usedVariations);
 }
 
-exports.getVariations = _.memoize(getVariations);
+exports.getVariations = memoize(getVariations);
 exports.setDefaultVariations = setDefaultVariations;

package/lib/utils.js

@@ -0,0 +1,127 @@
+'use strict';
+
+// The few behaviors of lodash that amphora-html depends on, in native code.
+
+/**
+ * Whether a value is an object or a function, as lodash's isObject
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isObject(value) {
+  return value !== null && (typeof value === 'object' || typeof value === 'function');
+}
+
+/**
+ * Set a property the way lodash's assign and set did: nothing is written when
+ * the object already has that value, a `__proto__` key becomes a property of
+ * its own instead of replacing the prototype, and a property that can't be
+ * written is left as it is instead of throwing.
+ *
+ * @param {Object} object
+ * @param {string|symbol} key
+ * @param {*} value
+ */
+function assignValue(object, key, value) {
+  const current = object[key];
+
+  // SameValueZero, like lodash's eq
+  if (Object.hasOwn(object, key) && (current === value || Number.isNaN(current) && Number.isNaN(value))) {
+    return;
+  }
+
+  if (key === '__proto__') {
+    Object.defineProperty(object, key, { configurable: true, enumerable: true, value, writable: true });
+  } else {
+    Reflect.set(object, key, value);
+  }
+}
+
+/**
+ * Copy the own enumerable properties of `source` onto `target`, as lodash's assign
+ *
+ * @param {Object} target
+ * @param {*} source
+ * @returns {Object} target
+ */
+function assign(target, source) {
+  for (const key of Object.keys(Object(source))) {
+    assignValue(target, key, source[key]);
+  }
+
+  return target;
+}
+
+/**
+ * The properties of `object` with these names, as lodash's pick: a name is
+ * picked when it is `in` the object, inherited or not, except the ones that
+ * would reach a prototype.
+ *
+ * @param {Object} object
+ * @param {string[]|string} keys
+ * @returns {Object}
+ */
+function pick(object, keys) {
+  const picked = {};
+
+  for (const key of [].concat(keys)) {
+    if (object != null && key in Object(object) && key !== '__proto__' && key !== 'constructor' && key !== 'prototype') {
+      picked[key] = object[key];
+    }
+  }
+
+  return picked;
+}
+
+/**
+ * The items of a collection, as lodash's map and each see them: nothing for
+ * null or undefined, every index of an array or anything with a length
+ * (holes included), the own values of anything else.
+ *
+ * @param {*} collection
+ * @returns {Array}
+ */
+function toList(collection) {
+  if (collection == null) {
+    return [];
+  }
+
+  if (typeof collection !== 'function' && Number.isSafeInteger(collection.length) && collection.length >= 0) {
+    return Array.from({ length: collection.length }, (item, index) => collection[index]);
+  }
+
+  return Object.values(Object(collection));
+}
+
+/**
+ * Remember what `fn` returns for each first argument, as lodash's memoize:
+ * the cache is read from `memoized.cache` on every call, so it can be cleared
+ * or replaced with anything that has `get`, `set` and `has`.
+ *
+ * @param {Function} fn
+ * @returns {Function}
+ */
+function memoize(fn) {
+  function memoized(key) {
+    const cache = memoized.cache;
+
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+
+    const result = fn.apply(this, arguments);
+
+    memoized.cache = cache.set(key, result) || cache;
+    return result;
+  }
+
+  memoized.cache = new Map();
+  return memoized;
+}
+
+module.exports.isObject = isObject;
+module.exports.assignValue = assignValue;
+module.exports.assign = assign;
+module.exports.pick = pick;
+module.exports.toList = toList;
+module.exports.memoize = memoize;

package/package.json

@@ -1,65 +1,39 @@
 {
   "name": "amphora-html",
-  "version": "6.0.0",
+  "version": "7.0.0",
   "description": "An HTML renderer for component data",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "!**/*.test.js"
+  ],
   "engines": {
-    "node": ">=20.14.0"
+    "node": ">=26.12.1"
   },
   "scripts": {
-    "test": "npm run eslint && npm run jest -- --coverage --no-cache",
-    "eslint": "eslint --max-warnings 0 lib test",
-    "jest": "jest"
+    "lint": "eslint --max-warnings 0",
+    "test-local": "node --test \"lib/*.test.js\" \"test/*.test.js\"",
+    "test": "npm run lint && node --test --experimental-test-coverage --test-coverage-exclude=\"**/*.test.js\" --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 \"lib/*.test.js\" \"test/*.test.js\""
   },
   "dependencies": {
-    "amphora-fs": "^2.0.0",
-    "bluebird": "^3.5.0",
-    "clay-log": "^1.2.0",
-    "clayutils": "^3.0.0",
-    "glob": "^7.1.1",
-    "js-yaml": "^3.8.2",
-    "lodash": "^4.17.5",
-    "nymag-fs": "^1.0.1",
-    "traverse": "^0.6.6"
+    "amphora-fs": "^3.0.0",
+    "clay-log": "^1.6.0",
+    "clayhandlebars": "^6.0.0",
+    "clayutils": "^4.0.0"
   },
   "devDependencies": {
-    "clayhandlebars": "^5.0.1",
-    "coveralls": "^3.0.2",
-    "eslint": "^3.19.0",
-    "jest": "23.6.0"
-  },
-  "peerDependencies": {
-    "handlebars": "4",
-    "clayhandlebars": "5"
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.14.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nymag/amphora-html.git"
-  },
-  "jest": {
-    "clearMocks": true,
-    "restoreMocks": true,
-    "collectCoverageFrom": [
-      "<rootDir>/lib/**/*.js"
-    ],
-    "coverageReporters": [
-      "lcov",
-      "text-summary"
-    ],
-    "moduleFileExtensions": [
-      "js"
-    ],
-    "setupFiles": [
-      "<rootDir>/test/setupFile.js"
-    ],
-    "moduleNameMapper": {
-      "\\.(hbs)$": "<rootDir>/__mocks__/fileMock.js"
-    }
+    "url": "git+https://github.com/clay/amphora-html.git"
   },
   "author": "",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/nymag/amphora-html/issues"
+    "url": "https://github.com/clay/amphora-html/issues"
   },
-  "homepage": "https://github.com/nymag/amphora-html#readme"
+  "homepage": "https://github.com/clay/amphora-html#readme"
 }

package/.eslintrc

@@ -1,75 +0,0 @@
-{
-  "env": {
-    "browser": false,
-    "node": true,
-    "mocha": true,
-    "es6": true
-  },
-  // enable the es6 features supported by our browsers / iojs
-  "ecmaFeatures": {
-    "arrowFunctions": true,
-    "blockBindings": true,
-    "forOf": true,
-    "objectLiteralDuplicateProperties": true,
-    "objectLiteralShorthandProperties": true,
-    "objectLiteralShorthandMethods": true,
-    "octalLiterals": true,
-    "binaryLiterals": true,
-    "templateStrings": true,
-    "generators": false
-  },
-  "rules": {
-    // possible errors
-    "no-extra-parens": 1,
-    "valid-jsdoc": [1, {
-      "requireReturn": false,
-      "requireParamDescription": false,
-      "requireReturnDescription": false
-    }],
-    // best practices
-    "complexity": [2, 8],
-    "default-case": 2,
-    "guard-for-in": 2,
-    "no-alert": 1,
-    "no-floating-decimal": 1,
-    "no-self-compare": 2,
-    "no-throw-literal": 2,
-    "no-void": 2,
-    "quote-props": [2, "as-needed"],
-    "vars-on-top": 2,
-    "wrap-iife": 2,
-    // strict mode
-    "strict": [2, "global"],
-    // variables
-    "no-unused-vars": 2,
-    // node.js
-    "handle-callback-err": [2, "^.*(e|E)rr"],
-    "no-mixed-requires": 0,
-    "no-new-require": 2,
-    "no-path-concat": 2,
-    // stylistic issues
-    "brace-style": [2, "1tbs", { "allowSingleLine": true }],
-    "comma-style": [2, "last"],
-    "indent": [2, 2, { "SwitchCase": 1 }],
-    "max-nested-callbacks": [2, 4],
-    "newline-after-var": [2, "always"],
-    "no-nested-ternary": 2,
-    "no-spaced-func": 0,
-    "no-trailing-spaces": 2,
-    "no-underscore-dangle": 0,
-    "no-unneeded-ternary": 1,
-    "one-var": 0,
-    "quotes": [2, "single", "avoid-escape"],
-    "semi": [2, "always"],
-    "keyword-spacing": 2,
-    "space-before-blocks": [2, "always"],
-    "space-before-function-paren": [2, {"anonymous": "always", "named": "never"}],
-    "space-infix-ops": [1, {"int32Hint": false}],
-    "spaced-comment": [2, "always"],
-    // es6
-    "generator-star-spacing": [2, "before"],
-    // legacy jshint rules
-    "max-depth": [2, 4],
-    "max-params": [2, 4]
-  }
-}

package/.github/workflows/ci.yml

@@ -1,40 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: ['**']
-    tags: ['**']
-  pull_request:
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    name: Test (Node ${{ matrix.node-version }})
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        node-version: [20]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
-          cache-dependency-path: package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test
-

package/.istanbul.yml

@@ -1,51 +0,0 @@
-verbose: false
-instrumentation:
-    root: .
-    default-excludes: true
-    excludes: []
-    embed-source: false
-    variable: __coverage__
-    compact: true
-    preserve-comments: false
-    complete-copy: false
-    save-baseline: false
-    baseline-file: ./coverage/coverage-baseline.json
-    include-all-sources: true
-    include-pid: false
-reporting:
-    print: summary
-    reports:
-        - lcov
-    dir: ./coverage
-    watermarks:
-        statements: [98, 100]
-        lines: [98, 100]
-        functions: [98, 100]
-        branches: [98, 100]
-    report-config:
-        clover: {file: clover.xml}
-        cobertura: {file: cobertura-coverage.xml}
-        json: {file: coverage-final.json}
-        json-summary: {file: coverage-summary.json}
-        lcovonly: {file: lcov.info}
-        teamcity: {file: null}
-        text: {file: null, maxCols: 0}
-        text-lcov: {file: lcov.info}
-        text-summary: {file: null}
-hooks:
-    hook-run-in-context: false
-    post-require-hook: null
-    handle-sigint: false
-check:
-    global:
-        statements: 100
-        lines: 100
-        branches: 100
-        functions: 100
-        excludes: []
-    each:
-        statements: 0
-        lines: 0
-        branches: 0
-        functions: 0
-        excludes: []

package/__mocks__/fileMock.js

@@ -1,3 +0,0 @@
-'use strict';
-
-module.exports = 'test-export';

package/docs/README.md

@@ -1,31 +0,0 @@
-# Clay Documentation
-
-On this directory, we have the pre-release documentation written using markdown. This file has the `.md` extension and as we mentioned before, these are pre-release if you haven't added a documentation version yet.
-
-## Markdown options
-
-These files have the following structure at the beginning of the file:
-
-```
----
-id: idOftheFile
-title: Title of your file
-sidebar_label: Title of the sidebar
----
-
-My new content here..
-```
-
-The previous example has a couple of the most important part to identify the content that you wish to add to your documentation. Here is a more detailed explanation on the [Markdown feature](https://docusaurus.io/docs/en/doc-markdown) that you can use.
-
-## Test documentation page
-
-We have a local server that we use to test your current docs content. Here are the steps on how to set the [local server](https://github.com/clay/amphora-html/tree/master/website#run-the-local-server). Normally you will have access on your browser with a url like this:
-
-`http://localhost:3000/amphora-html/docs/idOfTheDocs`
-
-But if you already have a [version](https://github.com/clay/amphora-html/tree/master/website#versioning-the-code) on your docs you will need to add `next` on your url
-
-`http://localhost:3000/amphora-html/docs/next/idOfTheDocs`
-
-[Here](https://docusaurus.io/docs/en/versioning) are more insights about what to do when you already have documentation with version.

package/docs/integration.md

@@ -1,93 +0,0 @@
----
-id: integration
-title: Integration
-sidebar_label: Integration
----
-
----
-## Basic Configuration
-
-First, ensure that you have a compatible version of Amphora installed (v3.x or greater) and require `amphora-html` from wherever you are running Amphora.
-
-```javascript
-const amphoraHtml = require('amphora-html');
-```
-
-Second, register a `rootPath` with the renderer. This will allow the renderer to reference your components directory and static assets directory properly. Usually this is the root of your project, but that may not be the case for your implementation.
-
-```javascript
-// Register a root path for Amphora HTML
-amphoraHtml.addRootPath(path.dirname(path.resolve('./package.json')));
-```
----
-## Handlebars Helpers
-
-If your templates require any custom [Handlebars Helpers](http://handlebarsjs.com/block_helpers.html) you can register them with the renderer's Handlebars instance. Simply pass in an object whose keys are the names of your helpers and whose values are the helper themselves. Like so:
-
-```javascript
-// My helpers
-const helpers = {
-  // set up handlebars helpers that rely on internal services
-  'nameOfHelper': () => {
-    // helper that does something you need.
-    return 'foobar';
-  }
-};
-
-// Register helpers
-amphoraHtml.addHelpers(helpers);
-```
----
-## Amphora HTML Plugins
-
-Amphora HTML plugins let you read and modify both the data sent to Handlebars and the HTML returned by Handlebars. An Amphora HTML plugin is an object with a `render` function that returns a modified `data` object and/or a `postRender` function that returns the rendered HTML string:
-
-```javascript
-
-module.exports.render = (ref, data, locals) => {
-  // you have the option to mutate `data` here
-  // do **not** attempt to mutate `locals`
-
-  // return `data` or a promise for `data`
-  return data;
-};
-
-module.exports.postRender = (ref, html, locals) => {
-  // you have the option to mutate `html` here
-  // do **not** attempt to mutate `locals`
-
-  // return `html` or a promise for `html`
-  return html;
-};
-```
-
-You can add Amphora HTML plugins like this:
-
-```javascript
-amphoraHtml.addPlugins([
-  { render: plugin1 },
-  { postRender: plugin2 }
-]);
-```
-
-One use case for Amphora HTML plugins is to skip rendering of certain components depending on query parameters, which are available in `locals.query`. Amphora HTML plugins do not run when rendering for edit mode.
-
----
-## Register Amphora HTML with your Amphora Instance
-
-Now that you have registered any helpers and plugins and have provided a root path which Amphora HTML can work from, you can register your renderer with Amphora. Registering consists of providing a `renderers` object whose keys are the extension of an HTTP request and whose values are the renderer. You can also specify a `default` property whose value is the extension that Amphora should default to when rendering. This is handy for rendering routes who don't end in extensions, such as `mycoolsite.com/about/`.
-
-```javascript
-return amphora({
-  app: app,
-  renderers: {
-    html: amphoraHtml,
-    default: 'html'
-  },
-  providers: ['apikey', amphoraProvider],
-  sessionStore: redisStore,
-  plugins: [
-    amphoraSearch
-  ]
-});
-```

package/docs/intro.md

@@ -1,21 +0,0 @@
----
-id: intro
-title: Amphora HTML
-sidebar_label: Amphora HTML
----
-
----
-The HTML renderer for Clay components that use [Handlebars](http://handlebarsjs.com/) templates.
-
----
-## 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.
-
----
-
-## Installation
-
----
-
-`$ npm install --save amphora-html`