zero-http 0.2.0

package/documentation/public/scripts/data-sections.js

@@ -0,0 +1,300 @@
+/**
+ * data-sections.js
+ * Fetches and renders the three data-driven documentation sections:
+ *   - API Reference   (/data/api.json)
+ *   - Options Table   (/data/options.json)
+ *   - Code Examples   (/data/examples.json)
+ *
+ * Also populates the sidebar TOC with sub-items for the API reference and
+ * examples sections.
+ *
+ * Depends on: helpers.js (provides $, escapeHtml, slugify, showJsonResult,
+ *             highlightAllPre)
+ */
+
+/* ── TOC Helpers ───────────────────────────────────────────────────────────── */
+
+/**
+ * Find a top-level `<li>` in the sidebar TOC whose link matches the given
+ * href, then append a sub-list of items beneath it.
+ * @param {string}   href  - Hash href to match (e.g. "#api-reference").
+ * @param {Object[]} items - Array of `{ slug, label }` objects.
+ */
+function populateTocSub(href, items)
+{
+    const nav = document.querySelector('.toc-sidebar nav ul');
+    if (!nav || !items || !items.length) return;
+
+    const parentLi = Array.from(nav.children).find(li =>
+    {
+        const a = li.querySelector && li.querySelector(`a[href="${href}"]`);
+        return !!a;
+    });
+    if (!parentLi) return;
+
+    /* Remove existing sub-list if present (re-render safe) */
+    const existing = parentLi.querySelector('ul.toc-sub');
+    if (existing) existing.remove();
+
+    const sub = document.createElement('ul');
+    sub.className = 'toc-sub';
+
+    for (const { slug, label } of items)
+    {
+        const li = document.createElement('li');
+        li.className = 'toc-sub-item';
+
+        const a = document.createElement('a');
+        a.href = '#' + slug;
+        a.textContent = label;
+        a.addEventListener('click', () => document.body.classList.remove('toc-open'));
+
+        li.appendChild(a);
+        sub.appendChild(li);
+    }
+
+    parentLi.appendChild(sub);
+}
+
+/* ── API Reference ─────────────────────────────────────────────────────────── */
+
+/**
+ * Render a list of API items into the `#api-items` container and Prism-highlight
+ * any code examples.
+ * @param {HTMLElement} container - Target element.
+ * @param {Object[]}   list      - API item descriptors.
+ */
+function renderApiList(container, list)
+{
+    container.innerHTML = '';
+    if (!list || !list.length) { container.textContent = 'No API items'; return; }
+
+    for (const it of list)
+    {
+        const d = document.createElement('details');
+        d.className = 'acc nested';
+        d.id = 'api-' + slugify(it.name || '');
+
+        const s = document.createElement('summary');
+        s.innerHTML = `<strong>${escapeHtml(it.name)}</strong>`;
+        d.appendChild(s);
+
+        const body = document.createElement('div');
+        body.className = 'acc-body';
+
+        /* Description */
+        if (it.description)
+        {
+            const p = document.createElement('p');
+            p.innerHTML = escapeHtml(it.description);
+            body.appendChild(p);
+        }
+
+        /* Options table */
+        if (Array.isArray(it.options) && it.options.length)
+        {
+            const table = document.createElement('table');
+            table.innerHTML = '<thead><tr><th>Option</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead>';
+            const tbody = document.createElement('tbody');
+            for (const opt of it.options)
+            {
+                const tr = document.createElement('tr');
+                tr.innerHTML =
+                    `<td><code>${escapeHtml(opt.option)}</code></td>` +
+                    `<td>${escapeHtml(opt.type || '')}</td>` +
+                    `<td>${escapeHtml(opt.default || '')}</td>` +
+                    `<td>${escapeHtml(opt.notes || '')}</td>`;
+                tbody.appendChild(tr);
+            }
+            table.appendChild(tbody);
+            body.appendChild(table);
+        }
+
+        /* Methods table */
+        if (Array.isArray(it.methods) && it.methods.length)
+        {
+            const table = document.createElement('table');
+            table.innerHTML = '<thead><tr><th>Method</th><th>Signature</th><th>Description</th></tr></thead>';
+            const tbody = document.createElement('tbody');
+            for (const m of it.methods)
+            {
+                const tr = document.createElement('tr');
+                tr.innerHTML =
+                    `<td><code>${escapeHtml(m.method || '')}</code></td>` +
+                    `<td><code>${escapeHtml(m.signature || '')}</code></td>` +
+                    `<td>${escapeHtml(m.description || '')}</td>`;
+                tbody.appendChild(tr);
+            }
+            table.appendChild(tbody);
+            body.appendChild(table);
+        }
+
+        /* Example code block */
+        if (it.example)
+        {
+            const h6 = document.createElement('h6');
+            h6.textContent = 'Example';
+            const pre = document.createElement('pre');
+            pre.className = 'language-javascript code';
+            const code = document.createElement('code');
+            code.className = 'language-javascript';
+            code.textContent = it.example;
+            pre.appendChild(code);
+            body.appendChild(h6);
+            body.appendChild(pre);
+        }
+
+        d.appendChild(body);
+        container.appendChild(d);
+    }
+
+    try { highlightAllPre(); } catch (e) { }
+}
+
+/**
+ * Fetch the API reference JSON, render it, populate the sidebar TOC, and wire
+ * the search / clear filter controls.
+ */
+async function loadApiReference()
+{
+    try
+    {
+        const res = await fetch('/data/api.json', { cache: 'no-store' });
+        if (!res.ok) return;
+
+        const items = await res.json();
+        const container = document.getElementById('api-items');
+        if (!container) return;
+
+        window._apiItems = items;
+        renderApiList(container, items);
+
+        /* Sidebar TOC sub-items */
+        populateTocSub('#api-reference', items.map(it => ({
+            slug:  'api-' + slugify(it.name),
+            label: it.name || '',
+        })));
+
+        /* Search / clear filter */
+        const search   = document.getElementById('api-search');
+        const clearBtn = document.getElementById('api-clear');
+
+        const doFilter = () =>
+        {
+            const q = (search && search.value || '').trim().toLowerCase();
+            if (!q) return renderApiList(container, window._apiItems);
+            const filtered = window._apiItems.filter(it =>
+                (it.name || '').toLowerCase().includes(q) ||
+                (it.description || '').toLowerCase().includes(q) ||
+                JSON.stringify(it.options || []).toLowerCase().includes(q)
+            );
+            renderApiList(container, filtered);
+        };
+
+        if (search)   search.addEventListener('input', doFilter);
+        if (clearBtn) clearBtn.addEventListener('click', () => { if (search) search.value = ''; renderApiList(container, window._apiItems); });
+    } catch (e) { }
+}
+
+/* ── Options Table ─────────────────────────────────────────────────────────── */
+
+/**
+ * Fetch the options JSON and render a `<table>` into `#options-items`.
+ */
+async function loadOptions()
+{
+    try
+    {
+        const container = document.getElementById('options-items');
+        if (!container) return;
+
+        const res = await fetch('/data/options.json', { cache: 'no-store' });
+        if (!res.ok) { container.textContent = 'Error loading options: ' + res.status + ' ' + res.statusText; return; }
+
+        let items;
+        try { items = await res.json(); }
+        catch (err) { container.textContent = 'Error parsing options JSON'; return; }
+
+        const table = document.createElement('table');
+        table.innerHTML = '<thead><tr><th>Option</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead>';
+        const tbody = document.createElement('tbody');
+
+        for (const it of items)
+        {
+            const tr = document.createElement('tr');
+            tr.innerHTML =
+                `<td><strong>${escapeHtml(it.option || '')}</strong></td>` +
+                `<td>${escapeHtml(it.type || '')}</td>` +
+                `<td>${escapeHtml(it.default || '')}</td>` +
+                `<td>${escapeHtml(it.notes || it.description || '')}</td>`;
+            tbody.appendChild(tr);
+        }
+
+        table.appendChild(tbody);
+        container.innerHTML = '';
+        container.appendChild(table);
+    } catch (e) { console.error('loadOptions error', e); }
+}
+
+/* ── Code Examples ─────────────────────────────────────────────────────────── */
+
+/**
+ * Fetch the examples JSON, render each as a collapsible accordion, and
+ * populate the sidebar TOC.
+ */
+async function loadExamples()
+{
+    try
+    {
+        const container = document.getElementById('examples-items');
+        if (!container) return;
+
+        const res = await fetch('/data/examples.json', { cache: 'no-store' });
+        if (!res.ok) { container.textContent = 'Error loading examples: ' + res.status; return; }
+
+        const items = await res.json();
+        container.innerHTML = '';
+
+        for (const it of items)
+        {
+            const id = 'example-' + slugify(it.title);
+            const d = document.createElement('details');
+            d.className = 'acc nested';
+            d.id = id;
+
+            const s = document.createElement('summary');
+            s.innerHTML = `<strong>${escapeHtml(it.title || '')}</strong>`;
+            d.appendChild(s);
+
+            const body = document.createElement('div');
+            body.className = 'acc-body';
+
+            if (it.description)
+            {
+                const p = document.createElement('p');
+                p.className = 'muted';
+                p.textContent = it.description;
+                body.appendChild(p);
+            }
+
+            const pre = document.createElement('pre');
+            pre.className = it.language ? 'language-' + it.language + ' code' : 'code';
+            const code = document.createElement('code');
+            if (it.language) code.className = 'language-' + it.language;
+            code.textContent = it.code || '';
+            pre.appendChild(code);
+            body.appendChild(pre);
+
+            d.appendChild(body);
+            container.appendChild(d);
+        }
+
+        try { highlightAllPre(); } catch (e) { }
+
+        /* Sidebar TOC sub-items */
+        populateTocSub('#simple-examples', items.map(it => ({
+            slug:  'example-' + slugify(it.title),
+            label: it.title || '',
+        })));
+    } catch (e) { console.error('loadExamples error', e); }
+}

