@taujs/react 0.1.0 → 0.1.2

package/README.md

@@ -11,3 +11,7 @@
 React Renderer: CSR, SSR, Streaming SSR
 
 https://taujs.dev/
+
+A lightweight, production-ready React SSR library with streaming capabilities, built for modern TypeScript applications. Designed as part of the taujs (τjs) ecosystem but fully standalone and runtime-agnostic.
+
+https://taujs.dev/renderers/react/

package/dist/index.d.ts

@@ -22,10 +22,10 @@ type UILogger = {
     error: (...args: unknown[]) => void;
 };
 type ServerLogs = {
-    info: (message: string, meta?: unknown) => void;
-    warn: (message: string, meta?: unknown) => void;
-    error: (message: string, meta?: unknown) => void;
-    debug?: (category: string, message: string, meta?: unknown) => void;
+    info: (meta?: unknown, message?: string) => void;
+    warn: (meta?: unknown, message?: string) => void;
+    error: (meta?: unknown, message?: string) => void;
+    debug?: (category: string, meta?: unknown, message?: string) => void;
     child?: (ctx: Record<string, unknown>) => ServerLogs;
     isDebugEnabled?: (category: string) => boolean;
 };
@@ -56,6 +56,10 @@ type StreamOptions = {
     /** Whether to use cork/uncork for batched writes (default: true) */
     useCork?: boolean;
 };
