@rangojs/router 0.0.0-experimental.110 → 0.0.0-experimental.111

package/src/route-definition/helper-factories.ts

@@ -11,122 +11,40 @@ import {
   when,
   errorBoundary,
   notFoundBoundary,
-  loaderFn,
-  loadingFn,
-  transitionFn,
-  routeFn,
+  route,
+  loader,
+  loading,
+  transition,
 } from "./dsl-helpers.js";
 import RootLayout from "../server/root-layout";
 import { invariant } from "../errors";
 
-/*
- * Create revalidate helper
- */
-const createRevalidateHelper = <TEnv>(): RouteHelpers<
-  any,
-  TEnv
->["revalidate"] => {
-  return revalidate as RouteHelpers<any, TEnv>["revalidate"];
-};
-
-/**
- * Create errorBoundary helper
- */
-const createErrorBoundaryHelper = <TEnv>(): RouteHelpers<
-  any,
-  TEnv
->["errorBoundary"] => {
-  return errorBoundary as RouteHelpers<any, TEnv>["errorBoundary"];
-};
-
-/**
- * Create notFoundBoundary helper
- */
-const createNotFoundBoundaryHelper = <TEnv>(): RouteHelpers<
-  any,
-  TEnv
->["notFoundBoundary"] => {
-  return notFoundBoundary as RouteHelpers<any, TEnv>["notFoundBoundary"];
-};
-
 /**
- * Create middleware helper
+ * Assemble the RouteHelpers object. The helpers are the DSL functions
+ * themselves; the single cast erases the phantom generics (and the extra
+ * `route` key) that the per-router RouteHelpers<T, TEnv> type carries but the
+ * runtime functions do not.
  */
-const createMiddlewareHelper = <TEnv>(): RouteHelpers<
-  any,
+function buildRouteHelpers<T extends RouteDefinition, TEnv>(): RouteHelpers<
+  T,
   TEnv
