@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

package/src/index.rsc.ts

@@ -11,8 +11,6 @@
 
 // Re-export all universal exports from index.ts
 export {
-  // Universal rendering utilities
-  renderSegments,
   // Error classes
   RouteNotFoundError,
   DataNotFoundError,
@@ -20,18 +18,17 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
+  Skip,
+  isSkip,
 } from "./index.js";
 
 // Re-export all types from types.ts (user-facing types only)
 export type {
   // Configuration types
   DocumentProps,
-  RouterEnv,
   DefaultEnv,
   RouteDefinition,
   RouteConfig,
@@ -39,7 +36,6 @@ export type {
   TrailingSlashMode,
   // Handler types
   Handler,
-  ScopedRouteMap,
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -48,6 +44,7 @@ export type {
   // Revalidation types
   RevalidateParams,
   Revalidate,
+  ActionRef,
   RouteKeys,
   // Loader types
   LoaderDefinition,
@@ -55,9 +52,6 @@ export type {
   LoaderContext,
   FetchableLoaderOptions,
   LoadOptions,
-  LoaderActionContext,
-  LoaderAction,
-  LoaderMiddlewareFn,
   // Error boundary types
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -67,45 +61,84 @@ export type {
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
 } from "./types.js";
 
 // Router options type (server-only, so import directly)
-export type { RSCRouterOptions } from "./router.js";
+export type {
+  RangoOptions,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
+} from "./router.js";
 
 // Server-side createLoader and redirect
-export { createLoader, redirect } from "./route-definition.js";
+export {
+  createLoader,
+  redirect,
+  type RouteHelpers,
+  type RouteHandlers,
+  // Globally importable route helpers for composition
+  layout,
+  cache,
+  middleware,
+  revalidate,
+  loader,
+  loading,
+  parallel,
+  intercept,
+  when,
+  errorBoundary,
+  notFoundBoundary,
+  transition,
+} from "./route-definition.js";
+
+// Composition types for reusable callback factories
+export type {
+  RouteUseItem,
+  LayoutUseItem,
+  AllUseItems,
+  UseItems,
+  HandlerUseItem,
+} from "./route-types.js";
 
 // Handle API
 export { createHandle, isHandle, type Handle } from "./handle.js";
 
+// Context variable API (typed ctx.set/ctx.get tokens)
+export { createVar, type ContextVar } from "./context-var.js";
+
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+export { nonce } from "./rsc/nonce.js";
+
 // Pre-render handler API
 export {
   Prerender,
-  isPrerenderHandler,
+  Passthrough,
   type PrerenderHandlerDefinition,
+  type PassthroughHandlerDefinition,
   type PrerenderOptions,
   type BuildContext,
+  type StaticBuildContext,
+  type GetParamsContext,
 } from "./prerender.js";
 
 // Static handler API
-export {
-  Static,
-  isStaticHandler,
-  type StaticHandlerDefinition,
-} from "./static-handler.js";
+export { Static, type StaticHandlerDefinition } from "./static-handler.js";
 
 // Django-style URL patterns (RSC/server context)
 export {
   urls,
-  RESPONSE_TYPE,
   type PathHelpers,
   type PathOptions,
   type UrlPatterns,
   type IncludeOptions,
   type IncludeItem,
   type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
+  type ProblemDetails,
   type ResponseHandler,
   type ResponseHandlerContext,
   type JsonResponseHandler,
@@ -119,8 +152,9 @@ export {
 // Core router (server-side)
 export {
   createRouter,
-  type RSCRouter,
+  type Rango,
   type RootLayoutProps,
+  type RouterRequestInput,
 } from "./router.js";
 
 // RSC handler types (server-side)
@@ -128,42 +162,78 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
 
 // Built-in handles (server-side)
 export { Meta } from "./handles/meta.js";
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
+
+// Request context (for accessing request data in server actions/components).
+// Re-exported with a narrowed return type so that public consumers only see
+// public members. Internal code imports from "./server/request-context.js"
+// directly and gets the full type.
+import { getRequestContext as _getRequestContextInternal } from "./server/request-context.js";
+export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
+import type { PublicRequestContext } from "./server/request-context.js";
+import type { DefaultEnv } from "./types/global-namespace.js";
+
+// Shared base for every user-facing request context (mirrors index.ts).
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
+export const getRequestContext: <
+  TEnv = DefaultEnv,
+>() => PublicRequestContext<TEnv> = _getRequestContextInternal;
 
-// Request context (for accessing request data in server actions/components)
+// Request-scoped shorthands
 export {
-  getRequestContext,
-  requireRequestContext,
-  type RequestContext,
-} from "./server/request-context.js";
+  cookies,
+  headers,
+  type CookieStore,
+  type Cookie,
+  type ReadonlyHeaders,
+} from "./server/cookie-store.js";
 
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 
 // Middleware context types
-export type {
-  MiddlewareContext,
-  CookieOptions,
-} from "./router/middleware.js";
+export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
 
 // Reverse type utilities for type-safe URL generation (Django-style URL reversal)
-export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes, PrefixedRoutes, PrefixRoutePatterns, ParamsFor, SanitizePrefix, MergeRoutes } from "./reverse.js";
+export type {
+  ScopedReverseFunction,
+  ReverseFunction,
+  ExtractLocalRoutes,
+  ParamsFor,
+} from "./reverse.js";
 export { scopedReverse, createReverse } from "./reverse.js";
 
 // Search params schema types
-export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams } from "./search-params.js";
-
-// Performance tracking (server-only)
-export { track } from "./server/context.js";
-
-// Debug utilities for route matching (development only)
-export {
-  enableMatchDebug,
-  getMatchDebugStats,
-} from "./router/pattern-matching.js";
+export type {
+  SearchSchema,
+  SearchSchemaValue,
+  ResolveSearchSchema,
+  RouteSearchParams,
+  RouteParams,
+} from "./search-params.js";
 
 // Location state (universal)
 export {
   createLocationState,
   type LocationStateDefinition,
   type LocationStateEntry,
+  type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
+
+// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
+// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
+
+// Telemetry sink
+export { createConsoleSink } from "./router/telemetry.js";
+export { createOTelSink } from "./router/telemetry-otel.js";
+export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";

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,26 +18,24 @@ export {
   MiddlewareError,
   HandlerError,
   BuildError,
+  DslContextError,
   InvalidHandlerError,
-  NetworkError,
-  isNetworkError,
-  sanitizeError,
   RouterError,
+  Skip,
+  isSkip,
 } from "./errors.js";
 
 // Types (safe to import anywhere - no runtime code)
 export type {
   // Configuration types
   DocumentProps,
-  RouterEnv,
   DefaultEnv,
   RouteDefinition,
   RouteConfig,
   RouteDefinitionOptions,
   TrailingSlashMode,
   // Handler types
-  Handler,            // Supports params object, path pattern, or route name
-  ScopedRouteMap,     // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
+  Handler, // Supports params object, path pattern, or route name
   HandlerContext,
   ExtractParams,
   GenericParams,
@@ -49,6 +44,7 @@ export type {
   // Revalidation types
   RevalidateParams,
   Revalidate,
+  ActionRef,
   RouteKeys,
   // Loader types
   LoaderDefinition,
@@ -56,9 +52,6 @@ export type {
   LoaderContext,
   FetchableLoaderOptions,
   LoadOptions,
-  LoaderActionContext,
-  LoaderAction,
-  LoaderMiddlewareFn,
   // Error boundary types
   ErrorInfo,
   ErrorBoundaryFallbackProps,
@@ -68,15 +61,38 @@ export type {
   NotFoundInfo,
   NotFoundBoundaryFallbackProps,
   NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
 } from "./types.js";
 
 // Search params schema types
-export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams } from "./search-params.js";
+export type {
+  SearchSchema,
+  SearchSchemaValue,
+  ResolveSearchSchema,
+  RouteSearchParams,
+  RouteParams,
+} from "./search-params.js";
 
 // Client-safe createLoader - only stores the $$id, function is not included
 // Use this when defining loaders that will be imported by client components
 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";
+
+// Composition types for reusable callback factories
+export type {
+  RouteUseItem,
+  LayoutUseItem,
+  AllUseItems,
+  UseItems,
+  HandlerUseItem,
+} from "./route-types.js";
+
 // Response route types (usable in both server and client contexts)
 export type {
   ResponseHandler,
@@ -88,126 +104,194 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
 } from "./urls.js";
 
 // Middleware context types
-export type {
-  MiddlewareContext,
-  CookieOptions,
-} from "./router/middleware.js";
+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";
 
+// Context variable API (typed ctx.set/ctx.get tokens)
+export { createVar, type ContextVar } from "./context-var.js";
+
+// CSP nonce token (use with ctx.get(nonce) in middleware/handlers)
+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 };
 }
 
 /**
- * Error-throwing stub for server-only `getRequestContext` function.
+ * 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 getRequestContext(): never {
-  throw new Error(
-    'getRequestContext() is server-only and requires RSC context.'
-  );
+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 `requireRequestContext` function.
+ * Error-throwing stub for server-only `getRequestContext` function.
  */
-export function requireRequestContext(): never {
-  throw new Error(
-    'requireRequestContext() is server-only and requires RSC context.'
-  );
+export function getRequestContext(): never {
+  throw serverOnlyStubError("getRequestContext");
 }
 
 /**
- * Error-throwing stub for server-only `createReverse` function.
+ * Error-throwing stub for server-only `cookies` function.
  */
-export function createReverse(): never {
-  throw new Error(
-    'createReverse() is server-only and requires RSC context.'
-  );
+export function cookies(): never {
+  throw serverOnlyStubError("cookies");
 }
 
 /**
- * Error-throwing stub for server-only `enableMatchDebug` function.
+ * Error-throwing stub for server-only `headers` function.
  */
-export function enableMatchDebug(): never {
-  throw new Error(
-    'enableMatchDebug() is server-only and requires RSC context.'
-  );
+export function headers(): never {
+  throw serverOnlyStubError("headers");
 }
 
 /**
- * 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 stub for server-only `track` function.
- */
-export function track(): never {
-  throw new Error(
-    'track() is server-only and requires RSC context.'
-  );
+// Error-throwing stubs for server-only route helpers
+export function layout(): never {
+  throw serverOnlyStubError("layout");
+}
+export function cache(): never {
+  throw serverOnlyStubError("cache");
+}
+export function middleware(): never {
+  throw serverOnlyStubError("middleware");
+}
+export function revalidate(): never {
+  throw serverOnlyStubError("revalidate");
+}
+export function loader(): never {
+  throw serverOnlyStubError("loader");
+}
+export function loading(): never {
+  throw serverOnlyStubError("loading");
+}
+export function parallel(): never {
+  throw serverOnlyStubError("parallel");
+}
+export function intercept(): never {
+  throw serverOnlyStubError("intercept");
+}
+export function when(): never {
+  throw serverOnlyStubError("when");
+}
+export function errorBoundary(): never {
+  throw serverOnlyStubError("errorBoundary");
+}
+export function notFoundBoundary(): never {
+  throw serverOnlyStubError("notFoundBoundary");
+}
+export function transition(): never {
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)
-export type { RequestContext } from "./server/request-context.js";
+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,
+  Cookie,
+  ReadonlyHeaders,
+} from "./server/cookie-store.js";
+
+// Built-in handles (universal — work on both server and client)
+export { Meta } from "./handles/meta.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, PrefixedRoutes, PrefixRoutePatterns, ParamsFor, SanitizePrefix, MergeRoutes } from "./reverse.js";
+export type {
+  ScopedReverseFunction,
+  ReverseFunction,
+  ExtractLocalRoutes,
+  ParamsFor,
+} from "./reverse.js";
 // scopedReverse() helper for handlers to get locally-typed reverse
 export { scopedReverse } from "./reverse.js";
 
@@ -216,7 +300,27 @@ export {
   createLocationState,
   type LocationStateDefinition,
   type LocationStateEntry,
+  type LocationStateOptions,
 } from "./browser/react/location-state-shared.js";
 
-// Path-based response type lookup from RegisteredRoutes
-export type { PathResponse } from "./href-client.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 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. Consumers
+// who need the values in non-RSC contexts can import from
+// `@rangojs/router/server`.
+export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
+export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
+
+// Timeout types and error class
+export { RouterTimeoutError } from "./router/timeout.js";
+export type {
+  RouterTimeouts,
+  TimeoutPhase,
+  TimeoutContext,
+} from "./router/timeout.js";

package/src/internal-debug.ts

@@ -1,5 +1,11 @@
 // Internal debug gate. Enable with INTERNAL_RANGO_DEBUG=1 in the environment.
-// Only checked on the server (Node.js / Bun); on workers process is undefined.
+// 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).
 export const INTERNAL_RANGO_DEBUG: boolean =
-  typeof process !== "undefined" &&
-  Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
+  typeof __RANGO_DEBUG__ !== "undefined"
+    ? __RANGO_DEBUG__
+    : typeof process !== "undefined" &&
+      Boolean((process as any).env?.INTERNAL_RANGO_DEBUG);
+
+declare const __RANGO_DEBUG__: boolean;