Use CSS selectors & HTML as a template language.
A re-implementation of the classic @substack module, using Web Streams for compatibility with browsers, Cloudflare Workers, and Deno.
npm i -S @substrate-system/hyperstreamTake some template HTML, and transform it using CSS selectors.
import hyperstream from '@substrate-system/hyperstream'
import { createReadStream, createWriteStream } from 'node:fs'
import { Readable, Writable } from 'node:stream'
const hs = hyperstream({
'#title': 'Hello World',
'.content': { _html: '<p>Injected content</p>' }
})
const destination = Writable.toWeb(createWriteStream('./output.html'))
Readable.toWeb(createReadStream('./template.html'))
.pipeThrough(hs.transform)
.pipeTo(destination)Because this is using
Web Streams,
we can run it in a browser too. A browser demo is in
/example_browser.
npm startStream a template file through hyperstream, inject streams by selector,
then stream the transformed output into result.html. The selector values
are streams here. You can also pass in string as values.
import hyperstream from '@substrate-system/hyperstream'
import { S } from '@substrate-system/stream'
import { createWriteStream } from 'node:fs'
import { Writable } from 'node:stream'
import { open } from 'node:fs/promises'
async function run ():Promise<void> {
const template = await open('./template.html', 'r')
const nav = await open('./partials/nav.html', 'r')
const footer = await open('./partials/footer.html', 'r')
try {
// setup template logic
const hs = hyperstream({
'#main-nav': nav.readableWebStream(),
'#main-footer': footer.readableWebStream(),
'#build-time': S.from([new Date().toISOString()]).toStream()
})
// build the template
await template.readableWebStream()
.pipeThrough(hs.transform)
.pipeTo(Writable.toWeb(createWriteStream('./result.html')))
} finally {
await Promise.allSettled([
template.close(),
nav.close(),
footer.close(),
])
}
}
await run()Use strings as selector values, and use a string as the template.
// our template is a string, not stream
import { fromString } from '@substrate-system/hyperstream'
const template = `<html>
<head>
<title id="title"></title>
</head>
<body>
<div class="content"></div>
</body>
</html>`
const result = await fromString(template, {
'#title': 'Hello World',
'.content': { _html: '<p>This is the content</p>' }
})
console.log(result)<html>
<head><title id="title">Hello World</title></head>
<body>
<div class="content"><p>This is the content</p></div>
</body>
</html>Use the TransformStream interface:
import hyperstream from '@substrate-system/hyperstream'
import { S } from '@substrate-system/stream'
const hs = hyperstream({
'#title': 'Hello World',
'.content': { _html: '<p>This is the content</p>' }
})
const template = `<html>
<head><title id="title"></title></head>
<body>
<div class="content"></div>
</body>
</html>
`
S.from([template]).toStream().pipeTo(hs.writable)
const result = await hs.asString()
console.log(result)Use _appendHtml, _prependHtml, _append (text), or _prepend (text)
to add content before or after existing content:
import { fromString } from '@substrate-system/hyperstream'
// takes a string as input
// returns a string as output
const result = await fromString(
'<ul class="list"><li>First</li></ul><span class="greeting">World</span>',
{
'.list': { _appendHtml: '<li>New item</li>' },
'.greeting': { _prepend: 'Hello, ' }
}
)
console.log(result)Output:
<ul class="list">
<li>First</li>
<li>New item</li>
</ul>
<span class="greeting">Hello, World</span>Pass a ReadableStream as the value to insert streamed content:
import hyperstream from '@substrate-system/hyperstream'
import fs from 'node:fs'
import { S } from '@substrate-system/stream'
// Helper to convert a file to a ReadableStream
function fileToStream(path: string): ReadableStream<Uint8Array> {
const content = fs.readFileSync(path)
return S.from([new Uint8Array(content)]).toStream()
}
const hs = hyperstream({
'#a': fileToStream('./content-a.html'),
'#b': fileToStream('./content-b.html')
})
// Process template
const template = fileToStream('./template.html')
const output = template.pipeThrough(hs.transform)
const chunks = await S(output).toArray()
const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0)
const bytes = new Uint8Array(totalLength)
let offset = 0
for (const chunk of chunks) {
bytes.set(chunk, offset)
offset += chunk.length
}
const decoder = new TextDecoder()
console.log(decoder.decode(bytes))Set attributes directly, or use append/prepend to modify existing values:
import { fromString } from '@substrate-system/hyperstream'
const result = await fromString(
'<input><button class="btn">Click</button><a>Link</a>',
{
'input': { value: 'default', placeholder: 'Enter text...' },
'.btn': { class: { append: ' active' } },
'a': { href: 'https://example.com' }
}
)
console.log(result)Output:
<input value="default" placeholder="Enter text...">
<button class="btn active">Click</button>
<a href="https://example.com">Link</a>Pass a function to transform the existing content:
import { fromString } from '@substrate-system/hyperstream'
const result = await fromString(
'<span class="count">41</span><span class="upper">hello</span>',
{
'.count': (html) => String(parseInt(html) + 1),
'.upper': (html) => html.toUpperCase()
}
)
console.log(result)Output:
<span class="count">42</span><span class="upper">HELLO</span>Create a Hyperstream instance with the given config.
Returns an object with:
transform: ATransformStream<Uint8Array|string, Uint8Array>for pipingreadable: The readable side of the transformwritable: The writable side of the transform
import hyperstream from '@substrate-system/hyperstream'
const hs = hyperstream({ '#title': 'Hello World' })
await someReadableStream
.pipeThrough(hs.transform)
.pipeTo(destination)Convenience function to process HTML from a string.
Returns a Promise<string> with the processed HTML.
import { fromString } from '@substrate-system/hyperstream'
const result = await fromString('<h1 id="title"></h1>', {
'#title': 'Hello World'
})
// => '<h1 id="title">Hello World</h1>'Create a raw TransformStream<Uint8Array|string, Uint8Array>.
import { transform } from '@substrate-system/hyperstream'
const ts = transform({ '#title': 'Hello World' })
const result = await someReadableStream
.pipeThrough(ts)
.pipeTo(destination)Process a ReadableStream<Uint8Array|string> and return a Promise<Uint8Array>.
import { toBuffer } from '@substrate-system/hyperstream'
import { S } from '@substrate-system/stream'
const input = S.from(['<h1 id="title"></h1>']).toStream()
const result = await toBuffer(input, { '#title': 'Hello World' })
// => Uint8Array of '<h1 id="title">Hello World</h1>'The config object maps CSS selectors to values:
- String/Number: Replace element content
{ _html: string }: Replace content with raw HTML{ _text: string }: Replace content with HTML-escaped text{ _appendHtml: string }: Append raw HTML to content{ _prependHtml: string }: Prepend raw HTML to content{ _append: string }: Append HTML-escaped text{ _prepend: string }: Prepend HTML-escaped text{ attr: value }: Set attribute value{ attr: { append: string } }: Append to attribute{ attr: { prepend: string } }: Prepend to attributeReadableStream: Replace content with stream output(html) => string: Transform existing contentnull: Skip this selector