@nexus_js/server 0.6.0

package/dist/streaming.js

@@ -0,0 +1,216 @@
+/**
+ * Nexus Streaming SSR — Out-of-order HTML flushing with Suspense boundaries.
+ *
+ * How it works:
+ *
+ *   1. The route render function returns immediately with the static shell.
+ *      Any Promise in the template becomes a placeholder:
+ *        <template id="nx-hole-3a9f"></template>
+ *
+ *   2. The HTTP connection stays OPEN (Transfer-Encoding: chunked).
+ *      The browser receives and paints the static shell instantly.
+ *
+ *   3. When each Promise resolves, the server writes two chunks:
+ *      a) The resolved HTML wrapped in a <template id="nx-fill-3a9f">
+ *      b) A tiny inline script that moves the template content
+ *         to the hole's position and removes both elements.
+ *
+ *   4. Error boundary: if a Promise rejects, the server writes the
+ *      error.nx fallback HTML instead.
+ *
+ * Result: Users see content as it becomes available, not all-at-once.
+ *         The Time-to-First-Byte is the server's fastest possible response.
+ *
+ * Wire format (chunks sent over HTTP):
+ *   Chunk 1: Full HTML with placeholders
+ *     <div>Static content</div>
+ *     <template id="nx-hole-3a9f" data-nx-fallback="<p>Loading...</p>"></template>
+ *     <template id="nx-hole-7b2c"></template>
+ *
+ *   Chunk 2: Resolved content (arrives async)
+ *     <template id="nx-fill-3a9f"><article>...</article></template>
+ *     <script>__nx_fill("3a9f")</script>
+ *
+ *   Chunk 3: Another resolution or error boundary
+ *     <template id="nx-fill-7b2c"><div class="error">...</div></template>
+ *     <script>__nx_fill("7b2c")</script>
+ *
+ *   Final chunk (closes stream):
+ *     <script>__nx_stream_complete()</script>
+ */
+/** Bootstrap script injected once per page */
+const BOOTSTRAP_SCRIPT = `<script id="__nx_stream_boot__">
+(function(){
+  function __nx_fill(id){
+    var fill=document.getElementById('nx-fill-'+id);
+    var hole=document.getElementById('nx-hole-'+id);
+    if(fill&&hole){
+      hole.replaceWith(fill.content.cloneNode(true));
+      fill.remove();
+    }
+  }
+  function __nx_fill_error(id,html){
+    var hole=document.getElementById('nx-hole-'+id);
+    if(hole){var d=document.createElement('div');d.innerHTML=html;hole.replaceWith(d);}
+  }
+  function __nx_stream_complete(){
+    document.dispatchEvent(new Event('nexus:stream-complete'));
+  }
+  window.__nx_fill=__nx_fill;
+  window.__nx_fill_error=__nx_fill_error;
+  window.__nx_stream_complete=__nx_stream_complete;
+})();
+</script>`;
+/**
+ * Creates a streaming SSR response.
+ * Returns a Web-standard `ReadableStream` for use in any edge runtime.
+ */
+export function createStreamingResponse(renderFn, opts = {}) {
+    const encoder = new TextEncoder();
+    const pending = [];
+    let controller;
+    const stream = new ReadableStream({
+        async start(ctrl) {
+            controller = ctrl;
+        },
+    });
+    const write = (html) => {
+        controller.enqueue(encoder.encode(html));
+    };
+    const streamCtrl = {
+        writeShell(html) {
+            // Inject bootstrap script before </head>
+            const injected = html.replace('</head>', `${BOOTSTRAP_SCRIPT}\n</head>`);
+            write(injected);
+        },
+        defer(boundary) {
+            pending.push(boundary);
+        },
+        close() {
+            write('<script>__nx_stream_complete()</script>');
+            controller.close();
+        },
+    };
+    // Start rendering
+    const work = async () => {
+        try {
+            await renderFn(streamCtrl);
+            // Resolve all pending boundaries in parallel
+            const tasks = pending.map(async (boundary) => {
+                try {
+                    const html = await boundary.promise;
+                    write(buildFillChunk(boundary.id, html));
+                }
+                catch (err) {
+                    const errorHtml = boundary.errorFallback ??
+                        opts.onError?.(err) ??
+                        buildDefaultErrorHTML(err);
+                    write(buildErrorChunk(boundary.id, errorHtml));
+                }
+            });
+            await Promise.all(tasks);
+            streamCtrl.close();
+        }
+        catch (err) {
+            write(buildFatalErrorChunk(err));
+            controller.close();
+        }
+    };
+    work();
+    const headers = new Headers(opts.headers);
+    headers.set('content-type', 'text/html; charset=utf-8');
+    headers.set('transfer-encoding', 'chunked');
+    headers.set('x-content-type-options', 'nosniff');
+    // Signal to CDN that this is a streaming response
+    headers.set('cache-control', 'no-store');
+    return new Response(stream, { status: 200, headers });
+}
+/**
+ * Template tag for deferred content in .nx templates.
+ *
+ * Usage in template:
+ *   {#await fetchPosts()}
+ *     <p>Loading posts...</p>
+ *   {:then posts}
+ *     {#each posts as p}<article>{p.title}</article>{/each}
+ *   {:catch error}
+ *     <p class="error">{error.message}</p>
+ *   {/await}
+ *
+ * Compiled output:
+ *   createSuspenseBoundary(fetchPosts(), {
+ *     fallback: '<p>Loading posts...</p>',
+ *     render: (posts) => posts.map(...).join(''),
+ *   })
+ */
+export function createSuspenseBoundary(promise, opts) {
+    const id = generateBoundaryId();
+    const placeholder = `<template id="nx-hole-${id}"${opts.fallback ? ` data-nx-fallback="${htmlEscape(opts.fallback)}"` : ''}></template>`;
+    const boundary = {
+        id,
+        promise: promise.then((value) => opts.render(value)),
+    };
+    if (opts.fallback !== undefined) {
+        boundary.fallback = opts.fallback;
+    }
+    const ef = typeof opts.errorFallback !== 'function' ? opts.errorFallback : undefined;
+    if (ef !== undefined) {
+        boundary.errorFallback = ef;
+    }
+    return { id, placeholder, boundary };
+}
+// ── Node.js adapter ───────────────────────────────────────────────────────────
+/**
+ * Pipes a streaming response to a Node.js `ServerResponse`.
+ * Used by the Node.js server adapter.
+ */
+export async function pipeToNodeResponse(webResponse, nodeRes) {
+    nodeRes.statusCode = webResponse.status;
+    webResponse.headers.forEach((value, key) => nodeRes.setHeader(key, value));
+    if (!webResponse.body) {
+        nodeRes.end();
+        return;
+    }
+    const reader = webResponse.body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            nodeRes.write(value);
+        }
+    }
+    finally {
+        nodeRes.end();
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function buildFillChunk(id, html) {
+    return (`<template id="nx-fill-${id}">${html}</template>` +
+        `<script>__nx_fill("${id}")</script>`);
+}
+function buildErrorChunk(id, html) {
+    return (`<template id="nx-fill-${id}">${html}</template>` +
+        `<script>__nx_fill("${id}")</script>`);
+}
+function buildFatalErrorChunk(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `<script>console.error('[Nexus Stream] Fatal error:', ${JSON.stringify(msg)})</script>`;
+}
+function buildDefaultErrorHTML(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `<div data-nx-error style="color:red;padding:1rem;border:1px solid red;border-radius:4px">
+    <strong>Error</strong>: ${htmlEscape(msg)}
+  </div>`;
+}
+let _counter = 0;
+function generateBoundaryId() {
+    _counter = (_counter + 1) % 0xffff;
+    return (_counter + Date.now()).toString(16).slice(-6);
+}
+function htmlEscape(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=streaming.js.map

package/dist/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nexus_js/server",
+  "version": "0.6.0",
+  "description": "Nexus HTTP server — SSR, Server Actions, Edge-ready",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./actions": {
+      "import": "./dist/actions.js",
+      "types": "./dist/actions.d.ts"
+    },
+    "./context": {
+      "import": "./dist/context.js",
+      "types": "./dist/context.d.ts"
+    }
+  },
+  "dependencies": {
+    "@nexus_js/serialize": "0.6.0",
+    "@nexus_js/assets": "0.6.0",
+    "@nexus_js/compiler": "0.6.0",
+    "@nexus_js/connect": "0.6.0",
+    "@nexus_js/router": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT",
+  "homepage": "https://nexusjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bierfor/nexus.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/bierfor/nexus/issues"
+  },
+  "keywords": [
+    "nexus",
+    "framework",
+    "full-stack",
+    "svelte",
+    "islands",
+    "ssr",
+    "vite",
+    "server-actions"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}