inertjs-vector 1.0.0-beta.7 → 1.0.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inertjs-vector",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "type": "module",
   "main": "src/index.js",
   "dependencies": {

package/src/index.js

@@ -1,6 +1,10 @@
 import { analyzeTemplateStrings, escape, CONTEXT } from './escaper.js';
 import { minifyHTML } from 'inertjs-optimizer';
 export { resolveToString } from './resolve.js';
+export { renderToStream, DeferTimeoutError } from './stream.js';
+// NOTE: index <-> stream is a cycle (stream imports RawString from here). Both
+// only touch each other's bindings at call time, by which point ESM has finished
+// initialising both modules, so the re-export above is safe.
 
 const planCache = new WeakMap();
 
@@ -44,13 +48,17 @@ export function raw(str, suppressWarning = false) {
  * `fallback` / `error` content is treated as trusted HTML (like `raw()`), so
  * interpolate untrusted values through `vec\`\`` before handing them in.
  *
- * @param {Promise<any>|AsyncIterable<any>|object|(() => any)} source
- *   The deferred value, or a factory that produces it (called lazily; a throw
- *   from the factory is caught and routed to `error`).
+ * @param {Promise<any>|AsyncIterable<any>|object|((ctx: { signal: AbortSignal }) => any)} source
+ *   The deferred value, or a factory that produces it (called lazily with an
+ *   `{ signal }` that aborts when the response is torn down; a throw from the
+ *   factory is caught and routed to `error`).
  * @param {object} [options]
  * @param {string|RawString} [options.fallback] Skeleton shown while pending.
  * @param {string|RawString|object|((err: Error) => string|RawString|object)} [options.error]
- *   Content to patch in if `source` rejects. A function receives the error.
+ *   Content to patch in if `source` rejects or times out. A function receives the error.
+ * @param {number} [options.timeout]
+ *   Milliseconds to wait before failing the fragment with a `DeferTimeoutError`
+ *   (routed to `error` / `onError` like any other rejection).
  * @returns {DeferredFragment}
  */
 export function defer(source, options = {}) {
@@ -64,6 +72,7 @@ export class DeferredFragment {
     this.source = source;
     this.fallback = options.fallback ?? null;
     this.error = options.error ?? null;
+    this.timeout = options.timeout ?? null;
   }
 }
 

package/src/stream.js

@@ -1,28 +1,84 @@
-import { escape } from './escaper.js';
+import { escape, CONTEXT } from './escaper.js';
 import { RawString } from './index.js';
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
-const PATCHER_SCRIPT = `<script nonce="[INERT_NONCE]">
+/**
+ * Error handed to the error boundary / `onError` hook when a deferred fragment
+ * exceeds its `timeout`.
+ */
+export class DeferTimeoutError extends Error {
+  constructor(slotId, ms) {
+    super(`Deferred fragment in slot ${slotId} timed out after ${ms}ms`);
+    this.name = 'DeferTimeoutError';
+    this.code = 'E_INERT_FRAGMENT_TIMEOUT';
+    this.slot = slotId;
+    this.timeout = ms;
+  }
+}
+
+function isDev() {
+  return typeof process !== 'undefined' && !!process.env && process.env.NODE_ENV !== 'production';
+}
+
+/**
+ * One inline script, emitted once into the shell. It applies every streamed
+ * `<template data-i-fill>` patch — synchronously for those already parsed, and
+ * via a MutationObserver for those that arrive later in the stream. Replaces the
+ * previous approach of re-emitting a full patcher script after every patch
+ * (which was O(n²) and multiplied inline-script surface under CSP).
+ */
+function bootstrapScript(nonce) {
+  return `<script nonce="${nonce}">
 (function(){
-  const ds=document.querySelectorAll('template[data-i-fill]');
-  for(let d of ds){
-    const id=d.getAttribute('data-i-fill');
-    const slot=document.getElementById('i-slot-'+id);
+  var W=window,D=document;
+  function patch(t){
+    var id=t.getAttribute('data-i-fill');
+    var slot=D.getElementById('i-slot-'+id);
     if(slot){
-      const errored=d.hasAttribute('data-i-error');
-      slot.replaceWith(d.content);
+      var errored=t.hasAttribute('data-i-error');
+      slot.replaceWith(t.content);
       if(errored){
-        const s=(window.__inert=window.__inert||{});
+        var s=(W.__inert=W.__inert||{});
         s.fragmentErrors=(s.fragmentErrors||0)+1;
-        try{window.dispatchEvent(new CustomEvent('inert:fragment:error',{detail:{slot:id}}));}catch(e){}
+        try{W.dispatchEvent(new CustomEvent('inert:fragment:error',{detail:{slot:id}}));}catch(e){}
       }
     }
-    d.remove();
+    if(t.parentNode)t.remove();
+  }
+  function sweep(root){
+    var ts=(root||D).querySelectorAll('template[data-i-fill]');
+    for(var i=0;i<ts.length;i++)patch(ts[i]);
+  }
+  sweep();
+  if(W.MutationObserver){
+    var mo=new MutationObserver(function(muts){
+      for(var i=0;i<muts.length;i++){
+        var added=muts[i].addedNodes;
+        for(var j=0;j<added.length;j++){
+          var n=added[j];
+          if(n.nodeType!==1)continue;
+          if(n.tagName==='TEMPLATE'&&n.hasAttribute('data-i-fill'))patch(n);
+          else if(n.querySelector&&n.querySelector('template[data-i-fill]'))sweep(n);
+        }
+      }
+    });
+    mo.observe(D.documentElement,{childList:true,subtree:true});
+    var done=function(){sweep();mo.disconnect();};
+    if(D.readyState==='complete')done();
+    else W.addEventListener('load',done);
+  }else{
+    W.addEventListener('load',function(){sweep();});
   }
 })();
 </script>`;
+}
+
+/** A bare patch: the bootstrap script (already in the shell) applies it. */
+function fillPatch(slotId, html, errored) {
+  return `\n<template data-i-fill="${slotId}"${errored ? ' data-i-error="1"' : ''}>${html}</template>`;
+}
 
 /**
  * Fully drains a WHATWG ReadableStream of Uint8Array chunks into a string,
@@ -48,15 +104,15 @@ async function drainStream(readable) {
  * Resolves an already-settled value (the result of `await`ing a hole) into an
  * HTML string, recursing through nested streams, RawStrings and arrays.
  */
-async function valueToHtml(value, ctx, attrName, nonce) {
+async function valueToHtml(value, ctx, attrName, nonce, options) {
   if (value == null || value === false) return '';
   if (value instanceof RawString) return value.value;
   if (value && value.type === 'VecStream') {
-    return drainStream(renderToStream(value, nonce));
+    return drainStream(renderToStream(value, nonce, options));
   }
   if (Array.isArray(value)) {
     let out = '';
-    for (const item of value) out += await valueToHtml(item, ctx, attrName, nonce);
+    for (const item of value) out += await valueToHtml(item, ctx, attrName, nonce, options);
     return out;
   }
   return escape(value, ctx, attrName);
@@ -72,27 +128,41 @@ function skeletonHtml(fragment) {
 }
 
 /** Resolves a fragment's error boundary content once the source has rejected. */
-async function errorBoundaryHtml(fragment, err, ctx, attrName, nonce) {
+async function errorBoundaryHtml(fragment, err, slotId, ctx, attrName, nonce, options) {
   let content = fragment && fragment.error;
   if (typeof content === 'function') {
     try {
       content = content(err);
     } catch (boundaryErr) {
       console.error('[InertJS] Fragment error boundary threw:', boundaryErr);
-      return '';
+      content = null;
+    }
+  }
+  if (content == null) {
+    if (isDev()) {
+      const msg = escape(err && err.message ? err.message : String(err), CONTEXT.TEXT);
+      return `<div data-inert-fragment-error style="border:1px dashed #f43f5e;background:#fff1f2;color:#9f1239;` +
+        `padding:6px 10px;font:12px/1.5 ui-monospace,monospace;border-radius:4px">` +
+        `⚠ InertJS fragment ${slotId} failed: ${msg}</div>`;
     }
+    return '';
   }
-  if (content == null) return '';
   if (content instanceof RawString) return content.value;
   if (content && content.type === 'VecStream') {
-    return drainStream(renderToStream(content, nonce));
+    return drainStream(renderToStream(content, nonce, options));
   }
   return String(content);
 }
 
