@emeryld/rrroutes-contract 2.4.13 → 2.4.15

package/README.md

@@ -37,8 +37,8 @@ import { z } from 'zod'
 
 // 1) Describe your API
 const leaves = resource('/v1')
-  .sub('users', (users) =>
-    users
+  .sub(
+    resource('users')
       .get({
         querySchema: z.object({
           search: z.string().optional(),
@@ -49,11 +49,13 @@ const leaves = resource('/v1')
         ),
         description: 'Find users',
       })
-      .subId('userId', z.string().uuid(), (user) =>
-        user.patch({
-          bodySchema: z.object({ name: z.string().min(1) }),
-          outputSchema: z.object({ ok: z.literal(true) }),
-        }),
+      .sub(
+        resource(':userId', undefined, z.string().uuid())
+          .patch({
+            bodySchema: z.object({ name: z.string().min(1) }),
+            outputSchema: z.object({ ok: z.literal(true) }),
+          })
+          .done(),
       )
       .done(),
   )
@@ -76,7 +78,7 @@ const key = buildCacheKey({
   leaf,
   params: { userId: 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2' },
 })
-// key => ['patch', 'v1', 'users', 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2', { userId: 'f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2' }]
+// key => ['patch', 'v1', 'users', ['f2b2e72a-7f6d-4c3f-9c6f-7f0d8f3ac9e2'], {}]
 ```
 
 ## Detailed usage
@@ -87,10 +89,9 @@ const key = buildCacheKey({
 import { resource } from '@emeryld/rrroutes-contract'
 import { z } from 'zod'
 
-const leaves = resource('/api') // base path, optional inherited cfg
-  .with({ feed: false }) // merges flags into descendants (extend NodeCfg via declaration merging if you add your own)
-  .sub('projects', (projects) =>
-    projects
+const leaves = resource('/api')
+  .sub(
+    resource('projects')
       .get({
         feed: true, // infinite/feed for clients
         querySchema: z.object({
@@ -107,15 +108,15 @@ const leaves = resource('/api') // base path, optional inherited cfg
         outputSchema: z.object({ id: z.string(), name: z.string() }),
         description: 'Create a project',
       })
-      .subId('projectId', z.string().uuid(), (project) =>
-        project
+      .sub(
+        resource(':projectId', undefined, z.string().uuid())
           .get({ outputSchema: z.object({ id: z.string(), name: z.string() }) })
           .patch({
             bodySchema: z.object({ name: z.string().min(1) }),
             outputSchema: z.object({ id: z.string(), name: z.string() }),
           })
-          .sub('avatar', (avatar) =>
-            avatar
+          .sub(
+            resource('avatar')
               .put({
                 bodyFiles: [{ name: 'avatar', maxCount: 1 }], // signals multipart upload
                 bodySchema: z.object({ avatar: z.instanceof(Blob) }),
@@ -130,8 +131,8 @@ const leaves = resource('/api') // base path, optional inherited cfg
   .done()
 ```
 
-- `sub(name, [cfg], builder?)` nests paths (`/api/projects`).
-- `subId(name, schema, builder)` creates `/:name` segments and merges param schemas downward.
+- `resource(segment, nodeCfg?, idSchema?)` scopes a branch. Pass a segment name (e.g. `'projects'`, `':projectId'`) plus optional per-node config. Supplying an `idSchema` along with a `:param` segment wires up the params schema for all descendants.
+- `sub(childA, childB, ...)` mounts one or more child resources built elsewhere via `resource(...).get(...).done()`. Call it once per branch; pass multiple children at once when needed.
 - Methods (`get/post/put/patch/delete`) merge the active param schema unless you override via `paramsSchema`.
 - `done()` closes a branch and returns the collected readonly tuple of leaves.
 
@@ -157,6 +158,7 @@ type Output = InferOutput<typeof leaf> // { id: string; name: string }
 // Runtime helpers
 const url = compilePath(leaf.path, { projectId: '123' }) // "/api/projects/123"
 const cacheKey = buildCacheKey({ leaf, params: { projectId: '123' } })
+// cacheKey => ['patch', 'api', 'projects', ['123'], {}]
 
 // Typed subsets for routers/microfrontends
 type ProjectRoutes = SubsetRoutes<typeof registry.all, '/api/projects'>
@@ -201,8 +203,8 @@ const leaves = r
     },
     ({ collection }) =>
       collection
-        .sub('stats', (stats) =>
-          stats
+        .sub(
+          resource('stats')
             .get({
               outputSchema: z.object({ total: z.number() }),
               description: 'Extra endpoint alongside CRUD',
@@ -280,7 +282,7 @@ function onChatMessage(raw: unknown) {
 
 ### Edge cases and notes
 
-- `paramsSchema` on a method overrides the merged schema from `subId`—useful when you need stricter validation per verb.
+- `paramsSchema` on a method overrides the merged schema from parent segments—useful when you need stricter validation per verb.
 - `bodyFiles` marks a route as multipart; servers can attach upload middleware, and clients should send `FormData`.
 - CRUD helper only emits create/update routes when the matching `bodySchema` is provided; delete can be disabled via `enable.remove: false`.
 - Feed-only behavior (`feed: true`) is intended for GET endpoints; clients treat them as infinite queries.

package/dist/core/routesV3.builder.d.ts

@@ -4,7 +4,6 @@ type ZodTypeAny = z.ZodTypeAny;
 type ParamZod<Name extends string, S extends ZodTypeAny> = z.ZodObject<{
     [K in Name]: S;
 }>;
-type MergedParamsResult<PS, Name extends string, P extends ZodTypeAny> = PS extends ZodTypeAny ? z.ZodIntersection<PS, ParamZod<Name, P>> : ParamZod<Name, P>;
 type BaseMethodCfg<C extends MethodCfg> = Merge<Omit<MethodCfg, 'querySchema' | 'outputSchema' | 'feed'>, Omit<C, 'querySchema' | 'outputSchema' | 'feed'>>;
 type FeedField<C extends MethodCfg> = C['feed'] extends true ? {
     feed: true;
@@ -22,9 +21,29 @@ type ParamsField<C extends MethodCfg, PS> = C['paramsSchema'] extends ZodTypeAny
     paramsSchema: PS;
 };
 type EffectiveFeedFields<C extends MethodCfg, PS> = C['feed'] extends true ? FeedField<C> & FeedQueryField<C> & OutputField<C> & ParamsField<C, PS> : FeedField<C> & NonFeedQueryField<C> & OutputField<C> & ParamsField<C, PS>;
-type EffectiveCfg<C extends MethodCfg, PS> = Prettify<Merge<MethodCfg, BaseMethodCfg<C> & EffectiveFeedFields<C, PS>>>;
-type BuiltLeaf<M extends HttpMethod, Base extends string, I extends NodeCfg, C extends MethodCfg, PS> = Leaf<M, Base, Merge<I, LowProfileCfg<EffectiveCfg<C, PS>>>>;
-type MethodFns<Base extends string, Acc extends readonly AnyLeafLowProfile[], I extends NodeCfg, PS extends ZodTypeAny | undefined, Used extends HttpMethod | 'add'> = {
+type WithNodeDefaults<C extends MethodCfg, I extends NodeCfg> = Merge<C, {
+    queryExtensionSchema: C['queryExtensionSchema'] extends ZodTypeAny ? C['queryExtensionSchema'] : NodeQueryExtension<I>;
+    outputMetaSchema: C['outputMetaSchema'] extends ZodTypeAny ? C['outputMetaSchema'] : NodeOutputMeta<I>;
+}>;
+type EffectiveCfg<C extends MethodCfg, PS, I extends NodeCfg> = Prettify<Merge<MethodCfg, BaseMethodCfg<WithNodeDefaults<C, I>> & EffectiveFeedFields<WithNodeDefaults<C, I>, PS>>>;
+type NodeWithoutSchemas<I extends NodeCfg> = Omit<I, 'queryExtensionSchema' | 'outputMetaSchema'>;
+type BuiltLeaf<M extends HttpMethod, Base extends string, I extends NodeCfg, C extends MethodCfg, PS> = Leaf<M, Base, Merge<NodeWithoutSchemas<I>, LowProfileCfg<EffectiveCfg<C, PS, I>>>>;
+type StripParamName<Name extends string> = Name extends `:${infer P}` ? P : Name;
+type NormalizeBaseLiteral<Base extends string, HasParam extends boolean> = HasParam extends true ? Base extends `:${string}` ? Base : Base extends '' ? '' : `:${Base}` : Base;
+type ParamSchemaForBase<Base extends string, Param extends ZodTypeAny | undefined> = Param extends ZodTypeAny ? ParamZod<StripParamName<Base>, Param> : undefined;
+type ResourceBase<Base extends string, Param extends ZodTypeAny | undefined> = NormalizeBaseLiteral<Base, Param extends ZodTypeAny ? true : false>;
+type NodeQueryExtension<I extends NodeCfg> = I extends {
+    queryExtensionSchema?: infer QE;
+} ? QE extends ZodTypeAny ? QE : undefined : undefined;
+type NodeOutputMeta<I extends NodeCfg> = I extends {
+    outputMetaSchema?: infer OE;
+} ? OE extends ZodTypeAny ? OE : undefined : undefined;
+type SubResourceCollections = readonly [
+    ReadonlyArray<AnyLeafLowProfile>,
+    ...ReadonlyArray<AnyLeafLowProfile>[]
+];
+type MergeAugmentedCollections<Base extends string, Param extends ZodTypeAny | undefined, Collections extends ReadonlyArray<ReadonlyArray<AnyLeafLowProfile>>, Acc extends readonly AnyLeafLowProfile[] = []> = Collections extends readonly [infer First, ...infer Rest] ? First extends ReadonlyArray<AnyLeafLowProfile> ? Rest extends ReadonlyArray<ReadonlyArray<AnyLeafLowProfile>> ? MergeAugmentedCollections<Base, Param, Rest, MergeArray<Acc, AugmentLeaves<Base, Param, First>>> : MergeArray<Acc, AugmentLeaves<Base, Param, First>> : MergeAugmentedCollections<Base, Param, Rest extends ReadonlyArray<ReadonlyArray<AnyLeafLowProfile>> ? Rest : [], Acc> : Acc;
+type MethodFns<Base extends string, Acc extends readonly AnyLeafLowProfile[], I extends NodeCfg, PS extends ZodTypeAny | undefined, Used extends HttpMethod | 'add' | 'sub'> = {
     /**
      * Register a GET leaf at the current path.
      */
@@ -55,24 +74,13 @@ type MethodFns<Base extends string, Acc extends readonly AnyLeafLowProfile[], I
     }>, PS>>>, I, PS, Used | 'delete'>;
 };
 /** Builder surface used by `resource(...)` to accumulate leaves. */
-export interface Branch<Base extends string, Acc extends readonly AnyLeafLowProfile[], I extends NodeCfg, PS extends ZodTypeAny | undefined, Used extends HttpMethod | 'add' = never> extends MethodFns<Base, Acc, I, PS, Used> {
-    /**
-     * Mount a static subtree under `name`.
-     * The `leaves` are built externally via `resource(...)` and will be
-     * rebased so that their paths become `${Base}/${name}${leaf.path}` and their
-     * paramsSchemas are merged with the parameters already accumulated on this branch.
-     */
-    sub<Name extends string, const R extends readonly AnyLeafLowProfile[]>(name: Name, leaves: R): Branch<Base, MergeArray<Acc, AugmentLeaves<`${Base}/${Name}`, PS, R>>, I, PS, Used>;
-    /**
-     * Mount a static subtree under `name` and merge extra node-level config.
-     */
-    sub<Name extends string, J extends NodeCfg, const R extends readonly AnyLeafLowProfile[]>(name: Name, cfg: J, leaves: R): Branch<Base, MergeArray<Acc, AugmentLeaves<`${Base}/${Name}`, PS, R>>, Merge<I, J>, PS, Used>;
+export interface Branch<Base extends string, Acc extends readonly AnyLeafLowProfile[], I extends NodeCfg, PS extends ZodTypeAny | undefined, Used extends HttpMethod | 'add' | 'sub' = never> extends MethodFns<Base, Acc, I, PS, Used> {
     /**
-     * Introduce a `:param` segment and mount a pre-built subtree beneath it.
-     * The subtree paths are rebased to `${Base}/:${Name}${leaf.path}` and
-     * their paramsSchemas are intersected with the accumulated params plus this new param.
+     * Mount one or more sub-resources that were built via `resource(...)`.
+     * Each resource carries its own base path (e.g. `users`, `:userId`, `posts`)
+     * so this branch simply prefixes its current `Base` and merges param schemas.
      */
-    subId<Name extends string, P extends ZodTypeAny, const R extends readonly AnyLeafLowProfile[]>(name: Name, paramsSchema: P, leaves: R): Branch<Base, MergeArray<Acc, AugmentLeaves<`${Base}/:${Name}`, MergedParamsResult<PS, Name, P>, R>>, I, PS, Used>;
+    sub: 'sub' extends Used ? never : <const Collections extends SubResourceCollections, NextAcc extends readonly AnyLeafLowProfile[] = MergeArray<Acc, MergeAugmentedCollections<Base, PS, Collections>>>(...collections: Collections) => Branch<Base, NextAcc, I, PS, Used | 'sub'>;
     /**
      * Finish the branch and return the collected leaves.
      * @returns Readonly tuple of accumulated leaves.
@@ -85,7 +93,7 @@ export interface Branch<Base extends string, Acc extends readonly AnyLeafLowProf
  * @param inherited Optional node configuration applied to all descendants.
  * @returns Root `Branch` instance used to compose the route tree.
  */
-export declare function resource<Base extends string = '', I extends NodeCfg = {}>(base?: Base, inherited?: I): Branch<Base, readonly [], I, undefined>;
+export declare function resource<Base extends string = '', I extends NodeCfg = {}, Param extends ZodTypeAny | undefined = undefined>(base?: Base, inherited?: I, idSchema?: Param): Branch<ResourceBase<Base, Param>, readonly [], I, ParamSchemaForBase<Base, Param>>;
 /**
  * Merge two readonly tuples (preserves literal tuple information).
  * @param arr1 First tuple.

package/dist/core/routesV3.core.d.ts

@@ -9,10 +9,16 @@ export type FileField = {
     maxCount: number;
 };
 /** Configuration that applies to an entire branch of the route tree. */
-export type NodeCfg = {
-    /** @deprecated. Does nothing. */
-    authenticated?: boolean;
-};
+export interface NodeCfg {
+    /**
+     * Feed-specific query schema applied to all descendants unless they override it.
+     */
+    queryExtensionSchema?: ZodType;
+    /**
+     * Feed meta schema applied to all descendants unless they override it.
+     */
+    outputMetaSchema?: ZodType;
+}
 export type RouteSchema<Output = unknown, Input = Output> = {
     __out: Output;
     __in?: Input;
@@ -52,7 +58,7 @@ export declare function mergeSchemas(a: ZodType | undefined, b: ZodType | undefi
 export declare function getZodShape(schema: ZodObject): any;
 export declare function collectNestedFieldSuggestions(shape: Record<string, ZodType> | undefined, prefix?: string[]): string[];
 export type ToRouteSchema<S> = S extends ZodType<infer Out, infer In> ? RouteSchema<Out, In> : S;
-export type LowProfileCfg<Cfg extends MethodCfg> = Prettify<Omit<Cfg, 'bodySchema' | 'querySchema' | 'paramsSchema' | 'outputSchema' | 'outputMetaSchema'> & {
+export type LowProfileCfg<Cfg extends MethodCfg = MethodCfg> = Prettify<Omit<Cfg, 'bodySchema' | 'querySchema' | 'paramsSchema' | 'outputSchema' | 'outputMetaSchema'> & {
     bodySchema: ToRouteSchema<Cfg['bodySchema']>;
     querySchema: ToRouteSchema<Cfg['querySchema']>;
     paramsSchema: ToRouteSchema<Cfg['paramsSchema']>;
@@ -66,7 +72,7 @@ export type MethodCfg = {
     bodySchema?: ZodType;
     /** Zod schema describing the query string. */
     querySchema?: ZodType;
-    /** Zod schema describing path params (Internal only, set through sub and subId). */
+    /** Zod schema describing path params (internal only, set through resource segments). */
     paramsSchema?: ZodType;
     /** Zod schema describing the response payload. */
     outputSchema?: ZodType;
@@ -131,12 +137,25 @@ export type Merge<A, B> = Prettify<Omit<A, keyof B> & B>;
 export type Append<T extends readonly unknown[], X> = [...T, X];
 /** Concatenate two readonly tuple types. */
 export type MergeArray<A extends readonly unknown[], B extends readonly unknown[]> = [...A, ...B];
+type TrimTrailingSlash<S extends string> = S extends `${infer R}/` ? TrimTrailingSlash<R> : S;
+type TrimLeadingSlash<S extends string> = S extends `/${infer R}` ? TrimLeadingSlash<R> : S;
+type NormalizedBase<Base extends string> = TrimTrailingSlash<Base>;
+type NormalizedChild<Child extends string> = TrimLeadingSlash<Child>;
+export type JoinPath<Base extends string, Child extends string> = NormalizedBase<Base> extends '' ? Child : NormalizedChild<Child> extends '' ? NormalizedBase<Base> : `${NormalizedBase<Base>}/${NormalizedChild<Child>}`;
 export type IntersectZod<A extends ZodType | undefined, B extends ZodType | undefined> = B extends ZodType ? A extends ZodType ? z.ZodIntersection<A, B> : B : A extends ZodType ? A : undefined;
 type MergeRouteSchemas<Existing extends RouteSchema | undefined, Parent extends ZodType | undefined> = Existing extends RouteSchema<infer ExistingOut> ? Parent extends ZodType<infer ParentOut> ? RouteSchema<ExistingOut & ParentOut> : Existing : Parent extends ZodType<infer ParentOut> ? RouteSchema<ParentOut> : undefined;
 type AugmentedCfg<Cfg extends MethodCfgLowProfile, Param extends ZodType | undefined> = Prettify<Omit<Cfg, 'paramsSchema'> & {
     paramsSchema: MergeRouteSchemas<Cfg['paramsSchema'], Param>;
 }>;
-export type AugmentLeaves<P extends string, Param extends ZodType | undefined, R extends readonly LeafLowProfile[], Acc extends readonly LeafLowProfile[] = []> = R extends readonly [infer First, ...infer Rest] ? First extends LeafLowProfile ? AugmentLeaves<P, Param, Rest extends readonly LeafLowProfile[] ? Rest : [], Append<Acc, LeafLowProfile<First['method'], `${P}${First['path']}`, AugmentedCfg<First['cfg'], Param>>>> : never : Acc;
+export type AugmentLeaves<P extends string, Param extends ZodType | undefined, R extends readonly LeafLowProfile[], Acc extends readonly LeafLowProfile[] = []> = R extends readonly [infer First, ...infer Rest] ? First extends LeafLowProfile ? AugmentLeaves<P, Param, Rest extends readonly LeafLowProfile[] ? Rest : [], Append<Acc, LeafLowProfile<First['method'], JoinPath<P, First['path']>, AugmentedCfg<First['cfg'], Param>>>> : never : Acc;
+type NodeQueryExtension<Node> = Node extends {
+    queryExtensionSchema?: infer QE;
+} ? QE extends ZodType ? QE : undefined : undefined;
+type NodeOutputMeta<Node> = Node extends {
+    outputMetaSchema?: infer OM;
+} ? OM extends ZodType ? OM : undefined : undefined;
+type EffectiveQueryExtensionSchema<Method extends ZodType | undefined, Node extends NodeCfg | undefined> = Method extends ZodType ? Method : NodeQueryExtension<Node>;
+type EffectiveOutputMetaSchema<Method extends ZodType | undefined, Node extends NodeCfg | undefined> = Method extends ZodType ? Method : NodeOutputMeta<Node>;
 type SegmentParams<S extends string> = S extends `:${infer P}` ? P : never;
 type Split<S extends string> = S extends '' ? [] : S extends `${infer A}/${infer B}` ? [A, ...Split<B>] : [S];
 type ExtractParamNames<Path extends string> = SegmentParams<Split<Path>[number]>;
@@ -149,11 +168,35 @@ export type ExtractParamsFromPath<Path extends string> = ExtractParamNames<Path>
  * @returns Path string with parameters substituted.
  */
 export declare function compilePath<Path extends string>(path: Path, params: ExtractParamsFromPath<Path>): string;
+/**
+ * Build a deterministic cache key for the given leaf.
+ * The key matches the shape consumed by React Query helpers.
+ * @param args.leaf Leaf describing the endpoint.
+ * @param args.params Optional params used to build the path.
+ * @param args.query Optional query payload.
+ * @returns Tuple suitable for React Query cache keys.
+ */
+type SplitPath<P extends string> = P extends '' ? [] : P extends `${infer A}/${infer B}` ? [A, ...SplitPath<B>] : [P];
+type ParamValue<Params, Key extends string> = Params extends Record<Key, infer V> ? V : undefined;
+type MapKeySegments<Segments extends readonly string[], Params> = Segments extends [infer A, ...infer Rest] ? A extends string ? A extends `:${infer Key}` ? [
+    [
+        ParamValue<Params, Key>
+    ],
+    ...MapKeySegments<Rest extends readonly string[] ? Rest : [], Params>
+] : [
+    A,
+    ...MapKeySegments<Rest extends readonly string[] ? Rest : [], Params>
+] : [] : [];
+type CacheKeyForLeaf<L extends AnyLeafLowProfile> = readonly [
+    L['method'],
+    ...MapKeySegments<SplitPath<L['path']>, ExtractParamsFromPath<L['path']>>,
+    InferQuery<L> extends never ? {} : InferQuery<L>
+];
 export declare function buildCacheKey<L extends AnyLeafLowProfile>(args: {
     leaf: L;
     params?: ExtractParamsFromPath<L['path']>;
     query?: InferQuery<L>;
-}): readonly [HttpMethod, string, {}];
+}): CacheKeyForLeaf<L>;
 /** Definition-time method config (for clarity). */
 export type MethodCfgDef = MethodCfg;
 /** Low-profile method config where schemas carry a phantom __out like SocketSchema. */
@@ -166,9 +209,10 @@ export type MethodCfgLowProfile = Omit<MethodCfg, 'bodySchema' | 'querySchema' |
     queryExtensionSchema?: RouteSchema;
 };
 export type AnyLeafLowProfile = LeafLowProfile<HttpMethod, string, MethodCfgLowProfile>;
-export declare function buildLowProfileLeaf<const M extends HttpMethod, const Path extends string, const O extends ZodType | undefined = undefined, const P extends ZodType | undefined = undefined, const Q extends ZodType | undefined = undefined, const B extends ZodType | undefined = undefined, const FO extends ZodType | undefined = undefined, const FQ extends ZodType | undefined = undefined, const Feed extends boolean = false>(leaf: {
+export declare function buildLowProfileLeaf<const M extends HttpMethod, const Path extends string, const Node extends NodeCfg | undefined = undefined, const O extends ZodType | undefined = undefined, const P extends ZodType | undefined = undefined, const Q extends ZodType | undefined = undefined, const B extends ZodType | undefined = undefined, const FO extends ZodType | undefined = undefined, const FQ extends ZodType | undefined = undefined, const Feed extends boolean = false>(leaf: {
     method: M;
     path: Path;
+    node?: Node;
     cfg: Omit<MethodCfg, 'bodySchema' | 'querySchema' | 'paramsSchema' | 'outputSchema' | 'feed' | 'outputMetaSchema' | 'queryExtensionSchema'> & {
         feed?: Feed;
         bodySchema?: B;
@@ -183,15 +227,15 @@ export declare function buildLowProfileLeaf<const M extends HttpMethod, const Pa
     bodySchema: B extends ZodType<infer BOut, infer BIn> ? RouteSchema<BOut, BIn> : undefined;
     querySchema: Feed extends true ? FeedQueryField<{
         querySchema: Q;
-        queryExtensionSchema: FQ;
+        queryExtensionSchema: EffectiveQueryExtensionSchema<FQ, Node>;
     }>['querySchema'] extends ZodType<infer QOut, infer QIn> ? RouteSchema<QOut, QIn> : never : Q extends ZodType<infer QOut, infer QIn> ? RouteSchema<QOut, QIn> : undefined;
     paramsSchema: P extends ZodType<infer POut, infer PIn> ? RouteSchema<POut, PIn> : undefined;
     outputSchema: OutputField<{
         outputSchema: O;
-        outputMetaSchema: FO;
+        outputMetaSchema: EffectiveOutputMetaSchema<FO, Node>;
     }>['outputSchema'] extends ZodType<infer OOut, infer OIn> ? RouteSchema<OOut, OIn> : never;
-    outputMetaSchema: FO extends ZodType<infer OOut, infer OIn> ? RouteSchema<OOut, OIn> : undefined;
-    queryExtensionSchema: FQ extends ZodType<infer QOut, infer QIn> ? RouteSchema<QOut, QIn> : undefined;
+    outputMetaSchema: EffectiveOutputMetaSchema<FO, Node> extends ZodType<infer OOut, infer OIn> ? RouteSchema<OOut, OIn> : undefined;
+    queryExtensionSchema: EffectiveQueryExtensionSchema<FQ, Node> extends ZodType<infer QOut, infer QIn> ? RouteSchema<QOut, QIn> : undefined;
 }>>;
 export type LeafLowProfile<M extends HttpMethod = HttpMethod, P extends string = string, C extends MethodCfgLowProfile = MethodCfgLowProfile> = {
     /** Lowercase HTTP method (get/post/...). */
@@ -208,7 +252,16 @@ export type InferQuery<L extends AnyLeafLowProfile, Fallback = never> = L['cfg']
 /** Infer request body shape from a Zod schema when present. */
 export type InferBody<L extends AnyLeafLowProfile, Fallback = never> = L['cfg']['bodySchema'] extends RouteSchema<any, infer BIn> ? BIn : L['cfg']['bodySchema'] extends ZodType<any, infer BIn> ? BIn : Fallback;
 /** Infer handler output shape from a Zod schema. Defaults to unknown. */
-export type InferOutput<L extends AnyLeafLowProfile, Fallback = never> = L['cfg']['outputSchema'] extends RouteSchema<infer O> ? O : L['cfg']['outputSchema'] extends ZodType<infer O> ? O : Fallback;
+type InferMetaFromCfg<L extends AnyLeafLowProfile> = L['cfg']['outputMetaSchema'] extends RouteSchema<infer O> ? O : L['cfg']['outputMetaSchema'] extends ZodType<infer O> ? O : string | undefined;
+type ResolvedMeta<L extends AnyLeafLowProfile, M> = [M] extends [never] | [unknown] ? InferMetaFromCfg<L> : M;
+type ApplyMetaFallback<L extends AnyLeafLowProfile, O> = O extends {
+    meta: infer M;
+} ? (undefined extends ResolvedMeta<L, M> ? {
+    meta?: ResolvedMeta<L, M>;
+} : {
+    meta: ResolvedMeta<L, M>;
+}) & Omit<O, 'meta'> : O;
+export type InferOutput<L extends AnyLeafLowProfile, Fallback = never> = L['cfg']['outputSchema'] extends RouteSchema<infer O> ? ApplyMetaFallback<L, O> : L['cfg']['outputSchema'] extends ZodType<infer O> ? ApplyMetaFallback<L, O> : Fallback;
 export type InferFeedOutputMeta<L extends AnyLeafLowProfile, Fallback = never> = L['cfg']['outputMetaSchema'] extends RouteSchema<infer O> ? O : L['cfg']['outputMetaSchema'] extends ZodType<infer O> ? O : Fallback;
 export type InferFeedQuery<L extends AnyLeafLowProfile, Fallback = never> = L['cfg']['queryExtensionSchema'] extends RouteSchema<any, infer QIn> ? QIn : L['cfg']['queryExtensionSchema'] extends ZodType<any, infer QIn> ? QIn : Fallback;
 /** Render a type as if it were a simple object literal. */

package/dist/index.cjs

@@ -87,25 +87,31 @@ function compilePath(path, params) {
   });
 }
 function buildCacheKey(args) {
-  let p = args.leaf.path;
-  if (args.params) {
-    p = compilePath(p, args.params);
+  const segments = args.leaf.path.split("/").filter(Boolean);
+  const keyParts = [args.leaf.method];
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      const value = args.params && paramName in args.params ? args.params[paramName] : void 0;
+      keyParts.push([value]);
+      continue;
+    }
+    keyParts.push(segment);
   }
-  return [
-    args.leaf.method,
-    ...p.split("/").filter(Boolean),
-    args.query ?? {}
-  ];
+  keyParts.push(args.query ?? {});
+  return keyParts;
 }
 function buildLowProfileLeaf(leaf) {
-  const effectiveQuerySchema = leaf.cfg.feed === true ? mergeSchemas(leaf.cfg.querySchema, leaf.cfg.queryExtensionSchema) : leaf.cfg.querySchema;
-  const effectiveOutputSchema = leaf.cfg.outputSchema ? import_zod.z.object({
-    out: leaf.cfg.outputSchema,
-    meta: leaf.cfg.outputMetaSchema ?? import_zod.z.string().optional()
+  const nodeCfg = leaf.node ?? {};
+  const mergedCfg = { ...nodeCfg, ...leaf.cfg };
+  const effectiveQuerySchema = mergedCfg.feed === true ? mergeSchemas(mergedCfg.querySchema, mergedCfg.queryExtensionSchema) : mergedCfg.querySchema;
+  const effectiveOutputSchema = mergedCfg.outputSchema ? import_zod.z.object({
+    out: mergedCfg.outputSchema,
+    meta: mergedCfg.outputMetaSchema ?? import_zod.z.string().optional()
   }) : import_zod.z.object({
-    meta: leaf.cfg.outputMetaSchema ?? import_zod.z.string().optional()
+    meta: mergedCfg.outputMetaSchema ?? import_zod.z.string().optional()
   });
-  if (leaf.cfg.feed === true && effectiveQuerySchema instanceof import_zod.ZodObject) {
+  if (mergedCfg.feed === true && effectiveQuerySchema instanceof import_zod.ZodObject) {
     const shape = getZodShape(effectiveQuerySchema);
     const nestedFieldSuggestions = collectNestedFieldSuggestions(shape);
     if (nestedFieldSuggestions.length > 0) {
@@ -117,41 +123,41 @@ function buildLowProfileLeaf(leaf) {
     }
   }
   return {
-    ...leaf,
+    method: leaf.method,
+    path: leaf.path,
     cfg: {
-      ...leaf.cfg,
-      bodySchema: leaf.cfg.bodySchema,
+      ...mergedCfg,
+      bodySchema: mergedCfg.bodySchema,
       querySchema: effectiveQuerySchema,
-      paramsSchema: leaf.cfg.paramsSchema,
+      paramsSchema: mergedCfg.paramsSchema,
       outputSchema: effectiveOutputSchema,
-      outputMetaSchema: leaf.cfg.outputMetaSchema,
-      queryExtensionSchema: leaf.cfg.queryExtensionSchema
+      outputMetaSchema: mergedCfg.outputMetaSchema,
+      queryExtensionSchema: mergedCfg.queryExtensionSchema
     }
   };
 }
 
 // src/core/routesV3.builder.ts
-function resource(base, inherited) {
-  const rootBase = base ?? "";
-  const rootInherited = { ...inherited };
+function resource(base, inherited, idSchema) {
+  const rawBase = base ?? "";
+  const normalizedBase = normalizeBaseSegment(
+    rawBase,
+    Boolean(idSchema)
+  );
+  const rootInherited = inherited === void 0 ? {} : { ...inherited };
+  const rootParams = createParamSchema(rawBase, idSchema);
   function makeBranch(base2, inherited2, mergedParamsSchema) {
     const stack = [];
-    let currentBase = base2;
-    let inheritedCfg = { ...inherited2 };
+    const currentBase = base2;
+    const inheritedCfg = inherited2;
     let currentParamsSchema = mergedParamsSchema;
     function add(method, cfg) {
       const effectiveParamsSchema = cfg.paramsSchema ?? currentParamsSchema;
-      const fullCfg = effectiveParamsSchema ? {
-        ...inheritedCfg,
-        ...cfg,
-        paramsSchema: effectiveParamsSchema
-      } : {
-        ...inheritedCfg,
-        ...cfg
-      };
+      const fullCfg = effectiveParamsSchema ? { ...cfg, paramsSchema: effectiveParamsSchema } : { ...cfg };
       const leaf = buildLowProfileLeaf({
         method,
         path: currentBase,
+        node: inheritedCfg,
         cfg: fullCfg
       });
       stack.push(leaf);
@@ -159,88 +165,42 @@ function resource(base, inherited) {
     }
     const api = {
       /**
-       * Mount a subtree built elsewhere.
-       *
+       * Mount one or more subtrees built elsewhere.
        * Usage:
-       *   const users = resource('').get(...).done()
-       *   resource('/api').sub('users', users).done()
+       *   resource('/api').sub(
+       *     resource('users').get(...).done(),
+       *     resource('projects').get(...).done()
+       *   )
        */
-      sub(name, cfgOrLeaves, maybeLeaves) {
-        let cfg;
-        let leaves;
-        if (Array.isArray(cfgOrLeaves)) {
-          leaves = cfgOrLeaves;
-        } else {
-          cfg = cfgOrLeaves;
-          leaves = maybeLeaves;
-        }
-        if (!leaves) {
-          throw new Error("sub() expects a leaves array as the last argument");
-        }
-        const childInherited = {
-          ...inheritedCfg,
-          ...cfg ?? {}
-        };
-        const baseForChildren = `${currentBase}/${name}`;
-        for (const leafLow of leaves) {
-          const leaf = leafLow;
-          const leafCfg = leaf.cfg;
-          const leafParams = leafCfg.paramsSchema;
-          const effectiveParams = mergeSchemas(
-            currentParamsSchema,
-            leafParams
-          );
-          const newCfg = {
-            ...childInherited,
-            ...leafCfg
-          };
-          if (effectiveParams) {
-            newCfg.paramsSchema = effectiveParams;
-          } else if ("paramsSchema" in newCfg) {
-            delete newCfg.paramsSchema;
-          }
-          const newLeaf = {
-            method: leaf.method,
-            path: `${baseForChildren}${leaf.path}`,
-            cfg: newCfg
-          };
-          stack.push(newLeaf);
+      sub(...collections) {
+        if (collections.length === 0) {
+          throw new Error("sub() expects at least one resource");
         }
-        return api;
-      },
-      /**
-       * Introduce a :param segment and mount a subtree under it.
-       *
-       * The subtree is built independently (e.g. resource('').get(...).done())
-       * and its paths become `${currentBase}/:${name}${leaf.path}`.
-       * Params schemas are intersected with the accumulated params plus the new param.
-       */
-      subId(name, paramsSchema, leaves) {
-        const paramObj = import_zod2.z.object({
-          [name]: paramsSchema
-        });
-        const mergedParams = currentParamsSchema ? mergeSchemas(currentParamsSchema, paramObj) : paramObj;
-        const baseForChildren = `${currentBase}/:${name}`;
-        for (const leafLow of leaves) {
-          const leaf = leafLow;
-          const leafCfg = leaf.cfg;
-          const leafParams = leafCfg.paramsSchema;
-          const effectiveParams = mergeSchemas(mergedParams, leafParams);
-          const newCfg = {
-            ...inheritedCfg,
-            ...leafCfg
-          };
-          if (effectiveParams) {
-            newCfg.paramsSchema = effectiveParams;
-          } else if ("paramsSchema" in newCfg) {
-            delete newCfg.paramsSchema;
+        for (const leaves of collections) {
+          for (const leafLow of leaves) {
+            const leaf = leafLow;
+            const leafCfg = leaf.cfg;
+            const leafParams = leafCfg.paramsSchema;
+            const effectiveParams = mergeSchemas(
+              currentParamsSchema,
+              leafParams
+            );
+            const newCfg = {
+              ...inheritedCfg,
+              ...leafCfg
+            };
+            if (effectiveParams) {
+              newCfg.paramsSchema = effectiveParams;
+            } else if ("paramsSchema" in newCfg) {
+              delete newCfg.paramsSchema;
+            }
+            const newLeaf = {
+              method: leaf.method,
+              path: joinPaths(currentBase, leaf.path),
+              cfg: newCfg
+            };
+            stack.push(newLeaf);
           }
-          const newLeaf = {
-            method: leaf.method,
-            path: `${baseForChildren}${leaf.path}`,
-            cfg: newCfg
-          };
-          stack.push(newLeaf);
         }
         return api;
       },
@@ -266,11 +226,47 @@ function resource(base, inherited) {
     };
     return api;
   }
-  return makeBranch(rootBase, rootInherited, void 0);
+  return makeBranch(normalizedBase, rootInherited, rootParams);
 }
 var mergeArrays = (arr1, arr2) => {
   return [...arr1, ...arr2];
 };
+function normalizeBaseSegment(base, hasParam) {
+  const value = base ?? "";
+  if (!hasParam) return value;
+  if (!value) {
+    throw new Error("resource() requires a segment name when defining an id schema");
+  }
+  if (value.includes("/")) {
+    const segments = value.split("/").filter(Boolean);
+    if (segments.length === 0) {
+      throw new Error("resource() received an invalid segment for param injection");
+    }
+    const lastIndex = segments.length - 1;
+    const last = segments[lastIndex];
+    segments[lastIndex] = last.startsWith(":") ? last : `:${last}`;
+    return `${value.startsWith("/") ? "/" : ""}${segments.join("/")}`;
+  }
+  return value.startsWith(":") ? value : `:${value}`;
+}
+function createParamSchema(nameSegment, schema) {
+  if (!schema) return void 0;
+  const segments = nameSegment.split("/").filter(Boolean);
+  const rawName = segments.length > 0 ? segments[segments.length - 1] : nameSegment;
+  const normalized = rawName.startsWith(":") ? rawName.slice(1) : rawName;
+  if (!normalized) {
+    throw new Error("resource() requires a non-empty name for id schema");
+  }
+  return import_zod2.z.object({ [normalized]: schema });
+}
+function joinPaths(parent, child) {
+  if (!parent) return child;
+  if (!child) return parent;
+  const trimmedParent = parent.endsWith("/") ? parent.replace(/\/+$/, "") : parent;
+  const trimmedChild = child.startsWith("/") ? child.replace(/^\/+/, "") : child;
+  if (!trimmedChild) return trimmedParent;
+  return `${trimmedParent}/${trimmedChild}`;
+}
 
 // src/core/routesV3.finalize.ts
 function finalize(leaves) {