->["middleware"] => {
-  return middleware as RouteHelpers<any, TEnv>["middleware"];
-};
-
-/**
- * Create parallel helper
- */
-const createParallelHelper = <TEnv>(): RouteHelpers<any, TEnv>["parallel"] => {
-  return parallel as RouteHelpers<any, TEnv>["parallel"];
-};
-
-/**
- * Create intercept helper
- */
-const createInterceptHelper = <
-  const T extends RouteDefinition,
-  TEnv,
->(): RouteHelpers<T, TEnv>["intercept"] => {
-  return intercept as RouteHelpers<T, TEnv>["intercept"];
-};
-
-/**
- * Create loader helper
- */
-const createLoaderHelper = <TEnv>(): RouteHelpers<any, TEnv>["loader"] => {
-  return loaderFn as RouteHelpers<any, TEnv>["loader"];
-};
-
-/**
- * Create loading helper
- */
-const createLoadingHelper = (): RouteHelpers<any, any>["loading"] => {
-  return loadingFn;
-};
-
-/**
- * Create route helper
- */
-const createRouteHelper = <
-  const T extends RouteDefinition,
-  TEnv,
->(): RouteHelpers<T, TEnv>["route"] => {
-  return routeFn as unknown as RouteHelpers<T, TEnv>["route"];
-};
-
-/**
- * Create layout helper
- */
-const createLayoutHelper = <TEnv>(): RouteHelpers<any, TEnv>["layout"] => {
-  return layout as RouteHelpers<any, TEnv>["layout"];
-};
-
-/**
- * Create when helper for intercept conditions
- */
-const createWhenHelper = (): RouteHelpers<any, any>["when"] => {
-  return when;
-};
-
-/**
- * Create cache helper for cache configuration
- */
-const createCacheHelper = (): RouteHelpers<any, any>["cache"] => {
-  return cache;
-};
-
-/**
- * Create transition helper
- */
-const createTransitionHelper = (): RouteHelpers<any, any>["transition"] => {
-  return transitionFn as RouteHelpers<any, any>["transition"];
-};
+> {
+  return {
+    route,
+    layout,
+    parallel,
+    intercept,
+    middleware,
+    revalidate,
+    loader,
+    loading,
+    errorBoundary,
+    notFoundBoundary,
+    when,
+    cache,
+    transition,
+  } as unknown as RouteHelpers<T, TEnv>;
+}
 
 /**
  * Branded type for route handlers that carries the route type info.
@@ -152,21 +70,7 @@ export function map<const T extends RouteDefinition, TEnv = DefaultEnv>(
       "map() expects a builder function as its argument",
     );
     // Create helpers
-    const helpers: RouteHelpers<T, TEnv> = {
-      route: createRouteHelper<T, TEnv>(),
-      layout: createLayoutHelper<TEnv>(),
-      parallel: createParallelHelper<TEnv>(),
-      intercept: createInterceptHelper<T, TEnv>(),
-      middleware: createMiddlewareHelper<TEnv>(),
-      revalidate: createRevalidateHelper<TEnv>(),
-      loader: createLoaderHelper<TEnv>(),
-      loading: createLoadingHelper(),
-      errorBoundary: createErrorBoundaryHelper<TEnv>(),
-      notFoundBoundary: createNotFoundBoundaryHelper<TEnv>(),
-      when: createWhenHelper(),
-      cache: createCacheHelper(),
-      transition: createTransitionHelper(),
-    };
+    const helpers = buildRouteHelpers<T, TEnv>();
 
     return [layout(RootLayout, () => builder(helpers))].flat(3);
   };
@@ -182,19 +86,5 @@ export function createRouteHelpers<
   T extends RouteDefinition,
   TEnv,
 >(): RouteHelpers<T, TEnv> {
-  return {
-    route: createRouteHelper<T, TEnv>(),
-    layout: createLayoutHelper<TEnv>(),
-    parallel: createParallelHelper<TEnv>(),
-    intercept: createInterceptHelper<T, TEnv>(),
-    middleware: createMiddlewareHelper<TEnv>(),
-    revalidate: createRevalidateHelper<TEnv>(),
-    loader: createLoaderHelper<TEnv>(),
-    loading: createLoadingHelper(),
-    errorBoundary: createErrorBoundaryHelper<TEnv>(),
-    notFoundBoundary: createNotFoundBoundaryHelper<TEnv>(),
-    when: createWhenHelper(),
-    cache: createCacheHelper(),
-    transition: createTransitionHelper(),
-  };
+  return buildRouteHelpers<T, TEnv>();
 }

package/src/route-definition/use-item-types.ts

@@ -0,0 +1,32 @@
+import type { AllUseItems, WhenItem } from "../route-types.js";
+
+/**
+ * The set of valid use-item `type` discriminants — the single runtime source of
+ * truth for "is this a well-formed use item?" shape validation.
+ *
+ * Declared via a `Record<...>` so that adding a member to the union without
+ * updating this map is a compile error. `when` is included because when() items
+ * are valid inside intercept() even though WhenItem is not part of AllUseItems
+ * (it lives only in InterceptUseItem). This is shape validation only; per-mount-
+ * site rules remain the narrower hand-written tables in resolve-handler-use.ts.
+ */
+const USE_ITEM_TYPES: Record<AllUseItems["type"] | WhenItem["type"], true> = {
+  layout: true,
+  route: true,
+  middleware: true,
+  revalidate: true,
+  parallel: true,
+  intercept: true,
+  loader: true,
+  loading: true,
+  errorBoundary: true,
+  notFoundBoundary: true,
+  when: true,
+  cache: true,
+  transition: true,
+  include: true,
+};
+
+export const ALL_USE_ITEM_TYPES: ReadonlySet<string> = new Set(
+  Object.keys(USE_ITEM_TYPES),
+);

package/src/route-types.ts

@@ -5,47 +5,43 @@
  */
 
 /**
- * Branded return types for route helpers
+ * Brand for UrlPatterns nominal typing (see pattern-types.ts). The route-item
+ * types below are discriminated by their `type` literal, so they carry no brand.
  */
