@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/urls.ts

@@ -1,726 +1 @@
-/**
- * Django-inspired URL patterns for @rangojs/router
- *
- * This module provides `urls()` and `path()` for defining routes with
- * URL patterns visible at the definition site.
- *
- * @example
- * ```typescript
- * // urls/blog.ts
- * export const blogPatterns = urls(({ path, layout, loader }) => [
- *   layout(BlogLayout, () => [
- *     path("/", BlogIndex, { name: "index" }),
- *     path("/:slug", BlogPost, { name: "post" }, () => [
- *       loader(PostLoader),
- *     ]),
- *   ]),
- * ]);
- *
- * // urls/index.ts
- * export const urlpatterns = urls(({ path, layout, include }) => [
- *   layout(RootLayout, () => [
- *     path("/", HomePage, { name: "home" }),
- *     include("/blog", blogPatterns, { name: "blog" }),
- *   ]),
- * ]);
- * ```
- */
-import type { ReactNode } from "react";
-import type {
-  DefaultEnv,
-  ErrorBoundaryHandler,
-  ExtractParams,
-  Handler,
-  LoaderDefinition,
-  MiddlewareFn,
-  NotFoundBoundaryHandler,
-  PartialCacheOptions,
-  ShouldRevalidateFn,
-  TrailingSlashMode,
-} from "./types.js";
-import type {
-  AllUseItems,
-  LayoutItem,
-  TypedLayoutItem,
-  RouteItem,
-  TypedRouteItem,
-  ParallelItem,
-  InterceptItem,
-  MiddlewareItem,
-  RevalidateItem,
-  LoaderItem,
-  LoadingItem,
-  ErrorBoundaryItem,
-  NotFoundBoundaryItem,
-  LayoutUseItem,
-  RouteUseItem,
-  ParallelUseItem,
-  InterceptUseItem,
-  LoaderUseItem,
-  WhenItem,
-  CacheItem,
-  TypedCacheItem,
-  IncludeItem,
-  TypedIncludeItem,
-  IncludeBrand,
-  UrlPatternsBrand,
-} from "./route-types.js";
-import {
-  getContext,
-  runWithPrefixes,
-  getUrlPrefix,
-  getNamePrefix,
-  type EntryData,
-  type InterceptEntry,
-  type InterceptWhenFn,
-} from "./server/context";
-import { invariant } from "./errors";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Sentinel type for unnamed routes.
- * Using a branded string instead of `never` prevents TypeScript from
- * widening array type inference when mixing named and unnamed routes.
- */
-export type UnnamedRoute = "$unnamed";
-
-/**
- * Options for path() function
- */
-export interface PathOptions<TName extends string = string> {
-  /** Route name for href() lookups */
-  name?: TName;
-  /** Trailing slash behavior: "never" (redirect /path/ to /path), "always" (redirect /path to /path/), "ignore" (match both) */
-  trailingSlash?: TrailingSlashMode;
-}
-
-/**
- * Internal representation of a URL pattern definition
- */
-export interface PathDefinition {
-  pattern: string;
-  name?: string;
-  handler: ReactNode | Handler<any, any>;
-  use?: RouteUseItem[];
-}
-
-/**
- * Result of urls() - contains the route definitions
- */
-export interface UrlPatterns<
-  TEnv = any,
-  TRoutes extends Record<string, string> = Record<string, string>
-> {
-  /** Internal: route definitions */
-  readonly definitions: PathDefinition[];
-  /** Internal: compiled handler function */
-  readonly handler: () => AllUseItems[];
-  /** Internal: trailing slash config per route name */
-  readonly trailingSlash: Record<string, TrailingSlashMode>;
-  /** Brand for type checking */
-  readonly [UrlPatternsBrand]: void;
-  /** Environment type brand (phantom) */
-  readonly _env?: TEnv;
-  /** Routes type brand (phantom) - carries route name -> pattern mapping */
-  readonly _routes?: TRoutes;
-}
-
-/**
- * Options for include()
- */
-export interface IncludeOptions<TNamePrefix extends string = string> {
-  /** Name prefix for all routes in this pattern set */
-  name?: TNamePrefix;
-}
-
-// ============================================================================
-// Route Type Extraction Utilities
-// ============================================================================
-
-/**
- * Prefix route names with a given prefix (e.g., "blog" + "post" = "blog.post")
- */
-type PrefixRoutes<
-  TRoutes extends Record<string, string>,
-  TPrefix extends string
-> = TPrefix extends ""
-  ? TRoutes
-  : {
-      [K in keyof TRoutes as K extends string ? `${TPrefix}.${K}` : never]: TRoutes[K];
-    };
-
-/**
- * Prefix route patterns with a URL prefix (e.g., "/blog" + "/:slug" = "/blog/:slug")
- */
-type PrefixPatterns<
-  TRoutes extends Record<string, string>,
-  TUrlPrefix extends string
-> = {
-  [K in keyof TRoutes]: TRoutes[K] extends string
-    ? `${TUrlPrefix}${TRoutes[K]}`
-    : TRoutes[K];
-};
-
-/**
- * Depth counter for limiting recursion (max 5 levels to avoid infinite types)
- */
-type Depth = [never, 0, 1, 2, 3, 4];
-
-/**
- * Extract routes from a single item (path, include, layout, cache with children)
- * D is the current depth level (0-4), stops at 5
- */
-type ExtractRoutesFromItem<T, D extends number = 5> = [D] extends [never]
-  ? {} // Max depth reached, stop recursion
-  : // TypedRouteItem: extract name -> pattern (exclude unnamed routes)
-    T extends TypedRouteItem<infer TName, infer TPattern>
-    ? TName extends string
-      ? TName extends UnnamedRoute
-        ? {} // Exclude unnamed routes from type map
-        : { [K in TName]: TPattern }
-      : {}
-    // TypedIncludeItem: extract prefixed routes
-    : T extends TypedIncludeItem<infer TRoutes, infer TPrefix>
-      ? TPrefix extends string
-        ? PrefixRoutes<TRoutes, TPrefix>
-        : TRoutes
-      // TypedLayoutItem: extract child routes from phantom type
-      : T extends TypedLayoutItem<infer TChildRoutes>
-        ? TChildRoutes
-        // TypedCacheItem: extract child routes from phantom type
-        : T extends TypedCacheItem<infer TChildRoutes>
-          ? TChildRoutes
-          // Fallback (won't extract routes)
-          : {};
-
-/**
- * Extract routes from an array of items (union of all extracted routes)
- * D is the current depth level
- */
-type ExtractRoutesFromItems<
-  T extends readonly any[],
-  D extends number = 5
-> = [D] extends [never]
-  ? {} // Max depth reached
-  : T extends readonly [infer First, ...infer Rest]
-    ? ExtractRoutesFromItem<First, D> &
-        ExtractRoutesFromItems<Rest, Depth[D]>
-    : {};
-
-/**
- * Main utility: extract route map from urls() callback return type
- * Supports up to 5 levels of nesting
- */
-export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<T, 5>;
-
-// ============================================================================
-// Path Helpers Type
-// ============================================================================
-
-/**
- * Helpers provided by urls()
- */
-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: <const TPattern extends string, const TName extends string = UnnamedRoute>(
-    pattern: TPattern,
-    handler: ReactNode | Handler<ExtractParams<TPattern>, TEnv>,
-    optionsOrUse?: PathOptions<TName> | (() => RouteUseItem[]),
-    use?: () => RouteUseItem[]
-  ) => TypedRouteItem<TName, TPattern>;
-
-  /**
-   * Define a layout that wraps child routes
-   */
-  layout: <const TChildren extends readonly LayoutUseItem[] = readonly LayoutUseItem[]>(
-    component: ReactNode | Handler<any, TEnv>,
-    use?: () => TChildren
-  ) => TypedLayoutItem<ExtractRoutes<TChildren>>;
-
-  /**
-   * Include nested URL patterns with optional name prefix
-   *
-   * ```typescript
-   * // Without name - routes keep local names
-   * include("/blog", blogPatterns)
-   *
-   * // With name - routes are prefixed (e.g., "index" → "blog.index")
-   * include("/blog", blogPatterns, { name: "blog" })
-   * ```
-   */
-  include: <
-    TRoutes extends Record<string, string>,
-    const TNamePrefix extends string = never
-  >(
-    prefix: string,
-    patterns: UrlPatterns<TEnv, TRoutes>,
-    options?: IncludeOptions<TNamePrefix>
-  ) => TypedIncludeItem<TRoutes, TNamePrefix>;
-
-  /**
-   * Define parallel routes that render simultaneously in named slots
-   */
-  parallel: <TSlots extends Record<`@${string}`, Handler<any, TEnv> | ReactNode>>(
-    slots: TSlots,
-    use?: () => ParallelUseItem[]
-  ) => ParallelItem;
-
-  /**
-   * Define an intercepting route for soft navigation
-   * Note: routeName must match a named path() in this urlpatterns
-   */
-  intercept: (
-    slotName: `@${string}`,
-    routeName: string,
-    handler: ReactNode | Handler<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: {
-    (): CacheItem;
-    <const TChildren extends readonly AllUseItems[] = readonly AllUseItems[]>(
-      children: () => TChildren
-    ): TypedCacheItem<ExtractRoutes<TChildren>>;
-    <const TChildren extends readonly AllUseItems[] = readonly AllUseItems[]>(
-      options: PartialCacheOptions | false,
-      use?: () => TChildren
-    ): TypedCacheItem<ExtractRoutes<TChildren>>;
-  };
-};
-
-// ============================================================================
-// Helper Implementations
-// ============================================================================
-
-/**
- * Check if a value is a valid use item
- */
-const isValidUseItem = (item: any): item is AllUseItems | undefined | null => {
-  return (
-    typeof item === "undefined" ||
-    item === null ||
-    (item &&
-      typeof item === "object" &&
-      "type" in item &&
-      [
-        "layout",
-        "route",
-        "middleware",
-        "revalidate",
-        "parallel",
-        "intercept",
-        "loader",
-        "loading",
-        "errorBoundary",
-        "notFoundBoundary",
-        "when",
-        "cache",
-        "include",
-      ].includes(item.type))
-  );
-};
-
-/**
- * Apply URL prefix to a pattern
- * Handles edge cases like "/" patterns and double slashes
- */
-function applyUrlPrefix(prefix: string, pattern: string): string {
-  if (!prefix) return pattern;
-  if (pattern === "/") return prefix;
-  if (prefix.endsWith("/") && pattern.startsWith("/")) {
-    return prefix + pattern.slice(1);
-  }
-  return prefix + pattern;
-}
-
-/**
- * Apply name prefix to a route name
- */
-function applyNamePrefix(prefix: string | undefined, name: string): string {
-  if (!prefix) return name;
-  return `${prefix}.${name}`;
-}
-
-/**
- * Create path() helper
- *
- * The path() function is the key new feature - it combines URL pattern
- * with handler at the definition site.
- */
-function createPathHelper<TEnv>(): PathHelpers<TEnv>["path"] {
-  return ((
-    pattern: string,
-    handler: ReactNode | Handler<any, TEnv>,
-    optionsOrUse?: PathOptions | (() => RouteUseItem[]),
-    maybeUse?: () => RouteUseItem[]
-  ): RouteItem => {
-    const store = getContext();
-    const ctx = store.getStore();
-    if (!ctx) throw new Error("path() must be called inside urls()");
-
-    // Determine options and use based on argument types
-    let options: PathOptions | undefined;
-    let use: (() => RouteUseItem[]) | undefined;
-
-    if (typeof optionsOrUse === "function") {
-      // path(pattern, handler, use)
-      use = optionsOrUse as () => RouteUseItem[];
-    } else if (typeof optionsOrUse === "object") {
-      // path(pattern, handler, options) or path(pattern, handler, options, use)
-      options = optionsOrUse as PathOptions;
-      use = maybeUse;
-    }
-
-    // Get prefixes from context (set by include())
-    const urlPrefix = getUrlPrefix();
-    const namePrefix = getNamePrefix();
-
-    // Apply URL prefix to pattern
-    const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
-
-    // Generate route name - use provided name or generate from pattern
-    const localName = options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
-    // Apply name prefix if set (from include())
-    const routeName = applyNamePrefix(namePrefix, localName);
-
-    const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
-
-    // Ensure handler is always a function (wrap ReactNode if needed)
-    const wrappedHandler: Handler<any, TEnv> =
-      typeof handler === "function"
-        ? (handler as Handler<any, TEnv>)
-        : () => handler;
-
-    const entry = {
-      id: namespace,
-      shortCode: store.getShortCode("route"),
-      type: "route" as const,
-      parent: ctx.parent,
-      handler: wrappedHandler,
-      // Store the PREFIXED pattern for route matching
-      pattern: prefixedPattern,
-      loading: undefined,
-      middleware: [],
-      revalidate: [],
-      errorBoundary: [],
-      notFoundBoundary: [],
-      layout: [],
-      parallel: [],
-      intercept: [],
-      loader: [],
-    };
-
-    // Check for duplicate route names (TypeScript should catch this, but runtime check too)
-    invariant(
-      ctx.manifest.get(routeName) === undefined,
-      `Duplicate route name: ${routeName} at ${namespace}`
-    );
-
-    // Register route entry with prefixed name
-    ctx.manifest.set(routeName, entry);
-
-    // Also store pattern in a separate map for URL generation
-    if (ctx.patterns) {
-      ctx.patterns.set(routeName, prefixedPattern);
-    }
-
-    // Store trailing slash config if specified
-    if (options?.trailingSlash && ctx.trailingSlash) {
-      ctx.trailingSlash.set(routeName, options.trailingSlash);
-    }
-
-    // Run use callback if provided
-    if (use && typeof use === "function") {
-      const result = store.run(namespace, entry, use);
-      invariant(
-        Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-        `path() use() callback must return an array of use items [${namespace}]`
-      );
-      return { name: namespace, type: "route", uses: result } as RouteItem;
-    }
-
-    return { name: namespace, type: "route" } as RouteItem;
-  }) as PathHelpers<TEnv>["path"];
-}
-
-/**
- * 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, options } = item;
-  const namePrefix = 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
- */
-function processItems(items: readonly AllUseItems[]): AllUseItems[] {
-  const result: AllUseItems[] = [];
-
-  for (const item of items) {
-    if (!item) continue;
-
-    if (item.type === "include") {
-      // Include items are already expanded during include() call
-      // Just extract the expanded items
-      const includeItem = item as IncludeItem & { _expanded?: AllUseItems[] };
-      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
- *
- * Unlike other helpers that return items for later processing,
- * include() IMMEDIATELY expands the nested patterns. This ensures
- * that routes from included patterns inherit the correct parent context
- * (the layout they're included in).
- */
-function createIncludeHelper<TEnv>(): PathHelpers<TEnv>["include"] {
-  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 namePrefix = options?.name;
-
-    // IMMEDIATELY expand the nested patterns with the current context
-    // This ensures routes inherit the correct parent (e.g., UserRootLayout)
-    const expandedItems = runWithPrefixes(prefix, namePrefix, () => {
-      return (patterns as UrlPatterns).handler();
-    });
-
-    // Return a marker item that contains the expanded items
-    // processItems will extract these expanded items
-    const name = `$include_${prefix.replace(/[/:*?]/g, "_")}`;
-    return {
-      type: "include",
-      name,
-      prefix,
-      patterns,
-      options,
-      // Store expanded items for processItems to extract
-      _expanded: expandedItems,
-    } as IncludeItem & { _expanded: AllUseItems[] };
-  };
-}
-
-// ============================================================================
-// Re-use existing helpers from route-definition.ts
-// ============================================================================
-
-// Import the helper creation functions from route-definition
-import {
-  createRouteHelpers,
-} from "./route-definition.js";
-
-// ============================================================================
-// urls() Main Entry Point
-// ============================================================================
-
-/**
- * Define URL patterns with Django-inspired syntax
- *
- * Replaces map() as the entry point for route definitions.
- * URL patterns are now visible at the definition site via path().
- *
- * @example
- * ```typescript
- * export const blogPatterns = urls(({ path, layout, loader }) => [
- *   layout(BlogLayout, () => [
- *     path("/", BlogIndex, { name: "index" }),
- *     path("/:slug", BlogPost, { name: "post" }, () => [
- *       loader(PostLoader),
- *     ]),
- *   ]),
- * ]);
- * ```
- */
-export function urls<
-  TEnv = DefaultEnv,
-  const TItems extends readonly AllUseItems[] = readonly AllUseItems[]
->(
-  builder: (helpers: PathHelpers<TEnv>) => TItems
-): UrlPatterns<TEnv, ExtractRoutes<TItems>> {
-  // Collect path definitions during build
-  const definitions: PathDefinition[] = [];
-
-  // Create the handler function that will be called by the router
-  const handler = () => {
-    invariant(
-      typeof builder === "function",
-      "urls() expects a builder function as its argument"
-    );
-
-    // Get base helpers from the existing route-definition module
-    const baseHelpers = createRouteHelpers<any, TEnv>();
-
-    // Create the path helper
-    const pathHelper = createPathHelper<TEnv>();
-
-    // Create the include helper
-    const includeHelper = createIncludeHelper<TEnv>();
-
-    // Combine all helpers
-    // Note: layout and cache are cast to their typed versions - phantom types don't affect runtime
-    const helpers: PathHelpers<TEnv> = {
-      path: pathHelper,
-      include: includeHelper,
-      layout: baseHelpers.layout as PathHelpers<TEnv>["layout"],
-      parallel: baseHelpers.parallel,
-      intercept: baseHelpers.intercept as PathHelpers<TEnv>["intercept"],
-      middleware: baseHelpers.middleware,
-      revalidate: baseHelpers.revalidate,
-      loader: baseHelpers.loader,
-      loading: baseHelpers.loading,
-      errorBoundary: baseHelpers.errorBoundary,
-      notFoundBoundary: baseHelpers.notFoundBoundary,
-      when: baseHelpers.when,
-      cache: baseHelpers.cache as PathHelpers<TEnv>["cache"],
-    };
-
-    // Execute builder directly - manifest.ts handles RootLayout wrapping
-    // for inline handlers (non-Promise results).
-    // For nested include() calls, routes inherit the outer RootLayout.
-    const builderResult = builder(helpers);
-    return processItems(builderResult);
-  };
-
-  // trailingSlash config is populated when handler() runs
-  // We expose it via a getter that reads from the context after handler execution
-  return {
-    definitions,
-    handler,
-    get trailingSlash() {
-      // Get the trailingSlash map from the current context
-      // This will be populated after handler() is called
-      const store = getContext();
-      const ctx = store.context.getStore();
-      if (!ctx?.trailingSlash) {
-        return {};
-      }
-      return Object.fromEntries(ctx.trailingSlash);
-    },
-  } as UrlPatterns<TEnv, ExtractRoutes<TItems>>;
-}
-
-// ============================================================================
-// Type Utilities for path()
-// ============================================================================
-
-/**
- * Extract route names from a UrlPatterns result
- * Used for type-safe href() generation
- */
-export type ExtractRouteNames<T extends UrlPatterns<any>> =
-  T extends UrlPatterns<infer _TEnv>
-    ? string // For now, will be refined with full implementation
-    : never;
-
-/**
- * Extract params for a specific route name
- */
-export type ExtractPathParams<
-  T extends UrlPatterns<any>,
-  K extends string
-> = ExtractParams<string>; // Will be refined with pattern tracking
-
-// ============================================================================
-// Exports
-// ============================================================================
-
-export type { AllUseItems, IncludeItem, TypedRouteItem, TypedIncludeItem, TypedLayoutItem, TypedCacheItem } from "./route-types.js";
+export * from "./urls/index.js";