package/documentation/public/scripts/helpers.js

@@ -0,0 +1,166 @@
+/**
+ * helpers.js
+ * Shared DOM selectors, formatters, and rendering utilities used across all
+ * documentation scripts. Loaded first so every other module can rely on these.
+ */
+
+/* ── DOM Selectors ─────────────────────────────────────────────────────────── */
+
+/**
+ * Query a single element by CSS selector.
+ * @param {string} sel  - CSS selector string.
+ * @param {Element} ctx - Optional root element (defaults to `document`).
+ * @returns {Element|null}
+ */
+const $ = (sel, ctx = document) => ctx.querySelector(sel);
+
+/**
+ * Query all matching elements and return a real array.
+ * @param {string} sel  - CSS selector string.
+ * @param {Element} ctx - Optional root element (defaults to `document`).
+ * @returns {Element[]}
+ */
+const $$ = (sel, ctx = document) => Array.from((ctx || document).querySelectorAll(sel));
+
+/**
+ * Attach an event listener, safely no-ops if element is null.
+ * @param {Element|null} el  - Target element.
+ * @param {string}       evt - Event name.
+ * @param {Function}     cb  - Callback.
+ */
+function on(el, evt, cb)
+{
+    if (!el) return;
+    el.addEventListener(evt, cb);
+}
+
+/* ── String Utilities ──────────────────────────────────────────────────────── */
+
+/**
+ * Escape HTML special characters for safe insertion into the DOM.
+ * @param {string} s - Raw string.
+ * @returns {string} Escaped string.
+ */
+function escapeHtml(s)
+{
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+/**
+ * Convert a human-readable name into a URL-safe slug.
+ * @param {string} str - Input string.
+ * @returns {string} Lower-cased, hyphenated slug.
+ */
+function slugify(str)
+{
+    return (str || '').toString()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '');
+}
+
+/**
+ * Format a byte count into a human-readable string (B / KB / MB / GB).
+ * @param {number} n - Byte count.
+ * @returns {string}
+ */
+function formatBytes(n)
+{
+    if (n === 0) return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(n) / Math.log(k));
+    return (n / Math.pow(k, i)).toFixed(i ? 1 : 0) + ' ' + sizes[i];
+}
+
+/* ── JSON / Code Rendering ─────────────────────────────────────────────────── */
+
+/**
+ * Build a highlighted `<pre>` block containing pretty-printed JSON.
+ * @param {*} obj - Any JSON-serialisable value.
+ * @returns {string} HTML string.
+ */
+function jsonHtml(obj)
+{
+    return `<pre class="code language-json"><code>${escapeHtml(JSON.stringify(obj, null, 2))}</code></pre>`;
+}
+
+/**
+ * Render a JSON object into a container element and trigger Prism highlighting.
+ * @param {Element|null} container - Target element.
+ * @param {*}            obj       - JSON-serialisable value.
+ */
+function showJsonResult(container, obj)
+{
+    if (!container) return;
+    container.innerHTML = jsonHtml(obj);
+    try { highlightAllPre(); } catch (e) { }
+}
+
+/* ── Prism / Code-Block Helpers ────────────────────────────────────────────── */
+
+/**
+ * Trigger Prism syntax highlighting on all `<pre class="code">` blocks, or
+ * fall back to a simple escape-and-wrap if Prism is not loaded.
+ */
+function highlightAllPre()
+{
+    if (window.Prism && typeof Prism.highlightAll === 'function')
+    {
+        try { Prism.highlightAll(); } catch (e) { }
+        document.querySelectorAll('pre.code').forEach(p => p.dataset.miniExpressHighlighted = '1');
+        return;
+    }
+    try
+    {
+        document.querySelectorAll('pre.code').forEach(p =>
+        {
+            if (p.dataset.miniExpressHighlighted) return;
+            const raw = p.textContent || p.innerText || '';
+            p.innerHTML = '<code>' + escapeHtml(raw) + '</code>';
+            p.dataset.miniExpressHighlighted = '1';
+        });
+    } catch (e) { }
+}
+
+/**
+ * Strip common leading whitespace from every `<pre>` block so that indented
+ * source pasted into the HTML renders flush-left.
+ */
+function dedentAllPre()
+{
+    document.querySelectorAll('pre').forEach(pre =>
+    {
+        try
+        {
+            if (pre.dataset.miniExpressDedented) return;
+            const txt = pre.textContent || '';
+            const lines = txt.replace(/\r/g, '').split('\n');
+
+            while (lines.length && lines[0].trim() === '') lines.shift();
+            while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+            if (!lines.length) { pre.dataset.miniExpressDedented = '1'; return; }
+
+            const indents = lines.filter(l => l.trim()).map(l =>
+            {
+                const match = l.match(/^[\t ]*/)[0] || '';
+                return match.replace(/\t/g, '    ').length;
+            });
+            const minIndent = indents.length ? Math.min(...indents) : 0;
+
+            if (minIndent > 0)
+            {
+                const dedented = lines.map(l =>
+                {
+                    const s = l.replace(/\t/g, '    ');
+                    return s.slice(Math.min(minIndent, s.length));
+                }).join('\n');
+                pre.textContent = dedented;
+            }
+            pre.dataset.miniExpressDedented = '1';
+        } catch (e) { }
+    });
+}