-export declare const LayoutBrand: unique symbol;
-export declare const RouteBrand: unique symbol;
-export declare const ParallelBrand: unique symbol;
-export declare const InterceptBrand: unique symbol;
-export declare const MiddlewareBrand: unique symbol;
-export declare const RevalidateBrand: unique symbol;
-export declare const LoaderBrand: unique symbol;
-export declare const LoadingBrand: unique symbol;
-export declare const ErrorBoundaryBrand: unique symbol;
-export declare const NotFoundBoundaryBrand: unique symbol;
-export declare const WhenBrand: unique symbol;
-export declare const CacheBrand: unique symbol;
-export declare const TransitionBrand: unique symbol;
-export declare const IncludeBrand: unique symbol;
 export declare const UrlPatternsBrand: unique symbol;
 
 export type LayoutItem = {
   name: string;
   type: "layout";
   uses?: AllUseItems[];
-  [LayoutBrand]: void;
 };
 
 /**
- * Typed layout item that carries child routes as phantom type
- * Used for type inference in urls() API
+ * Phantom inference fields attached to wrapper items (layout/cache/transition)
+ * so the urls() type extractor can read their child routes/responses. The fields
+ * never exist at runtime.
  */
-export type TypedLayoutItem<
+type WithChildren<
+  TBase,
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = LayoutItem & {
+> = TBase & {
   readonly __childRoutes?: TChildRoutes;
   readonly __childResponses?: TChildResponses;
 };
+
+/**
+ * Typed layout item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedLayoutItem<
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<LayoutItem, TChildRoutes, TChildResponses>;
 export type RouteItem = {
   name: string;
   type: "route";
   uses?: AllUseItems[];
-  [RouteBrand]: void;
 };
 
 /**
@@ -67,64 +63,53 @@ export type ParallelItem = {
   name: string;
   type: "parallel";
   uses?: ParallelUseItem[];
-  [ParallelBrand]: void;
 };
 export type InterceptItem = {
   name: string;
   type: "intercept";
   uses?: InterceptUseItem[];
-  [InterceptBrand]: void;
 };
 export type LoaderItem = {
   name: string;
   type: "loader";
   uses?: LoaderUseItem[];
-  [LoaderBrand]: void;
 };
 export type MiddlewareItem = {
   name: string;
   type: "middleware";
   uses?: AllUseItems[];
-  [MiddlewareBrand]: void;
 };
 export type RevalidateItem = {
   name: string;
   type: "revalidate";
   uses?: AllUseItems[];
-  [RevalidateBrand]: void;
 };
 export type LoadingItem = {
   name: string;
   type: "loading";
-  [LoadingBrand]: void;
 };
 export type ErrorBoundaryItem = {
   name: string;
   type: "errorBoundary";
   uses?: AllUseItems[];
-  [ErrorBoundaryBrand]: void;
 };
 export type NotFoundBoundaryItem = {
   name: string;
   type: "notFoundBoundary";
   uses?: AllUseItems[];
-  [NotFoundBoundaryBrand]: void;
 };
 export type WhenItem = {
   name: string;
   type: "when";
-  [WhenBrand]: void;
 };
 export type CacheItem = {
   name: string;
   type: "cache";
   uses?: AllUseItems[];
-  [CacheBrand]: void;
 };
 export type TransitionItem = {
   name: string;
   type: "transition";
-  [TransitionBrand]: void;
 };
 
 /**
@@ -134,10 +119,7 @@ export type TransitionItem = {
 export type TypedTransitionItem<
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = TransitionItem & {
-  readonly __childRoutes?: TChildRoutes;
-  readonly __childResponses?: TChildResponses;
-};
+> = WithChildren<TransitionItem, TChildRoutes, TChildResponses>;
 
 /**
  * Typed cache item that carries child routes as phantom type
@@ -146,10 +128,7 @@ export type TypedTransitionItem<
 export type TypedCacheItem<
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = CacheItem & {
-  readonly __childRoutes?: TChildRoutes;
-  readonly __childResponses?: TChildResponses;
-};
+> = WithChildren<CacheItem, TChildRoutes, TChildResponses>;
 
 /**
  * Include item for URL pattern composition (used by urls() API)
@@ -184,7 +163,6 @@ export type IncludeItem = {
      */
     includeScope?: string;
   };
