nukejs 0.0.27 → 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)
@@ -688,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/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/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.27",
+  "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",