@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.125

package/src/types/route-entry.ts

@@ -1,9 +1,6 @@
 import type { AllUseItems } from "../route-types.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
 
-/**
- * Context captured for lazy include evaluation
- */
 export interface LazyIncludeContext {
   urlPrefix: string;
   namePrefix: string | undefined;
@@ -25,9 +22,6 @@ export interface LazyIncludeContext {
   includeScope?: string;
 }
 
-/**
- * Internal route entry stored in router
- */
 export interface RouteEntry<TEnv = any> {
   prefix: string;
   /**

package/src/types/segments.ts

@@ -41,14 +41,6 @@ export interface TransitionConfig {
 /**
  * Resolved segment with component
  *
- * Segment types:
- * - layout: Wraps child content via <Outlet />
- * - route: The leaf content for a URL
- * - parallel: Named slots rendered via <ParallelOutlet name="@slot" />
- * - loader: Data segment (no visual rendering, carries loaderData)
- * - error: Error fallback segment (replaces failed segment with error UI)
- * - notFound: Not found fallback segment (replaces segment when data not found)
- *
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface ResolvedSegment {
@@ -89,11 +81,6 @@ export interface ResolvedSegment {
   _handlerRan?: boolean;
 }
 
-/**
- * Segment metadata (without component)
- *
- * @internal This type is an implementation detail and may change without notice.
- */
 export interface SegmentMetadata {
   id: string;
   type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";

package/src/urls/include-helper.ts

@@ -37,10 +37,8 @@ export function processItems(items: readonly AllUseItems[]): AllUseItems[] {
     if (!item) continue;
 
     if (item.type === "include") {
-      // All includes are lazy; the router expands them on first matching request.
       result.push(item);
     } 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);
@@ -141,8 +139,6 @@ export function createIncludeHelper<TEnv>(): IncludeFn<TEnv> {
           ? (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,

package/src/urls/index.ts

@@ -1,4 +1,3 @@
-// Response types and symbols
 export {
   RESPONSE_TYPE,
   type ResponseHandler,
@@ -8,7 +7,6 @@ export {
   type ResponseHandlerContext,
 } from "./response-types.js";
 
-// Pattern types
 export type {
   UnnamedRoute,
   LocalOnlyInclude,
@@ -17,7 +15,6 @@ export type {
   IncludeOptions,
 } from "./pattern-types.js";
 
-// Type extraction utilities
 export type {
   ExtractRoutes,
   ExtractResponses,
@@ -25,7 +22,6 @@ export type {
   RouteResponse,
 } from "./type-extraction.js";
 
-// Path helper types
 export type {
   PathFn,
   ResponsePathFn,
@@ -35,10 +31,8 @@ export type {
   PathHelpers,
 } from "./path-helper-types.js";
 
-// Main entry point
 export { urls } from "./urls-function.js";
 
-// Re-exports from route-types
 export type {
   AllUseItems,
   IncludeItem,

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

@@ -348,9 +348,9 @@ export type PathHelpers<TEnv> = {
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
       children: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
-    (options: PartialCacheOptions | false): TypedCacheItem<{}, {}>;
+    (options: PartialCacheOptions<TEnv> | false): TypedCacheItem<{}, {}>;
     <const TChildren extends readonly (AllUseItems | readonly AllUseItems[])[]>(
-      options: PartialCacheOptions | false,
+      options: PartialCacheOptions<TEnv> | false,
       use: () => TChildren,
     ): TypedCacheItem<ExtractRoutes<TChildren>, ExtractResponses<TChildren>>;
   };

package/src/urls/path-helper.ts

@@ -39,10 +39,6 @@ import {
   runAndValidateUseItems,
 } from "../route-definition/dsl-helpers.js";
 
-/**
- * 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;
@@ -52,29 +48,17 @@ function applyUrlPrefix(prefix: string, pattern: string): string {
   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}`;
 }
 
-/**
- * Resolve response type from path options (set by path.json(), path.text(), etc.)
- */
 function resolveResponseType(
   options: PathOptions | undefined,
 ): string | undefined {
   return options?.[RESPONSE_TYPE];
 }
 
-/**
- * Create path() helper
- *
- * The path() function is the key new feature - it combines URL pattern
- * with handler at the definition site.
- */
 export function createPathHelper<TEnv>(): PathFn<TEnv> {
   return ((
     pattern: string,
@@ -91,8 +75,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       "path() cannot be used inside parallel()",
     );
 
-    // Walk the parent chain to prevent path() nested under another path(),
-    // even when separated by intermediate layouts (e.g. path(layout(path())))
     {
       let ancestor = ctx.parent;
       while (ancestor) {
@@ -104,7 +86,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       }
     }
 
-    // Determine options and use based on argument types
     let options: PathOptions | undefined;
     let use: (() => UseItems<RouteUseItem>) | undefined;
 
@@ -117,49 +98,29 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       use = maybeUse;
     }
 
-    // Merge handler.use() defaults with explicit use()
-    // Response routes (path.json, path.text, etc.) only allow middleware + cache
     const handlerUseFn = resolveHandlerUse(handler);
     const mountSite = resolveResponseType(options) ? "response" : "path";
     const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
 
-    // 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, "_")}`;
     if (options?.name) {
       validateUserRouteName(options.name);
     }
-    // Apply name prefix if set (from include())
     const routeName = applyNamePrefix(namePrefix, localName);
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
 
-    // Per-request pruning: skip registration for routes that won't be rendered.
-    // forRoute is set by loadManifest() to the matched route name. During
-    // evaluateLazyEntry() (route matching), forRoute is unset so all routes
-    // register normally. We still increment counters to keep shortCodes stable
-    // across different routes (needed for segment reconciliation on navigation).
-    //
-    // include() does not need its own forRoute pruning. include() creates lazy
-    // entries that defer handler execution until route matching. When the lazy
-    // handler eventually runs inside loadManifest(), this path() check already
-    // covers all routes defined inside the include.
     if (ctx.forRoute && routeName !== ctx.forRoute) {
       store.getShortCode("route");
       return { type: "route" } as RouteItem;
     }
 
-    // Ensure handler is always a function (wrap ReactNode or extract from prerender/static def)
-    // For prerender stubs (production builds where handler code is evicted),
-    // handler.handler is undefined — provide a notFound fallback so requests
-    // for non-prerendered params get 404 instead of "handler is not a function".
     const wrappedHandler: Handler<any, any, TEnv> =
       typeof handler === "function"
         ? (handler as Handler<any, any, TEnv>)
@@ -190,7 +151,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       type: "route" as const,
       parent: ctx.parent,
       handler: wrappedHandler,
-      // Store the PREFIXED pattern for route matching
       pattern: prefixedPattern,
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
       ...(isPassthroughHandler(handler)
@@ -217,29 +177,23 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
         : {}),
     };
 
-    // Capture namespace prefix on static handler for build-time reverse() resolution
     if (isStaticHandler(handler) && handler.$$id && ctx.namePrefix) {
       (handler as any).$$routePrefix = ctx.namePrefix;
     }
 
-    // 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);
 
-    // Register root-scope flag for dot-local reverse resolution
     registerRouteRootScope(routeName, getRootScoped());
 
-    // Also store pattern in a separate map for URL generation
     if (ctx.patterns) {
       ctx.patterns.set(routeName, prefixedPattern);
     }
 
-    // Store pattern grouped by URL prefix for separate entry creation
     if (ctx.patternsByPrefix) {
       const urlPrefix = getUrlPrefix() || "";
       if (!ctx.patternsByPrefix.has(urlPrefix)) {
@@ -248,12 +202,10 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ctx.patternsByPrefix.get(urlPrefix)!.set(routeName, prefixedPattern);
     }
 
-    // Store trailing slash config if specified
     if (options?.trailingSlash && ctx.trailingSlash) {
       ctx.trailingSlash.set(routeName, options.trailingSlash);
     }
 
-    // Store search schema if specified
     if (options?.search) {
       if (ctx.searchSchemas) {
         ctx.searchSchemas.set(routeName, options.search);
@@ -261,7 +213,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       registerSearchSchema(routeName, options.search);
     }
 
-    // Run merged use callback (handler.use defaults + explicit use) if present
     if (mergedUse) {
       const result = runAndValidateUseItems(
         store,
@@ -278,10 +229,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
   }) as PathFn<TEnv>;
 }
 
-/**
- * Attach response type tag methods (.json, .text, .html, .xml, .md, .image, .stream, .any) to a path helper.
- * Each tag wraps the original path() call with the RESPONSE_TYPE option set.
- */
 export function attachPathResponseTags<TEnv>(
   pathFn: PathFn<TEnv>,
 ): PathFn<TEnv> & {
@@ -303,7 +250,6 @@ export function attachPathResponseTags<TEnv>(
     ) => {
       let options: PathOptions;
       let use: (() => any[]) | undefined;
-
       if (typeof optionsOrUse === "function") {
         options = { [RESPONSE_TYPE]: responseType };
         use = optionsOrUse;

package/src/urls/urls-function.ts

@@ -34,24 +34,18 @@ export function urls<
 >(
   builder: (helpers: PathHelpers<TEnv>) => TItems,
 ): UrlPatterns<TEnv, ExtractRoutes<TItems>, ExtractResponses<TItems>> {
-  // 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 (with .json, .text, .html, .xml, .image, .stream, .any tags)
     const pathHelper = attachPathResponseTags(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 as any,
       include: includeHelper as any,
@@ -69,20 +63,13 @@ export function urls<
       transition: baseHelpers.transition as PathHelpers<TEnv>["transition"],
     };
 
-    // 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).flat(3) as AllUseItems[];
     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 {
     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) {