hadars 0.1.35 → 0.1.37

package/dist/hadars-B3b_6sj2.d.cts

@@ -0,0 +1,188 @@
+import { MetaHTMLAttributes, LinkHTMLAttributes, StyleHTMLAttributes, ScriptHTMLAttributes } from 'react';
+
+type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest) => Promise<T> | T;
+type HadarsGetClientProps<T extends {}> = (props: T) => Promise<T> | T;
+type HadarsGetAfterRenderProps<T extends {}> = (props: HadarsProps<T>, html: string) => Promise<HadarsProps<T>> | HadarsProps<T>;
+type HadarsGetFinalProps<T extends {}> = (props: HadarsProps<T>) => Promise<T> | T;
+type HadarsApp<T extends {}> = React.FC<HadarsProps<T>>;
+type HadarsEntryModule<T extends {}> = {
+    default: HadarsApp<T>;
+    getInitProps?: HadarsGetInitialProps<T>;
+    getAfterRenderProps?: HadarsGetAfterRenderProps<T>;
+    getFinalProps?: HadarsGetFinalProps<T>;
+    getClientProps?: HadarsGetClientProps<T>;
+};
+interface AppHead {
+    title: string;
+    status: number;
+    meta: Record<string, MetaProps>;
+    link: Record<string, LinkProps>;
+    style: Record<string, StyleProps>;
+    script: Record<string, ScriptProps>;
+}
+type UnsuspendEntry = {
+    status: 'pending';
+    promise: Promise<unknown>;
+} | {
+    status: 'fulfilled';
+    value: unknown;
+} | {
+    status: 'rejected';
+    reason: unknown;
+};
+/** @internal Populated by the framework's render loop — use useServerData() instead. */
+interface AppUnsuspend {
+    cache: Map<string, UnsuspendEntry>;
+}
+interface AppContext {
+    path?: string;
+    head: AppHead;
+    /** @internal Framework use only — use the useServerData() hook instead. */
+    _unsuspend?: AppUnsuspend;
+}
+type HadarsEntryBase = {
+    location: string;
+    context: AppContext;
+};
+type HadarsProps<T extends {}> = T & HadarsEntryBase;
+type MetaProps = MetaHTMLAttributes<HTMLMetaElement>;
+type LinkProps = LinkHTMLAttributes<HTMLLinkElement>;
+type StyleProps = StyleHTMLAttributes<HTMLStyleElement>;
+type ScriptProps = ScriptHTMLAttributes<HTMLScriptElement>;
+interface HadarsOptions {
+    port?: number;
+    entry: string;
+    baseURL?: string;
+    swcPlugins?: SwcPluginList;
+    proxy?: Record<string, string> | ((req: HadarsRequest) => Promise<Response | null> | Response | null);
+    proxyCORS?: boolean;
+    define?: Record<string, string>;
+    /**
+     * Bun WebSocket handler passed directly to `Bun.serve()`.
+     * Ignored on Node.js and Deno — use `fetch` + a third-party WS library there.
+     * Pass a `Bun.WebSocketHandler` instance here when running on Bun.
+     */
+    websocket?: unknown;
+    fetch?: (req: HadarsRequest) => Promise<Response | undefined> | Response | undefined;
+    wsPath?: string;
+    hmrPort?: number;
+    /**
+     * Parallelism level for `run()` mode (production server). Defaults to 1.
+     * Has no effect in `dev()` mode.
+     *
+     * **Node.js** — forks this many worker processes via `node:cluster`, each
+     * binding to the same port via OS round-robin. Set to `os.cpus().length`
+     * to saturate all CPU cores.
+     *
+     * **Bun / Deno** — creates a `node:worker_threads` render pool of this size.
+     * Each thread handles the synchronous `renderToString` step, freeing the
+     * main event loop for I/O.
+     */
+    workers?: number;
+    /**
+     * Override or extend rspack's `optimization` config for production client builds.
+     * Merged on top of hadars defaults (splitChunks vendor splitting, deterministic moduleIds).
+     * Has no effect on the SSR bundle or dev mode.
+     */
+    optimization?: Record<string, unknown>;
+    /**
+     * Path to a custom HTML template file (relative to the project root).
+     * Replaces the built-in minimal template used to generate the HTML shell.
+     *
+     * The file must include two marker elements so hadars can inject the
+     * per-request head tags and the server-rendered body:
+     *
+     * ```html
+     * <meta name="HADARS_HEAD">   <!-- replaced with <title>, <meta>, <link>, <style> tags -->
+     * <meta name="HADARS_BODY">   <!-- replaced with the SSR-rendered React tree -->
+     * ```
+     *
+     * Any `<style>` blocks in the template are automatically processed through
+     * PostCSS (using the project's `postcss.config.js`) at build/dev startup time,
+     * so `@import "tailwindcss"` and other PostCSS directives work as expected.
+     * Note: inline styles are processed once at startup and are not live-reloaded.
+     */
+    htmlTemplate?: string;
+    /**
+     * Force the React runtime mode independently of the build mode.
+     * Useful when you need production build optimizations (minification, tree-shaking)
+     * but want React's development build for debugging hydration mismatches or
+     * component stack traces.
+     *
+     * - `'development'` — forces `process.env.NODE_ENV = "development"` and enables
+     *   JSX source info even in `hadars build`. React prints detailed hydration error
+     *   messages and component stacks.
+     * - `'production'` — the default; React uses the optimised production bundle.
+     *
+     * Only affects the **client** bundle. The SSR bundle always uses slim-react.
+     *
+     * @example
+     * // hadars.config.ts — debug hydration errors in a production build
+     * reactMode: 'development'
+     */
+    reactMode?: 'development' | 'production';
+    /**
+     * Additional rspack module rules appended to the built-in rule set.
+     * Applied to both the client and the SSR bundle.
+     *
+     * Useful for loaders not included by default, such as `@mdx-js/loader`,
+     * `less-loader`, `yaml-loader`, etc.
+     *
+     * @example
+     * moduleRules: [
+     *   {
+     *     test: /\.mdx?$/,
+     *     use: [{ loader: '@mdx-js/loader' }],
+     *   },
+     * ]
+     */
+    moduleRules?: Record<string, any>[];
+    /**
+     * Additional rspack/webpack-compatible plugins applied to both the client
+     * and SSR bundles. Any object that implements the `apply(compiler)` method
+     * (the standard webpack/rspack plugin interface) is accepted.
+     *
+     * @example
+     * import { SubresourceIntegrityPlugin } from 'webpack-subresource-integrity';
+     * plugins: [new SubresourceIntegrityPlugin()]
+     */
+    plugins?: Array<{
+        apply(compiler: any): void;
+    }>;
+    /**
+     * SSR response cache for `run()` mode. Has no effect in `dev()` mode.
+     *
+     * Receives the incoming request and should return `{ key, ttl? }` to cache
+     * the response, or `null`/`undefined` to skip caching for that request.
+     * `ttl` is the time-to-live in milliseconds; omit for entries that never expire.
+     * The function may be async.
+     *
+     * @example
+     * // Cache every page by pathname (no per-user personalisation):
+     * cache: (req) => ({ key: req.pathname })
+     *
+     * @example
+     * // Cache with a per-route TTL, skip authenticated requests:
+     * cache: (req) => req.cookies.session ? null : { key: req.pathname, ttl: 60_000 }
+     */
+    cache?: (req: HadarsRequest) => {
+        key: string;
+        ttl?: number;
+    } | null | undefined | Promise<{
+        key: string;
+        ttl?: number;
+    } | null | undefined>;
+}
+type SwcPluginItem = string | [string, Record<string, unknown>] | {
+    path: string;
+    options?: Record<string, unknown>;
+} | ((...args: any[]) => any);
+type SwcPluginList = SwcPluginItem[];
+interface HadarsRequest extends Request {
+    pathname: string;
+    search: string;
+    location: string;
+    cookies: Record<string, string>;
+}
+
+export type { AppContext as A, HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetAfterRenderProps as c, HadarsGetClientProps as d, HadarsGetFinalProps as e, HadarsGetInitialProps as f, HadarsProps as g, HadarsRequest as h };