-  [IncludeBrand]: void;
 };
 
 /**

package/src/server/context.ts

@@ -10,7 +10,7 @@ import type {
   ShouldRevalidateFn,
   TransitionConfig,
 } from "../types";
-import { invariant } from "../errors";
+import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 
 // ============================================================================
@@ -71,6 +71,10 @@ export type EntryPropCommon = {
 };
 
 /**
+ * Attachments resolved by walking the parent chain, not owned by the entry:
+ * middleware composes downward; revalidate and the error/notFound boundaries are
+ * resolved by nearest-ancestor lookup. Inherited, not a single execution chain.
+ *
  * @internal This type is an implementation detail and may change without notice.
  */
 export type EntryPropDatas = {
@@ -80,6 +84,16 @@ export type EntryPropDatas = {
   notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
 };
 
+/**
+ * Render-time presentation fields shared by every entry variant.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export type EntryPropRender = {
+  loading?: ReactNode | false;
+  transition?: TransitionConfig;
+};
+
 /**
  * Loader entry stored in EntryData
  * Contains the loader definition and its revalidation rules
@@ -158,11 +172,9 @@ export type InterceptEntry = {
 };
 
 export interface ParallelEntryData
-  extends EntryPropCommon, EntryPropDatas, EntryPropSegments {
+  extends EntryPropCommon, EntryPropDatas, EntryPropSegments, EntryPropRender {
   type: "parallel";
   handler: Record<`@${string}`, Handler<any, any, any> | ReactNode>;
-  loading?: ReactNode | false;
-  transition?: TransitionConfig;
   /** Set when any parallel slot is a Static definition */
   isStaticPrerender?: true;
   /** Per-slot static handler $$ids for build-time store lookup */
@@ -171,6 +183,13 @@ export interface ParallelEntryData
 
 export type ParallelEntries = Partial<Record<`@${string}`, ParallelEntryData>>;
 
+/**
+ * This entry's own structural children plus its owned loaders. `loader` lives
+ * here (not in EntryPropDatas) because loaders are owned by the entry, not
+ * inherited from ancestors.
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
 export type EntryPropSegments = {
   loader: LoaderEntry[];
   layout: EntryData[];
@@ -182,8 +201,6 @@ export type EntryData =
   | ({
       type: "route";
       handler: Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
       /** URL pattern for this route (used by path() in urls()) */
       pattern?: string;
       /** Set when handler is a Prerender definition */
@@ -205,29 +222,28 @@ export type EntryData =
       responseType?: string;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments)
