@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.190fb30d

package/src/index.ts

@@ -10,9 +10,6 @@
  *   import from "@rangojs/router/client"
  */
 
-// Universal rendering utilities (work on both server and client)
-export { renderSegments } from "./segment-system.js";
-
 // Error classes (can be used on both server and client)
 export {
   RouteNotFoundError,
@@ -21,10 +18,8 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
   Skip,
   isSkip,
@@ -41,7 +36,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler, // Supports params object, path pattern, or route name
-  ScopedRouteMap, // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -50,6 +44,7 @@ export type {
   // Revalidation types
   RevalidateParams,
   Revalidate,
+  ActionRef,
   RouteKeys,
   // Loader types
   LoaderDefinition,
@@ -87,7 +82,12 @@ export { createLoader } from "./loader.js";
 
 // Route definition types (safe to import anywhere)
 export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
-export type { TransitionConfig, ViewTransitionClass } from "./types.js";
+export type {
+  TransitionConfig,
+  TransitionWhenFn,
+  TransitionWhenContext,
+  ViewTransitionClass,
+} from "./types.js";
 
 // Composition types for reusable callback factories
 export type {
@@ -95,6 +95,7 @@ export type {
   LayoutUseItem,
   AllUseItems,
   UseItems,
+  HandlerUseItem,
 } from "./route-types.js";
 
 // Response route types (usable in both server and client contexts)
@@ -108,36 +109,49 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
+  PartialPrerenderProps,
 } from "./urls.js";
 
 // Middleware context types
 export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
 
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
 export function urls(): never {
-  throw new Error("urls() is server-only and requires RSC context.");
+  throw serverOnlyStubError("urls");
 }
 
 /**
  * Error-throwing stub for server-only `createRouter` function.
  */
 export function createRouter(): never {
-  throw new Error("createRouter() is server-only and requires RSC context.");
+  throw serverOnlyStubError("createRouter");
 }
 
 /**
  * Error-throwing stub for server-only `redirect` function.
  */
 export function redirect(): never {
-  throw new Error("redirect() is server-only and requires RSC context.");
+  throw serverOnlyStubError("redirect");
 }
 
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
+export {
+  DEFAULT_DEFER_TIMEOUT_MS,
+  type DeferOptions,
+  type HandlePush,
+  type HandlePushFn,
+} from "./defer.js";
 
 // Context variable API (typed ctx.set/ctx.get tokens)
 export { createVar, type ContextVar } from "./context-var.js";
@@ -146,110 +160,146 @@ export { createVar, type ContextVar } from "./context-var.js";
 export { nonce } from "./rsc/nonce.js";
 
 /**
- * Error-throwing stub for server-only `Prerender` function.
+ * SSR/client stub for server-only `Prerender` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Prerender
+ * calls in RSC code must not crash at module-evaluation time.
  */
-export function Prerender(): never {
-  throw new Error("Prerender() is server-only and requires RSC context.");
+export function Prerender(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "prerenderHandler" as const, $$id: id };
 }
 
 /**
- * Error-throwing stub for server-only `Static` function.
+ * SSR/client stub for server-only `Passthrough` function.
  */
-export function Static(): never {
-  throw new Error("Static() is server-only and requires RSC context.");
+export function Passthrough(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "passthroughHandler" as const, $$id: id };
+}
+
+/**
+ * SSR/client stub for server-only `Static` function.
+ *
+ * Returns a lightweight stub object instead of throwing so that the
+ * production SSR build can safely bundle the RSC entry chunk — the SSR
+ * bundler resolves `@rangojs/router` to this (SSR) entry, so Static
+ * calls in RSC code must not crash at module-evaluation time.
+ */
+export function Static(
+  _handler?: any,
+  _optionsOrId?: any,
+  __injectedId?: string,
+): any {
+  const id =
+    typeof _optionsOrId === "string" ? _optionsOrId : __injectedId || "";
+  return { __brand: "staticHandler" as const, $$id: id };
 }
 
 /**
  * Error-throwing stub for server-only `getRequestContext` function.
  */
 export function getRequestContext(): never {
-  throw new Error(
-    "getRequestContext() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("getRequestContext");
 }
 
 /**
  * Error-throwing stub for server-only `cookies` function.
  */
 export function cookies(): never {
-  throw new Error("cookies() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cookies");
 }
 
 /**
  * Error-throwing stub for server-only `headers` function.
  */
 export function headers(): never {
-  throw new Error("headers() is server-only and requires RSC context.");
-}
-
-/**
- * Error-throwing stub for server-only `createReverse` function.
- */
-export function createReverse(): never {
-  throw new Error("createReverse() is server-only and requires RSC context.");
+  throw serverOnlyStubError("headers");
 }
 
 /**
- * Error-throwing stub for server-only `enableMatchDebug` function.
+ * Client implementation of `invalidateClientCache()`. Unlike the server-only
+ * stubs above this is a REAL function under the `default` condition (it marks
+ * the client's caches stale); the `react-server` condition (index.rsc.ts)
+ * selects the server implementation that writes a rotated `Set-Cookie`.
  */
-export function enableMatchDebug(): never {
-  throw new Error(
-    "enableMatchDebug() is server-only and requires RSC context.",
-  );
-}
+export {
+  invalidateClientCache,
+  keepClientCache,
+} from "./browser/invalidate-client-cache.js";
 
 /**
- * Error-throwing stub for server-only `getMatchDebugStats` function.
+ * Error-throwing stub for server-only `createReverse` function.
  */
-export function getMatchDebugStats(): never {
-  throw new Error(
-    "getMatchDebugStats() is server-only and requires RSC context.",
-  );
+export function createReverse(): never {
+  throw serverOnlyStubError("createReverse");
 }
 
 // Error-throwing stubs for server-only route helpers
 export function layout(): never {
-  throw new Error("layout() is server-only and requires RSC context.");
+  throw serverOnlyStubError("layout");
 }
 export function cache(): never {
-  throw new Error("cache() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cache");
 }
 export function middleware(): never {
-  throw new Error("middleware() is server-only and requires RSC context.");
+  throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw new Error("revalidate() is server-only and requires RSC context.");
+  throw serverOnlyStubError("revalidate");
+}
+// Cache tag APIs are server-only (real implementations in index.rsc.ts). These
+// stubs keep the named-export shape identical under the default/non-react-server
+// condition so SSR/client/default bundles that encounter the import link cleanly.
+export function cacheTag(): never {
+  throw serverOnlyStubError("cacheTag");
+}
+export function updateTag(): never {
+  throw serverOnlyStubError("updateTag");
+}
+export function revalidateTag(): never {
+  throw serverOnlyStubError("revalidateTag");
 }
 export function loader(): never {
-  throw new Error("loader() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loader");
 }
 export function loading(): never {
-  throw new Error("loading() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loading");
 }
 export function parallel(): never {
-  throw new Error("parallel() is server-only and requires RSC context.");
+  throw serverOnlyStubError("parallel");
 }
 export function intercept(): never {
-  throw new Error("intercept() is server-only and requires RSC context.");
-}
-export function when(): never {
-  throw new Error("when() is server-only and requires RSC context.");
+  throw serverOnlyStubError("intercept");
 }
 export function errorBoundary(): never {
-  throw new Error("errorBoundary() is server-only and requires RSC context.");
+  throw serverOnlyStubError("errorBoundary");
 }
 export function notFoundBoundary(): never {
-  throw new Error(
-    "notFoundBoundary() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw new Error("transition() is server-only and requires RSC context.");
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)
 export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
 
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 // Cookie store types (safe for client)
 export type {
   CookieStore,
@@ -257,17 +307,27 @@ export type {
   ReadonlyHeaders,
 } from "./server/cookie-store.js";
 
+// Built-in handles (universal — work on both server and client)
+export { Meta } from "./handles/meta.js";
+export {
+  Script,
+  type ScriptConfig,
+  type ScriptAttributes,
+} from "./handles/script.js";
+export { Breadcrumbs } from "./handles/breadcrumbs.js";
+
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
+// Breadcrumb types
+export type { BreadcrumbItem } from "./handles/breadcrumbs.js";
+
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
 export type {
   ScopedReverseFunction,
   ReverseFunction,
   ExtractLocalRoutes,
   ParamsFor,
-  SanitizePrefix,
-  MergeRoutes,
 } from "./reverse.js";
 // scopedReverse() helper for handlers to get locally-typed reverse
 export { scopedReverse } from "./reverse.js";
@@ -280,28 +340,58 @@ export {
   type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.js";
-
-// Telemetry sink
-export { createConsoleSink } from "./router/telemetry.js";
-export { createOTelSink } from "./router/telemetry-otel.js";
-export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
+
+// Telemetry types only — the createConsoleSink / createOTelSink /
+// createOTelTracing VALUES are server-only and live in index.rsc.ts (the
+// `react-server` condition of the bare `@rangojs/router` import). Re-exporting
+// them as values from this (default/client) entry would pull telemetry.ts and
+// telemetry-otel.ts into the client module graph; both tree-shake to zero bytes
+// but still appear in bundle analysis output and slow build-time module
+// resolution. The factory values are NOT re-exported from `@rangojs/router/server`
+// either — that subpath is internal, not user-facing (see server.ts header).
+// Non-RSC server code imports these TYPES from the root and obtains the factory
+// VALUES from its own router definition module, which resolves to index.rsc.ts
+// under the `react-server` condition.
+export type {
+  OTelTracer,
+  OTelActiveSpanTracer,
+  OTelSpan,
+  OTelTracingOptions,
+} from "./router/telemetry-otel.js";
+// The full TelemetryEvent union PLUS its member types, so a consumer writing a
+// TelemetrySink can annotate a per-`type` handler (or construct an event literal
+// in a test) instead of only narrowing the opaque union.
 export type {
   TelemetrySink,
   TelemetryEvent,
   RequestStartEvent,
   RequestEndEvent,
   RequestErrorEvent,
-  RequestTimeoutEvent,
   LoaderStartEvent,
   LoaderEndEvent,
   LoaderErrorEvent,
   HandlerErrorEvent,
+  CacheSegmentStatus,
+  CacheSegmentSignal,
   CacheDecisionEvent,
   RevalidationDecisionEvent,
+  RequestTimeoutEvent,
+  OriginCheckRejectedEvent,
 } from "./router/telemetry.js";
 
+// Span tracing config types a consumer annotates. SpanRunner/TraceSpan are the
+// internal runner contract (consumers go through createOTelTracing /
+// createCloudflareTracing, which return a ready RouterTracingConfig) and are not
+// exported.
+export type {
+  RouterTracingConfig,
+  TracePhase,
+  TracePhaseToggles,
+  TracingToggleOptions,
+} from "./router/tracing.js";
+
 // Timeout types and error class
 export { RouterTimeoutError } from "./router/timeout.js";
 export type {

package/src/internal-debug.ts

@@ -1,11 +1,12 @@
-// Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
-// Uses a Vite define (__RANGO_DEBUG__) for compile-time injection so it works
-// in all runtimes including Cloudflare Workers where process.env is unavailable.
-// Falls back to process.env for non-Vite contexts (tests, direct Node usage).
+// Runtime fallback for non-Vite contexts (Node, tests, raw imports). In the Vite
+// pipeline -- dev and build, every environment -- the router discovery plugin's
+// transform replaces this module with the build-time-resolved flag (see
+// vite/inject-client-debug.ts), so the CLIENT debug flag no longer depends on a
+// `__RANGO_DEBUG__` define being delivered to the browser (which dev did only as
+// an injected global whose presence varied across consumer setups).
+//
+// Keep this module to the single INTERNAL_RANGO_DEBUG export: the transform
+// replaces the whole file, so a second export would be dropped from the bundle.
 export const INTERNAL_RANGO_DEBUG: boolean =
-  typeof __RANGO_DEBUG__ !== "undefined"
-    ? __RANGO_DEBUG__
-    : typeof process !== "undefined" &&
-      Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
-
-declare const __RANGO_DEBUG__: boolean;
+  typeof process !== "undefined" &&
+  Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);