@spfn/core 0.3.0-beta.1 → 0.3.0-beta.11

package/dist/{types-Bvvig_tT.d.ts → types-ClQVomgV.d.ts}

@@ -1,4 +1,4 @@
-import { b as RouteAuthProfile } from './router-ukNdAZcN.js';
+import { b as RouteAuthProfile } from './route-builder-2ani2jEI.js';
 import { HttpMethod } from './route/types.js';
 
 /**

package/dist/{types-9oszaJqp.d.ts → types-yv6z_mK7.d.ts}

@@ -62,13 +62,112 @@ type InferRouteInput<TRoute> = TRoute extends RouteDef<infer TInput, any, any> ?
  * ```
  */
 type InferRouteOutput<TRoute> = TRoute extends RouteDef<any, any, infer TResponse> ? TResponse : never;
+/**
+ * True only for `any`.
+ *
+ * `any` satisfies both branches of a conditional type, so a router whose routes are
+ * unresolved (`Router<any>`) would otherwise flatten into "every name exists" and
+ * accept a misspelled route name. A route record that is not known contributes no
+ * names instead.
+ */
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+/**
+ * True when `T` is a union of two or more members.
+ */
+type IsUnion<T, TCopy = T> = T extends unknown ? ([TCopy] extends [T] ? false : true) : false;
+/**
+ * One leaf of a router tree: the name a route is registered under, its definition, and
+ * the path it was reached by.
+ *
+ * A route is identified by its own key whatever depth it sits at — `registerRoutes`
+ * mounts a nested route under that key, and the contract collector reports a collision
+ * on it. Nesting groups the source; it does not qualify the name. The trail is carried
+ * so that one name reached through two branches stays two leaves.
+ */
+interface RouteLeaf<TName extends PropertyKey, TDef, TTrail extends PropertyKey[]> {
+    name: TName;
+    def: TDef;
+    trail: TTrail;
+}
+/** Decrements the nesting budget; `PrevDepth[0]` is `never`, which ends the walk. */
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/**
+ * How many levels of nesting are followed.
+ *
+ * A budget rather than open recursion: a router type that refers to itself would
+ * otherwise never terminate, and TypeScript would report an instantiation-depth error
+ * in whichever component happened to read a route type. A route below the budget is not
+ * visible to these types; ten levels is far past any hand-written tree.
+ */
+type MaxNesting = 10;
+/**
+ * Collect every route in a route record as a leaf, descending into nested routers
+ * exactly as `registerRoutes` does.
+ */
+type RouteLeaves<TRoutes, TTrail extends PropertyKey[] = [], TDepth extends number = MaxNesting> = [
+    TDepth
+] extends [never] ? never : IsAny<TRoutes> extends true ? never : {
+    [K in keyof TRoutes]-?: RouteLeafOf<K, Exclude<TRoutes[K], undefined>, [...TTrail, K], TDepth>;
+}[keyof TRoutes];
+/**
+ * A nested router contributes its own leaves; anything else is a leaf.
+ *
+ * `{ _routes: ... }` is the runtime's own test for a router (`isRouter`), and a
+ * `RouteDef` carries `handler`, `_input` and `_response` but never `_routes`, so a
+ * route cannot be mistaken for a router.
+ */
+type RouteLeafOf<TName extends PropertyKey, TValue, TTrail extends PropertyKey[], TDepth extends number> = TValue extends {
+    _routes: infer TNested;
+} ? RouteLeaves<TNested, TTrail, PrevDepth[TDepth]> : RouteLeaf<TName, TValue, TTrail>;
+/** Every name the tree declares. */
+type LeafNames<TLeaves> = Extract<TLeaves extends RouteLeaf<infer TName, any, any> ? TName : never, PropertyKey>;
+/**
+ * The leaves declaring exactly this name.
+ *
+ * Exactly, not assignably: a record typed `Record<string, RouteDef>` contributes the
+ * name `string`, which every literal name is assignable to, and a loose sibling must
+ * not make each of its siblings look doubly declared.
+ */
+type LeavesNamed<TLeaves, TName extends PropertyKey> = TLeaves extends RouteLeaf<infer TLeafName, any, any> ? [TLeafName] extends [TName] ? [TName] extends [TLeafName] ? TLeaves : never : never : never;
+/** The definition a leaf carries. */
+type LeafDef<TLeaves> = TLeaves extends RouteLeaf<any, infer TDef, any> ? TDef : never;
+/** Where a leaf was found — one distinct trail per place the name is declared. */
+type LeafTrail<TLeaves> = TLeaves extends RouteLeaf<any, any, infer TTrail> ? TTrail : never;
+/**
+ * Flatten the leaves into one namespace of name → definition.
+ *
+ * A name that two branches both declare is left out rather than resolved to one of
+ * them: the tree gives it no single meaning, and picking a winner silently would hand
+ * a component another route's types. Naming it then fails the `K` constraint on
+ * `RouterOutput`/`RouterInput`, on the line that named it. Two places is counted by
+ * trail, so one slot holding a union of route definitions stays one route and still
+ * infers the union.
+ *
+ * The result is a fresh mapped type, so no key carries an optional or readonly modifier
+ * out of the source record — a route key that turned optional would change what
+ * `InferRouteInput` returns for it.
+ */
+type FlattenLeaves<TLeaves> = {
+    [TName in LeafNames<TLeaves> as UnambiguousName<TLeaves, TName>]: LeafDef<LeavesNamed<TLeaves, TName>>;
+};
+/** The name itself when one place declares it, and nothing when two do. */
+type UnambiguousName<TLeaves, TName extends PropertyKey> = IsUnion<LeafTrail<LeavesNamed<TLeaves, TName>>> extends true ? never : TName;
 /**
  * Extract routes from Router type
- * Router<TRoutes> has routes in `_routes` property
+ *
+ * `Router<TRoutes>` holds its routes in `_routes`, and a value in that record is either
+ * a route or another router. Nested routers are flattened away, so every route appears
+ * here under its own name at one level — the same set of names the server registers.
+ *
+ * Exported so that the typed client (`Client`, in `./builder`) names a route the same
+ * way `RouterOutput` and `RouterInput` do; the two must not diverge, or a route would
+ * type in one place and not the other. It stays internal to the package: the
+ * `@spfn/core/nextjs` entry point exports a fixed list of type names, and this is not
+ * one of them.
  */
 type ExtractRoutes<TRouter> = TRouter extends {
     _routes: infer TRoutes;
-} ? TRoutes : TRouter;
+} ? FlattenLeaves<RouteLeaves<TRoutes>> : FlattenLeaves<RouteLeaves<TRouter>>;
 /**
  * Extract output type for a specific route from router
  *
@@ -88,6 +187,23 @@ type ExtractRoutes<TRouter> = TRouter extends {
  * // Extract item type from paginated response
  * type Example = RouterOutput<AppRouter, 'listExamples'>['items'][number];
  * ```
+ *
+ * A route declared inside a nested router is named the same way. The server registers
+ * a nested route under its own key, so `K` is the flat set of route names in the tree
+ * and the depth the route was declared at never appears here:
+ *
+ * ```typescript
+ * const appRouter = defineRouter({
+ *     getRoot,
+ *     examples: defineRouter({ listExamples, createExample }),
+ * });
+ *
+ * type ListData = RouterOutput<typeof appRouter, 'listExamples'>;
+ * ```
+ *
+ * Two branches declaring the same name make that name ambiguous, and it is left out of
+ * `K` rather than resolved to one of them — naming it is a compile error here instead
+ * of the wrong route's types reaching a component.
  */
 type RouterOutput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteOutput<ExtractRoutes<TRouter>[K]>;
 /**
@@ -106,6 +222,9 @@ type RouterOutput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteO
  *     // ...
  * }
  * ```
+ *
+ * `K` is the flat set of route names, so a route declared inside a nested router is
+ * named by its own key here too — see {@link RouterOutput}.
  */
 type RouterInput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteInput<ExtractRoutes<TRouter>[K]>;
 /**
@@ -247,4 +366,4 @@ interface CallOptions {
     };
 }
 
-export type { ApiConfig as A, CallOptions as C, InferRouteInput as I, RequestInterceptor as R, SetCookie as S, ResponseInterceptor as a, InferRouteOutput as b, CookieOptions as c, RouterInput as d, RouterOutput as e, StructuredInput as f };
+export type { ApiConfig as A, CallOptions as C, ExtractRoutes as E, InferRouteInput as I, RequestInterceptor as R, SetCookie as S, ResponseInterceptor as a, InferRouteOutput as b, CookieOptions as c, RouterInput as d, RouterOutput as e, StructuredInput as f };