+      EntryPropSegments &
+      EntryPropRender)
   | ({
       type: "layout";
       handler: ReactNode | Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
       /** Set when handler is a Static definition (build-time only) */
       isStaticPrerender?: true;
       /** Static handler $$id for build-time store lookup */
       staticHandlerId?: string;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments)
+      EntryPropSegments &
+      EntryPropRender)
   | ParallelEntryData
   | ({
       type: "cache";
       /** Cache entries create cache boundaries and render like layouts (with Outlet) */
       handler: ReactNode | Handler<any, any, any>;
-      loading?: ReactNode | false;
-      transition?: TransitionConfig;
     } & EntryPropCommon &
       EntryPropDatas &
-      EntryPropSegments);
+      EntryPropSegments &
+      EntryPropRender);
 
 /**
  * Tracked include info for build-time manifest generation
@@ -307,6 +323,24 @@ export const RangoContext: AsyncLocalStorage<HelperContext> = ((
   globalThis as any
 )[RSC_CONTEXT_KEY] ??= new AsyncLocalStorage<HelperContext>());
 
+/** shortCode prefix letter per entry type (e.g. "L0", "R2", "M1C0"). */
+const SHORT_CODE_PREFIX: Record<
+  "layout" | "parallel" | "route" | "loader" | "cache",
+  string
+> = {
+  layout: "L",
+  parallel: "P",
+  route: "R",
+  loader: "D",
+  cache: "C",
+};
+
+/** Post-increment a named per-store counter, returning the prior value. */
+function bumpCounter(store: HelperContext, key: string): number {
+  store.counters[key] ??= 0;
+  return store.counters[key]++;
+}
+
 export const getContext = (): {
   context: AsyncLocalStorage<HelperContext>;
   getStore: () => HelperContext;
@@ -373,10 +407,7 @@ export const getContext = (): {
     ) => {
       const store = context.getStore();
       invariant(store, "No context RangoContext available");
-      store.counters[type] ??= 0;
-      const index = store.counters[type];
-      store.counters[type] = index + 1;
-      return `$${type}.${index}`;
+      return `$${type}.${bumpCounter(store, type)}`;
     },
     getShortCode: (
       type: "layout" | "parallel" | "route" | "loader" | "cache",
@@ -385,16 +416,7 @@ export const getContext = (): {
       invariant(store, "No context RangoContext available");
 
       const parent = store.parent;
-      const prefix =
-        type === "layout"
-          ? "L"
-          : type === "parallel"
-            ? "P"
-            : type === "loader"
-              ? "D"
-              : type === "cache"
-                ? "C"
-                : "R";
+      const prefix = SHORT_CODE_PREFIX[type];
       const mountPrefix =
         store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
 
@@ -405,10 +427,7 @@ export const getContext = (): {
         const counterKey = mountPrefix
           ? `${mountPrefix}_root_${type}`
           : `root_${type}`;
-        store.counters[counterKey] ??= 0;
-        const index = store.counters[counterKey];
-        store.counters[counterKey] = index + 1;
-        return `${mountPrefix}${prefix}${index}`;
+        return `${mountPrefix}${prefix}${bumpCounter(store, counterKey)}`;
       } else {
         // Child entry: use parent-scoped counter with includeScope appended.
         // When we're evaluating a lazy include's direct children, includeScope
@@ -416,10 +435,7 @@ export const getContext = (): {
         // parent's counter namespace so routes inside one include cannot
         // collide with siblings declared outside it.
         const counterKey = `${parent.shortCode}${includeScope}_${type}`;
-        store.counters[counterKey] ??= 0;
-        const index = store.counters[counterKey];
-        store.counters[counterKey] = index + 1;
-        return `${parent.shortCode}${includeScope}${prefix}${index}`;
+        return `${parent.shortCode}${includeScope}${prefix}${bumpCounter(store, counterKey)}`;
       }
     },
     runWithStore: <T>(
@@ -493,6 +509,31 @@ export const getContext = (): {
   };
 };
 
+/**
+ * Acquire the active DSL build context, throwing `message` if a helper was
+ * called outside a urls()/map() builder. Returns the store API and the live
+ * HelperContext so callers avoid a second getContext() lookup.
+ */
+export function requireDslContext(message: string): {
+  store: ReturnType<typeof getContext>;
+  ctx: HelperContext;
+} {
+  const store = getContext();
+  const ctx = store.context.getStore();
+  if (!ctx) {
+    // The only reason the store is absent here is that a route-definition helper
+    // ran with no active RangoContext — i.e. outside a urls()/map() builder.
+    // Record that as the cause so the throw is self-explanatory, not a bare
+    // "must be called inside urls()" with no indication of the mechanism.
+    throw new DslContextError(message, {
+      cause:
+        "RangoContext store is undefined: a route-definition helper was called " +
+        "outside an active urls()/map() builder.",
+    });
+  }
+  return { store, ctx };
+}
+
 /**
  * Run a callback with specific URL and name prefixes
  * Used by include() to apply prefixes to nested patterns