@rangojs/router 0.0.0-experimental.0f44aca1

package/src/urls/include-helper.ts

@@ -0,0 +1,197 @@
+import type { AllUseItems, IncludeItem } from "../route-types.js";
+import {
+  getContext,
+  runWithPrefixes,
+  getUrlPrefix,
+  getNamePrefix,
+  getRootScoped,
+} from "../server/context";
+import {
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+  validateUserRouteName,
+} from "../route-name.js";
+import type { UrlPatterns, IncludeOptions } from "./pattern-types.js";
+import type { IncludeFn } from "./path-helper-types.js";
+
+function hasExplicitNameOption(options: IncludeOptions | undefined): boolean {
+  return !!options && Object.prototype.hasOwnProperty.call(options, "name");
+}
+
+function allocateInternalIncludeScopeId(
+  counters: Record<string, number>,
+): string {
+  const key = "__include_scope__";
+  const index = counters[key] ?? 0;
+  counters[key] = index + 1;
+  return `${INTERNAL_INCLUDE_SCOPE_PREFIX}${index}`;
+}
+
+/**
+ * Process an IncludeItem by executing its nested patterns with prefixes
+ * This expands the include into actual route registrations
+ */
+function processIncludeItem(item: IncludeItem): AllUseItems[] {
+  const { prefix, patterns } = item;
+  const namePrefix =
+    (item as IncludeItem & { _lazyContext?: { namePrefix?: string } })
+      ._lazyContext?.namePrefix ?? item.options?.name;
+
+  // Execute the nested patterns' handler with URL and name prefixes
+  // The urlPrefix being set tells nested urls() to skip RootLayout wrapping
+  return runWithPrefixes(prefix, namePrefix, () => {
+    // Call the nested patterns' handler - this registers routes with prefixed patterns/names
+    return (patterns as UrlPatterns).handler();
+  });
+}
+
+/**
+ * Recursively process items, expanding any IncludeItems
+ * Returns items with IncludeItems expanded into actual route items
+ *
+ * Lazy includes are kept as-is (not expanded) for the router to handle later.
+ */
+export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
+  const result: AllUseItems[] = [];
+
+  for (const item of items) {
+    if (!item) continue;
+
+    if (item.type === "include") {
+      const includeItem = item as IncludeItem & {
+        _expanded?: AllUseItems[];
+        lazy?: boolean;
+      };
+
+      // Lazy includes are NOT expanded here - kept for router to handle
+      if (includeItem.lazy) {
+        result.push(item);
+        continue;
+      }
+
+      // Eager includes are already expanded during include() call
+      if (includeItem._expanded) {
+        // Items were expanded immediately - just process them recursively
+        result.push(...processItems(includeItem._expanded));
+      } else {
+        // Fallback for legacy include items without _expanded
+        const expanded = processIncludeItem(item as IncludeItem);
+        result.push(...processItems(expanded));
+      }
+    } else if (item.type === "layout" && (item as any).uses) {
+      // Process nested items in layout
+      const layoutItem = item as any;
+      layoutItem.uses = processItems(layoutItem.uses);
+      result.push(layoutItem);
+    } else {
+      result.push(item);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create include() helper for composing URL patterns
+ *
+ * By default, include() IMMEDIATELY expands the nested patterns. This ensures
+ * that routes from included patterns inherit the correct parent context
+ * (the layout they're included in).
+ *
+ * With `lazy: true`, patterns are NOT expanded at definition time. Instead,
+ * they're evaluated on first request that matches the prefix. This improves
+ * cold start time for apps with many routes.
+ */
+export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
+  return (
+    prefix: string,
+    patterns: UrlPatterns<TEnv>,
+    options?: IncludeOptions,
+  ): IncludeItem => {
+    const store = getContext();
+    const ctx = store.getStore();
+    if (!ctx) throw new Error("include() must be called inside urls()");
+
+    const explicitName = options?.name;
+    const hasExplicitName = hasExplicitNameOption(options);
+    if (hasExplicitName && explicitName) {
+      validateUserRouteName(explicitName);
+    }
+    const name = `$include_${prefix.replace(/[/:*?]/g, "_")}`;
+
+    // Capture context for deferred evaluation
+    const capturedUrlPrefix = getUrlPrefix();
+    const capturedNamePrefix = getNamePrefix();
+    const capturedParent = ctx.parent;
+    const fullPrefix = capturedUrlPrefix
+      ? capturedUrlPrefix.endsWith("/") && prefix.startsWith("/")
+        ? capturedUrlPrefix + prefix.slice(1)
+        : capturedUrlPrefix + prefix
+      : prefix;
+    const internalScope = !hasExplicitName
+      ? allocateInternalIncludeScopeId(ctx.counters)
+      : undefined;
+    const nextSegment = hasExplicitName ? explicitName : internalScope;
+    const fullNamePrefix =
+      nextSegment !== undefined && nextSegment !== ""
+        ? capturedNamePrefix
+          ? `${capturedNamePrefix}.${nextSegment}`
+          : nextSegment
+        : capturedNamePrefix;
+
+    // Track this include for build-time manifest generation
+    if (ctx.trackedIncludes) {
+      ctx.trackedIncludes.push({
+        prefix,
+        fullPrefix,
+        namePrefix: fullNamePrefix,
+        patterns,
+        lazy: true,
+      });
+    }
+
+    // Snapshot parent's counters so lazy manifest generation starts
+    // at the correct index, preventing shortCode collisions with
+    // sibling entries (e.g., BlogLayout and ArticlesLayout under NavLayout).
+    const capturedCounters = { ...ctx.counters };
+
+    // Reserve a layout slot in the parent's counter so sibling lazy includes
+    // produce different shortCode indices for their root layout.
+    // Without this, consecutive include() calls capture identical counters
+    // and their first child layouts get the same shortCode (e.g., both M0L0L0),
+    // causing the client partial-update diff to see no changes on navigation.
+    if (capturedParent?.shortCode) {
+      const layoutCounterKey = `${capturedParent.shortCode}_layout`;
+      ctx.counters[layoutCounterKey] ??= 0;
+      ctx.counters[layoutCounterKey]++;
+    }
+
+    // Compute rootScoped at capture time, mirroring the logic in runWithPrefixes.
+    // This ensures lazy evaluation restores the correct scope state.
+    const parentRootScoped = ctx.rootScoped;
+    const capturedRootScoped =
+      nextSegment === ""
+        ? (parentRootScoped ?? true)
+        : nextSegment !== undefined
+          ? (parentRootScoped ?? false)
+          : parentRootScoped;
+
+    // All includes are lazy - patterns are evaluated on first matching request
+    // This improves cold start time significantly for large route sets
+    return {
+      type: "include",
+      name,
+      prefix,
+      patterns,
+      options,
+      lazy: true,
+      _lazyContext: {
+        urlPrefix: capturedUrlPrefix,
+        namePrefix: fullNamePrefix,
+        parent: capturedParent,
+        counters: capturedCounters,
+        cacheProfiles: ctx.cacheProfiles,
+        rootScoped: capturedRootScoped,
+      },
+    } as IncludeItem;
+  };
+}

package/src/urls/index.ts

@@ -0,0 +1,53 @@
+// Response types and symbols
+export {
+  RESPONSE_TYPE,
+  type ResponseHandler,
+  type JsonValue,
+  type JsonResponseHandler,
+  type TextResponseHandler,
+  type ResponseHandlerContext,
+} from "./response-types.js";
+
+// Pattern types
+export type {
+  UnnamedRoute,
+  LocalOnlyInclude,
+  PathOptions,
+  PathDefinition,
+  UrlPatterns,
+  IncludeOptions,
+} from "./pattern-types.js";
+
+// Type extraction utilities
+export type {
+  ExtractRoutes,
+  ExtractResponses,
+  ExtractRouteNames,
+  ExtractPathParams,
+  ResponseError,
+  ResponseEnvelope,
+  RouteResponse,
+} from "./type-extraction.js";
+
+// Path helper types
+export type {
+  PathFn,
+  ResponsePathFn,
+  JsonResponsePathFn,
+  TextResponsePathFn,
+  IncludeFn,
+  PathHelpers,
+} from "./path-helper-types.js";
+
+// Main entry point
+export { urls } from "./urls-function.js";
+
+// Re-exports from route-types
+export type {
+  AllUseItems,
+  IncludeItem,
+  TypedRouteItem,
+  TypedIncludeItem,
+  TypedLayoutItem,
+  TypedCacheItem,
+} from "../route-types.js";

package/src/urls/path-helper-types.ts

@@ -0,0 +1,339 @@
+import type { ReactNode } from "react";
+import type {
+  ErrorBoundaryHandler,
+  ExtractParams,
+  Handler,
+  HandlerContext,
+  LoaderDefinition,
+  MiddlewareFn,
+  NotFoundBoundaryHandler,
+  PartialCacheOptions,
+  ShouldRevalidateFn,
+  TransitionConfig,
+} from "../types.js";
+import type {
+  AllUseItems,
+  TypedLayoutItem,
+  ParallelItem,
+  InterceptItem,
+  MiddlewareItem,
+  RevalidateItem,
+  LoaderItem,
+  LoadingItem,
+  ErrorBoundaryItem,
+  NotFoundBoundaryItem,
+  LayoutUseItem,
+  RouteUseItem,
+  ResponseRouteUseItem,
+  ParallelUseItem,
+  InterceptUseItem,
+  LoaderUseItem,
+  WhenItem,
+  TypedCacheItem,
+  TransitionItem,
+  TypedTransitionItem,
+  TypedRouteItem,
+  TypedIncludeItem,
+  UseItems,
+} from "../route-types.js";
+import type { SearchSchema } from "../search-params.js";
+import type { PrerenderHandlerDefinition } from "../prerender.js";
+import type { StaticHandlerDefinition } from "../static-handler.js";
+import type { InterceptWhenFn } from "../server/context";
+import type {
+  ResponseHandler,
+  ResponseHandlerContext,
+  TextResponseHandler,
+} from "./response-types.js";
+import type {
+  UnnamedRoute,
+  LocalOnlyInclude,
+  PathOptions,
+  UrlPatterns,
+  IncludeOptions,
+} from "./pattern-types.js";
+import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
+
+/**
+ * Base path function signature for defining routes with URL patterns.
+ */
+export type PathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+  TParams extends Record<string, any> = ExtractParams<TPattern>,
+>(
+  pattern: TPattern,
+  handler:
+    | ReactNode
+    | ((
+        ctx: HandlerContext<TParams, TEnv, TSearch>,
+      ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>)
+    | PrerenderHandlerDefinition<TParams>
+    | StaticHandlerDefinition<TParams>,
+  optionsOrUse?: PathOptions<TName, TSearch> | (() => UseItems<RouteUseItem>),
+  use?: () => UseItems<RouteUseItem>,
+  // Generic handler bypass: when handler uses index-signature params
+  // (e.g. Handler<Record<string, any>>), skip the biconditional.
+  // `string extends keyof TParams` is true for index signatures,
+  // false for concrete params ({id: string}) and empty ({}).
+  //
+  // Subset check: pattern params must be assignable to handler params,
+  // but handler can have MORE params (e.g. from parent include() prefix).
+  // This allows Prerender<"locale.detail"> with {locale, slug} to mount
+  // on path("/blog/:slug") where the pattern only declares {slug}.
+) => string extends keyof TParams
+  ? TypedRouteItem<TName, TPattern, unknown, TSearch>
+  : TParams extends ExtractParams<TPattern>
+    ? TypedRouteItem<TName, TPattern, unknown, TSearch>
+    : { __error: `Handler params do not match pattern "${TPattern}"` };
+
+/**
+ * Path function for response routes that must return Response (image, stream, any).
+ * Handler must return Response, not ReactNode. Uses lighter ResponseHandlerContext.
+ * Use items restricted to middleware() and cache() only.
+ */
+export type ResponsePathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+>(
+  pattern: TPattern,
+  handler: ResponseHandler<ExtractParams<TPattern>, TEnv>,
+  optionsOrUse?:
+    | PathOptions<TName, TSearch>
+    | (() => UseItems<ResponseRouteUseItem>),
+  use?: () => UseItems<ResponseRouteUseItem>,
+) => TypedRouteItem<TName, TPattern, unknown, TSearch>;
+
+/**
+ * Path function for JSON response routes (path.json()).
+ * Handler can return plain JSON-serializable values or Response.
+ * TData is inferred from the handler's return type (excluding Response/Promise wrappers).
+ */
+export type JsonResponsePathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+  TData = unknown,
+>(
+  pattern: TPattern,
+  handler: (
+    ctx: ResponseHandlerContext<ExtractParams<TPattern>, TEnv>,
+  ) => TData | Response | Promise<TData | Response>,
+  optionsOrUse?:
+    | PathOptions<TName, TSearch>
+    | (() => UseItems<ResponseRouteUseItem>),
+  use?: () => UseItems<ResponseRouteUseItem>,
+) => TypedRouteItem<TName, TPattern, TData, TSearch>;
+
+/**
+ * Path function for text-based response routes (path.text(), path.html(), path.xml()).
+ * Handler can return a string or Response. TData is always `string`.
+ */
+export type TextResponsePathFn<TEnv> = <
+  const TPattern extends string,
+  const TName extends string = UnnamedRoute,
+  const TSearch extends SearchSchema = {},
+>(
+  pattern: TPattern,
+  handler: TextResponseHandler<ExtractParams<TPattern>, TEnv>,
+  optionsOrUse?:
+    | PathOptions<TName, TSearch>
+    | (() => UseItems<ResponseRouteUseItem>),
+  use?: () => UseItems<ResponseRouteUseItem>,
+) => TypedRouteItem<TName, TPattern, string, TSearch>;
+
+/**
+ * Base include function signature.
+ */
+export type IncludeFn<TEnv> = <
+  TRoutes extends Record<string, any>,
+  const TUrlPrefix extends string,
+  const TNamePrefix extends string = LocalOnlyInclude,
+  TResponses extends Record<string, unknown> = Record<string, unknown>,
+>(
+  prefix: TUrlPrefix,
+  patterns: UrlPatterns<TEnv, TRoutes, TResponses>,
+  options?: IncludeOptions<TNamePrefix>,
+) => TypedIncludeItem<TRoutes, TNamePrefix, TUrlPrefix, TResponses>;
+
+export type PathHelpers<TEnv> = {
+  /**
+   * Define a route with URL pattern at definition site
+   *
+   * @example
+   * ```typescript
+   * // Pattern and component only
+   * path("/about", AboutPage)
+   *
+   * // With options
+   * path("/:slug", PostPage, { name: "post" })
+   *
+   * // With children (loaders, middleware, etc.)
+   * path("/:slug", PostPage, { name: "post" }, () => [
+   *   loader(PostLoader),
+   * ])
+   * ```
+   */
+  path: PathFn<TEnv> & {
+    json: JsonResponsePathFn<TEnv>;
+    text: TextResponsePathFn<TEnv>;
+    html: TextResponsePathFn<TEnv>;
+    xml: TextResponsePathFn<TEnv>;
+    md: TextResponsePathFn<TEnv>;
+    image: ResponsePathFn<TEnv>;
+    stream: ResponsePathFn<TEnv>;
+    any: ResponsePathFn<TEnv>;
+  };
+
+  /**
+   * Define a layout that wraps child routes
+   */
+  layout: {
+    (
+      component: ReactNode | Handler<any, any, TEnv> | StaticHandlerDefinition,
+    ): TypedLayoutItem<{}, {}>;
+    <
+      const TChildren extends readonly (
+        | LayoutUseItem
+        | readonly LayoutUseItem[]
+      )[],
+    >(
+      component: ReactNode | Handler<any, any, TEnv> | StaticHandlerDefinition,
+      use: () => TChildren,
+    ): TypedLayoutItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
+  };
+
+  /**
+   * Include nested URL patterns under a URL prefix.
+   *
+   * The `name` option controls how child route names appear in the
+   * global route map and generated types:
+   *
+   * ```typescript
+   * // Named — children become "blog.index", "blog.post", etc.
+   * // Visible in generated types and globally reversible.
+   * include("/blog", blogPatterns, { name: "blog" })
+   *
+   * // Flattened — children merge into the parent namespace as-is.
+   * // Equivalent to defining those routes inline at the include site.
+   * include("/blog", blogPatterns, { name: "" })
+   *
+   * // Local-only (default) — children are scoped privately.
+   * // Hidden from generated types and global reverse resolution.
+   * // Only dot-local reverse (reverse(".child")) works inside.
+   * include("/blog", blogPatterns)
+   * ```
+   */
+  include: IncludeFn<TEnv>;
+
+  /**
+   * Define parallel routes that render simultaneously in named slots
+   */
+  parallel: <
+    TSlots extends Record<
+      `@${string}`,
+      Handler<any, any, TEnv> | ReactNode | StaticHandlerDefinition
+    >,
+  >(
+    slots: TSlots,
+    use?: () => ParallelUseItem[],
+  ) => ParallelItem;
+
+  /**
+   * Define an intercepting route for soft navigation
+   * Note: routeName must match a named path() in this urlpatterns
+   */
+  intercept: keyof RSCRouter.GeneratedRouteMap extends never
+    ? (
+        slotName: `@${string}`,
+        routeName: string,
+        handler: ReactNode | Handler<any, any, TEnv>,
+        use?: () => InterceptUseItem[],
+      ) => InterceptItem
+    : (
+        slotName: `@${string}`,
+        routeName: (keyof RSCRouter.GeneratedRouteMap & string) | `.${string}`,
+        handler: ReactNode | Handler<any, any, TEnv>,
+        use?: () => InterceptUseItem[],
+      ) => InterceptItem;
+
+  /**
+   * Attach middleware to the current route/layout
+   */
+  middleware: (...fns: MiddlewareFn<TEnv>[]) => MiddlewareItem;
+
+  /**
+   * Control when a segment should revalidate during navigation
+   */
+  revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+
+  /**
+   * Attach a data loader to the current route/layout
+   */
+  loader: <TData>(
+    loaderDef: LoaderDefinition<TData>,
+    use?: () => LoaderUseItem[],
+  ) => LoaderItem;
+
+  /**
+   * Attach a loading component to the current route/layout
+   */
+  loading: (component: ReactNode, options?: { ssr?: boolean }) => LoadingItem;
+
+  /**
+   * Attach an error boundary to catch errors in this segment
+   */
+  errorBoundary: (
+    fallback: ReactNode | ErrorBoundaryHandler,
+  ) => ErrorBoundaryItem;
+
+  /**
+   * Attach a not-found boundary to handle notFound() calls
+   */
+  notFoundBoundary: (
+    fallback: ReactNode | NotFoundBoundaryHandler,
+  ) => NotFoundBoundaryItem;
+
+  /**
+   * Define a condition for when an intercept should activate
+   */
+  when: (fn: InterceptWhenFn) => WhenItem;
+
+  /**
+   * Define cache configuration for segments
+   */
+  cache: {
+    (): TypedCacheItem<{}, {}>;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      children: () => TChildren,
+    ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
+    (options: PartialCacheOptions | false): TypedCacheItem<{}, {}>;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      options: PartialCacheOptions | false,
+      use: () => TChildren,
+    ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
+  };
+
+  /**
+   * Attach a ViewTransition boundary to the current segment or a group of routes
+   */
+  transition: {
+    (): TransitionItem;
+    (config: TransitionConfig): TransitionItem;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      children: () => TChildren,
+    ): TypedTransitionItem<
+      ExtractRoutes<TChildren>,
+      ExtractResponses<TChildren>
+    >;
+    <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
+      config: TransitionConfig,
+      children: () => TChildren,
+    ): TypedTransitionItem<
+      ExtractRoutes<TChildren>,
+      ExtractResponses<TChildren>
+    >;
+  };
+};