-function fillPatch(slotId, html, nonce, errored) {
-  return `\n<template data-i-fill="${slotId}"${errored ? ' data-i-error="1"' : ''}>${html}</template>` +
-    PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
+/** Races a fragment's html production against its `timeout`, if any. */
+function withTimeout(promise, ms, slotId) {
+  if (!ms || ms <= 0) return promise;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new DeferTimeoutError(slotId, ms)), ms);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
 /**
@@ -110,7 +180,10 @@ function fillPatch(slotId, html, nonce, errored) {
  * @param {string} [nonce] The CSP nonce for inline scripts
  * @param {object} [options]
  * @param {(err: Error, info: { slot: number }) => void} [options.onError]
- *   Called for every hole that rejects after the shell was flushed.
+ *   Called for every hole that rejects (or times out) after the shell flushed.
+ * @param {AbortSignal} [options.signal]
+ *   Aborting it stops the stream and is forwarded to deferred fragment
+ *   factories as `defer(({ signal }) => ...)`.
  * @returns {ReadableStream}
  */
 export function renderToStream(vecResult, nonce = '', options = {}) {
@@ -126,6 +199,17 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
 
   const { plan, values } = vecResult;
   const onError = typeof options.onError === 'function' ? options.onError : null;
+
+  // Every render has a real AbortSignal so `defer` factories can always rely on
+  // `({ signal })`. It fires when the caller's signal fires, when the consumer
+  // cancels the stream, or when a write reveals the client has gone away.
+  const abort = new AbortController();
+  const signal = abort.signal;
+  if (options.signal) {
+    if (options.signal.aborted) abort.abort();
+    else options.signal.addEventListener('abort', () => abort.abort(), { once: true });
+  }
+
   let slotCounter = 0;
   const pendingTasks = new Set();
 
@@ -134,12 +218,13 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
       let closed = false;
 
       const enqueue = (str) => {
-        if (closed) return;
+        if (closed || signal.aborted) return;
         try {
           controller.enqueue(encoder.encode(str));
         } catch {
-          // Client went away; stop trying to write.
+          // Client went away; stop trying to write and let fragments bail.
           closed = true;
+          abort.abort();
         }
       };
 
@@ -153,6 +238,12 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
         }
       };
 
