hadars 0.1.31 → 0.1.32

package/README.md

@@ -16,6 +16,10 @@ hadars is an alternative to Next.js for apps that just need SSR.
 
 Bring your own router (or none), keep your components as plain React, and get SSR, HMR, and a production build from a single config file.
 
+## Benchmarks
+
+Benchmarks against an equivalent Next.js app show significantly faster server throughput (requests/second) and meaningfully better page load metrics (TTFB, FCP, DOMContentLoaded). Build times are also much lower due to rspack.
+
 ## Quick start
 
 Scaffold a new project in seconds:
@@ -114,7 +118,6 @@ const UserCard = ({ userId }: { userId: string }) => {
 - **`key`** - string or string array; must be stable and unique within the page
 - **Server** - calls `fn()`, awaits the result across render iterations, returns `undefined` until resolved
 - **Client** - reads the pre-resolved value from the hydration cache serialised by the server; `fn()` is never called in the browser
-- **Suspense libraries** - also works when `fn()` throws a thenable (e.g. Relay `useLazyLoadQuery` with `suspense: true`); the thrown promise is awaited and the next render re-calls `fn()` synchronously
 
 ## Data lifecycle hooks
 
@@ -182,21 +185,14 @@ export default config;
 
 ## slim-react
 
-hadars ships its own lightweight React-compatible SSR renderer called **slim-react** (`src/slim-react/`). It replaces `react-dom/server` entirely on the server side - no `renderToStaticMarkup`, no `renderToPipeableStream`, no react-dom dependency at all.
-
-For server builds, rspack aliases `react` and `react/jsx-runtime` to slim-react, so your components and any libraries they import render through it automatically without any code changes.
-
-**What it does:**
-
-- Renders the full component tree to an HTML string with native `async/await` support - async components and hooks that return Promises are awaited directly without streaming workarounds
-- Implements the React Suspense protocol: when a component throws a Promise (e.g. from `useServerData` or a Suspense-enabled data library), slim-react awaits it and retries the tree automatically
-- Emits React-compatible hydration markers - `<!--$-->…<!--/$-->` for resolved Suspense boundaries, `<!-- -->` separators between adjacent text nodes - so `hydrateRoot` on the client works without mismatches
-- Supports `React.memo`, `React.forwardRef`, `React.lazy`, `Context.Provider`, `Context.Consumer`, and the React 18/19 element wire formats
-- Covers the full hook surface needed for SSR: `useState`, `useReducer`, `useContext`, `useRef`, `useMemo`, `useCallback`, `useId`, `useSyncExternalStore`, `use`, and more - all as lightweight SSR stubs
+hadars ships its own lightweight React-compatible SSR renderer called **slim-react** (`src/slim-react/`). It replaces `react-dom/server` on the server side entirely.
 
-**Why not react-dom/server?**
+For server builds, rspack aliases `react` and `react/jsx-runtime` to slim-react, so your components and any libraries they import render through it automatically without code changes.
 
-`react-dom/server` cannot `await` arbitrary Promises thrown during render - it only handles Suspense via streaming and requires components to use `React.lazy` or Relay-style Suspense resources. slim-react's retry loop makes `useServerData` (and any hook that throws a Promise) work without wrapping every async component in a `<Suspense>` boundary.
+- Renders the full component tree to an HTML string with native `async/await` — async components are awaited directly
+- Implements the React Suspense protocol: thrown Promises (e.g. from `useSuspenseQuery`) are awaited and the component retried automatically
+- Compatible with `hydrateRoot` — output matches what React expects on the client
+- Supports `React.memo`, `React.forwardRef`, `React.lazy`, `Context.Provider`, `Context.Consumer`, and the React 19 element format
 
 ## License
 

package/dist/index.cjs

@@ -189,37 +189,8 @@ function useServerData(key, fn) {
   if (!unsuspend)
     return void 0;
   const existing = unsuspend.cache.get(cacheKey);
-  if (existing?.status === "suspense-resolved") {
-    try {
-      const value = fn();
-      unsuspend.cache.set(cacheKey, { status: "suspense-cached", value });
-      return value;
-    } catch {
-      return void 0;
-    }
-  }
-  if (existing?.status === "suspense-cached") {
-    return existing.value;
-  }
   if (!existing) {
-    let result;
-    try {
-      result = fn();
-    } catch (thrown) {
-      if (thrown !== null && typeof thrown === "object" && typeof thrown.then === "function") {
-        const suspensePromise = Promise.resolve(thrown).then(
-          () => {
-            unsuspend.cache.set(cacheKey, { status: "suspense-resolved" });
-          },
-          () => {
-            unsuspend.cache.set(cacheKey, { status: "suspense-resolved" });
-          }
-        );
-        unsuspend.cache.set(cacheKey, { status: "pending", promise: suspensePromise });
-        throw suspensePromise;
-      }
-      throw thrown;
-    }
+    const result = fn();
     const isThenable = result !== null && typeof result === "object" && typeof result.then === "function";
     if (!isThenable) {
       const value = result;

package/dist/index.d.ts

@@ -28,11 +28,6 @@ type UnsuspendEntry = {
 } | {
     status: 'fulfilled';
     value: unknown;
-} | {
-    status: 'suspense-resolved';
-} | {
-    status: 'suspense-cached';
-    value: unknown;
 } | {
     status: 'rejected';
     reason: unknown;
@@ -40,7 +35,6 @@ type UnsuspendEntry = {
 /** @internal Populated by the framework's render loop — use useServerData() instead. */
 interface AppUnsuspend {
     cache: Map<string, UnsuspendEntry>;
-    hasPending: boolean;
 }
 interface AppContext {
     path?: string;
@@ -197,16 +191,11 @@ declare function initServerDataCache(data: Record<string, unknown>): void;
  * across all SSR render passes and client hydration — it must be stable and
  * unique within the page.
  *
- * `fn` may return a `Promise<T>` (normal async usage), return `T` synchronously,
- * or throw a thenable (React Suspense protocol). All three cases are handled:
- * - Async `Promise<T>`: awaited across render iterations, result cached.
- * - Synchronous return: value stored immediately, returned on the same pass.
- * - Thrown thenable (e.g. `useQuery({ suspense: true })`): the thrown promise is
- *   awaited, the cache entry is then cleared so that the next render re-calls
- *   `fn()` — at that point the Suspense hook returns synchronously.
+ * `fn` may return a `Promise<T>` (async usage) or return `T` synchronously.
+ * The resolved value is serialised into `__serverData` and returned from cache
+ * during hydration.
  *
- * `fn` is **server-only**: it is never called in the browser. The resolved value
- * is serialised into `__serverData` and returned from cache during hydration.
+ * `fn` is **server-only**: it is never called in the browser.
  *
  * @example
  * const user = useServerData('current_user', () => db.getUser(id));

package/dist/index.js

@@ -146,37 +146,8 @@ function useServerData(key, fn) {
   if (!unsuspend)
     return void 0;
   const existing = unsuspend.cache.get(cacheKey);
-  if (existing?.status === "suspense-resolved") {
-    try {
-      const value = fn();
-      unsuspend.cache.set(cacheKey, { status: "suspense-cached", value });
-      return value;
-    } catch {
-      return void 0;
-    }
-  }
-  if (existing?.status === "suspense-cached") {
-    return existing.value;
-  }
   if (!existing) {
-    let result;
-    try {
-      result = fn();
-    } catch (thrown) {
-      if (thrown !== null && typeof thrown === "object" && typeof thrown.then === "function") {
-        const suspensePromise = Promise.resolve(thrown).then(
-          () => {
-            unsuspend.cache.set(cacheKey, { status: "suspense-resolved" });
-          },
-          () => {
-            unsuspend.cache.set(cacheKey, { status: "suspense-resolved" });
-          }
-        );
-        unsuspend.cache.set(cacheKey, { status: "pending", promise: suspensePromise });
-        throw suspensePromise;
-      }
-      throw thrown;
-    }
+    const result = fn();
     const isThenable = result !== null && typeof result === "object" && typeof result.then === "function";
     if (!isThenable) {
       const value = result;

package/dist/utils/Head.tsx

@@ -196,16 +196,11 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * across all SSR render passes and client hydration — it must be stable and
  * unique within the page.
  *
- * `fn` may return a `Promise<T>` (normal async usage), return `T` synchronously,
- * or throw a thenable (React Suspense protocol). All three cases are handled:
- * - Async `Promise<T>`: awaited across render iterations, result cached.
- * - Synchronous return: value stored immediately, returned on the same pass.
- * - Thrown thenable (e.g. `useQuery({ suspense: true })`): the thrown promise is
- *   awaited, the cache entry is then cleared so that the next render re-calls
- *   `fn()` — at that point the Suspense hook returns synchronously.
+ * `fn` may return a `Promise<T>` (async usage) or return `T` synchronously.
+ * The resolved value is serialised into `__serverData` and returned from cache
+ * during hydration.
  *
- * `fn` is **server-only**: it is never called in the browser. The resolved value
- * is serialised into `__serverData` and returned from cache during hydration.
+ * `fn` is **server-only**: it is never called in the browser.
  *
  * @example
  * const user = useServerData('current_user', () => db.getUser(id));
@@ -230,51 +225,11 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
 
     const existing = unsuspend.cache.get(cacheKey);
 
-    // Suspense promise has resolved — re-call fn() so the hook returns its value
-    // synchronously from its own internal cache. Cache the result as
-    // 'suspense-cached' so later renders (e.g. the final renderToString in
-    // buildSsrResponse, which runs after getFinalProps may have cleared the
-    // user's QueryClient) can return the value without calling fn() again.
-    // NOT stored as 'fulfilled' so it is never included in serverData sent to
-    // the client — the Suspense library owns its own hydration.
-    if (existing?.status === 'suspense-resolved') {
-        try {
-            const value = fn() as T;
-            unsuspend.cache.set(cacheKey, { status: 'suspense-cached', value });
-            return value;
-        } catch {
-            return undefined;
-        }
-    }
-
-    // Return the cached Suspense value on all subsequent renders.
-    if (existing?.status === 'suspense-cached') {
-        return existing.value as T;
-    }
-
     if (!existing) {
         // First encounter — call fn(), which may:
-        //   (a) return a Promise<T>  — normal async usage (serialised for the client)
+        //   (a) return a Promise<T>  — async usage (serialised for the client)
         //   (b) return T synchronously — e.g. a sync data source
-        //   (c) throw a thenable     — Suspense protocol (e.g. useSuspenseQuery)
-        let result: Promise<T> | T;
-        try {
-            result = fn();
-        } catch (thrown) {
-            // (c) Suspense protocol: fn() threw a thenable. Await it, then mark the
-            // entry as 'suspense-resolved' so the next render re-calls fn() to get
-            // the synchronously available value. Not stored as 'fulfilled' → not
-            // serialised to the client (the Suspense library handles its own hydration).
-            if (thrown !== null && typeof thrown === 'object' && typeof (thrown as any).then === 'function') {
-                const suspensePromise = Promise.resolve(thrown as Promise<unknown>).then(
-                    () => { unsuspend.cache.set(cacheKey, { status: 'suspense-resolved' }); },
-                    () => { unsuspend.cache.set(cacheKey, { status: 'suspense-resolved' }); },
-                );
-                unsuspend.cache.set(cacheKey, { status: 'pending', promise: suspensePromise });
-                throw suspensePromise; // slim-react will await and retry
-            }
-            throw thrown;
-        }
+        const result = fn();
 
         const isThenable = result !== null && typeof result === 'object' && typeof (result as any).then === 'function';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",

package/src/types/hadars.ts

@@ -26,14 +26,11 @@ export interface AppHead {
 export type UnsuspendEntry =
     | { status: 'pending'; promise: Promise<unknown> }
     | { status: 'fulfilled'; value: unknown }
-    | { status: 'suspense-resolved' }
-    | { status: 'suspense-cached'; value: unknown }
     | { status: 'rejected'; reason: unknown };
 
 /** @internal Populated by the framework's render loop — use useServerData() instead. */
 export interface AppUnsuspend {
     cache: Map<string, UnsuspendEntry>;
-    hasPending: boolean;
 }
 
 export interface AppContext {

package/src/utils/Head.tsx

@@ -196,16 +196,11 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * across all SSR render passes and client hydration — it must be stable and
  * unique within the page.
  *
- * `fn` may return a `Promise<T>` (normal async usage), return `T` synchronously,
- * or throw a thenable (React Suspense protocol). All three cases are handled:
- * - Async `Promise<T>`: awaited across render iterations, result cached.
- * - Synchronous return: value stored immediately, returned on the same pass.
- * - Thrown thenable (e.g. `useQuery({ suspense: true })`): the thrown promise is
- *   awaited, the cache entry is then cleared so that the next render re-calls
- *   `fn()` — at that point the Suspense hook returns synchronously.
+ * `fn` may return a `Promise<T>` (async usage) or return `T` synchronously.
+ * The resolved value is serialised into `__serverData` and returned from cache
+ * during hydration.
  *
- * `fn` is **server-only**: it is never called in the browser. The resolved value
- * is serialised into `__serverData` and returned from cache during hydration.
+ * `fn` is **server-only**: it is never called in the browser.
  *
  * @example
  * const user = useServerData('current_user', () => db.getUser(id));
@@ -230,51 +225,11 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
 
     const existing = unsuspend.cache.get(cacheKey);
 
-    // Suspense promise has resolved — re-call fn() so the hook returns its value
-    // synchronously from its own internal cache. Cache the result as
-    // 'suspense-cached' so later renders (e.g. the final renderToString in
-    // buildSsrResponse, which runs after getFinalProps may have cleared the
-    // user's QueryClient) can return the value without calling fn() again.
-    // NOT stored as 'fulfilled' so it is never included in serverData sent to
-    // the client — the Suspense library owns its own hydration.
-    if (existing?.status === 'suspense-resolved') {
-        try {
-            const value = fn() as T;
-            unsuspend.cache.set(cacheKey, { status: 'suspense-cached', value });
-            return value;
-        } catch {
-            return undefined;
-        }
-    }
-
-    // Return the cached Suspense value on all subsequent renders.
-    if (existing?.status === 'suspense-cached') {
-        return existing.value as T;
-    }
-
     if (!existing) {
         // First encounter — call fn(), which may:
-        //   (a) return a Promise<T>  — normal async usage (serialised for the client)
+        //   (a) return a Promise<T>  — async usage (serialised for the client)
         //   (b) return T synchronously — e.g. a sync data source
-        //   (c) throw a thenable     — Suspense protocol (e.g. useSuspenseQuery)
-        let result: Promise<T> | T;
-        try {
-            result = fn();
-        } catch (thrown) {
-            // (c) Suspense protocol: fn() threw a thenable. Await it, then mark the
-            // entry as 'suspense-resolved' so the next render re-calls fn() to get
-            // the synchronously available value. Not stored as 'fulfilled' → not
-            // serialised to the client (the Suspense library handles its own hydration).
-            if (thrown !== null && typeof thrown === 'object' && typeof (thrown as any).then === 'function') {
-                const suspensePromise = Promise.resolve(thrown as Promise<unknown>).then(
-                    () => { unsuspend.cache.set(cacheKey, { status: 'suspense-resolved' }); },
-                    () => { unsuspend.cache.set(cacheKey, { status: 'suspense-resolved' }); },
-                );
-                unsuspend.cache.set(cacheKey, { status: 'pending', promise: suspensePromise });
-                throw suspensePromise; // slim-react will await and retry
-            }
-            throw thrown;
-        }
+        const result = fn();
 
         const isThenable = result !== null && typeof result === 'object' && typeof (result as any).then === 'function';