hadars 0.4.1 → 0.4.2

package/src/cloudflare.ts

@@ -1,140 +0,0 @@
-/**
- * Cloudflare Workers adapter for hadars.
- *
- * After running `hadars build`, bundle your app with:
- *
- *   hadars export cloudflare
- *
- * This produces a self-contained `cloudflare.mjs` that you deploy with:
- *
- *   wrangler deploy
- *
- * Static assets (JS, CSS, fonts) under `.hadars/static/` must be served from
- * R2 or another CDN — the Worker only handles HTML rendering. Route requests
- * for static file extensions to R2 and everything else to the Worker.
- *
- * @example wrangler.toml
- *   name = "my-app"
- *   main = "cloudflare.mjs"
- *   compatibility_date = "2024-09-23"
- *   compatibility_flags = ["nodejs_compat"]
- */
-
-import React from 'react';
-import { parseRequest } from './utils/request';
-import { createProxyHandler } from './utils/proxyHandler';
-import { getReactResponse, buildHeadHtml } from './utils/response';
-import { buildSsrHtml, makePrecontentHtmlGetter, createRenderCache } from './utils/ssrHandler';
-import type { HadarsOptions, HadarsEntryModule, HadarsProps } from './types/hadars';
-
-// ── Public types ──────────────────────────────────────────────────────────────
-
-/**
- * Pre-loaded SSR module and HTML template for single-file Cloudflare bundles
- * produced by `hadars export cloudflare`. All I/O is eliminated at runtime —
- * the Worker is fully self-contained.
- */
-export interface CloudflareBundled {
-    /** The compiled SSR module — import it statically in your entry shim. */
-    ssrModule: HadarsEntryModule<any>;
-    /**
-     * The contents of `.hadars/static/out.html` — esbuild inlines this as a
-     * string when `hadars export cloudflare` runs.
-     */
-    outHtml: string;
-}
-
-/**
- * The shape of a Cloudflare Workers export object.
- * Return this as the default export of your Worker entry file.
- */
-export interface CloudflareHandler {
-    fetch(request: Request, env: unknown, ctx: unknown): Promise<Response>;
-}
-
-// ── Handler factory ───────────────────────────────────────────────────────────
-
-/**
- * Creates a Cloudflare Workers handler from a hadars config and a pre-bundled
- * SSR module. Use this as the default export of your Worker entry.
- *
- * Unlike the Lambda adapter, Cloudflare Workers receive a standard Web
- * `Request` and return a standard `Response` — no event format conversion is
- * required. Static assets must be routed to R2/CDN via wrangler rules; this
- * Worker handles only HTML rendering and API routes.
- *
- * @example — generated entry shim (created by `hadars export cloudflare`)
- * import * as ssrModule from './.hadars/index.ssr.js';
- * import outHtml from './.hadars/static/out.html';
- * import { createCloudflareHandler } from 'hadars/cloudflare';
- * import config from './hadars.config';
- * export default createCloudflareHandler(config, { ssrModule, outHtml });
- */
-export function createCloudflareHandler(
-    options: HadarsOptions,
-    bundled: CloudflareBundled,
-): CloudflareHandler {
-    const fetchHandler     = options.fetch;
-    const handleProxy      = createProxyHandler(options);
-    const getPrecontentHtml = makePrecontentHtmlGetter(Promise.resolve(bundled.outHtml));
-    const { ssrModule }    = bundled;
-
-    const runHandler = async (req: Request): Promise<Response> => {
-        const request = parseRequest(req);
-
-        if (fetchHandler) {
-            const res = await fetchHandler(request);
-            if (res) return res;
-        }
-
-        const proxied = await handleProxy(request);
-        if (proxied) return proxied;
-
-        try {
-            const { default: Component, getInitProps, getFinalProps } = ssrModule;
-
-            const { head, status, getAppBody, finalize } = await getReactResponse(request, {
-                document: {
-                    body: Component as React.FC<HadarsProps<object>>,
-                    lang: 'en',
-                    getInitProps,
-                    getFinalProps,
-                },
-            });
-
-            // Data-only requests from client-side navigation.
-            if (request.headers.get('Accept') === 'application/json') {
-                const { clientProps } = await finalize();
-                const serverData = (clientProps as any).__serverData ?? {};
-                return new Response(JSON.stringify({ serverData }), {
-                    status,
-                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
-                });
-            }
-
-            const bodyHtml = await getAppBody();
-            const { clientProps } = await finalize();
-            const headHtml = buildHeadHtml(head);
-            const html = await buildSsrHtml(bodyHtml, clientProps, headHtml, getPrecontentHtml);
-
-            return new Response(html, {
-                status,
-                headers: { 'Content-Type': 'text/html; charset=utf-8' },
-            });
-        } catch (err: any) {
-            console.error('[hadars] SSR render error:', err);
-            options.onError?.(err, request)?.catch?.(() => {});
-            return new Response('Internal Server Error', { status: 500 });
-        }
-    };
-
-    const finalFetch = options.cache
-        ? createRenderCache(options.cache, (req) => runHandler(req))
-        : (req: Request) => runHandler(req);
-
-    return {
-        fetch: async (request: Request, _env: unknown, ctx: unknown): Promise<Response> => {
-            return (await finalFetch(request, ctx)) ?? new Response('Not Found', { status: 404 });
-        },
-    };
-}

