angular-typed-router 0.1.1-2 → 0.1.1-3

package/README.md

@@ -7,6 +7,7 @@ Type-safe ergonomic primitives on top of Angular's standalone router. Automatica
 ## Why
 
 Angular's router is powerful but untyped for URL literals – a misspelled path or an outdated segment only fails at runtime. This library lets your application declare routes once, then:
+
 - Navigate with `TypedRouter.navigateByUrl(path)` where `path` is validated at compile time.
 - Use `<a routerLink="...">` with type checking via an augmented `TypedRouterLink` directive.
 - Build command tuples with correct literal segments (`Commands` type).
@@ -15,6 +16,10 @@ No decorators, no custom builders, no code generation – just TypeScript type i
 
 ## Installation
 
+`ng add angular-ryped-router` will set up the package and create a declaration file for you.
+
+Or install manually:
+
 ```bash
 npm install angular-typed-router
 # or
@@ -34,24 +39,24 @@ import { DashboardComponent } from './dashboard.component';
 
 export const appRoutes = [
   { path: 'dashboard', component: DashboardComponent },
-  { path: 'projects/:id', loadComponent: () => import('./project.component').then(m => m.ProjectComponent) },
-  { path: '**', redirectTo: 'dashboard' }
+  { path: 'projects/:id', loadComponent: () => import('./project.component').then((m) => m.ProjectComponent) },
+  { path: '**', redirectTo: 'dashboard' },
 ] as const satisfies Routes;
 ```
 
 2. Create the augmentation file so the library can “see” your routes:
 
 ```ts
-// angular-typed-router.d.ts (sibling to main.ts or inside src/ root)
+// typed-router.d.ts (sibling to main.ts or inside src/ root)
 import type { appRoutes } from './app/app.routes';
 
 declare module 'angular-typed-router' {
   interface UserTypedRoutes {
     routes: typeof appRoutes;
   }
-  // Customize route param types here
-  interface AllowedRouteParamValues {
-    ids: `${number}`;
+  // Customize route param types here, the keys of this interface match your route param names
+  interface RouteParamTypes {
+    id: `${number}`;
     // other params...
   }
 }
@@ -63,13 +68,14 @@ declare module 'angular-typed-router' {
 // tsconfig.app.json
 {
   "extends": "./tsconfig.json",
-  "compilerOptions": { },
+  "compilerOptions": {},
   "include": [
     "src/**/*.ts",
-    "angular-typed-router.d.ts" // <— add this line
+    "typed-router.d.ts" // <— add this line
   ]
 }
 ```
+
 If you have multiple tsconfigs, ensure the specific app tsconfig that drives the build/test includes the file.
 
 4. Use the typed router & link:
@@ -83,12 +89,13 @@ import { TypedRouter, Path } from 'angular-typed-router';
   template: `
     <a routerLink="dashboard">Dashboard</a>
     <a routerLink="projects/123">Project 123</a>
-  `
+  `,
 })
 export class NavComponent {
   private readonly router = inject(TypedRouter);
 
-  go(p: Path) { // p must be one of the inferred paths
+  go(p: Path) {
+    // p must be one of the inferred paths
     this.router.navigateByUrl(p);
   }
 
@@ -104,7 +111,7 @@ If you try `this.router.navigateByUrl('projcts/123')` (typo) or `<a routerLink="
 ## Exports
 
 ```ts
-import { TypedRouter, TypedRouterLink, Path, Commands, UserTypedRoutes } from 'angular-typed-router';
+import { TypedRouter, TypedRouterLink, Path, Commands, UserTypedRoutes, RouteParamTypes } from 'angular-typed-router';
 ```
 
 - `TypedRouter` – Extends Angular `Router`, overrides `navigateByUrl` & `navigate` signatures to accept `Path` / `Commands`.