package/documentation/public/scripts/playground.js

@@ -0,0 +1,71 @@
+/**
+ * playground.js
+ * Echo playground forms — JSON, URL-encoded, and plain-text body parsers.
+ *
+ * Depends on: helpers.js (provides $, on, escapeHtml, showJsonResult,
+ *             highlightAllPre)
+ */
+
+/**
+ * Wire the three echo playground forms so submissions hit the server and
+ * display the response.  Called once from the DOMContentLoaded handler in
+ * app.js.
+ */
+function initPlayground()
+{
+    /* JSON echo */
+    on($('#jsonPlay'), 'submit', async (e) =>
+    {
+        e.preventDefault();
+        const raw = e.target.json.value || '';
+        const playResult = $('#playResult');
+
+        try { JSON.parse(raw); }
+        catch (err)
+        {
+            playResult.innerHTML = `<pre class="code"><code>${escapeHtml('Invalid JSON: ' + err.message)}</code></pre>`;
+            return;
+        }
+
+        const r = await fetch('/echo', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: raw,
+        });
+        const j = await r.json();
+        showJsonResult(playResult, j);
+    });
+
+    /* URL-encoded echo */
+    on($('#urlPlay'), 'submit', async (e) =>
+    {
+        e.preventDefault();
+        const body = e.target.url.value || '';
+        const playResult = $('#playResult');
+
+        const r = await fetch('/echo-urlencoded', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+        });
+        const j = await r.json();
+        showJsonResult(playResult, j);
+    });
+
+    /* Plain-text echo */
+    on($('#textPlay'), 'submit', async (e) =>
+    {
+        e.preventDefault();
+        const txt = e.target.txt.value || '';
+        const playResult = $('#playResult');
+
+        const r = await fetch('/echo-text', {
+            method: 'POST',
+            headers: { 'Content-Type': 'text/plain' },
+            body: txt,
+        });
+        const text = await r.text();
+        playResult.innerHTML = `<pre class="code"><code>${escapeHtml(text)}</code></pre>`;
+        try { highlightAllPre(); } catch (e) { }
+    });
+}