package/src/index.tsx

@@ -1,41 +0,0 @@
-export type {
-    HadarsOptions,
-    HadarsProps,
-    HadarsRequest,
-    HadarsGetFinalProps,
-    HadarsGetInitialProps,
-    HadarsGetClientProps,
-    HadarsEntryModule,
-    HadarsApp,
-    HadarsStaticContext,
-    GraphQLExecutor,
-    HadarsSourceEntry,
-    HadarsDocumentNode,
-} from "./types/hadars";
-export { Head as HadarsHead, useServerData, useGraphQL, initServerDataCache } from './utils/Head';
-
-/**
- * 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');
- */
-export function loadModule<T = any>(path: string): Promise<T> {
-    // webpackIgnore suppresses rspack's "critical dependency" warning for the
-    // variable import. This body is a fallback only — the hadars loader
-    // transforms every loadModule('./...') call site at compile time, so this
-    // function is never invoked in a bundled build.
-    return import(/* webpackIgnore: true */ path) as Promise<T>;
-}

package/src/lambda.ts

@@ -1,287 +0,0 @@
-/**
- * AWS Lambda adapter for hadars.
- *
- * After running `hadars build`, import this in your Lambda entry file:
- *
- *   // lambda.ts
- *   import { createLambdaHandler } from 'hadars/lambda';
- *   import config from './hadars.config';
- *   export const handler = createLambdaHandler(config);
- *
- * The returned handler speaks the API Gateway HTTP API (v2) payload format.
- * API Gateway REST API (v1) events are also accepted.
- *
- * Static assets (JS, CSS, fonts) are served directly from the bundled
- * `.hadars/static/` directory. For production use, front the Lambda with
- * CloudFront and route static paths to an S3 origin instead.
- */
-
-import React from 'react';
-import pathMod from 'node:path';
-import { pathToFileURL } from 'node:url';
-import fs from 'node:fs/promises';
-import { createProxyHandler } from './utils/proxyHandler';
-import { parseRequest } from './utils/request';
-import { tryServeFile } from './utils/staticFile';
-import { getReactResponse, buildHeadHtml } from './utils/response';
-import { buildSsrResponse, buildSsrHtml, makePrecontentHtmlGetter, createRenderCache } from './utils/ssrHandler';
-import type { HadarsOptions, HadarsEntryModule, HadarsProps } from './types/hadars';
-
-// ── Lambda event / response types ────────────────────────────────────────────
-
-/** API Gateway HTTP API (v2) event. */
-export interface APIGatewayV2Event {
-    version: '2.0';
-    routeKey: string;
-    rawPath: string;
-    rawQueryString: string;
-    cookies?: string[];
-    headers: Record<string, string>;
-    requestContext: {
-        http: { method: string };
-        domainName: string;
-    };
-    body?: string;
-    isBase64Encoded: boolean;
-}
-
-/** API Gateway REST API (v1) event. */
-export interface APIGatewayV1Event {
-    httpMethod: string;
-    path: string;
-    queryStringParameters?: Record<string, string> | null;
-    headers?: Record<string, string> | null;
-    body?: string | null;
-    isBase64Encoded: boolean;
-}
-
-export type APIGatewayEvent = APIGatewayV2Event | APIGatewayV1Event;
-
-export interface LambdaResponse {
-    statusCode: number;
-    headers: Record<string, string>;
-    body: string;
-    isBase64Encoded: boolean;
-}
-
-export type LambdaHandler = (event: APIGatewayEvent) => Promise<LambdaResponse>;
-
-// ── Event → Request ───────────────────────────────────────────────────────────
-
-function eventToRequest(event: APIGatewayEvent): Request {
-    let method: string;
-    let path: string;
-    let queryString: string;
-    let headers: Record<string, string>;
-    let rawBody: string | undefined | null;
-    let isBase64: boolean;
-    let host: string;
-
-    if ('version' in event && event.version === '2.0') {
-        method      = event.requestContext.http.method;
-        path        = event.rawPath;
-        queryString = event.rawQueryString;
-        headers     = { ...event.headers };
-        // v2 puts cookies in a separate array; merge them back into the header
-        if (event.cookies?.length) headers['cookie'] = event.cookies.join('; ');
-        rawBody     = event.body;
-        isBase64    = event.isBase64Encoded;
-        host        = event.requestContext.domainName;
-    } else {
-        const e  = event as APIGatewayV1Event;
-        method      = e.httpMethod;
-        path        = e.path;
-        const qs    = e.queryStringParameters;
-        queryString = qs ? new URLSearchParams(qs as Record<string, string>).toString() : '';
-        headers     = (e.headers as Record<string, string>) ?? {};
-        rawBody     = e.body;
-        isBase64    = e.isBase64Encoded;
-        host        = headers['host'] ?? 'lambda';
-    }
-
-    const url  = `https://${host}${path}${queryString ? '?' + queryString : ''}`;
-    let body: BodyInit | undefined;
-    if (rawBody) body = isBase64 ? Buffer.from(rawBody, 'base64') : rawBody;
-
-    return new Request(url, {
-        method,
-        headers,
-        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
-    });
-}
-
-// ── Response → Lambda ─────────────────────────────────────────────────────────
-
-const TEXT_RE = /\b(?:text\/|application\/(?:json|javascript|xml)|image\/svg\+xml)/;
-
-async function responseToLambda(response: Response): Promise<LambdaResponse> {
-    const headers: Record<string, string> = {};
-    response.headers.forEach((v, k) => { headers[k] = v; });
-
-    const contentType = response.headers.get('Content-Type') ?? '';
-    // A Content-Encoding header means the body is already compressed (binary).
-    // Calling .text() on gzip/br/deflate bytes would corrupt the data, so always
-    // treat compressed responses as binary regardless of Content-Type.
-    const encoding = response.headers.get('Content-Encoding') ?? '';
-    if (!encoding && TEXT_RE.test(contentType)) {
-        return {
-            statusCode: response.status,
-            headers,
-            body: await response.text(),
-            isBase64Encoded: false,
-        };
-    }
-
-    // Binary response (images, fonts, pre-compressed assets, gzip cache hits, etc.)
-    return {
-        statusCode: response.status,
-        headers,
-        body: Buffer.from(await response.arrayBuffer()).toString('base64'),
-        isBase64Encoded: true,
-    };
-}
-
-// ── Public API ────────────────────────────────────────────────────────────────
-
-const HadarsFolder = './.hadars';
-const StaticPath   = `${HadarsFolder}/static`;
-const SSR_FILENAME = 'index.ssr.js';
-const noopCtx      = { upgrade: () => false };
-
-/**
- * Pre-loaded module and HTML for single-file Lambda bundles created by
- * `hadars export lambda`. Passing this bypasses all runtime file I/O so
- * the handler works without a `.hadars/` directory on disk.
- */
-export interface LambdaBundled {
-    /** The compiled SSR module — import it statically in your entry shim. */
-    ssrModule: HadarsEntryModule<any>;
-    /**
-     * The contents of `.hadars/static/out.html` — load it as a text string
-     * at build time (esbuild's `--loader:.html=text` does this automatically
-     * when `hadars export lambda` runs).
-     */
-    outHtml: string;
-}
-
-/**
- * Creates an AWS Lambda handler from a hadars config.
- *
- * Must be called after `hadars build` has produced the `.hadars/` output
- * directory. The handler is stateless — Lambda can reuse the same instance
- * across invocations; the SSR module and HTML template are cached in memory
- * after the first warm invocation.
- *
- * Pass a {@link LambdaBundled} object as the second argument when using
- * `hadars export lambda` to produce a single-file bundle — in that mode all
- * I/O is eliminated and the handler is fully self-contained.
- *
- * @example — standard (file-based) deployment
- * export const handler = createLambdaHandler(config);
- *
- * @example — single-file bundle (generated entry shim)
- * import * as ssrModule from './.hadars/index.ssr.js';
- * import outHtml from './.hadars/static/out.html';
- * export const handler = createLambdaHandler(config, { ssrModule, outHtml });
- */
-export function createLambdaHandler(options: HadarsOptions, bundled?: LambdaBundled): LambdaHandler {
-    const cwd          = process.cwd();
-    const fetchHandler = options.fetch;
-    const handleProxy  = createProxyHandler(options);
-
-    const getPrecontentHtml = bundled
-        ? makePrecontentHtmlGetter(Promise.resolve(bundled.outHtml))
-        : makePrecontentHtmlGetter(fs.readFile(pathMod.join(cwd, StaticPath, 'out.html'), 'utf-8'));
-
-    // Start loading the SSR module immediately — during Lambda's init phase this
-    // is "free" time not billed against request latency.  Lazy loading would
-    // push the module parse cost onto the first request.
-    const ssrModulePromise: Promise<HadarsEntryModule<any>> = bundled
-        ? Promise.resolve(bundled.ssrModule)
-        : import(pathToFileURL(pathMod.resolve(cwd, HadarsFolder, SSR_FILENAME)).href) as Promise<HadarsEntryModule<any>>;
-    const getSsrModule = () => ssrModulePromise;
-
-    const runHandler = async (req: Request): Promise<Response> => {
-        const request = parseRequest(req);
-
-        if (fetchHandler) {
-            const res = await fetchHandler(request);
-            if (res) return res;
-        }
-
-        const proxied = await handleProxy(request);
-        if (proxied) return proxied;
-
-        // parseRequest already extracted pathname — no need to re-parse the URL.
-        const urlPath = request.pathname;
-
-        if (!bundled) {
-            // File-based deployment: serve static assets from disk.
-            // Run the three candidate lookups in parallel to avoid sequential stat() syscalls.
-            const projectStaticPath = pathMod.resolve(cwd, 'static');
-            const routeClean = urlPath.replace(/(^\/|\/$)/g, '');
-            const [staticRes, projectRes, routeRes] = await Promise.all([
-                tryServeFile(pathMod.join(cwd, StaticPath, urlPath)),
-                tryServeFile(pathMod.join(projectStaticPath, urlPath)),
-                routeClean
-                    ? tryServeFile(pathMod.join(cwd, StaticPath, routeClean, 'index.html'))
-                    : Promise.resolve(null),
-            ]);
-            if (staticRes) return staticRes;
-            if (projectRes) return projectRes;
-            if (routeRes)   return routeRes;
-        }
-        // bundled mode: static assets are not served from Lambda — route them to S3/CDN.
-
-        try {
-            const {
-                default: Component,
-                getInitProps,
-                getFinalProps,
-            } = await getSsrModule();
-
-            const { head, status, getAppBody, finalize } = await getReactResponse(request, {
-                document: {
-                    body: Component as React.FC<HadarsProps<object>>,
-                    lang: 'en',
-                    getInitProps,
-                    getFinalProps,
-                },
-            });
-
-            if (request.headers.get('Accept') === 'application/json') {
-                const { clientProps } = await finalize();
-                const serverData = (clientProps as any).__serverData ?? {};
-                return new Response(JSON.stringify({ serverData }), {
-                    status,
-                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
-                });
-            }
-
-            // Build the HTML string directly — avoids creating a ReadableStream
-            // that would immediately be drained by the Lambda response serialiser.
-            const bodyHtml = await getAppBody();
-            const { clientProps } = await finalize();
-            const headHtml = buildHeadHtml(head);
-            const html = await buildSsrHtml(bodyHtml, clientProps, headHtml, getPrecontentHtml);
-            return new Response(html, {
-                status,
-                headers: { 'Content-Type': 'text/html; charset=utf-8' },
-            });
-        } catch (err: any) {
-            console.error('[hadars] SSR render error:', err);
-            options.onError?.(err, request)?.catch?.(() => {});
-            return new Response('Internal Server Error', { status: 500 });
-        }
-    };
-
-    const finalHandler: (req: Request, ctx: any) => Promise<Response | undefined> = options.cache
-        ? createRenderCache(options.cache, (req) => runHandler(req))
-        : (req: Request) => runHandler(req);
-
-    return async (event: APIGatewayEvent): Promise<LambdaResponse> => {
-        const req      = eventToRequest(event);
-        const response = (await finalHandler(req, noopCtx)) ?? new Response('Not Found', { status: 404 });
-        return responseToLambda(response);
-    };
-}

