inertjs-vector 1.0.0-beta.0

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "inertjs-vector",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "main": "src/index.js",
+  "dependencies": {
+    "inertjs-optimizer": "^1.0.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/escaper.js

@@ -0,0 +1,211 @@
+export const CONTEXT = {
+  TEXT: 0,
+  TAG_NAME: 1,
+  ATTR_NAME: 2,
+  ATTR_VALUE_UNQUOTED: 3,
+  ATTR_VALUE_SINGLE: 4,
+  ATTR_VALUE_DOUBLE: 5,
+  SCRIPT: 6,
+  STYLE: 7,
+};
+
+export const URL_ATTRIBUTES = new Set(['href', 'src', 'action', 'formaction', 'data', 'manifest', 'poster']);
+
+/**
+ * Escapes a string for insertion into a specific HTML context.
+ * 
+ * @param {string} value The value to escape.
+ * @param {number} context The CONTEXT enum value.
+ * @param {string} attrName The name of the attribute (if in an attribute context).
+ * @returns {string} The escaped string.
+ * @throws {Error} If interpolation is hard-refused in this context.
+ */
+export function escape(value, context, attrName = '') {
+  if (value == null) return '';
+  const str = String(value);
+
+  switch (context) {
+    case CONTEXT.SCRIPT:
+    case CONTEXT.STYLE:
+      throw new Error(`E_INERT_VECTOR_UNSAFE: Interpolation inside <script> or <style> is hard-refused. Use raw() if absolutely necessary, but be aware of XSS.`);
+    
+    case CONTEXT.TEXT:
+      return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    
+    case CONTEXT.ATTR_VALUE_DOUBLE:
+      if (URL_ATTRIBUTES.has(attrName.toLowerCase())) {
+        if (/^\s*javascript:/i.test(str)) {
+          throw new Error(`E_INERT_VECTOR_UNSAFE: javascript: URLs are hard-refused in URL attributes.`);
+        }
+      }
+      return str
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    
+    case CONTEXT.ATTR_VALUE_SINGLE:
+      if (URL_ATTRIBUTES.has(attrName.toLowerCase())) {
+        if (/^\s*javascript:/i.test(str)) {
+          throw new Error(`E_INERT_VECTOR_UNSAFE: javascript: URLs are hard-refused in URL attributes.`);
+        }
+      }
+      return str
+        .replace(/&/g, '&amp;')
+        .replace(/'/g, '&#39;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+
+    case CONTEXT.ATTR_VALUE_UNQUOTED:
+      if (URL_ATTRIBUTES.has(attrName.toLowerCase())) {
+        if (/^\s*javascript:/i.test(str)) {
+          throw new Error(`E_INERT_VECTOR_UNSAFE: javascript: URLs are hard-refused in URL attributes.`);
+        }
+      }
+      return str
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/`/g, '&#96;')
+        .replace(/\s/g, '&#32;'); // Spaces break unquoted attributes
+        
+    case CONTEXT.TAG_NAME:
+    case CONTEXT.ATTR_NAME:
+      // Strictly alphanumeric/dashes for tag/attr names to prevent breaking out
+      if (!/^[a-z0-9-]+$/i.test(str)) {
+        throw new Error(`E_INERT_VECTOR_UNSAFE: Invalid characters in tag or attribute name interpolation.`);
+      }
+      return str;
+      
+    default:
+      throw new Error(`E_INERT_VECTOR_UNSAFE: Unknown context ${context}`);
+  }
+}
+
+/**
+ * A basic state machine to determine the HTML context at the end of a string chunk.
+ */
+export function analyzeTemplateStrings(strings) {
+  const statics = [...strings];
+  const contexts = [];
+  const attrNames = [];
+  
+  let state = CONTEXT.TEXT;
+  let currentAttrName = '';
+
+  for (let i = 0; i < strings.length - 1; i++) {
+    const chunk = strings[i];
+    
+    // We process the chunk character by character to track the state
+    for (let j = 0; j < chunk.length; j++) {
+      const char = chunk[j];
+      
+      switch (state) {
+        case CONTEXT.TEXT:
+          if (char === '<') {
+            // Check for </script> or </style>
+            if (chunk.startsWith('</script>', j) || chunk.startsWith('</SCRIPT>', j)) {
+              j += 8;
+            } else if (chunk.startsWith('</style>', j) || chunk.startsWith('</STYLE>', j)) {
+              j += 7;
+            } else if (chunk.startsWith('!--', j + 1)) {
+              // Comment - simplified, just let it be TEXT for now as it's safe to escape
+            } else if (chunk.startsWith('script', j + 1) || chunk.startsWith('SCRIPT', j + 1)) {
+               state = CONTEXT.TAG_NAME; // Going into script tag definition
+            } else if (chunk.startsWith('style', j + 1) || chunk.startsWith('STYLE', j + 1)) {
+               state = CONTEXT.TAG_NAME; // Going into style tag definition
+            } else {
+              state = CONTEXT.TAG_NAME;
+            }
+          }
+          break;
+          
+        case CONTEXT.TAG_NAME:
+          if (/\s/.test(char)) {
+            state = CONTEXT.ATTR_NAME;
+            currentAttrName = '';
+          } else if (char === '>') {
+            // Determine if we just opened a script or style
+            // We need to look back to see the tag name
+            const tagMatch = chunk.substring(0, j).match(/<\s*([a-z0-9-]+)[^>]*$/i);
+            const tag = tagMatch ? tagMatch[1].toLowerCase() : '';
+            if (tag === 'script') state = CONTEXT.SCRIPT;
+            else if (tag === 'style') state = CONTEXT.STYLE;
+            else state = CONTEXT.TEXT;
+          }
+          break;
+          
+        case CONTEXT.ATTR_NAME:
+          if (char === '=') {
+            state = CONTEXT.ATTR_VALUE_UNQUOTED;
+          } else if (char === '>') {
+            const tagMatch = chunk.substring(0, j).match(/<\s*([a-z0-9-]+)[^>]*$/i);
+            const tag = tagMatch ? tagMatch[1].toLowerCase() : '';
+            if (tag === 'script') state = CONTEXT.SCRIPT;
+            else if (tag === 'style') state = CONTEXT.STYLE;
+            else state = CONTEXT.TEXT;
+          } else if (/\s/.test(char)) {
+            // Keep in ATTR_NAME
+          } else {
+            currentAttrName += char;
+          }
+          break;
+          
+        case CONTEXT.ATTR_VALUE_UNQUOTED:
+          if (char === '"') {
+            state = CONTEXT.ATTR_VALUE_DOUBLE;
+          } else if (char === "'") {
+            state = CONTEXT.ATTR_VALUE_SINGLE;
+          } else if (/\s/.test(char)) {
+            state = CONTEXT.ATTR_NAME;
+            currentAttrName = '';
+          } else if (char === '>') {
+            const tagMatch = chunk.substring(0, j).match(/<\s*([a-z0-9-]+)[^>]*$/i);
+            const tag = tagMatch ? tagMatch[1].toLowerCase() : '';
+            if (tag === 'script') state = CONTEXT.SCRIPT;
+            else if (tag === 'style') state = CONTEXT.STYLE;
+            else state = CONTEXT.TEXT;
+          }
+          break;
+          
+        case CONTEXT.ATTR_VALUE_DOUBLE:
+          if (char === '"') {
+            state = CONTEXT.ATTR_NAME;
+            currentAttrName = '';
+          }
+          break;
+          
+        case CONTEXT.ATTR_VALUE_SINGLE:
+          if (char === "'") {
+            state = CONTEXT.ATTR_NAME;
+            currentAttrName = '';
+          }
+          break;
+          
+        case CONTEXT.SCRIPT:
+          if (char === '<' && (chunk.startsWith('</script>', j) || chunk.startsWith('</SCRIPT>', j))) {
+            state = CONTEXT.TAG_NAME; // Closing tag
+            j += 8;
+          }
+          break;
+          
+        case CONTEXT.STYLE:
+           if (char === '<' && (chunk.startsWith('</style>', j) || chunk.startsWith('</STYLE>', j))) {
+            state = CONTEXT.TAG_NAME; // Closing tag
+            j += 7;
+          }
+          break;
+      }
+    }
+    
+    contexts.push(state);
+    attrNames.push(currentAttrName.trim());
+  }
+
+  return { statics, contexts, attrNames };
+}

package/src/index.js

@@ -0,0 +1,102 @@
+import { analyzeTemplateStrings, escape, CONTEXT } from './escaper.js';
+import { minifyHTML } from 'inertjs-optimizer';
+export { resolveToString } from './resolve.js';
+
+const planCache = new WeakMap();
+
+export class RawString {
+  constructor(str) {
+    this.value = str;
+  }
+  toString() {
+    return this.value;
+  }
+}
+
+/**
+ * Opt-out of HTML escaping. 
+ * Use with extreme caution.
+ * 
+ * @param {string} str Unescaped HTML string
+ * @returns {RawString}
+ */
+export function raw(str, suppressWarning = false) {
+  if (!suppressWarning && process.env.NODE_ENV !== 'production') {
+    const stack = new Error().stack;
+    // index 1 is raw(), index 2 is the caller
+    const callSite = stack && stack.split('\n')[2] ? stack.split('\n')[2].trim() : 'unknown location';
+    console.warn(`[Lens] Warning: raw() escape hatch used at ${callSite}. Ensure this string is safe.`);
+  }
+  return new RawString(str);
+}
+
+/**
+ * Tagged template literal for Vector template engine.
+ * Safely escapes all interpolations based on their HTML context.
+ * 
+ * @param {TemplateStringsArray} strings 
+ * @param  {...any} values 
+ */
+export function vec(strings, ...values) {
+  let plan = planCache.get(strings);
+  if (!plan) {
+    plan = analyzeTemplateStrings(strings);
+    // Minify statics on the fly during template parse
+    plan.statics = plan.statics.map(staticStr => minifyHTML(staticStr));
+    planCache.set(strings, plan);
+  }
+
+  // Check if we need to stream (any value is a Promise or AsyncIterable)
+  const isAsync = values.some(v => v instanceof Promise || (v && typeof v[Symbol.asyncIterator] === 'function') || (v && v.type === 'VecStream'));
+  
+  if (isAsync) {
+    return {
+      type: 'VecStream',
+      plan,
+      values
+    };
+  }
+
+  let result = plan.statics[0];
+  for (let i = 0; i < values.length; i++) {
+    const val = values[i];
+    const ctx = plan.contexts[i];
+    const attrName = plan.attrNames[i];
+
+    if (val instanceof RawString) {
+      result += val.value;
+    } else if (val && val.type === 'VecStream') {
+       throw new Error('E_INERT_VECTOR_NESTED_ASYNC: Async nested vec`` found in synchronous render context.');
+    } else if (Array.isArray(val)) {
+       result += val.map(v => v instanceof RawString ? v.value : escape(v, ctx, attrName)).join('');
+    } else {
+      result += escape(val, ctx, attrName);
+    }
+    result += plan.statics[i + 1];
+  }
+  
+  // Return RawString so nested `vec` calls aren't double-escaped
+  return new RawString(result);
+}
+
+/**
+ * Generates an optimized image tag that hooks into InertJS's on-the-fly optimizer.
+ * 
+ * @param {object} props Image properties: src, width, height, quality, class, alt
+ * @returns {RawString}
+ */
+export function img({ src, width, height, quality, ...rest }) {
+  const query = new URLSearchParams();
+  query.set('src', src);
+  if (width) query.set('w', width);
+  if (height) query.set('h', height);
+  if (quality) query.set('q', quality);
+
+  const url = `/_inert/image?${query.toString()}`;
+  
+  const attrs = Object.entries(rest)
+    .map(([key, val]) => `${key}="${escape(val, CONTEXT.ATTR_VALUE_DOUBLE)}"`)
+    .join(' ');
+    
+  return raw(`<img src="${url}" ${attrs} />`, true);
+}

package/src/resolve.js

@@ -0,0 +1,48 @@
+import { escape } from './escaper.js';
+import { RawString } from './index.js';
+
+/**
+ * Fully resolves a VecStream and all its asynchronous holes into a single string.
+ */
+export async function resolveToString(val, ctx = 'text', attrName = '') {
+  if (val == null || val === false) return '';
+  if (typeof val === 'string' || typeof val === 'number') return escape(String(val), ctx, attrName);
+  if (val instanceof RawString) return val.value;
+  
+  if (val instanceof Promise) {
+    return resolveToString(await val, ctx, attrName);
+  }
+
+  if (Array.isArray(val)) {
+    let res = '';
+    for (const item of val) {
+      res += await resolveToString(item, ctx, attrName);
+    }
+    return res;
+  }
+
+  if (val && val.type === 'VecStream') {
+    let result = '';
+    for (let i = 0; i < val.values.length; i++) {
+      result += val.plan.statics[i];
+      
+      const part = val.values[i];
+      const nextCtx = val.plan.contexts[i];
+      const nextAttrName = val.plan.attrNames[i];
+
+      result += await resolveToString(part, nextCtx, nextAttrName);
+    }
+    result += val.plan.statics[val.plan.statics.length - 1];
+    return result;
+  }
+  
+  if (val && typeof val[Symbol.asyncIterator] === 'function') {
+    let res = '';
+    for await (const chunk of val) {
+      res += await resolveToString(chunk, ctx, attrName);
+    }
+    return res;
+  }
+
+  return escape(String(val), ctx, attrName);
+}

package/src/stream.js

@@ -0,0 +1,142 @@
+import { escape } from './escaper.js';
+import { RawString } from './index.js';
+
+const encoder = new TextEncoder();
+
+const PATCHER_SCRIPT = `<script nonce="[INERT_NONCE]">
+(function(){
+  const ds=document.querySelectorAll('template[data-i-fill]');
+  for(let d of ds){
+    const id=d.getAttribute('data-i-fill');
+    const target=document.getElementById('i-slot-'+id);
+    if(target){
+      target.replaceWith(d.content);
+    }
+    d.remove();
+  }
+})();
+</script>`;
+
+/**
+ * Renders a VecStream (or RawString) to a WHATWG ReadableStream.
+ * Handles out-of-order streaming for Promises and AsyncIterables.
+ * 
+ * @param {object} vecResult The result from calling vec\`\`
+ * @param {string} nonce The CSP nonce for inline scripts
+ * @returns {ReadableStream}
+ */
+export function renderToStream(vecResult, nonce = '') {
+  if (!(vecResult && vecResult.type === 'VecStream')) {
+    const value = vecResult instanceof RawString ? vecResult.value : String(vecResult);
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(value));
+        controller.close();
+      }
+    });
+  }
+
+  const { plan, values } = vecResult;
+  let slotCounter = 0;
+  const pendingTasks = new Set();
+  
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        let initialHtml = plan.statics[0];
+        
+        for (let i = 0; i < values.length; i++) {
+          const val = values[i];
+          const ctx = plan.contexts[i];
+          const attrName = plan.attrNames[i];
+
+          const isPromise = val instanceof Promise;
+          const isAsyncIter = val && typeof val[Symbol.asyncIterator] === 'function';
+          const isNestedStream = val && val.type === 'VecStream';
+
+          if (isPromise || isAsyncIter || isNestedStream) {
+            const slotId = ++slotCounter;
+            initialHtml += `<i-slot id="i-slot-${slotId}"></i-slot>`;
+            
+            const task = (async () => {
+              try {
+                if (isPromise) {
+                  const resolved = await val;
+                  let str = '';
+                  if (resolved && resolved.type === 'VecStream') {
+                    // Resolve nested stream by reading from it
+                    const nestedReadable = renderToStream(resolved, nonce);
+                    const reader = nestedReadable.getReader();
+                    let nestedHtml = '';
+                    while (true) {
+                      const { done, value } = await reader.read();
+                      if (done) break;
+                      // value is Uint8Array
+                      nestedHtml += new TextDecoder().decode(value);
+                    }
+                    str = nestedHtml;
+                  } else if (resolved instanceof RawString) {
+                    str = resolved.value;
+                  } else {
+                    str = escape(resolved, ctx, attrName);
+                  }
+                  const patch = `\n<template data-i-fill="${slotId}">${str}</template>` + 
+                                PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
+                  controller.enqueue(encoder.encode(patch));
+                } else if (isAsyncIter) {
+                  let accumulated = '';
+                  for await (const chunk of val) {
+                    accumulated += (chunk instanceof RawString ? chunk.value : escape(chunk, ctx, attrName));
+                  }
+                  const patch = `\n<template data-i-fill="${slotId}">${accumulated}</template>` + 
+                                PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
+                  controller.enqueue(encoder.encode(patch));
+                } else if (isNestedStream) {
+                  const nestedReadable = renderToStream(val, nonce);
+                  const reader = nestedReadable.getReader();
+                  let nestedHtml = '';
+                  while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    nestedHtml += new TextDecoder().decode(value);
+                  }
+                  const patch = `\n<template data-i-fill="${slotId}">${nestedHtml}</template>` + 
+                                PATCHER_SCRIPT.replace('[INERT_NONCE]', nonce);
+                  controller.enqueue(encoder.encode(patch));
+                }
+              } catch (err) {
+                console.error(`[InertJS] Error streaming slot ${slotId}:`, err);
+              } finally {
+                pendingTasks.delete(task);
+                if (pendingTasks.size === 0) {
+                  controller.close();
+                }
+              }
+            })();
+            
+            pendingTasks.add(task);
+          } else {
+            // Synchronous value
+            if (val instanceof RawString) {
+              initialHtml += val.value;
+            } else if (Array.isArray(val)) {
+              initialHtml += val.map(v => v instanceof RawString ? v.value : escape(v, ctx, attrName)).join('');
+            } else {
+              initialHtml += escape(val, ctx, attrName);
+            }
+          }
+          initialHtml += plan.statics[i + 1];
+        }
+
+        // Flush the synchronous initial shell
+        controller.enqueue(encoder.encode(initialHtml));
+
+        if (pendingTasks.size === 0) {
+          controller.close();
+        }
+      } catch (err) {
+        controller.error(err);
+      }
+    }
+  });
+}

package/test/stress.test.js

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { vec } from '../src/index.js';
+import { renderToStream } from '../src/stream.js';
+import { Readable } from 'node:stream';
+
+test('Vector Stress Test (100,000 DOM nodes)', async (t) => {
+  // Generate 10,000 items, each item will have 10 nodes, totaling 100,000 nodes.
+  const data = Array.from({ length: 10000 }).map((_, i) => ({
+    id: i,
+    name: `Item ${i}`,
+    desc: `Description for ${i}`
+  }));
+
+  function itemTemplate(item) {
+    return vec`
+      <div id="item-${item.id}" class="item-container">
+        <h2>${item.name}</h2>
+        <p>${item.desc}</p>
+        <span>Extra node 1</span>
+        <span>Extra node 2</span>
+        <ul>
+          <li>Child 1</li>
+          <li>Child 2</li>
+          <li>Child 3</li>
+        </ul>
+      </div>
+    `;
+  }
+
+  function rootTemplate(items) {
+    return vec`
+      <main>
+        <h1>100k Node Stress Test</h1>
+        <div class="list">
+          ${items.map(itemTemplate)}
+        </div>
+      </main>
+    `;
+  }
+
+  const start = performance.now();
+  
+  const webStream = renderToStream(rootTemplate(data));
+  const nodeStream = Readable.fromWeb(webStream);
+  
+  let chunkCount = 0;
+  let totalBytes = 0;
+
+  for await (const chunk of nodeStream) {
+    chunkCount++;
+    totalBytes += chunk.length;
+  }
+
+  const end = performance.now();
+  const timeMs = end - start;
+  
+  console.log(`Rendered ${totalBytes} bytes in ${chunkCount} chunks. Time: ${timeMs.toFixed(2)}ms`);
+
+  assert.ok(totalBytes > 1000000, `Expected > 1MB of HTML, got ${totalBytes} bytes`);
+  assert.ok(timeMs < 2000, `Expected render under 2s, took ${timeMs}ms`);
+});

package/test/xss.test.js

@@ -0,0 +1,68 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { vec, raw } from '../src/index.js';
+
+test('Vector Template Engine XSS Corpus', async (t) => {
+  await t.test('escapes basic text interpolation', () => {
+    const malicious = '<script>alert(1)</script>';
+    const result = vec`<div>${malicious}</div>`;
+    assert.strictEqual(result.toString(), '<div>&lt;script&gt;alert(1)&lt;/script&gt;</div>');
+  });
+
+  await t.test('escapes double-quoted attributes', () => {
+    const malicious = '"> <script>alert(1)</script>';
+    const result = vec`<div class="${malicious}"></div>`;
+    assert.strictEqual(result.toString(), '<div class="&quot;&gt; &lt;script&gt;alert(1)&lt;/script&gt;"></div>');
+  });
+
+  await t.test('escapes single-quoted attributes', () => {
+    const malicious = "'> <script>alert(1)</script>";
+    const result = vec`<div class='${malicious}'></div>`;
+    assert.strictEqual(result.toString(), "<div class='&#39;&gt; &lt;script&gt;alert(1)&lt;/script&gt;'></div>");
+  });
+
+  await t.test('escapes unquoted attributes', () => {
+    const malicious = 'onclick=alert(1)';
+    const result = vec`<div class=${malicious}></div>`;
+    assert.strictEqual(result.toString(), '<div class=onclick=alert(1)></div>');
+  });
+
+  await t.test('hard-refuses javascript: in URL attributes', () => {
+    const malicious = 'javascript:alert(1)';
+    assert.throws(
+      () => vec`<a href="${malicious}">link</a>`,
+      /E_INERT_VECTOR_UNSAFE/
+    );
+    assert.throws(
+      () => vec`<a href='  ${malicious}  '>link</a>`,
+      /E_INERT_VECTOR_UNSAFE/
+    );
+    assert.throws(
+      () => vec`<iframe src=${malicious}></iframe>`,
+      /E_INERT_VECTOR_UNSAFE/
+    );
+  });
+
+  await t.test('hard-refuses interpolation in <script> and <style>', () => {
+    const data = 'alert(1)';
+    assert.throws(
+      () => vec`<script>${data}</script>`,
+      /E_INERT_VECTOR_UNSAFE/
+    );
+    assert.throws(
+      () => vec`<style>${data}</style>`,
+      /E_INERT_VECTOR_UNSAFE/
+    );
+  });
+
+  await t.test('raw() escape hatch bypasses escaping', () => {
+    const result = vec`<div>${raw('<b>bold</b>')}</div>`;
+    assert.strictEqual(result.toString(), '<div><b>bold</b></div>');
+  });
+
+  await t.test('nested vec calls do not double-escape', () => {
+    const child = vec`<span>${'<escaped>'}</span>`;
+    const parent = vec`<div>${child}</div>`;
+    assert.strictEqual(parent.toString(), '<div><span>&lt;escaped&gt;</span></div>');
+  });
+});