3.0.10 • Published 1 week ago

nebbia

Licence

MIT

Version

3.0.10

Deps

Size

46 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Nebbia

Nebbia is a JavaScript Template literals (Template strings) compiler. It makes templates more expressive.

To improve reliability and maintainability the codebase has been migrated to TypeScript.

Template literals are enclosed by the back-tick ` character instead of double or single quotes. Template literals can contain placeholders. These are indicated by the dollar sign and curly braces `${expression}`. The expressions in the placeholders and the text between them get passed to a function. The default function just concatenates the parts into a single string.

Template literals are useful, but placeholders can only contain expressions. The following example demonstrates the problem of string interpolation.

`${1 + 1}` // '2'
`${}` // SyntaxError: Unexpected token }
`${if (true) {}}` // SyntaxError: Unexpected token if

Nebbia was created to help solve this problem. The compiler extends the capabilities of Template literals (Template strings) with the capabilities of standard JavaScript statements and declarations.

List of supported statements:

if
if...else
if...else if
for
for...in
for...of
while
do...while
break
continue

NOTE The break and continue statements are supported only inside iteration blocks: for, for...in, for...of, while, and do...while.

Nebbia was created to make template strings more forgiving. An empty expression ${} will not throw an exception. It supports closures and multiple nesting of expressions. The compiled pattern does not use regular expressions.

Getting Started

Installation

To use Nebbia in your project, run:

npm i nebbia

Nebbia is a Node.js module with bundled TypeScript declarations. It is built for Node.js >=18.6.0 and targets ECMAScript 2023.

Development

Development tooling requires Node.js ^20.19.0 or >=22.12.0.

This repository supports npm as its only package manager. Yarn, pnpm, Bun, and other alternative package managers must not be used.

Install the exact development dependency tree from package-lock.json with:

npm ci

Security

Nebbia compiles template expressions and statements into JavaScript source for execution. Only compile and execute trusted templates. Nebbia is not a sandbox and does not sanitize JavaScript embedded in templates.

API docs

nebbia(template)

class Node
class Expression
class Statement
class Text
nebbia.parse(template)

nebbia(template)

template <String> The template source to compile. By default, '__string__' is the name of the internal variable used to concatenate strings. You can change this marker to a valid, non-reserved JavaScript identifier by assigning a value to nebbia.Node.unity.
returns: <String> Represents the compiled template strings of a node and its descendants. Template literals are enclosed by the back-tick ` (grave accent).

Malformed syntax is handled permissively: an unclosed ${...} fragment ends at the end of the template, while standalone else and else if blocks are ignored.

template.html

<!DOCTYPE html>
<html>
  <head>
    <title>Nebbia</title>
  </head>
  <body>
    <h1>${h1}</h1>
    ${if (list instanceof Array) {
      <header></header>
      ${for (let i of list) {
        <div>${i}</div>
      }}
    }
    if (footer) {
      <footer></footer>
    }}
  </body>
</html>

template.txt

${if (user === 'admin') {
  📆 To-do list
  for (let i of list) {
    - ${i.date} ${i.note}
  }
}
else {
  Offer a cup of coffee!
}}

A JavaScript template literal inside a statement is processed by the parser as is.

${if (arg === `;)`) {
  <p>Maybe it's a smile</p>
}}

This is useful when you need to escape arguments in a statement. Otherwise, the parser will read the statement like arg === ;.

Statements by category

Nebbia uses JavaScript-like statement syntax to compile template strings. Several instructions can be in the same expression. Spaces and tabs are not taken into account by the parser.

if

import nebbia from 'nebbia';

const template = '${if (arg === true) {<p>${arg}</p>}}';
const invoke = new Function('arg', 'return ' + nebbia(template));

invoke(true); // <p>true</p>

if...else

import nebbia from 'nebbia';

const template = '${if (arg === true) {<p>${arg}</p>} else {<p>else</p>}}';
const invoke = new Function('arg', 'return ' + nebbia(template));

invoke(false); // <p>else</p>

if...else if

import nebbia from 'nebbia';

const template = '${if (arg === 1) {<p>one</p>} else if (arg === 2) {<p>two</p>} else {<p>else</p>}}';
const invoke = new Function('arg', 'return ' + nebbia(template));

invoke(2); // <p>two</p>

