feat(core): toStream() and lazy() routes — the answer to choojs/choo#653

toStream(location, state) renders to a web-standard ReadableStream of UTF-8 bytes: pass it to new Response() on web servers or Readable.fromWeb().pipe(res) on Node. It awaits store prefetch promises (state.prefetch, the pattern the #653 thread wanted standardized) and lazy route views before rendering, then flushes template output progressively through async holes. lazy(loader, loadingView?) wraps a dynamic import as a route handler: loads once, caches forever, renders the loading view (or holds the current tree via a placeholder) while in flight, emits render on arrival. toString() refuses lazy routes and prefetching stores with pointers to toStream() — both halves of the async-route story ship together, unlike the original PR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NgfSjHE11oFpoSnLVKLXd
2026-09-08 18:43:40 +02:00
parent 9cf9e51ac9
commit 22c5045c25
4 changed files with 318 additions and 2 deletions
@@ -0,0 +1,96 @@
+// choo.toStream(): web-standard streaming SSR with prefetch and lazy routes.
+
+import { test } from 'node:test'
+import assert from 'node:assert'
+
+import html from '@choojs/html'
+import choo, { lazy } from '@choojs/core'
+
+const wait = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms))
+
+async function readAll (stream) {
+  const decoder = new TextDecoder()
+  const chunks = []
+  for await (const chunk of stream) chunks.push(decoder.decode(chunk, { stream: true }))
+  return chunks
+}
+
+test('toStream matches toString for a plain sync app', async () => {
+  const makeApp = () => {
+    const app = choo()
+    app.route('/', (state) => html`<div><h1>hi</h1></div>`)
+    return app
+  }
+  const chunks = await readAll(makeApp().toStream('/'))
+  assert.strictEqual(chunks.join(''), makeApp().toString('/'))
+})
+
+test('returns a web ReadableStream', () => {
+  const app = choo()
+  app.route('/', () => html`<div></div>`)
+  assert.ok(app.toStream('/') instanceof ReadableStream)
+})
+
+test('stores can defer rendering with state.prefetch promises', async () => {
+  const app = choo()
+  app.use((state) => {
+    state.user = null
+    state.prefetch.push(wait(10, null).then(() => { state.user = 'bendik' }))
+  })
+  app.route('/', (state) => html`<p>hello ${state.user}</p>`)
+
+  const chunks = await readAll(app.toStream('/'))
+  assert.strictEqual(chunks.join(''), '<p>hello bendik</p>', 'render waited for prefetch')
+})
+
+test('toString refuses prefetching stores with guidance', () => {
+  const app = choo()
+  app.use((state) => { state.prefetch.push(Promise.resolve()) })
+  app.route('/', () => html`<div></div>`)
+  assert.throws(() => app.toString('/'), /toStream/)
+})
+
+test('async template holes stream: shell first, slow content later', async () => {
+  const app = choo()
+  app.route('/', (state) => html`<body><h1>shell</h1>${wait(15, html`<section>slow</section>`)}</body>`)
+
+  const stream = app.toStream('/')
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+
+  const started = performance.now()
+  const first = decoder.decode((await reader.read()).value)
+  const firstAt = performance.now() - started
+
+  assert.strictEqual(first, '<body><h1>shell</h1>', 'shell flushed immediately')
+  assert.ok(firstAt < 10, `shell arrived before the slow hole resolved (${firstAt.toFixed(1)}ms)`)
+
+  let rest = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    rest += decoder.decode(value, { stream: true })
+  }
+  assert.strictEqual(rest, '<section>slow</section></body>')
+})
+
+test('toStream awaits lazy route views; toString refuses them', async () => {
+  const makeApp = () => {
+    const app = choo()
+    app.route('/', lazy(() => wait(10, {
+      default: (state) => html`<main>lazy view</main>`
+    })))
+    return app
+  }
+
+  assert.throws(() => makeApp().toString('/'), /toStream/)
+
+  const chunks = await readAll(makeApp().toStream('/'))
+  assert.strictEqual(chunks.join(''), '<main>lazy view</main>')
+})
+
+test('stream errors propagate through the stream, not as sync throws', async () => {
+  const app = choo()
+  app.route('/', () => html`<div>${Promise.reject(new Error('boom'))}</div>`)
+  await assert.rejects(async () => readAll(app.toStream('/')), /boom/)
+})