Merge pull request #2728 from atscott/feat/typed-routing-resource-inheritance

Feat/typed routing resource inheritance

Author: brandonroberts

apps/docs-analog/src/content/features/routing/typed-routes.md

@@ -118,9 +118,15 @@ Type checking comes from the generated table. The `experimental.typedRouting` op
 
 ```ts
 // src/app/pages/products.page.ts (layout)
+import { resource } from '@angular/core';
 import type { RouteMeta } from '@analogjs/router';
 
-export const routeMeta = { data: { section: 'catalog' } } satisfies RouteMeta;
+export const routeMeta = {
+  data: { section: 'catalog' },
+  resources: () => ({
+    catalog: resource({ loader: async () => fetchCatalog() }),
+  }),
+} satisfies RouteMeta;
 ```
 
 ```ts
@@ -129,8 +135,10 @@ import { Component, inject } from '@angular/core';
 import { injectRouteData, type RouteMeta } from '@analogjs/router';
 
 export const routeMeta = {
-  resolve: { related: () => inject(ProductsService).related() },
-} satisfies RouteMeta;
+  resolve: {
+    related: (route) => inject(ProductsService).related(route.params.id),
+  },
+} satisfies RouteMeta<'/products/[id]'>;
 
 @Component({ template: `{{ data().section }}` })
 export default class ProductPage {
@@ -139,7 +147,7 @@ export default class ProductPage {
 }
 ```
 
-Use `satisfies RouteMeta` instead of a `RouteMeta` annotation. An annotation widens the object, so data values are typed as `unknown`.
+Use `satisfies RouteMeta` (or `satisfies RouteMeta<'/products/[id]'>` to also type `route.params`, `route.queryParams`, and inherited layout `route.data` inside resolvers) instead of a `RouteMeta` annotation. An annotation widens the object, so data values are typed as `unknown`.
 
 `injectLoad` also accepts a route path. The result is typed from the page's `.server.ts` `load` function, so the page does not need to import it:
 
@@ -153,17 +161,33 @@ As with Angular's route data inheritance, a page's keys override the same keys f
 
 ## Access route resources
 
