nukejs 0.0.26 → 0.0.28

package/README.md

@@ -25,6 +25,7 @@ npm create nuke@latest
 - [Configuration](#configuration)
 - [Link Component & Navigation](#link-component--navigation)
 - [useRequest() — URL Params, Query & Headers](#userequest--url-params-query--headers)
+- [cache() — Request-Scoped Data Caching](#cache--request-scoped-data-caching)
 - [Error Pages](#error-pages)
 - [Building & Deploying](#building--deploying)
 
@@ -1104,6 +1105,73 @@ Changing `?lang=fr` in the URL re-renders client components automatically.
 
 ---
 
+## cache() — Request-Scoped Data Caching
+
+Server components render independently, so if two components in the same page tree both need the same data, NukeJS has no way to know they're asking for the same thing — each one triggers its own database call, fetch, or computation, even though they're part of the same request:
+
+```tsx
+// app/components/Nav.tsx
+export default async function Nav() {
+  const user = await db.getUser(useRequest().params.id); // DB call #1
+  return <nav>{user.name}</nav>;
+}
+
+// app/pages/dashboard.tsx
+export default async function Dashboard() {
+  const user = await db.getUser(useRequest().params.id); // DB call #2 — same data
+  return <main>{user.email}</main>;
+}
+```
+
+`cache()` wraps an async function so repeated calls with the same arguments, **within the same request**, share a single call:
+
+```ts
+// lib/data.ts
+import { cache } from 'nukejs';
+
+export const getUser = cache(async (id: string) => {
+  return db.getUser(id); // only runs once per request, however many
+                          // components call getUser(id) with that id
+});
+```
+
+```tsx
+// app/components/Nav.tsx
+import { getUser } from '../../lib/data';
+
+export default async function Nav() {
+  const user = await getUser(useRequest().params.id as string);
+  return <nav>{user.name}</nav>;
+}
+
+// app/pages/dashboard.tsx
+import { getUser } from '../../lib/data';
+
+export default async function Dashboard() {
+  const user = await getUser(useRequest().params.id as string); // same call → no extra DB hit
+  return <main>{user.email}</main>;
+}
+```
+
+Whichever component calls `getUser('42')` first triggers the real call; every other call with `'42'` in that same request — even ones that fire concurrently, before the first has resolved — awaits that same in-flight promise instead of starting a new one.
+
+### Why not just use React's `cache()`?
+
+React ships its own `cache()`, but it relies on the React Server Components renderer to signal "this is a new request, reset the memoization table." NukeJS doesn't run the RSC protocol — it renders each request to a single HTML string (see [Pages & Routing](#pages--routing)) — so nothing would ever tell React's `cache()` to reset, risking one request's cached data leaking into another's response. NukeJS's `cache()` has the same signature and mental model as React's, but is tied to NukeJS's own per-request lifecycle instead, so it resets correctly on every request.
+
+### Scope & behaviour
+
+- **One request, one cache.** The cache is created fresh before rendering starts and discarded once the response is sent. There's no cross-request caching and nothing to invalidate — the next request simply starts with an empty cache.
+- **Keyed by function + arguments.** Two different `cache()`-wrapped functions never share entries, even if called with identical arguments. Arguments are compared by value (via JSON serialization), so `getUser('42')` and `getUser('42')` hit the same entry, but `getUser('42')` and `getUser('43')` don't.
+- **Concurrent calls are deduped too.** If two components call the same cached function before the first call has settled, both await the same pending promise — only one underlying call is made.
+- **Failed calls aren't stuck.** If a cached call rejects, that entry is removed immediately, so a later call with the same arguments in the same request retries instead of replaying the same error.
+- **Non-serializable arguments skip caching.** Arguments that can't be safely compared by value (functions, Symbols, cyclic objects) just call straight through, unmemoized, rather than being cached under an incorrect key.
+- **Safe to call anywhere.** Outside of an active request — a script, a test, client-side code — a `cache()`-wrapped function simply calls straight through with no memoization. It's always safe to import and call.
+
+`cache()` is a pure optimization: removing it (or calling the wrapped function directly) never changes what your app returns, only how many times the underlying work runs.
+
+---
+
 ## Error Pages
 
 NukeJS supports custom error pages for **404 Not Found** and **500 Internal Server Error**. Place them directly in `app/pages/` — they are standard server components and support everything regular pages do: layouts, `useHtml()`, client components, and HMR in dev.

package/dist/build-common.js

@@ -387,6 +387,46 @@ async function runWithRequestStore<T>(ctx: any, fn: () => Promise<T>): Promise<T
   try { return await fn(); } finally { __setReq(null); }
 }
 
+// \u2500\u2500\u2500 cache-store (inlined) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// See src/cache-store.ts for the full explanation. Request-scoped memoisation
+// for async data loaders, keyed on the wrapped function + its (serialisable)
+// arguments. Reset per request exactly like the request/html stores above.
+const __CACHE_KEY__ = Symbol.for('__nukejs_cache_store__');
+const __getCache = (): { entries: Map<string, Promise<unknown>> } | null =>
+  (globalThis as any)[__CACHE_KEY__] ?? null;
+const __setCache = (v: { entries: Map<string, Promise<unknown>> } | null): void => {
+  (globalThis as any)[__CACHE_KEY__] = v;
+};
+async function runWithCacheStore<T>(fn: () => Promise<T>): Promise<T> {
+  __setCache({ entries: new Map() });
+  try { return await fn(); } finally { __setCache(null); }
+}
+let __cacheIdCounter = 0;
+function __serialiseArgs(args: unknown[]): string | null {
+  try {
+    return JSON.stringify(args, (_k, v) => {
+      if (typeof v === 'function' || typeof v === 'symbol') throw new Error('non-serialisable');
+      return v;
+    });
+  } catch { return null; }
+}
+function cache<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>): (...args: Args) => Promise<R> {
+  const id = \`c\${++__cacheIdCounter}\`;
+  return function cached(...args: Args): Promise<R> {
+    const store = __getCache();
+    if (!store) return fn(...args);
+    const argsKey = __serialiseArgs(args);
+    if (argsKey === null) return fn(...args);
+    const key = \`\${id}:\${argsKey}\`;
+    const existing = store.entries.get(key);
+    if (existing) return existing as Promise<R>;
+    const result = fn(...args);
+    store.entries.set(key, result);
+    result.catch(() => { store.entries.delete(key); });
+    return result;
+  };
+}
+
 // \u2500\u2500\u2500 HTML helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 function escapeHtml(s: string): string {
   return String(s)
@@ -495,27 +535,83 @@ function buildWrapperAttrString(attrs: Record<string, any>): string {
   return parts.length ? ' ' + parts.join(' ') : '';
 }
 
-function serializeProps(value: any): any {
-  if (typeof value === 'function') return undefined;   // must come before the object check
-  if (value == null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.map(serializeProps).filter((v: any) => v !== undefined);
-  if ((value as any).$$typeof) {
-    const { type, props: p } = value as any;
-    if (typeof type === 'string') return { __re: 'html', tag: type, props: serializeProps(p) };
-    if (typeof type === 'function') {
-      const cid = (type as any).__nukeClientId ?? CLIENT_COMPONENTS[type.name];
-      if (cid) return { __re: 'client', componentId: cid, props: serializeProps(p) };
-    }
-    return undefined;
-  }
-  const out: any = {};
-  for (const [k, v] of Object.entries(value as Record<string, any>)) {
-    const s = serializeProps(v);
-    if (s !== undefined) out[k] = s;
+function prepareProps(props, hydrated) {
+  if (!props || typeof props !== 'object') return Promise.resolve({ real: props, json: props });
+  const entries = Object.entries(props);
+  return Promise.all(entries.map(([, v]) => prepareValue(v, hydrated))).then((results) => {
+    const real = {};
+    const json = {};
+    entries.forEach(([key], i) => {
+      real[key] = results[i].real;
+      if (results[i].json !== undefined) json[key] = results[i].json;
+    });
+    return { real, json };
+  });
+}
+
+async function prepareValue(value, hydrated) {
+  if (value === null || value === undefined) return { real: value, json: value };
+  if (typeof value === 'function') return { real: value, json: undefined };
+  if (typeof value !== 'object') return { real: value, json: value };
+
+  if (Array.isArray(value)) {
+    const items = await Promise.all(value.map((v) => prepareValue(v, hydrated)));
+    return {
+      real: items.map((i) => i.real),
+      json: items.map((i) => i.json).filter((i) => i !== undefined),
+    };
   }
+
+  if (value.$$typeof) return prepareElement(value, hydrated);
+
+  const out = await prepareProps(value, hydrated);
   return out;
 }
 
+// Resolves a single React element found inside a client component's props.
+// Native elements and fragments recurse into their own props. Client
+// components are left untouched for 'real' (react-dom/server renders them
+// normally within the boundary's own renderToString call below) and wired
+// through as { __re: 'client', componentId, props } for the browser to
+// mount for real. Server components can't run in the browser at all, so
+// they're rendered once with this same file's renderNode() (handles async
+// components and any nested client boundaries inside them) and wrapped in
+// an inert <span style="display:contents"> carrying that HTML \u2014
+// identically on both 'real' and 'json', so the SSR markup and the
+// browser's reconstructed tree have the same shape and hydrateRoot() can
+// reconcile them without a mismatch.
+async function prepareElement(element, hydrated) {
+  const { type, props } = element;
+
+  if (type === Symbol.for('react.fragment')) {
+    const p = await prepareProps(props, hydrated);
+    return { real: __createElement__(Symbol.for('react.fragment'), p.real), json: { __re: 'fragment', props: p.json } };
+  }
+
+  if (typeof type === 'string') {
+    const p = await prepareProps(props, hydrated);
+    return { real: __createElement__(type, p.real), json: { __re: 'html', tag: type, props: p.json } };
+  }
+
+  if (typeof type === 'function') {
+    const cid = type.__nukeClientId ?? CLIENT_COMPONENTS[type.name];
+    if (cid) {
+      const p = await prepareProps(props, hydrated);
+      return { real: element, json: { __re: 'client', componentId: cid, props: p.json } };
+    }
+
+    const html = await renderNode(element, hydrated);
+    const wrapperProps = {
+      style: { display: 'contents' },
+      'data-n-static': true,
+      dangerouslySetInnerHTML: { __html: html },
+    };
+    return { real: __createElement__('span', wrapperProps), json: { __re: 'static', html } };
+  }
+
+  return { real: element, json: undefined };
+}
+
 async function renderNode(node: any, hydrated: Set<string>): Promise<string> {
   if (node == null || typeof node === 'boolean') return '';
   if (typeof node === 'string') return escapeHtml(node);
@@ -557,10 +653,10 @@ async function renderNode(node: any, hydrated: Set<string>): Promise<string> {
       hydrated.add(clientId);
       const { wrapperAttrs, componentProps } = splitWrapperAttrs(props);
       const wrapperAttrStr  = buildWrapperAttrString(wrapperAttrs);
-      const serializedProps = serializeProps(componentProps ?? {});
+      const { real: hydrationSafeProps, json: serializedProps } = await prepareProps(componentProps ?? {}, hydrated);
       let ssrHtml: string;
       try {
-        ssrHtml = __renderToString__(__createElement__(type as any, componentProps || {}));
+        ssrHtml = __renderToString__(__createElement__(type as any, hydrationSafeProps || {}));
       } catch {
         ssrHtml = PRERENDERED_HTML[clientId] ?? '';
       }
@@ -632,7 +728,7 @@ export default async function handler(req: IncomingMessage, res: ServerResponse)
     let appHtml = '';
     const store = await runWithRequestStore(
       { url, pathname, params, query, headers: normHeaders },
-      () => runWithHtmlStore(async () => { appHtml = await renderNode(wrapped, hydrated); }),
+      () => runWithCacheStore(() => runWithHtmlStore(async () => { appHtml = await renderNode(wrapped, hydrated); })),
     );
 
     const pageTitle = resolveTitle(store.titleOps, 'NukeJS');

package/dist/bundle.js

@@ -50,6 +50,20 @@ async function reconstructElement(node, mods) {
     const React = await import("react");
     return React.default.createElement(n.tag, await reconstructProps(n.props, mods));
   }
+  if (node.__re === "fragment") {
+    const n = node;
+    const React = await import("react");
+    return React.default.createElement(React.default.Fragment, await reconstructProps(n.props, mods));
+  }
+  if (node.__re === "static") {
+    const n = node;
+    const React = await import("react");
+    return React.default.createElement("span", {
+      style: { display: "contents" },
+      "data-n-static": true,
+      dangerouslySetInnerHTML: { __html: n.html }
+    });
+  }
   return node;
 }
 async function reconstructProps(props, mods) {

package/dist/cache-store.js

@@ -0,0 +1,48 @@
+const KEY = /* @__PURE__ */ Symbol.for("__nukejs_cache_store__");
+const getGlobal = () => globalThis[KEY] ?? null;
+const setGlobal = (store) => {
+  globalThis[KEY] = store;
+};
+async function runWithCacheStore(fn) {
+  setGlobal({ entries: /* @__PURE__ */ new Map() });
+  try {
+    return await fn();
+  } finally {
+    setGlobal(null);
+  }
+}
+let cacheIdCounter = 0;
+function serialiseArgs(args) {
+  try {
+    return JSON.stringify(args, (_key, value) => {
+      if (typeof value === "function" || typeof value === "symbol") {
+        throw new Error("non-serialisable value");
+      }
+      return value;
+    });
+  } catch {
+    return null;
+  }
+}
+function cache(fn) {
+  const cacheId = `c${++cacheIdCounter}`;
+  return function cached(...args) {
+    const store = getGlobal();
+    if (!store) return fn(...args);
+    const argsKey = serialiseArgs(args);
+    if (argsKey === null) return fn(...args);
+    const key = `${cacheId}:${argsKey}`;
+    const existing = store.entries.get(key);
+    if (existing) return existing;
+    const result = fn(...args);
+    store.entries.set(key, result);
+    result.catch(() => {
+      store.entries.delete(key);
+    });
+    return result;
+  };
+}
+export {
+  cache,
+  runWithCacheStore
+};

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { default as useRouter } from './use-router';
 export { useRequest } from './use-request';
 export type { RequestContext } from './use-request';
 export { normaliseHeaders, sanitiseHeaders, getRequestStore } from './request-store';
+export { cache } from './cache-store';
 export { default as Link } from './Link';
 export { setupLocationChangeMonitor, initRuntime } from './bundle';
 export type { RuntimeData } from './bundle';

package/dist/index.js

@@ -3,6 +3,7 @@ import { useHtml } from "./use-html.js";
 import { default as default2 } from "./use-router.js";
 import { useRequest } from "./use-request.js";
 import { normaliseHeaders, sanitiseHeaders, getRequestStore } from "./request-store.js";
+import { cache } from "./cache-store.js";
 import { default as default3 } from "./Link.js";
 import { setupLocationChangeMonitor, initRuntime } from "./bundle.js";
 import { escapeHtml } from "./utils.js";
@@ -11,6 +12,7 @@ export {
   default3 as Link,
   ansi,
   c,
+  cache,
   createPersistedStore,
   createStore,
   escapeHtml,

package/dist/renderer.js

@@ -90,9 +90,9 @@ async function renderFunctionComponent(type, props, ctx) {
       ctx.hydrated.add(id);
       const { wrapperAttrs, componentProps } = splitWrapperAttrs(props);
       const wrapperAttrStr = buildWrapperAttrString(wrapperAttrs);
-      const serializedProps = serializePropsForHydration(componentProps, ctx.registry);
+      const { real: hydrationSafeProps, json: serializedProps } = await prepareProps(componentProps, ctx);
       log.verbose(`Client component rendered for hydration: ${id} (${path.basename(filePath)})`);
-      const html = ctx.skipClientSSR ? "" : renderToString(createElement(type, componentProps));
+      const html = ctx.skipClientSSR ? "" : renderToString(createElement(type, hydrationSafeProps));
       return `<span data-hydrate-id="${id}"${wrapperAttrStr} data-hydrate-props="${escapeHtml(
         JSON.stringify(serializedProps)
       )}">${html}</span>`;
@@ -105,51 +105,72 @@ async function renderFunctionComponent(type, props, ctx) {
   const resolved = result?.then ? await result : result;
   return renderElementToHtml(resolved, ctx);
 }
-function serializePropsForHydration(props, registry) {
-  if (!props || typeof props !== "object") return props;
-  const out = {};
+async function prepareProps(props, ctx) {
+  if (!props || typeof props !== "object") return { real: props, json: props };
+  const real = {};
+  const json = {};
   for (const [key, value] of Object.entries(props)) {
-    const s = serializeValue(value, registry);
-    if (s !== void 0) out[key] = s;
+    const p = await prepareValue(value, ctx);
+    real[key] = p.real;
+    if (p.json !== void 0) json[key] = p.json;
   }
-  return out;
+  return { real, json };
 }
-function serializeValue(value, registry) {
-  if (value === null || value === void 0) return value;
-  if (typeof value === "function") return void 0;
-  if (typeof value !== "object") return value;
-  if (Array.isArray(value))
-    return value.map((v) => serializeValue(v, registry)).filter((v) => v !== void 0);
-  if (value.$$typeof)
-    return serializeReactElement(value, registry);
-  const out = {};
+async function prepareValue(value, ctx) {
+  if (value === null || value === void 0) return { real: value, json: value };
+  if (typeof value === "function") return { real: value, json: void 0 };
+  if (typeof value !== "object") return { real: value, json: value };
+  if (Array.isArray(value)) {
+    const items = await Promise.all(value.map((v) => prepareValue(v, ctx)));
+    return {
+      real: items.map((i) => i.real),
+      json: items.map((i) => i.json).filter((i) => i !== void 0)
+    };
+  }
+  if (value.$$typeof) return prepareElement(value, ctx);
+  const real = {};
+  const json = {};
   for (const [k, v] of Object.entries(value)) {
-    const s = serializeValue(v, registry);
-    if (s !== void 0) out[k] = s;
+    const p = await prepareValue(v, ctx);
+    real[k] = p.real;
+    if (p.json !== void 0) json[k] = p.json;
   }
-  return out;
+  return { real, json };
 }
-function serializeReactElement(element, registry) {
+async function prepareElement(element, ctx) {
   const { type, props } = element;
+  if (type === Fragment) {
+    const p = await prepareProps(props, ctx);
+    return { real: createElement(Fragment, p.real), json: { __re: "fragment", props: p.json } };
+  }
   if (typeof type === "string") {
-    return { __re: "html", tag: type, props: serializePropsForHydration(props, registry) };
+    const p = await prepareProps(props, ctx);
+    return { real: createElement(type, p.real), json: { __re: "html", tag: type, props: p.json } };
   }
   if (typeof type === "function") {
     const componentCache = getComponentCache();
-    for (const [id, filePath] of registry.entries()) {
+    for (const [id, filePath] of ctx.registry.entries()) {
       const info = componentCache.get(filePath);
       if (!info?.isClientComponent) continue;
       if (type.__nukeClientId === id || info.exportedName && type.name === info.exportedName) {
         type.__nukeClientId = id;
+        const p = await prepareProps(props, ctx);
         return {
-          __re: "client",
-          componentId: id,
-          props: serializePropsForHydration(props, registry)
+          real: element,
+          // untouched — React renders it directly within the outer renderToString call
+          json: { __re: "client", componentId: id, props: p.json }
         };
       }
     }
+    const html = await renderElementToHtml(element, ctx);
+    const wrapperProps = {
+      style: { display: "contents" },
+      "data-n-static": true,
+      dangerouslySetInnerHTML: { __html: html }
+    };
+    return { real: createElement("span", wrapperProps), json: { __re: "static", html } };
   }
-  return void 0;
+  return { real: element, json: void 0 };
 }
 export {
   renderElementToHtml

package/dist/ssr.js

@@ -8,6 +8,7 @@ import { matchRoute, findLayoutsForRoute } from "./router.js";
 import { findClientComponentsInTree } from "./component-analyzer.js";
 import { renderElementToHtml } from "./renderer.js";
 import { runWithRequestStore, normaliseHeaders, sanitiseHeaders } from "./request-store.js";
+import { runWithCacheStore } from "./cache-store.js";
 import {
   runWithHtmlStore,
   resolveTitle
@@ -130,9 +131,9 @@ async function renderFile(filePath, params, url, pagesDir, isDev, res, req, stat
       query: queryParams,
       headers: normHeaders
     },
-    () => runWithHtmlStore(async () => {
+    () => runWithCacheStore(() => runWithHtmlStore(async () => {
       appHtml = await renderElementToHtml(wrappedElement, ctx);
-    })
+    }))
   );
   const pageTitle = resolveTitle(store.titleOps, "NukeJS");
   const headLines = [

package/dist/use-router.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 const SSR_ROUTER = { push: () => {
 }, replace: () => {
 }, back: () => {
@@ -28,7 +28,10 @@ function useRouter() {
   const refresh = useCallback(() => {
     window.dispatchEvent(new Event("locationchange"));
   }, []);
-  return { path, push, replace, back, refresh };
+  return useMemo(
+    () => ({ path, push, replace, back, refresh }),
+    [path, push, replace, back, refresh]
+  );
 }
 export {
   useRouter as default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nukejs",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "A minimal, opinionated full-stack React framework on Node.js that server-renders everything and hydrates only interactive parts.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",