package/src/slim-react/context.ts

@@ -1,55 +0,0 @@
-import type { SlimNode } from "./types";
-import { getContextValue } from "./renderContext";
-
-/**
- * Minimal Context implementation for SSR.
- *
- * Because SSR is single-pass and synchronous within each component,
- * we just track the "current" value on the context object and
- * save / restore around Provider renders (handled by the renderer).
- */
-
-export interface Context<T> {
-  _defaultValue: T;
-  _currentValue: T; // kept for external compat (real React contexts passed to useContext)
-  Provider: ContextProvider<T>;
-  Consumer: (props: { children: (value: T) => SlimNode }) => SlimNode;
-}
-
-export type ContextProvider<T> = ((props: {
-  value: T;
-  children?: SlimNode;
-}) => SlimNode) & {
-  _context: Context<T>;
-};
-
-export function createContext<T>(defaultValue: T): Context<T> {
-  const context: Context<T> = {
-    _defaultValue: defaultValue,
-    _currentValue: defaultValue,
-    Provider: null!,
-    Consumer: null!,
-  };
-
-  // Provider is a function component recognised by the renderer.
-  // The `_context` tag tells the renderer to push / pop the value.
-  const Provider = function ContextProvider({
-    children,
-  }: {
-    value: T;
-    children?: SlimNode;
-  }): SlimNode {
-    return children ?? null;
-  } as unknown as ContextProvider<T>;
-
-  Provider._context = context;
-  context.Provider = Provider;
-
-  context.Consumer = ({ children }) => {
-    return (children as unknown as (value: T) => SlimNode)(
-      getContextValue<T>(context),
-    );
-  };
-
-  return context;
-}

