@thefarce/loom

What is this?

Loom is a tool for weaving form data with content data in Node.js. It does this by using elements of the Unified.js toolkit for parsing text into abstract syntax trees (AST).

The fundamental idea of Loom is that presentation and content are orthogonal dimensions of data. A communication has values in these two dimensions integrated into a coherent whole.

When should I use this?

When you want to blend form (such as HTML) with content (such as JSON) into a single document. Unlike other systems, Loom does not require writing to or reading from files.

Installation

$ npm install @thefarce/loom

Usage Example

For more thorough usage examples, see the examples directory and refer to the transformations documentation and the interpolation documentation.

Simple Example

In this simple example, we will make two changes. First, we will replace the strong tag in our HTML fragment with an em tag. Second, we will replace the name variable in our template with the value Othello.

import { interpolateTree, transform } from '@thefarce/loom'
import { astToHtml, htmlToAst } from '@thefarce/loom-html5'

// Get our HTML fragment.
const ast = htmlToAst('<p>Hello, <strong>${name}</strong>!</p>', { fragment: true });

// Now we have an abstract syntax tree (AST) representation of our HTML
// fragment. First, let's transform the <strong> tag to an <em> tag.
// Note that transform() takes three parameters:
//   1) The AST to transform
//   2) The initial context (here, an empty object {} )
//   3) An array of transformer functions

let updated = await transform(
  ast,
  {},
  [
    (node, context, next) => {
      if (node.type === 'element' && node.tagName === 'strong') {
        node.tagName = 'em';
        return { node, context };
      }
      return next();
    },
  ]
);

// Now let's interpolate the value `name`. 
// Note that interpolateTree() is async and requires await.
// There is another major mechanism for providing interpolation values; 
// see the docs for more detailed information.
let intercepted = await interpolateTree(
  updated, 
  { name: 'Othello' }
);

console.log(astToHtml(interpolated));

Running this script produces the following output:

<p>Hello, <em>Othello</em>!</p>

API

Value Interpolation

Interpolation is the process of executing code within the AST's values. This uses a syntax identical to JavaScript's backtick interpolation. For example, in the following script, JavaScript will replace ${name} with the value Othello:

See the interpolation documentation for more detailed information.

const name = 'Othello';
console.log(`Hello, \${name}!`);

This interpolation uses variables in scope to expand values. Loom interpolation works the same way: any string[^1] in the AST will be replaced with the value in the data. All interpolation functions are asynchronous and return Promises.

[^1]: The type, data, and position values of a node will not be interpolated automatically. You may still update them manually if desired.

AST Transformation

Transformation is the process of making systematic changes to an AST. This is accomplished by creating "transformer functions" (or "transformers") that apply changes to a node based on its content.

See the transformations documentation for more detailed information.

Glossary

ast

The AST to be transformed. This can be any AST that conforms to the Unified.js specification.

Contributing to Loom

Contributions to Loom are welcome.

Community Guidelines

Contribute good code with full tests and docs, then submit a pull request. I don't care about any of your other behaviors.

VIM

This project contains a .vimrc file to help with development and maintenance. See that file for more information and instructions for use.