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

packages/core/test/lazy-browser.test.js

@@ -0,0 +1,82 @@
+// Lazy routes in the browser (happy-dom): loading view while the module
+// is in flight, morph to the real view on arrival, PENDING keeps the
+// current tree during route changes, view cached after first load.
+
+import { test, before } from 'node:test'
+import assert from 'node:assert'
+import { Window } from 'happy-dom'
+
+let choo, lazy, html
+
+before(async () => {
+  const win = new Window({ url: 'http://localhost/' })
+  globalThis.window = win
+  globalThis.document = win.document
+  globalThis.requestAnimationFrame = win.requestAnimationFrame.bind(win)
+  ;({ default: choo, lazy } = await import('@choojs/core'))
+  ;({ default: html } = await import('@choojs/html/browser'))
+})
+
+const tick = (ms = 30) => new Promise((resolve) => setTimeout(resolve, ms))
+
+test('lazy route with a loading view: loading first, real view after', async () => {
+  let resolveLoader
+  const loaderDone = new Promise((resolve) => { resolveLoader = resolve })
+
+  const app = choo()
+  app.route('/', lazy(
+    () => loaderDone,
+    () => html`<div><p>loading…</p></div>`
+  ))
+
+  const tree = app.start()
+  assert.strictEqual(tree.textContent, 'loading…', 'loading view rendered while in flight')
+
+  resolveLoader({ default: (state) => html`<div><p>arrived</p></div>` })
+  await tick()
+  assert.strictEqual(tree.textContent, 'arrived', 'real view morphed in over the loading view')
+})
+
+test('lazy route without a loading view: placeholder, then wholesale replace', async () => {
+  let resolveLoader
+  const loaderDone = new Promise((resolve) => { resolveLoader = resolve })
+
+  const app = choo()
+  app.route('/', lazy(() => loaderDone))
+
+  const tree = app.start()
+  assert.ok(tree.hasAttribute('data-choo-pending'), 'placeholder holds the spot')
+  document.body.appendChild(tree)
+
+  resolveLoader({ default: (state) => html`<main><h1>real</h1></main>` })
+  await tick()
+
+  assert.strictEqual(document.querySelector('main h1').textContent, 'real', 'real view replaced the placeholder in the DOM')
+  assert.strictEqual(document.querySelector('[data-choo-pending]'), null, 'placeholder gone')
+  document.querySelector('main').remove()
+})
+
+test('loaded lazy views render synchronously ever after', async () => {
+  const view = (state) => html`<div>cached ${state.count}</div>`
+  const wrapped = lazy(() => Promise.resolve({ default: view }))
+
+  const app = choo()
+  app.use((state, emitter) => {
+    state.count = 0
+    emitter.on('bump', () => { state.count++; emitter.emit('render') })
+  })
+  app.route('/', wrapped)
+
+  // no loading view: the placeholder must live in the DOM to be replaced
+  const holder = document.createElement('section')
+  document.body.appendChild(holder)
+  holder.appendChild(app.start())
+  await tick() // let the loader resolve + re-render
+
+  assert.strictEqual(holder.textContent, 'cached 0')
+
+  app.emit('bump')
+  await tick()
+  assert.strictEqual(holder.textContent, 'cached 1', 'subsequent renders are sync through the cache')
+  holder.remove()
+})

packages/core/test/stream.test.js

@@ -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/)
+})