@@ -113,6 +120,7 @@ import { TypedRouter, TypedRouterLink, Path, Commands, UserTypedRoutes } from 'a
 - `Commands` – Union of tuple command arrays representing valid `Router.navigate()` inputs (each static segment as a literal, each parameter position as `string`).
 - `UserTypedRoutes` – Empty interface you augment with your `routes` reference.
 - `ExtractPathsFromRoutes<Routes>` – Utility type if you need to compute from an arbitrary `Routes` array manually.
+- `RouteParamTypes` – Interface you can augment to specify types for route parameters by name (e.g. `id: ${number}`).
 
 ## How It Works
 
@@ -127,6 +135,7 @@ All compile-time only; nothing ships to runtime.
 ## Lazy Routes
 
 Works with any lazy route whose `loadChildren` resolves to:
+
 - `Promise<Route[]>`
 - `Promise<{ routes: Route[] }>` (Angular v17+ pattern)
 
@@ -141,59 +150,68 @@ Those child paths get prefixed (`admin/...`) in `Path` & `Commands`.
 ## Parameter Segments
 
 A pattern `projects/:id/details/:section` produces a `Path` variant like:
+
 ```
-'projects/' + string + '/details/' + string
+'projects/' + IdParamType + '/details/' + SectionParamType
 ```
+
 and a `Commands` tuple like:
+
 ```
-['projects', string, 'details', string]
+['projects', IdParamType, 'details', SectionParamType]
 ```
-You pass real runtime values for the `string` positions. Empty string values and values like 'param/still-param' cannot currently be prevented at the type level without hurting DX (see Limitations).
+
+You pass real runtime values for the `IdParamType` and `SectionParamType` positions. Empty string values and values like 'param/still-param' cannot currently be prevented at the type level without hurting DX (see Limitations).
 
 ## Usage Patterns
 
 Navigate by full path (typed):
+
 ```ts
 router.navigateByUrl('/dashboard');
 ```
+
 Navigate with commands array:
+
 ```ts
 router.navigate(['/', 'projects', someId]);
 ```
+
 Generate a `UrlTree`:
+
 ```ts
 router.createUrlTree(['/', 'projects', id]);
 ```
+
 Template links:
+
 ```html
-<a routerLink="/projects/42">Project 42</a>
-<a [routerLink]="['/', 'projects', projectId]"></a>
+<a routerLink="/projects/42">Project 42</a> <a [routerLink]="['/', 'projects', projectId]"></a>
 ```
 
-
 ## Augmentation Placement
 
 Keep the augmentation in a `.d.ts` that is included by `tsconfig.app.json` (`include` array). If you see `Path` still as `never`, ensure:
+
 - The augmentation file is included.
 - The `routes` constant is `as const satisfies Routes`.
 - No circular import (augmentation file should only import the routes, nothing else runtime-heavy).
 
 ## Limitations & Tradeoffs
 
-| Concern | Status / Rationale                                                                    |
-|---------|---------------------------------------------------------------------------------------|
+| Concern                            | Status / Rationale                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------- |
 | `relativeTo` (relative navigation) | Not supported – all inferred `Path` / `Commands` are absolute. Use absolute commands. |
 
-
 ## ESLint Recommendation (Optional)
 
 You can use `angular-typed-router-eslint` plugin to forbid untyped navigation calls.
 
 ## Troubleshooting
 
-| Symptom | Fix |
-|---------|-----|
-| `Path` is `never` | Check augmentation file is included in tsconfig. |
+| Symptom               | Fix                                                            |
+| --------------------- | -------------------------------------------------------------- |
+| `Path` is `never`     | Check augmentation file is included in tsconfig.               |
 | Lazy children missing | Ensure promise resolves to `Route[]` or `{ routes: Route[] }`. |
 
 ## Contributing
@@ -205,4 +223,5 @@ PRs welcome.
 MIT
 
 ---
+
 Happy routing.

package/index.d.ts