-On Angular 22.2+, when using `withRouterResources()`, `injectResources` returns the reactive resources defined on the route via `routeMeta.resources`:
+On Angular 22.2+, when using `withRouterResources()`, `injectResources` returns the reactive resources defined on the route via `routeMeta.resources` (and on Angular 22.3+, resources inherited from ancestor [layout routes](/docs/features/routing/overview#layout-routes) as well). As with route data, a child route's resource keys override matching keys from its layouts.
+
+Pass the route path to `RouteMeta` to type `ctx.params`, `ctx.queryParams`, `ctx.data`, and inherited ancestor `ctx.resources` inside `routeMeta.resources`:
 
 ```ts
-import { injectResources } from '@analogjs/router';
+// src/app/pages/products/[id].page.ts
+import { resource } from '@angular/core';
+import { injectResources, type RouteMeta } from '@analogjs/router';
+
+export const routeMeta = {
+  resources: (ctx) => ({
+    product: resource({
+      params: () => ({
+        id: ctx.params().id,
+        catalog: ctx.resources().catalog.value(),
+      }),
+      loader: async ({ params }) => fetchProduct(params.id, params.catalog),
+    }),
+  }),
+} satisfies RouteMeta<'/products/[id]'>;
 
 const resources = injectResources('/products/[id]');
-// resources.user is a typed Resource instance
-const user = resources.user.value();
+// resources.product and inherited resources.catalog are typed Resource instances
+const product = resources.product.value();
 ```
 
-Calling `injectResources()` without a route path returns untyped route resources. On older Angular versions without router resources, it returns an empty object. The other typed-routing helpers do not require router resources.
+Calling `injectResources()` without a route path returns untyped route resources. On older Angular versions without router resources, it returns an empty object. Shared URLs have no typed resource keys, matching `injectRouteData`. The other typed-routing helpers do not require router resources.
 
 ## Navigate relative to the current route
 

apps/typed-router-app/src/app/pages/orgs/[orgId].page.ts

@@ -1,12 +1,18 @@
 import { injectRouteData, LinkTo, type RouteMeta } from '@analogjs/router';
-import { Component } from '@angular/core';
+import { Component, resource } from '@angular/core';
 import { RouterLinkActive, RouterOutlet } from '@angular/router';
 
 import { findOrg } from '../../data';
 
 export const routeMeta = {
-  resolve: { org: (route) => findOrg(route.paramMap.get('orgId')) },
-} satisfies RouteMeta;
+  resolve: { org: (route) => findOrg(route.params.orgId) },
+  resources: (ctx) => ({
+    orgResource: resource({
+      params: ctx.params,
+      loader: async ({ params }) => findOrg(params.orgId),
+    }),
+  }),
+} satisfies RouteMeta<'/orgs/[orgId]'>;
 
 @Component({
   imports: [LinkTo, RouterLinkActive, RouterOutlet],

apps/typed-router-app/src/app/pages/orgs/[orgId]/teams/[teamId].page.ts

@@ -1,5 +1,5 @@
 import { injectRouteData, LinkTo, type RouteMeta } from '@analogjs/router';
-import { Component } from '@angular/core';
+import { Component, resource } from '@angular/core';
 import { RouterOutlet } from '@angular/router';
 import { of } from 'rxjs';
 
@@ -8,10 +8,15 @@ import { findTeam } from '../../../../data';
 export const routeMeta = {
   data: { area: 'team' },
   resolve: {
-    team: (route) =>
-      of(findTeam(route.paramMap.get('orgId'), route.paramMap.get('teamId'))),
+    team: (route) => of(findTeam(route.params.orgId, route.params.teamId)),
   },
-} satisfies RouteMeta;
+  resources: (ctx) => ({
+    teamResource: resource({
+      params: ctx.params,
+      loader: async ({ params }) => findTeam(params.orgId, params.teamId),
+    }),
+  }),
+} satisfies RouteMeta<'/orgs/[orgId]/teams/[teamId]'>;
 
 @Component({
   imports: [LinkTo, RouterOutlet],

apps/typed-router-app/src/app/pages/users.page.ts

@@ -1,5 +1,5 @@
 import type { RouteMeta } from '@analogjs/router';
-import { Component } from '@angular/core';
+import { Component, resource } from '@angular/core';
 import { RouterOutlet } from '@angular/router';
 import { of } from 'rxjs';
 
@@ -10,6 +10,11 @@ export const routeMeta = {
   resolve: {
     directory: () => of(USERS.map(({ id, name }) => ({ id, name }))),
   },
+  resources: () => ({
+    directoryResource: resource({
+      loader: async () => USERS.map(({ id, name }) => ({ id, name })),
+    }),
+  }),
 } satisfies RouteMeta;
 
 @Component({

apps/typed-router-app/src/app/pages/users/[userId].page.ts

@@ -15,15 +15,15 @@ import { findUser } from '../../data';
 
 export const routeMeta = {
   resolve: {
-    profile: async (route) => findUser(route.paramMap.get('userId')),
+    profile: async (route) => findUser(route.params.userId),
   },
   resources: (ctx) => ({
     userResource: resource({
       params: ctx.params,
-      loader: async ({ params }) => findUser(params['userId']),
+      loader: async ({ params }) => findUser(params.userId),
     }),
   }),
-} satisfies RouteMeta;
+} satisfies RouteMeta<'/users/[userId]'>;
 
 @Component({
   imports: [LinkTo],

apps/typed-router-app/src/app/route-type-assertions.ts

@@ -9,9 +9,10 @@ import {
   toRoute,
   type LinkToInput,
   type RouteDataOutput,
+  type RouteMeta,
   type RouteResourcesOutput,
 } from '@analogjs/router';
-import type { ResourceRef } from '@angular/core';
+import { resource, type ResourceRef } from '@angular/core';
 
 import type { Org, Team, User } from './data';
 
@@ -128,21 +129,78 @@ export function routeTypeAssertions() {
   const anyData: Record<string, unknown> = injectRouteData()();
   const anyResources = injectResources();
   const anyRouteResources = injectRouteResources();
+  const anyResourceValue: unknown = anyResources['user']?.value();
+  const anyResourceReload: (() => boolean) | undefined =
+    anyRouteResources['user']?.reload;
+  void [anyResourceValue, anyResourceReload];
+  // @ts-expect-error untyped resources entries are Resource instances, not strings
+  const invalidAnyResource: string = anyResources['user'];
   // @ts-expect-error untyped values may be missing
   const anyUserId: string = injectParams()()['userId'];
 
-  // Route resources
+  // Route resources (including multi-level layout inheritance and context)
   const userResources: RouteResourcesOutput<'/users/[userId]'> =
     injectResources('/users/[userId]');
   const userResourceRef: ResourceRef<User | undefined> =
     userResources.userResource;
+  const inheritedDirectoryRef: ResourceRef<
+    { id: string; name: string }[] | undefined
+  > = userResources.directoryResource;
   const userName: string | undefined = userResources.userResource.value()?.name;
   // @ts-expect-error unknown resource name
   userResources.missing;
+  // @ts-expect-error dot notation is not wrapped by users.page.ts
+  void injectResources('/users/[userId]/posts/[postId]').directoryResource;
+  // @ts-expect-error users.page.ts and users/index.page.ts share /users
+  void injectResources('/users').directoryResource;
   const aliasedResources = injectRouteResources('/users/[userId]');
   const aliasedRef: ResourceRef<User | undefined> =
     aliasedResources.userResource;
 
+  const memberListResources = injectResources(
+    '/orgs/[orgId]/teams/[teamId]/members',
+  );
+  const listOrgRef: ResourceRef<Org | undefined> =
+    memberListResources.orgResource;
+  const listTeamRef: ResourceRef<Team | undefined> =
+    memberListResources.teamResource;
+
+  const memberResources: RouteResourcesOutput<typeof MEMBER> =
+    injectResources(MEMBER);
+  const memberOrgRef: ResourceRef<Org | undefined> =
+    memberResources.orgResource;
+  const memberTeamRef: ResourceRef<Team | undefined> =
+    memberResources.teamResource;
+
+  const memberMetaCheck = {
+    resolve: {
+      check: (route) => ({
+        memberId: route.params.memberId,
+        orgName: route.data.org?.name,
+        teamName: route.data.team?.name,
+      }),
+    },
+    resources: (ctx) => ({
+      memberSummary: resource({
+        params: () => ({
+          memberId: ctx.params().memberId,
+          org: ctx.resources().orgResource.value(),
+          team: ctx.resources().teamResource.value(),
+          projects: ctx.data().load.projects,
+        }),
+        loader: async ({ params }) => params,
+      }),
+    }),
+  } satisfies RouteMeta<typeof MEMBER>;
+  void [
+    inheritedDirectoryRef,
+    listOrgRef,
+    listTeamRef,
+    memberOrgRef,
+    memberTeamRef,
+    memberMetaCheck,
+  ];
+
   // LinkTo inputs
   const links: LinkToInput<'/users/[userId]'>[] = [
     '..',