+      if (signal.aborted) {
+        closeController();
+        return;
+      }
+      signal.addEventListener('abort', closeController, { once: true });
+
       try {
         let initialHtml = plan.statics[0];
 
@@ -173,28 +264,31 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
 
             const task = (async () => {
               try {
-                let source = fragment ? fragment.source : val;
-                if (typeof source === 'function') source = source();
-
-                let html;
-                if (source && source.type === 'VecStream') {
-                  html = await drainStream(renderToStream(source, nonce, options));
-                } else if (source && typeof source[Symbol.asyncIterator] === 'function') {
-                  let accumulated = '';
-                  for await (const chunk of source) {
-                    accumulated += chunk instanceof RawString
-                      ? chunk.value
-                      : escape(chunk, ctx, attrName);
+                const build = (async () => {
+                  let source = fragment ? fragment.source : val;
+                  if (typeof source === 'function') source = source({ signal });
+
+                  if (source && source.type === 'VecStream') {
+                    return drainStream(renderToStream(source, nonce, options));
                   }
-                  html = accumulated;
-                } else {
-                  html = await valueToHtml(await source, ctx, attrName, nonce);
-                }
+                  if (source && typeof source[Symbol.asyncIterator] === 'function') {
+                    let accumulated = '';
+                    for await (const chunk of source) {
+                      accumulated += chunk instanceof RawString
+                        ? chunk.value
+                        : escape(chunk, ctx, attrName);
+                    }
+                    return accumulated;
+                  }
+                  return valueToHtml(await source, ctx, attrName, nonce, options);
+                })();
+                build.catch(() => {}); // a lost timeout race must not warn
 
-                enqueue(fillPatch(slotId, html, nonce, false));
+                const html = await withTimeout(build, fragment && fragment.timeout, slotId);
+                enqueue(fillPatch(slotId, html, false));
               } catch (err) {
                 console.error(
-                  `[InertJS] Deferred fragment in slot ${slotId} rejected after the shell was flushed:`,
+                  `[InertJS] Deferred fragment in slot ${slotId} failed after the shell was flushed:`,
                   err
                 );
                 if (onError) {
@@ -206,11 +300,11 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
                 }
                 let boundary = '';
                 try {
-                  boundary = await errorBoundaryHtml(fragment, err, ctx, attrName, nonce);
+                  boundary = await errorBoundaryHtml(fragment, err, slotId, ctx, attrName, nonce, options);
                 } catch (boundaryErr) {
                   console.error('[InertJS] Fragment error boundary failed:', boundaryErr);
                 }
-                enqueue(fillPatch(slotId, boundary, nonce, true));
+                enqueue(fillPatch(slotId, boundary, true));
               } finally {
                 pendingTasks.delete(task);
                 if (pendingTasks.size === 0) closeController();
@@ -231,6 +325,11 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
           initialHtml += plan.statics[i + 1];
         }
 
+        // One patcher for the whole document, only when something actually streams.
+        if (slotCounter > 0) {
+          initialHtml += bootstrapScript(nonce);
+        }
+
         // Flush the synchronous initial shell
         enqueue(initialHtml);
 
@@ -246,6 +345,10 @@ export function renderToStream(vecResult, nonce = '', options = {}) {
           /* already torn down */
         }
       }
+    },
+    cancel() {
+      // Consumer walked away: let in-flight fragment work abort itself.
+      abort.abort();
     }
   });
 }

package/test/streaming-error.test.js

@@ -106,3 +106,97 @@ test('Out-of-order streaming: fragment errors after shell flush', async (t) => {
     assert.strictEqual(await resolveToString(vec`<p>${failed}</p>`), '<p><i>oops</i></p>');
   });
 });
