@substrate-system/hyperstream
v0.0.3
Published
Stream html by CSS selector.
Readme
hyperstream
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.
Install
npm i -S @substrate-system/hyperstreamExample
Take 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)Browser Example
Because this is using
Web Streams,
we can run it in a browser too. A browser demo is in
/example_browser.
npm startStreams as Values
Stream 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()Strings
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)Output
<html>
<head><title id="title">Hello World</title></head>
<body>
<div class="content"><p>This is the content</p></div>
</body>
</html>TransformStream API
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)Append and prepend
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>Streams
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))Attribute manipulation
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>Transform functions
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>API
hyperstream(config)
Create a Hyperstream instance with the given configuration.
Returns an object with:
transform: ATransformStream<Uint8Array, Uint8Array>for pipingreadable: The readable side of the transformwritable: The writable side of the transform
fromString(html, config)
Convenience function to process HTML from a string.
Returns a Promise<string> with the processed HTML.
createHyperstream(config)
Create a raw TransformStream<Uint8Array, Uint8Array>.
processHyperstream(input, config)
Process a ReadableStream<Uint8Array> and return a Promise<Uint8Array>.
Configuration
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