Prostamp

Incremental asynchronous template rendering

Eager, incremental template rendering with automatic promise resolution and partial support through nested rendering.

Prostamp is an invented contraction of progressive stamping, an analogy of what this library does.

API

prostamp(template, locals) => AsyncIterator (default export)

Consume with for await:

for await (const output of prostamp(template, locals)) {
  process.stdout.write(output)
}

Consume with streams:

import { Readable } from 'stream'
Readable.from(prostamp(template, locals)).pipe(process.stdout)

Template

The template argument should be a string or Buffer that contains content and template variables.

A template variable is denoted with __name__. Template variables may also contain extra meta data delimited by :. For instance __name:more:info__.

Locals

The locals argument should be an object that contains keys which correspond to the template variable names. The values may be strings, numbers, promises or async iterators as returned from prostamp, arrays or async functions or plain functions.. Async functions and plain functions are called with (key, meta) where key is the name in __name:more:info__ and meta is an array containing any meta data, in the example case it will be ['more', 'info']. In the case of an async function the returned promise is resolved to its value before interpolation.

Example

import prostamp from './index.js'

const template = `
Some content: __something__

__another__

More things:

__more__

__dynamic:with:metadata__
`

const locals = {
  something: 'here it is',
  another: Promise.resolve('promises are auto resolved before rendering'),
  more: prostamp('Nesting is possible, __items__', { items: ['arrays ', 'are ', Promise.resolve('expanded')] }),
  async dynamic (key, meta) {
    return `Name is "${key}", meta[0] is "${meta[0]}" and meta[1] is "${meta[1]}"`
  }
}

for await (const output of prostamp(template, locals)) process.stdout.write(output)

Outputs:

Some content: here it is

promises are auto resolved before rendering

More things:

Nesting is possible, arrays are expanded

Name is "dynamic", meta[0] is "with" and meta[1] is "metadata"

render `template`

The render function is a tagged template function that has the same qualities as the prostamp function when it comes to promise resolution, array expansion and prostamp async renderer nesting but it works with native JS template strings.

import { render } from 'prostamp'
const something = 'here it is'
const another = Promise.resolve('promises are auto resolved before rendering')
const items = ['arrays ', 'are ', Promise.resolve('expanded')]
const more = render `Nesting is possible, ${items}`

const iterator = render `
  Some content: ${something}

  ${another}

  More things:

  ${more}

`

for await (const output of iterator) process.stdout.write(output)

Support

Node 12 and up.

License

MIT