package/dist/hadars-B3b_6sj2.d.ts

@@ -0,0 +1,188 @@
+import { MetaHTMLAttributes, LinkHTMLAttributes, StyleHTMLAttributes, ScriptHTMLAttributes } from 'react';
+
+type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest) => Promise<T> | T;
+type HadarsGetClientProps<T extends {}> = (props: T) => Promise<T> | T;
+type HadarsGetAfterRenderProps<T extends {}> = (props: HadarsProps<T>, html: string) => Promise<HadarsProps<T>> | HadarsProps<T>;
+type HadarsGetFinalProps<T extends {}> = (props: HadarsProps<T>) => Promise<T> | T;
+type HadarsApp<T extends {}> = React.FC<HadarsProps<T>>;
+type HadarsEntryModule<T extends {}> = {
+    default: HadarsApp<T>;
+    getInitProps?: HadarsGetInitialProps<T>;
+    getAfterRenderProps?: HadarsGetAfterRenderProps<T>;
+    getFinalProps?: HadarsGetFinalProps<T>;
+    getClientProps?: HadarsGetClientProps<T>;
+};
+interface AppHead {
+    title: string;
+    status: number;
+    meta: Record<string, MetaProps>;
+    link: Record<string, LinkProps>;
+    style: Record<string, StyleProps>;
+    script: Record<string, ScriptProps>;
+}
+type UnsuspendEntry = {
+    status: 'pending';
+    promise: Promise<unknown>;
+} | {
+    status: 'fulfilled';
+    value: unknown;
+} | {
+    status: 'rejected';
+    reason: unknown;
+};
+/** @internal Populated by the framework's render loop — use useServerData() instead. */
+interface AppUnsuspend {
+    cache: Map<string, UnsuspendEntry>;
+}
+interface AppContext {
+    path?: string;
+    head: AppHead;
+    /** @internal Framework use only — use the useServerData() hook instead. */
+    _unsuspend?: AppUnsuspend;
+}
+type HadarsEntryBase = {
+    location: string;
+    context: AppContext;
+};
+type HadarsProps<T extends {}> = T & HadarsEntryBase;
+type MetaProps = MetaHTMLAttributes<HTMLMetaElement>;
+type LinkProps = LinkHTMLAttributes<HTMLLinkElement>;
+type StyleProps = StyleHTMLAttributes<HTMLStyleElement>;
+type ScriptProps = ScriptHTMLAttributes<HTMLScriptElement>;
+interface HadarsOptions {
+    port?: number;
+    entry: string;
+    baseURL?: string;
+    swcPlugins?: SwcPluginList;
+    proxy?: Record<string, string> | ((req: HadarsRequest) => Promise<Response | null> | Response | null);
+    proxyCORS?: boolean;
+    define?: Record<string, string>;
+    /**
+     * Bun WebSocket handler passed directly to `Bun.serve()`.
+     * Ignored on Node.js and Deno — use `fetch` + a third-party WS library there.
+     * Pass a `Bun.WebSocketHandler` instance here when running on Bun.
+     */
+    websocket?: unknown;
+    fetch?: (req: HadarsRequest) => Promise<Response | undefined> | Response | undefined;
+    wsPath?: string;
+    hmrPort?: number;
+    /**
+     * Parallelism level for `run()` mode (production server). Defaults to 1.
+     * Has no effect in `dev()` mode.
+     *
+     * **Node.js** — forks this many worker processes via `node:cluster`, each
+     * binding to the same port via OS round-robin. Set to `os.cpus().length`
+     * to saturate all CPU cores.
+     *
+     * **Bun / Deno** — creates a `node:worker_threads` render pool of this size.
+     * Each thread handles the synchronous `renderToString` step, freeing the
+     * main event loop for I/O.
+     */
+    workers?: number;
+    /**
+     * Override or extend rspack's `optimization` config for production client builds.
+     * Merged on top of hadars defaults (splitChunks vendor splitting, deterministic moduleIds).
+     * Has no effect on the SSR bundle or dev mode.
+     */
+    optimization?: Record<string, unknown>;
+    /**
+     * Path to a custom HTML template file (relative to the project root).
+     * Replaces the built-in minimal template used to generate the HTML shell.
+     *
+     * The file must include two marker elements so hadars can inject the
+     * per-request head tags and the server-rendered body:
+     *
+     * ```html
+     * <meta name="HADARS_HEAD">   <!-- replaced with <title>, <meta>, <link>, <style> tags -->
+     * <meta name="HADARS_BODY">   <!-- replaced with the SSR-rendered React tree -->
+     * ```
+     *
+     * Any `<style>` blocks in the template are automatically processed through
+     * PostCSS (using the project's `postcss.config.js`) at build/dev startup time,
+     * so `@import "tailwindcss"` and other PostCSS directives work as expected.
+     * Note: inline styles are processed once at startup and are not live-reloaded.
+     */
+    htmlTemplate?: string;
+    /**
+     * Force the React runtime mode independently of the build mode.
+     * Useful when you need production build optimizations (minification, tree-shaking)
+     * but want React's development build for debugging hydration mismatches or
+     * component stack traces.
+     *
+     * - `'development'` — forces `process.env.NODE_ENV = "development"` and enables
+     *   JSX source info even in `hadars build`. React prints detailed hydration error
+     *   messages and component stacks.
+     * - `'production'` — the default; React uses the optimised production bundle.
+     *
+     * Only affects the **client** bundle. The SSR bundle always uses slim-react.
+     *
+     * @example
+     * // hadars.config.ts — debug hydration errors in a production build
+     * reactMode: 'development'
+     */
+    reactMode?: 'development' | 'production';
+    /**
+     * Additional rspack module rules appended to the built-in rule set.
+     * Applied to both the client and the SSR bundle.
+     *
+     * Useful for loaders not included by default, such as `@mdx-js/loader`,
+     * `less-loader`, `yaml-loader`, etc.
+     *
+     * @example
+     * moduleRules: [
+     *   {
+     *     test: /\.mdx?$/,
+     *     use: [{ loader: '@mdx-js/loader' }],
+     *   },
+     * ]
+     */
+    moduleRules?: Record<string, any>[];
+    /**
+     * Additional rspack/webpack-compatible plugins applied to both the client
+     * and SSR bundles. Any object that implements the `apply(compiler)` method
+     * (the standard webpack/rspack plugin interface) is accepted.
+     *
+     * @example
+     * import { SubresourceIntegrityPlugin } from 'webpack-subresource-integrity';
+     * plugins: [new SubresourceIntegrityPlugin()]
+     */
+    plugins?: Array<{
+        apply(compiler: any): void;
+    }>;
+    /**
+     * SSR response cache for `run()` mode. Has no effect in `dev()` mode.
+     *
+     * Receives the incoming request and should return `{ key, ttl? }` to cache
+     * the response, or `null`/`undefined` to skip caching for that request.
+     * `ttl` is the time-to-live in milliseconds; omit for entries that never expire.
+     * The function may be async.
+     *
+     * @example
+     * // Cache every page by pathname (no per-user personalisation):
+     * cache: (req) => ({ key: req.pathname })
+     *
+     * @example
+     * // Cache with a per-route TTL, skip authenticated requests:
+     * cache: (req) => req.cookies.session ? null : { key: req.pathname, ttl: 60_000 }
+     */
+    cache?: (req: HadarsRequest) => {
+        key: string;
+        ttl?: number;
+    } | null | undefined | Promise<{
+        key: string;
+        ttl?: number;
+    } | null | undefined>;
+}
+type SwcPluginItem = string | [string, Record<string, unknown>] | {
+    path: string;
+    options?: Record<string, unknown>;
+} | ((...args: any[]) => any);
+type SwcPluginList = SwcPluginItem[];
+interface HadarsRequest extends Request {
+    pathname: string;
+    search: string;
+    location: string;
+    cookies: Record<string, string>;
+}
+
+export type { AppContext as A, HadarsEntryModule as H, HadarsOptions as a, HadarsApp as b, HadarsGetAfterRenderProps as c, HadarsGetClientProps as d, HadarsGetFinalProps as e, HadarsGetInitialProps as f, HadarsProps as g, HadarsRequest as h };