package/src/slim-react/dispatcher.ts

@@ -1,87 +0,0 @@
-/**
- * React dispatcher shim for slim-react SSR.
- *
- * During a slim-react render, `React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE.H`
- * is null, so any component that calls `React.useId()` (or another hook) via
- * React's own package will hit `resolveDispatcher()` → null → error.
- *
- * We install a minimal dispatcher object for the duration of each component
- * call so that `React.useId()` routes through slim-react's tree-aware
- * `makeId()`.  All other hooks already have working SSR stubs in hooks.ts;
- * they are forwarded here so libraries that call them via `React.*` also work.
- *
- * In the Rspack SSR bundle `react` is aliased to `slim-react`, which does NOT
- * export `__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE`.
- * Accessing that property via a namespace import (`import * as`) always returns
- * `undefined` safely — `import default from "react"` would crash via interop
- * because Rspack compiles it as `require("react").default`, and slim-react has
- * no `default` export, so `.default` itself is `undefined` and the subsequent
- * property access throws.
- *
- * With the namespace import, `_internals` is `undefined` in the SSR bundle and
- * the install/restore functions become no-ops, which is correct: the SSR bundle
- * already routes all `React.*` hook calls to slim-react's own implementations.
- */
-
-import { makeId, getContextValue } from "./renderContext";
-import {
-  useState, useReducer, useEffect, useLayoutEffect, useInsertionEffect,
-  useRef, useMemo, useCallback, useDebugValue, useImperativeHandle,
-  useSyncExternalStore, useTransition, useDeferredValue,
-  useOptimistic, useActionState, use,
-} from "./hooks";
-
-// Use namespace import so that when `react` is aliased to slim-react in the
-// Rspack SSR bundle, `ReactNS` is always an object (never undefined), and
-// accessing a missing property returns `undefined` rather than throwing.
-import * as ReactNS from "react";
-
-// React 19 exposes its shared internals under this key.
-// Bracket notation prevents rspack from treating this as a named-export access
-// on the "react" module (which would produce an ESModulesLinkingWarning).
-const _reactInternalsKey = "__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE";
-const _internals: { H: object | null } | undefined =
-  (ReactNS as any)[_reactInternalsKey];
-
-// The dispatcher object we install. We keep a stable reference so the same
-// object is reused across every component call.
-const slimDispatcher: Record<string, unknown> = {
-  useId: makeId,
-  readContext: (ctx: any) => getContextValue(ctx),
-  useContext: (ctx: any) => getContextValue(ctx),
-  useState,
-  useReducer,
-  useEffect,
-  useLayoutEffect,
-  useInsertionEffect,
-  useRef,
-  useMemo,
-  useCallback,
-  useDebugValue,
-  useImperativeHandle,
-  useSyncExternalStore,
-  useTransition,
-  useDeferredValue,
-  useOptimistic,
-  useActionState,
-  use,
-  // React internals that compiled output may call
-  useMemoCache: (size: number) => new Array(size).fill(undefined),
-  useCacheRefresh: () => () => {},
-  useHostTransitionStatus: () => false,
-};
-
-/**
- * Install the slim dispatcher and return the previous value.
- * Call `restoreDispatcher(prev)` when the component finishes.
- */
-export function installDispatcher(): object | null {
-  if (!_internals) return null;
-  const prev = _internals.H;
-  _internals.H = slimDispatcher;
-  return prev;
-}
-
-export function restoreDispatcher(prev: object | null): void {
-  if (_internals) _internals.H = prev;
-}