@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/route-definition/index.ts

@@ -0,0 +1,55 @@
+// Type definitions
+export type { RouteHelpers } from "./helpers-types.js";
+export type {
+  AllUseItems,
+  LayoutItem,
+  RouteItem,
+  ParallelItem,
+  InterceptItem,
+  MiddlewareItem,
+  RevalidateItem,
+  LoaderItem,
+  ErrorBoundaryItem,
+  NotFoundBoundaryItem,
+  LayoutUseItem,
+  RouteUseItem,
+  ParallelUseItem,
+  InterceptUseItem,
+  WhenItem,
+  CacheItem,
+  InterceptSelectorContext,
+  InterceptSegmentsState,
+  InterceptWhenFn,
+} from "./helpers-types.js";
+
+// DSL helpers
+export {
+  layout,
+  cache,
+  middleware,
+  revalidate,
+  parallel,
+  intercept,
+  when,
+  errorBoundary,
+  notFoundBoundary,
+  loader,
+  loading,
+  transition,
+} from "./dsl-helpers.js";
+
+// Helper factories and map
+export {
+  map,
+  createRouteHelpers,
+  type RouteHandlers,
+} from "./helper-factories.js";
+
+// Handler use resolver
+export { resolveHandlerUse } from "./resolve-handler-use.js";
+
+// Redirect
+export { redirect } from "./redirect.js";
+
+// Re-export createLoader from loader.rsc.ts for RSC/server context
+export { createLoader } from "../loader.rsc.js";

package/src/route-definition/redirect.ts