for

import nebbia from 'nebbia';

const template = '${for (let i = 0; i < count; i++) {<p>${i}</p>}}';
const invoke = new Function('count', 'return ' + nebbia(template));

invoke(2); // <p>0</p><p>1</p>

for...in

import nebbia from 'nebbia';

const template = '${for (let i in obj) {<p>${i}</p>}}';
const invoke = new Function('obj', 'return ' + nebbia(template));

invoke({
  fruit: 'apple',
  cart: 1
}); // <p>fruit</p><p>cart</p>

for...of

import nebbia from 'nebbia';

const template = '${for (let i of list) {<p>${i}</p>}}';
const invoke = new Function('list', 'return ' + nebbia(template));

invoke([ 0, 1 ]); // <p>0</p><p>1</p>

while

import nebbia from 'nebbia';

const template = '${while (list.length > 0) {<p>${list.pop()}</p>}}';
const invoke = new Function('list', 'return ' + nebbia(template));

invoke([ 0, 1 ]); // <p>1</p><p>0</p>

do...while

import nebbia from 'nebbia';

const template = '${do {<p>${arg}</p>} while (arg-- > 0)}';
const invoke = new Function('arg', 'return ' + nebbia(template));

invoke(1); // <p>1</p><p>0</p>

break

import nebbia from 'nebbia';

const template = '${for (let i = 0; i < list.length; i++) {${if (list[i] === stop) {${break}}}<p>${list[i]}</p>}}';
const invoke = new Function('list', 'stop', 'return ' + nebbia(template));

invoke([ 1, 2, 3 ], 3); // <p>1</p><p>2</p>

continue

import nebbia from 'nebbia';

const template = '${for (let i = 0; i < list.length; i++) {${if (list[i] === skip) {${continue}}}<p>${list[i]}</p>}}';
const invoke = new Function('list', 'skip', 'return ' + nebbia(template));

invoke([ 1, 2, 3 ], 2); // <p>1</p><p>3</p>

class Node

Node is the base AST class used by the compiler tree. Concrete node classes inherit its tree fields and methods.

yuml diagram

The following classes inherit from Node’s methods and properties: Expression, Statement and Text.

child <Node> The node to append to the given parent node.
returns: <undefined>

Adds the specified node argument as the last child to the current node.

node.build()

returns: <String> Represents the compiled template strings of a node and its descendants. Template literals are enclosed by the back-tick ` (grave accent).

node.children

<Array> Contains all the children of this node.

node.name

<String|null> Contains the name of the node. The structure of the name will differ with the node type. E.g. A Statement will contain the name of the corresponding statement, a Text node will have the #text string. Default: null.

node.parent

<Node|null> Returns a node that is the parent of this node. If there is no such node, for example when this node is the top of the tree or does not participate in a tree, this property returns null.

node.type

<Number|null> Returns an unsigned short representing the type of the node. Default: null.

Possible values are:

Name	Value
Expression	0
Text	1
Statement	2

template <String> The template source to parse. By default, '__string__' is the name of the internal variable used to concatenate strings. You can change this marker to a valid, non-reserved JavaScript identifier by assigning a value to nebbia.Node.unity.
returns: <Expression> Returns the root expression node. The returned AST gives programmatic access to the template string structure.

An example of parsing the template:

template.html

<div>
${if (typeof value === 'string') {
  <p>${value}</p>
}}
</div>

index.js

import fs from 'fs';
import nebbia from 'nebbia';

const content = fs.readFileSync('./template.html', 'utf8');
const ast = nebbia.parse(content);
const template = ast.build();

const ast:

const template:

`<div>
${((__string__)=>{if(typeof value === 'string'){__string__+=`
  <p>${value}</p>
`;};return __string__})(``)}
</div>
`

Development

Planned:

Measure benchmark.

Keywords

template literals compiler

nebbia

Nebbia

How it works?

Getting Started

Installation

Development

Security

API docs

Table of Contents

nebbia(template)

Statements by category

if

if...else

if...else if

for

for...in

for...of

while

do...while

break

continue

class Node

static: Node.unity

constructors

node.append(child)

node.build()

node.children

node.name

node.parent

node.type

node.value

class Expression

class Text

class Statement

nebbia.parse(template)

Development

Keywords