+type HeadContext<T extends Record<string, unknown> = Record<string, unknown>> = {
+    data: T;
+    meta: Record<string, unknown>;
+};
 type SSRResult = {
     headContent: string;
     appHtml: string;
@@ -68,10 +72,7 @@ declare function createRenderer<T extends Record<string, unknown>>({ appComponen
     appComponent: (props: {
         location: string;
     }) => React.ReactElement;
-    headContent: (ctx: {
-        data: T;
-        meta: Record<string, unknown>;
-    }) => string;
+    headContent: (ctx: HeadContext<T>) => string;
     enableDebug?: boolean;
     logger?: LoggerLike;
     streamOptions?: StreamOptions;
@@ -85,4 +86,70 @@ declare function createRenderer<T extends Record<string, unknown>>({ appComponen
     };
 };
 
-export { type HydrateAppOptions, type RenderCallbacks, type SSRStore, SSRStoreProvider, type ServerLogs, type StreamOptions, createRenderer, createSSRStore, hydrateApp, useSSRStore };
+/**
+ * τjs Client Data Bridge
+ *
+ * Provides framework-agnostic primitives for accessing route data:
+ * - SSR hydration (window.__INITIAL_DATA__)
+ * - Client-side fetch (/__taujs/data endpoint)
+ *
+ * This is a transport layer only. For data orchestration (caching, refetch, etc.),
+ * use TanStack Query or similar.
+ */
+type RouteData = Record<string, unknown>;
+/**
+ * Error thrown when fetchRouteData receives a non-2xx response.
+ * Contains structured error information from the server.
+ */
+declare class RouteDataError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly code?: string;
+    readonly body?: unknown;
+    constructor(message: string, opts: {
+        status: number;
+        statusText: string;
+        code?: string;
+        body?: unknown;
+    });
+}
+/**
+ * Read SSR boot data from window.__INITIAL_DATA__ exactly once.
+ * Subsequent calls return null (forces client-side fetch).
+ *
+ * Returns null on server (typeof window === 'undefined').
+ */
+declare function readInitialDataOnce<T extends RouteData = RouteData>(): T | null;
+/**
+ * Fetch route data from the τjs data endpoint.
+ *
+ * Calls: GET /__taujs/data?url=<pathname>
+ * Returns: { data: T }
+ *
+ * Throws RouteDataError on non-2xx responses with structured error info.
+ *
+ * @example
+ * const data = await fetchRouteData('/app/dashboard');
+ *
+ * @example
+ * try {
+ *   const data = await fetchRouteData('/app/dashboard');
+ * } catch (err) {
+ *   if (err instanceof RouteDataError && err.status === 404) {
+ *     // Handle not found
+ *   }
+ * }
+ */
+declare function fetchRouteData<T extends RouteData = RouteData>(pathname: string, init?: RequestInit): Promise<T>;
+/**
+ * Get the current browser path (pathname + search).
+ * Does not include hash.
+ *
+ * Returns null on server (typeof window === 'undefined').
+ *
+ * @example
+ * const path = getCurrentPath(); // "/app/dashboard?tab=overview"
+ */
+declare function getCurrentPath(): string | null;
+
+export { type HeadContext, type HydrateAppOptions, type RenderCallbacks, type RouteData, RouteDataError, type SSRStore, SSRStoreProvider, type ServerLogs, type StreamOptions, createRenderer, createSSRStore, fetchRouteData, getCurrentPath, hydrateApp, readInitialDataOnce, useSSRStore };

package/dist/index.js

@@ -90,10 +90,16 @@ var splitMsgAndMeta = (args) => {
 };
 function createUILogger(logger, opts = {}) {
   const { debugCategory = "ssr", context, preferDebug = false, enableDebug = false } = opts;
-  if (!enableDebug) return { log: () => {
-  }, warn: () => {
-  }, error: () => {
-  } };
+  if (!enableDebug) {
+    return {
+      log: () => {
+      },
+      warn: () => {
+      },
+      error: () => {
+      }
+    };
+  }
   const looksServer = !!logger && ("info" in logger || "debug" in logger || "child" in logger || "isDebugEnabled" in logger);
   if (looksServer) {
     let s = logger;
@@ -103,11 +109,11 @@ function createUILogger(logger, opts = {}) {
       } catch {
       }
     }
-    const info = s.info ? s.info.bind(s) : (m, meta) => meta ? console.log(m, meta) : console.log(m);
-    const warn = s.warn ? s.warn.bind(s) : (m, meta) => meta ? console.warn(m, meta) : console.warn(m);
-    const error = s.error ? s.error.bind(s) : (m, meta) => meta ? console.error(m, meta) : console.error(m);
-    const debug = s.debug ? s.debug.bind(s) : void 0;
-    const isDebugEnabled = s.isDebugEnabled ? s.isDebugEnabled.bind(s) : void 0;
+    const info = s.info ? (msg, meta) => s.info(meta, msg) : (msg, meta) => meta ? console.log(msg, meta) : console.log(msg);
+    const warn = s.warn ? (msg, meta) => s.warn(meta, msg) : (msg, meta) => meta ? console.warn(msg, meta) : console.warn(msg);
+    const error = s.error ? (msg, meta) => s.error(meta, msg) : (msg, meta) => meta ? console.error(msg, meta) : console.error(msg);
+    const debug = s.debug ? (category, msg, meta) => s.debug(category, meta, msg) : void 0;
+    const isDebugEnabled = s.isDebugEnabled ? (category) => s.isDebugEnabled(category) : void 0;
     return {
       log: (...args) => {
         const { msg, meta } = splitMsgAndMeta(args);
@@ -345,6 +351,8 @@ function createStreamController(writable, logger) {
 
 // src/SSRRender.tsx
 import { jsx as jsx3 } from "react/jsx-runtime";
+var NOOP = () => {
+};
 function createRenderer({
   appComponent,
   headContent,
@@ -385,7 +393,13 @@ function createRenderer({
     }
   };
   const renderStream = (writable, callbacks = {}, initialData, location, bootstrapModules, meta = {}, cspNonce, signal, opts) => {
-    const { onAllReady, onError, onHead, onShellReady, onFinish } = callbacks;
+    const cb = {
+      onHead: callbacks.onHead ?? NOOP,
+      onShellReady: callbacks.onShellReady ?? NOOP,
+      onAllReady: callbacks.onAllReady ?? NOOP,
+      onFinish: callbacks.onFinish ?? NOOP,
+      onError: callbacks.onError ?? NOOP
+    };
     const { log, warn, error } = createUILogger(opts?.logger ?? logger, {
       debugCategory: "ssr",
       context: { scope: "react-streaming" },
@@ -412,17 +426,17 @@ function createRenderer({
     const { cleanup: guardsCleanup } = wireWritableGuards(writable, {
       benignAbort: (why) => controller.benignAbort(why),
       fatalAbort: (err) => {
-        onError?.(err);
+        cb.onError(err);
         controller.fatalAbort(err);
       },
-      onError,
+      onError: cb.onError,
       onFinish: () => controller.complete("Stream finished (normal completion)")
     });
     controller.setGuardsCleanup(guardsCleanup);
     const stopShellTimer = startShellTimer(effectiveShellTimeout, () => {
       if (controller.isAborted) return;
       const timeoutErr = new Error(`Shell not ready after ${effectiveShellTimeout}ms`);
-      onError?.(timeoutErr);
+      cb.onError(timeoutErr);
       controller.fatalAbort(timeoutErr);
     });
     controller.setStopShellTimer(stopShellTimer);
@@ -451,16 +465,15 @@ function createRenderer({
               }
             }
             const head = headContent({ data: headData ?? {}, meta });
-            const canCork = effectiveUseCork && typeof writable?.cork === "function" && typeof writable?.uncork === "function";
-            if (canCork) {
+            const canCork = effectiveUseCork && typeof writable.cork === "function" && typeof writable.uncork === "function";
+            if (canCork)
               try {
                 writable.cork();
               } catch {
               }
-            }
             let wroteOk = true;
             try {
-              const res = writable?.write ? writable.write(head) : true;
+              const res = typeof writable.write === "function" ? writable.write(head) : true;
               wroteOk = res !== false;
             } finally {
               if (canCork) {
@@ -472,21 +485,25 @@ function createRenderer({
             }
             let forceWait = false;
             try {
-              const ret = onHead?.(head);
-              forceWait = ret === false;
+              forceWait = cb.onHead(head) === false;
             } catch (cbErr) {
               warn("onHead callback threw:", cbErr);
             }
             const startPipe = () => stream.pipe(writable);
-            if (forceWait || !wroteOk) writable?.once?.("drain", startPipe);
-            else startPipe();
+            if (forceWait || !wroteOk) {
+              if (typeof writable.once === "function") {
+                writable.once("drain", startPipe);
+              } else {
+                startPipe();
+              }
+            } else startPipe();
             try {
-              onShellReady?.();
+              cb.onShellReady();
             } catch (cbErr) {
               warn("onShellReady callback threw:", cbErr);
             }
           } catch (err) {
-            onError?.(err);
+            cb.onError(err);
             controller.fatalAbort(err);
           }
         },
@@ -496,18 +513,18 @@ function createRenderer({
           const deliver = () => {
             try {
               const data = store.getSnapshot();
-              onAllReady?.(data);
-              onFinish?.(data);
+              cb.onAllReady(data);
+              cb.onFinish(data);
             } catch (thrown) {
               if (thrown && typeof thrown.then === "function") {
                 thrown.then(deliver).catch((e) => {
                   error("Data promise rejected:", e);
-                  onError?.(e);
+                  cb.onError(e);
                   controller.fatalAbort(e);
                 });
               } else {
                 error("Unexpected throw from getSnapshot:", thrown);
-                onError?.(thrown);
+                cb.onError(thrown);
                 controller.fatalAbort(thrown);
               }
             }
@@ -520,24 +537,24 @@ function createRenderer({
             stopShellTimer();
           } catch {
           }
-          onError?.(err);
+          cb.onError(err);
           controller.fatalAbort(err);
         },
         onError(err) {
           if (controller.isAborted) return;
           const msg = String(err?.message ?? "");
-          warn?.("React stream error:", msg);
+          warn("React stream error:", msg);
           if (isBenignStreamErr(err)) {
             controller.benignAbort("Client disconnected before stream finished");
             return;
           }
-          onError?.(err);
+          cb.onError(err);
           controller.fatalAbort(err);
         }
       });
       controller.setStreamAbort(() => stream.abort());
     } catch (err) {
-      onError?.(err);
+      cb.onError(err);
       controller.fatalAbort(err);
     }
     return {
@@ -548,10 +565,73 @@ function createRenderer({
   };
   return { renderSSR, renderStream };
 }
+
+// src/RouteData.ts
+var RouteDataError = class _RouteDataError extends Error {
+  status;
+  statusText;
+  code;
+  body;
+  constructor(message, opts) {
+    super(message);
+    this.name = "RouteDataError";
+    this.status = opts.status;
+    this.statusText = opts.statusText;
+    this.code = opts.code;
+    this.body = opts.body;
+    Object.setPrototypeOf(this, _RouteDataError.prototype);
+  }
+};
+var INITIAL_DATA_KEY = "__INITIAL_DATA__";
+function readInitialDataOnce() {
+  if (typeof window === "undefined") return null;
+  const w = window;
+  const data = w[INITIAL_DATA_KEY];
+  if (!data) return null;
+  delete w[INITIAL_DATA_KEY];
+  return data;
+}
+async function fetchRouteData(pathname, init) {
+  if (!pathname) {
+    throw new Error("fetchRouteData: pathname is required");
+  }
+  const url = `/__taujs/data?url=${encodeURIComponent(pathname)}`;
+  const res = await fetch(url, {
+    credentials: "include",
+    ...init
+  });
+  if (!res.ok) {
+    let body2;
+    try {
+      body2 = await res.json();
+    } catch {
+      const text = await res.text().catch(() => "");
+      body2 = { error: text };
+    }
+    const json = body2;
+    throw new RouteDataError(json.error ?? `Request failed: ${res.status}`, {
+      status: res.status,
+      statusText: json.statusText ?? res.statusText,
+      code: json.code,
+      body: body2
+    });
+  }
+  const body = await res.json();
+  return body.data ?? {};
+}
+function getCurrentPath() {
+  if (typeof window === "undefined") return null;
+  const { pathname, search } = window.location;
+  return `${pathname}${search}`;
+}
 export {
+  RouteDataError,
   SSRStoreProvider,
   createRenderer,
   createSSRStore,
+  fetchRouteData,
+  getCurrentPath,
   hydrateApp,
+  readInitialDataOnce,
   useSSRStore
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taujs/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "taujs | τjs",
   "author": "Aoede <taujs@aoede.uk.net> (https://www.aoede.uk.net)",
   "license": "MIT",