package/dist/index.cjs

@@ -28,8 +28,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.tsx
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   CacheSegment: () => CacheSegment,
   HadarsContext: () => HadarsContext,
   HadarsHead: () => Head,
@@ -39,7 +39,7 @@ __export(src_exports, {
   loadModule: () => loadModule,
   useServerData: () => useServerData
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/utils/Head.tsx
 var import_react = __toESM(require("react"), 1);
@@ -179,8 +179,7 @@ var fetchedPaths = /* @__PURE__ */ new Set();
 var ssrInitialKeys = null;
 var unclaimedKeyCheckScheduled = false;
 function scheduleUnclaimedKeyCheck() {
-  if (unclaimedKeyCheckScheduled)
-    return;
+  if (unclaimedKeyCheckScheduled) return;
   unclaimedKeyCheckScheduled = true;
   setTimeout(() => {
     unclaimedKeyCheckScheduled = false;
@@ -241,13 +240,10 @@ function useServerData(key, fn) {
     throw pendingDataFetch.get(pathKey);
   }
   const unsuspend = globalThis.__hadarsUnsuspend;
-  if (!unsuspend)
-    return void 0;
+  if (!unsuspend) return void 0;
   const _u = unsuspend;
-  if (!_u.seenThisPass)
-    _u.seenThisPass = /* @__PURE__ */ new Set();
-  if (!_u.seenLastPass)
-    _u.seenLastPass = /* @__PURE__ */ new Set();
+  if (!_u.seenThisPass) _u.seenThisPass = /* @__PURE__ */ new Set();
+  if (!_u.seenLastPass) _u.seenLastPass = /* @__PURE__ */ new Set();
   if (_u.newPassStarting) {
     _u.seenLastPass = new Set(_u.seenThisPass);
     _u.seenThisPass.clear();
@@ -289,8 +285,7 @@ function useServerData(key, fn) {
     _u.newPassStarting = true;
     throw existing.promise;
   }
-  if (existing.status === "rejected")
-    throw existing.reason;
+  if (existing.status === "rejected") throw existing.reason;
   return existing.value;
 }
 var genRandomId = () => {
@@ -309,8 +304,7 @@ var Head = import_react.default.memo(({ children, status }) => {
     setStatus(status);
   }
   import_react.default.Children.forEach(children, (child) => {
-    if (!import_react.default.isValidElement(child))
-      return;
+    if (!import_react.default.isValidElement(child)) return;
     const childType = child.type;
     const childProps = child.props;
     const id = childProps["id"] || genRandomId();
@@ -357,8 +351,7 @@ function getStore() {
 }
 function getSegment(key) {
   const entry = getStore().get(key);
-  if (!entry)
-    return null;
+  if (!entry) return null;
   if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
     getStore().delete(key);
     return null;
@@ -391,8 +384,7 @@ function CacheSegment({ cacheKey, ttl, children }) {
     "data-key": cacheKey,
     "data-cache": "miss"
   };
-  if (ttl != null)
-    props["data-ttl"] = ttl;
+  if (ttl != null) props["data-ttl"] = ttl;
   return import_react2.default.createElement(CACHE_TAG, props, children);
 }
 

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+import { A as AppContext } from './hadars-B3b_6sj2.cjs';
+export { b as HadarsApp, H as HadarsEntryModule, c as HadarsGetAfterRenderProps, d as HadarsGetClientProps, e as HadarsGetFinalProps, f as HadarsGetInitialProps, a as HadarsOptions, g as HadarsProps, h as HadarsRequest } from './hadars-B3b_6sj2.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/** Call this before hydrating to seed the client cache from the server's data.
+ *  Invoked automatically by the hadars client bootstrap.
+ *  Always clears the existing cache before populating — call with `{}` to just clear. */
+declare function initServerDataCache(data: Record<string, unknown>): void;
+/**
+ * Fetch async data on the server during SSR. Returns `undefined` on the first
+ * render pass(es) while the promise is in flight; returns the resolved value
+ * once the framework's render loop has awaited it.
+ *
+ * On the client the pre-resolved value is read from the hydration cache
+ * serialised into the page by the server, so no fetch is issued in the browser.
+ *
+ * The `key` (string or array of strings) uniquely identifies the cached value
+ * across all SSR render passes and client hydration — it must be stable and
+ * unique within the page.
+ *
+ * `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. On client-side
+ * navigation (after the initial SSR load), hadars automatically fires a
+ * data-only request to the current URL (`X-Hadars-Data: 1`) and suspends via
+ * React Suspense until the server returns the JSON map of resolved values.
+ *
+ * @example
+ * const user = useServerData('current_user', () => db.getUser(id));
+ * const post = useServerData(['post', postId], () => db.getPost(postId));
+ * if (!user) return null; // undefined while pending on the first SSR pass
+ */
+declare function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined;
+declare const Head: React__default.FC<{
+    children?: React__default.ReactNode;
+    status?: number;
+}>;
+
+interface CacheSegmentProps {
+    /**
+     * Unique cache key for this segment. Use a key that encodes all values
+     * the output depends on, e.g. `"product-" + product.id`.
+     */
+    cacheKey: string;
+    /**
+     * Time-to-live in milliseconds. Omit for entries that never expire.
+     */
+    ttl?: number;
+    children: React__default.ReactNode;
+}
+/**
+ * Caches the server-rendered HTML of its children across requests.
+ *
+ * **Server (SSR):**
+ * - Cache miss — children are rendered normally as part of the main
+ *   `renderToString` call, so React context propagates correctly. The output
+ *   is wrapped in a `<hadars-c>` marker that `processSegmentCache` uses to
+ *   extract and store the HTML. The marker is stripped before the response
+ *   is sent; the browser never sees it.
+ * - Cache hit — children are **not** rendered at all. The cached HTML is
+ *   injected directly, saving the entire subtree render cost.
+ *
+ * **Client:** renders children normally (no caching). Because the server
+ * strips the marker wrapper, the client output matches the server HTML and
+ * React hydration succeeds without warnings for deterministic components.
+ *
+ * **Note:** components that rely on request-specific data (cookies, auth,
+ * personalisation) must not be wrapped in `CacheSegment` unless the cache
+ * key encodes that data — otherwise a cached response for one user could be
+ * served to another.
+ */
+declare function CacheSegment({ cacheKey, ttl, children }: CacheSegmentProps): react_jsx_runtime.JSX.Element;
+
+declare function deleteSegment(key: string): void;
+declare function clearSegments(): void;
+
+declare const HadarsContext: React$1.FC<{
+    children: React.ReactNode;
+    context: AppContext;
+}>;
+/**
+ * Dynamically loads a module with target-aware behaviour:
+ *
+ * - **Browser** (after loader transform): becomes `import('./path')`, which
+ *   rspack splits into a separate chunk for true code splitting.
+ * - **SSR** (after loader transform): becomes
+ *   `Promise.resolve(require('./path'))`, which rspack bundles statically.
+ *
+ * The hadars rspack loader must be active for the transform to apply.
+ * This runtime fallback uses a plain dynamic import (no code splitting).
+ *
+ * @example
+ * // Code-split React component:
+ * const MyComp = React.lazy(() => loadModule('./MyComp'));
+ *
+ * // Dynamic data:
+ * const { default: fn } = await loadModule<typeof import('./util')>('./util');
+ */
+declare function loadModule<T = any>(path: string): Promise<T>;
+
+export { CacheSegment, HadarsContext, Head as HadarsHead, clearSegments, deleteSegment, initServerDataCache, loadModule, useServerData };