+
+test('Out-of-order streaming: hardening (beta.8)', async (t) => {
+  await t.test('one bootstrap patcher script, patches are bare templates', async () => {
+    const a = Promise.resolve(raw('<p>a</p>'));
+    const b = Promise.resolve(raw('<p>b</p>'));
+    const html = await collect(renderToStream(vec`<div>${a}</div><div>${b}</div>`, 'nn'));
+
+    const scripts = html.match(/<script nonce="nn">/g) || [];
+    assert.strictEqual(scripts.length, 1, 'exactly one inline script');
+    assert.ok(html.includes('MutationObserver'), 'bootstrap installs a MutationObserver');
+    assert.match(html, /<template data-i-fill="1"><p>a<\/p><\/template>/);
+    assert.match(html, /<template data-i-fill="2"><p>b<\/p><\/template>/);
+  });
+
+  await t.test('no patcher script when nothing streams', async () => {
+    const html = await collect(renderToStream(vec`<p>${Promise.resolve('x')}</p>`, 'z'));
+    // one slot -> one script; a fully sync template never reaches renderToStream's stream path
+    assert.ok(html.includes('<script nonce="z">'));
+    const sync = await collect(renderToStream(raw('<p>hi</p>'), 'z'));
+    assert.strictEqual(sync, '<p>hi</p>');
+  });
+
+  await t.test('defer timeout patches the error boundary and closes the stream', async () => {
+    const frag = defer(new Promise(() => {}), { timeout: 40, error: raw('<p>too slow</p>') });
+    const html = await collect(renderToStream(vec`<main>${frag}</main>`, 'n'), 2000);
+    assert.ok(html.includes('data-i-error="1"'));
+    assert.ok(html.includes('<p>too slow</p>'));
+  });
+
+  await t.test('timeout surfaces as DeferTimeoutError on the onError hook', async () => {
+    const seen = [];
+    const frag = defer(new Promise(() => {}), { timeout: 30 });
+    await collect(renderToStream(vec`<main>${frag}</main>`, 'n', {
+      onError: (err) => seen.push(err)
+    }), 2000);
+    assert.strictEqual(seen.length, 1);
+    assert.strictEqual(seen[0].code, 'E_INERT_FRAGMENT_TIMEOUT');
+    assert.strictEqual(seen[0].slot, 1);
+  });
+
+  await t.test('abort signal stops the stream', async () => {
+    const ac = new AbortController();
+    const frag = defer(new Promise(() => {}), { fallback: raw('<i>loading</i>') });
+    const reader = renderToStream(vec`<main>${frag}</main>`, 'n', { signal: ac.signal }).getReader();
+
+    const shell = decoder.decode((await reader.read()).value);
+    assert.ok(shell.includes('i-slot-1'));
+    ac.abort();
+    assert.strictEqual((await reader.read()).done, true, 'closed after abort');
+  });
+
+  await t.test('a pre-aborted signal yields an immediately-closed stream', async () => {
+    const ac = new AbortController();
+    ac.abort();
+    const reader = renderToStream(vec`<main>${Promise.resolve('x')}</main>`, 'n', { signal: ac.signal }).getReader();
+    assert.strictEqual((await reader.read()).done, true);
+  });
+
+  await t.test('fragment factory receives an abort signal', async () => {
+    let received;
+    const frag = defer(({ signal }) => { received = signal; return Promise.resolve(raw('ok')); });
+    await collect(renderToStream(vec`<main>${frag}</main>`, 'n'));
+    assert.ok(received && typeof received.aborted === 'boolean');
+  });
+
+  await t.test('dev mode: a boundary-less failure renders a visible marker', async () => {
+    const prev = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
+    try {
+      const bad = Promise.reject(new Error('kaboom <x>'));
+      bad.catch(() => {});
+      const html = await collect(renderToStream(vec`<main>${bad}</main>`, 'n'));
+      assert.ok(html.includes('data-inert-fragment-error'));
+      assert.ok(html.includes('kaboom &lt;x&gt;'), 'error message is escaped');
+    } finally {
+      if (prev !== undefined) process.env.NODE_ENV = prev;
+    }
+  });
+
+  await t.test('production mode: a boundary-less failure renders nothing visible', async () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+      const bad = Promise.reject(new Error('kaboom'));
+      bad.catch(() => {});
+      const html = await collect(renderToStream(vec`<main>${bad}</main>`, 'n'));
+      assert.ok(html.includes('data-i-fill="1" data-i-error="1"'));
+      assert.ok(!html.includes('data-inert-fragment-error'));
+      assert.match(html, /<template data-i-fill="1" data-i-error="1"><\/template>/);
+    } finally {
+      if (prev !== undefined) process.env.NODE_ENV = prev; else delete process.env.NODE_ENV;
+    }
+  });
+});