package/documentation/public/scripts/proxy.js

@@ -0,0 +1,98 @@
+/**
+ * proxy.js
+ * Proxy playground — fetches an external URL through the server and renders
+ * the response based on its content-type (JSON, image, audio/video, text,
+ * or a binary download link).
+ *
+ * Depends on: helpers.js (provides $, on, escapeHtml, showJsonResult,
+ *             highlightAllPre)
+ */
+
+/**
+ * Wire the proxy form.  Called once from the DOMContentLoaded handler in
+ * app.js.
+ */
+function initProxy()
+{
+    const proxyForm   = $('#proxyForm');
+    const proxyResult = $('#proxyResult');
+    if (!proxyForm) return;
+
+    on(proxyForm, 'submit', async (e) =>
+    {
+        e.preventDefault();
+        const urlInput = $('#proxyUrl');
+        const url = urlInput && urlInput.value ? urlInput.value.trim() : '';
+
+        if (!url)
+        {
+            proxyResult.innerHTML = `<pre class="code"><code>${escapeHtml('Please enter a URL')}</code></pre>`;
+            return;
+        }
+
+        try
+        {
+            proxyResult.innerHTML = `<div class="muted">Fetching ${escapeHtml(url)}…</div>`;
+            const r = await fetch('/proxy?url=' + encodeURIComponent(url));
+
+            /* Upstream error */
+            if (r.status >= 400)
+            {
+                const j = await r.json();
+                showJsonResult(proxyResult, j);
+                return;
+            }
+
+            const ct = (r.headers && typeof r.headers.get === 'function')
+                ? (r.headers.get('content-type') || '')
+                : '';
+
+            /* JSON */
+            if (ct.includes('application/json') || ct.includes('application/problem+json'))
+            {
+                showJsonResult(proxyResult, await r.json());
+            }
+            /* Image */
+            else if (ct.startsWith('image/'))
+            {
+                const blob = new Blob([await r.arrayBuffer()], { type: ct });
+                const src  = URL.createObjectURL(blob);
+                proxyResult.innerHTML =
+                    `<div style="display:flex;align-items:center;gap:12px">` +
+                    `<img src="${src}" style="max-width:240px;max-height:240px;border-radius:8px"/>` +
+                    `<div class="mono" style="max-width:480px;overflow:auto">${escapeHtml('Image received: ' + ct)}</div></div>`;
+            }
+            /* Audio / Video / Octet-stream */
+            else if (ct.startsWith('audio/') || ct.startsWith('video/') || ct === 'application/octet-stream' || ct.includes('wav') || ct.includes('wave'))
+            {
+                const proxiedUrl = '/proxy?url=' + encodeURIComponent(url);
+                let mediaHtml = '';
+                if (ct.startsWith('audio/'))
+                    mediaHtml = `<audio controls src="${proxiedUrl}" style="max-width:480px;display:block;margin-bottom:8px"></audio>`;
+                else if (ct.startsWith('video/'))
+                    mediaHtml = `<video controls src="${proxiedUrl}" style="max-width:480px;display:block;margin-bottom:8px"></video>`;
+                proxyResult.innerHTML = `<div>${mediaHtml}<div class="mono">${escapeHtml('Streaming: ' + ct)}</div></div>`;
+            }
+            /* Text */
+            else if (ct.startsWith('text/') || ct === '')
+            {
+                const txt = await r.text();
+                proxyResult.innerHTML = `<pre class="code"><code>${escapeHtml(txt)}</code></pre>`;
+                try { highlightAllPre(); } catch (e) { }
+            }
+            /* Binary fallback — offer download */
+            else
+            {
+                const ab   = await r.arrayBuffer();
+                const blob = new Blob([ab], { type: ct || 'application/octet-stream' });
+                const href = URL.createObjectURL(blob);
+                proxyResult.innerHTML =
+                    `<div class="mono">${escapeHtml('Binary response: ' + ct + ' — ' + ab.byteLength + ' bytes')}</div>` +
+                    `<div style="margin-top:8px"><a href="${href}" download="proxied-file">Download file</a></div>`;
+            }
+        } catch (err)
+        {
+            proxyResult.innerHTML = `<pre class="code"><code>${escapeHtml(String(err))}</code></pre>`;
+        }
+    });
+}