@@ -0,0 +1,101 @@
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+import {
+  requireRequestContext,
+  getRequestContext,
+  _getRequestContext,
+} from "../server/request-context.js";
+
+/**
+ * Create a soft redirect Response for middleware short-circuit
+ *
+ * Returns a Response that signals a client-side navigation to the target URL.
+ * Unlike Response.redirect() which causes a full page reload, this redirect
+ * is handled by the router for SPA-style navigation.
+ *
+ * Supports an optional state parameter to carry location state through the
+ * redirect. On the target page, state can be read via useLocationState()
+ * (use { flash: true } in createLocationState for read-once flash messages).
+ *
+ * @param url - The URL to redirect to
+ * @param statusOrOptions - HTTP status code (default: 302) or options object
+ *
+ * @example
+ * ```typescript
+ * // Simple redirect
+ * middleware((ctx, next) => {
+ *   if (!ctx.get('user')) {
+ *     return redirect('/login');
+ *   }
+ *   next();
+ * })
+ *
+ * // Redirect with state
+ * return redirect('/dashboard', {
+ *   state: [Flash({ text: "Item saved!" })],
+ * });
+ *
+ * // Redirect with custom status and state
+ * return redirect('/login', {
+ *   status: 303,
+ *   state: [Flash({ text: "Session expired" })],
+ * });
+ * ```
+ */
+export function redirect(url: string, status?: number): Response;
+export function redirect(
+  url: string,
+  options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+  },
+): Response;
+export function redirect(
+  url: string,
+  statusOrOptions?:
+    | number
+    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
+): Response {
+  const status =
+    typeof statusOrOptions === "number"
+      ? statusOrOptions
+      : (statusOrOptions?.status ?? 302);
+  const state =
+    typeof statusOrOptions === "object" ? statusOrOptions?.state : undefined;
+
+  if (state) {
+    const ctx = requireRequestContext();
+    ctx.setLocationState(state);
+
+    if (process.env.NODE_ENV !== "production") {
+      const reqCtx = getRequestContext();
+      // Warn only on true full-page SSR loads. SPA partial requests and server
+      // actions both deliver state through Flight payloads, so suppress for those.
+      if (
+        reqCtx &&
+        !reqCtx.originalUrl.searchParams.has("_rsc_partial") &&
+        !reqCtx.request.headers.has("rsc-action") &&
+        !reqCtx.originalUrl.searchParams.has("_rsc_action")
+      ) {
+        console.warn(
+          `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
+            "Location state is only delivered during SPA navigations and will be lost on this request.",
+        );
+      }
+    }
+  }
+
+  // Auto-prefix root-relative URLs with basename for app-local redirects.
+  const bn = _getRequestContext()?._basename;
+  let resolvedUrl = url;
+  if (bn && url.startsWith("/") && !url.startsWith(bn + "/") && url !== bn) {
+    resolvedUrl = url === "/" ? bn : bn + url;
+  }
+
+  return new Response(null, {
+    status,
+    headers: {
+      Location: resolvedUrl,
+      "X-RSC-Redirect": "soft",
+    },
+  });
+}

package/src/route-definition/resolve-handler-use.ts

@@ -0,0 +1,155 @@
+import type { AllUseItems } from "../route-types.js";
+import { isPrerenderHandler, isPassthroughHandler } from "../prerender.js";
+import { isStaticHandler } from "../static-handler.js";
+
+/**
+ * Extract the .use callback from any handler shape.
+ *
+ * Checks definition brands first (objects with __brand), then plain functions.
+ * ReactNode handlers return undefined (no .use possible).
+ */
+export function resolveHandlerUse(handler: unknown): (() => any[]) | undefined {
+  if (handler == null) return undefined;
+
+  // Check branded definitions first — they're objects but also have typeof "object"
+  if (isPassthroughHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isPrerenderHandler(handler)) {
+    return (handler as any).use;
+  }
+  if (isStaticHandler(handler)) {
+    return (handler as any).use;
+  }
+  // Loader definitions from createLoader() — branded objects with optional .use
+  if (typeof handler === "object" && (handler as any).__brand === "loader") {
+    return (handler as any).use;
+  }
+  // Plain handler function
+  if (typeof handler === "function") {
+    return (handler as any).use;
+  }
+  // ReactNode or other — no .use
+  return undefined;
+}
+
+/**
+ * Allowed item types per mount site.
+ * Mirrors the RouteUseItem / ParallelUseItem / InterceptUseItem / LayoutUseItem unions
+ * from route-types.ts for runtime validation.
+ */
+const MOUNT_SITE_ALLOWED_TYPES: Record<string, Set<string>> = {
+  path: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // Response routes (path.json, path.text, etc.) — mirrors ResponseRouteUseItem
+  response: new Set(["middleware", "cache"]),
+  route: new Set([
+    "layout",
+    "parallel",
+    "intercept",
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+  ]),
+  // layout allows AllUseItems — no validation needed, but included for completeness
+  layout: new Set([
+    "layout",
+    "route",
+    "middleware",
+    "revalidate",
+    "parallel",
+    "intercept",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "cache",
+    "transition",
+    "include",
+  ]),
+  parallel: new Set([
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "transition",
+  ]),
+  intercept: new Set([
+    "middleware",
+    "revalidate",
+    "loader",
+    "loading",
+    "errorBoundary",
+    "notFoundBoundary",
+    "layout",
+    "route",
+    "when",
+    "transition",
+  ]),
+  // LoaderUseItem — only revalidate + cache can attach to a loader entry
+  loader: new Set(["revalidate", "cache"]),
+};
+
+/**
+ * Validate that items from handler.use() are valid for the given mount site.
+ * Throws a descriptive error if any item is not allowed.
+ */
+export function validateHandlerUseItems(
+  items: AllUseItems[],
+  mountSite: string,
+): void {
+  const allowed = MOUNT_SITE_ALLOWED_TYPES[mountSite];
+  if (!allowed) return;
+  for (const item of items) {
+    if (item == null) continue;
+    if (!allowed.has((item as any).type)) {
+      throw new Error(
+        `handler.use() returned ${(item as any).type}() which is not valid inside ${mountSite}(). ` +
+          `Allowed types: ${[...allowed].join(", ")}.`,
+      );
+    }
+  }
+}
+
+/**
+ * Create a merged use callback from handler.use and explicit use.
+ * handler.use items come first (defaults), explicit items second (overrides).
+ * Returns undefined if both are absent.
+ */
+export function mergeHandlerUse(
+  handlerUse: (() => any[]) | undefined,
+  explicitUse: (() => any[]) | undefined,
+  mountSite: string,
+): (() => any[]) | undefined {
+  if (!handlerUse && !explicitUse) return undefined;
+  if (!handlerUse) return explicitUse;
+  if (!explicitUse) {
+    return () => {
+      const items = handlerUse().flat(3);
+      validateHandlerUseItems(items, mountSite);
+      return items;
+    };
+  }
+  return () => {
+    const hItems = handlerUse().flat(3);
+    validateHandlerUseItems(hItems, mountSite);
+    return [...hItems, ...explicitUse()];
+  };
+}