@@ -16,10 +16,10 @@ declare const __rootCatchAll: unique symbol;
 type RootCatchAll = string & {
     readonly [__rootCatchAll]: true;
 };
-interface AllowedRouteParamValues {
+interface RouteParamTypes {
 }
-type AllowedRouteParamValue = AllowedRouteParamValues[keyof AllowedRouteParamValues];
-type _ReplaceParams<S extends string> = S extends `${infer Start}:${string}/${infer Rest}` ? `${Start}${AllowedRouteParamValue}/${_ReplaceParams<Rest>}` : S extends `${infer Start}:${string}` ? `${Start}${AllowedRouteParamValue}` : S extends `${infer Start}**/${infer Rest}` ? `${Start}${string}/${_ReplaceParams<Rest>}` : S extends `${infer Start}**` ? Start extends '' ? RootCatchAll : `${Start}${string}` : S;
+type ParamValueType<Name extends string> = Name extends keyof RouteParamTypes ? RouteParamTypes[Name] : never;
+type _ReplaceParams<S extends string> = S extends `${infer Start}:${infer Param}/${infer Rest}` ? `${Start}${ParamValueType<Param>}/${_ReplaceParams<Rest>}` : S extends `${infer Start}:${infer Param}` ? `${Start}${ParamValueType<Param>}` : S extends `${infer Start}**/${infer Rest}` ? `${Start}${string}/${_ReplaceParams<Rest>}` : S extends `${infer Start}**` ? Start extends '' ? RootCatchAll : `${Start}${string}` : S;
 type ReplaceParams<S extends string> = _ReplaceParams<S>;
 
 type PathOrEmptyString<R extends Route> = R['path'] extends string ? R['path'] : '';
@@ -65,4 +65,4 @@ declare class TypedRouterLink extends RouterLink {
 }
 
 export { TypedRouter, TypedRouterLink };
-export type { AllowedRouteParamValues, Commands, ExtractPathsFromRoutes, Path, UserTypedRoutes };
+export type { Commands, ExtractPathsFromRoutes, Path, RouteParamTypes, UserTypedRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "angular-typed-router",
-  "version": "0.1.1-2",
+  "version": "0.1.1-3",
   "peerDependencies": {
     "@angular/common": "^20.0.0",
     "@angular/core": "^20.0.0"

package/schematics/ng-add/steps/add-declaration-file.js

@@ -21,7 +21,7 @@ const addDeclarationFile = (options) => (host, context) => __awaiter(void 0, voi
     if (project &&
         project.extensions['projectType'] === workspace_models_1.ProjectType.Application) {
         const projectRoot = project.root;
-        const augmentationFileName = 'angular-typed-router.d.ts';
+        const augmentationFileName = 'typed-router.d.ts';
         const declarationFilePath = (0, path_1.join)(projectRoot, augmentationFileName);
         // TODO: Check if app.routes.ts exists and if it has the correct export
         const augmentationFileContent = `import type { routes } from './src/app/app.routes';
@@ -30,7 +30,7 @@ declare module 'angular-typed-router' {
   interface UserTypedRoutes {
     routes: typeof routes;
   }
-  interface AllowedRouteParamValues {
+  interface RouteParamTypes {
 
   }
 }

package/schematics/ng-add/steps/add-declaration-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-declaration-file.js","sourceRoot":"","sources":["../../../../../../libs/typed-router/schematics/ng-add/steps/add-declaration-file.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,yDAA4D;AAC5D,mFAA2E;AAC3E,+BAA+C;AAC/C,qEAAiE;AAE1D,MAAM,kBAAkB,GAC7B,CAAC,OAAe,EAAE,EAAE,CAAC,CAAO,IAAU,EAAE,OAAyB,EAAE,EAAE;;IACnE,MAAM,SAAS,GAAG,MAAM,IAAA,uBAAa,EAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,OAAQ,CAAC,CAAC;IACzD,IACE,OAAO;QACP,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,8BAAW,CAAC,WAAW,EAC7D,CAAC;QACD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;QACjC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;QACzD,MAAM,mBAAmB,GAAG,IAAA,WAAI,EAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;QACpE,uEAAuE;QACvE,MAAM,uBAAuB,GAAG;;;;;;;;;;CAUrC,CAAC;QACI,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;QAE1D,MAAM,aAAa,GAAG,MAAA,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,0CAAE,OAAO,0CAAE,QAAQ,CAAC;QACvE,MAAM,YAAY,GAAG,MAAA,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,0CAAE,OAAO,0CAAE,QAAQ,CAAC;QAErE,IAAI,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YACvD,4BAA4B,CAAC,IAAI,EAAE,aAAa,EAAE,mBAAmB,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrD,4BAA4B,CAAC,IAAI,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,IAAI,CACjB,YAAY,OAAO,CAAC,OAAO,uCAAuC,CACnE,CAAC;IACJ,CAAC;AACH,CAAC,CAAA,CAAC;AAvCS,QAAA,kBAAkB,sBAuC3B;AAEJ,SAAS,4BAA4B,CACnC,IAAU,EACV,YAAoB,EACpB,mBAA2B;IAE3B,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,oBAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAE9C,MAAM,YAAY,GAAI,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAc,IAAI,EAAE,CAAC;QAE/D,MAAM,YAAY,GAAG,IAAA,eAAQ,EAAC,IAAA,cAAO,EAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAE1E,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACzC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"add-declaration-file.js","sourceRoot":"","sources":["../../../../../../libs/typed-router/schematics/ng-add/steps/add-declaration-file.ts"],"names":[],"mappings":";;;;;;;;;;;;AAEA,yDAA4D;AAC5D,mFAA2E;AAC3E,+BAA+C;AAC/C,qEAAiE;AAE1D,MAAM,kBAAkB,GAC7B,CAAC,OAAe,EAAE,EAAE,CAAC,CAAO,IAAU,EAAE,OAAyB,EAAE,EAAE;;IACnE,MAAM,SAAS,GAAG,MAAM,IAAA,uBAAa,EAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,OAAQ,CAAC,CAAC;IACzD,IACE,OAAO;QACP,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,KAAK,8BAAW,CAAC,WAAW,EAC7D,CAAC;QACD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;QACjC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;QACjD,MAAM,mBAAmB,GAAG,IAAA,WAAI,EAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;QACpE,uEAAuE;QACvE,MAAM,uBAAuB,GAAG;;;;;;;;;;CAUrC,CAAC;QACI,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,uBAAuB,CAAC,CAAC;QAE1D,MAAM,aAAa,GAAG,MAAA,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,0CAAE,OAAO,0CAAE,QAAQ,CAAC;QACvE,MAAM,YAAY,GAAG,MAAA,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,0CAAE,OAAO,0CAAE,QAAQ,CAAC;QAErE,IAAI,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;YACvD,4BAA4B,CAAC,IAAI,EAAE,aAAa,EAAE,mBAAmB,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrD,4BAA4B,CAAC,IAAI,EAAE,YAAY,EAAE,mBAAmB,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,MAAM,CAAC,IAAI,CACjB,YAAY,OAAO,CAAC,OAAO,uCAAuC,CACnE,CAAC;IACJ,CAAC;AACH,CAAC,CAAA,CAAC;AAvCS,QAAA,kBAAkB,sBAuC3B;AAEJ,SAAS,4BAA4B,CACnC,IAAU,EACV,YAAoB,EACpB,mBAA2B;IAE3B,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,oBAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAE9C,MAAM,YAAY,GAAI,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAc,IAAI,EAAE,CAAC;QAE/D,MAAM,YAAY,GAAG,IAAA,eAAQ,EAAC,IAAA,cAAO,EAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAE1E,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACzC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;AACH,CAAC"}