feat: create @ngworker/router-signal-store package using NgRx Signals (#356)

Author: LayZeeDK

.github/workflows/ci.yml

@@ -97,14 +97,14 @@ jobs:
 
       - name: Build
         run: yarn build
-      - name: Bundle readme
-        run: cp README.md dist/packages/router-component-store/
 
-      - name: '[Merge] Upload package bundle'
+      - name: '[Merge] Upload package bundles'
         if: ${{ env.is-merge-to-main == 'true' }}
         uses: actions/upload-artifact@v4
         with:
           name: ngworker-router-component-store
-          path: dist/packages/router-component-store
+          path: |
+            dist/packages/router-component-store
+            dist/packages/router-signal-store
           if-no-files-found: error
           retention-days: 7

README.md

@@ -1,210 +1,205 @@
-# Router Component Store
+# ngworkers Router Store
 
-[`@ngworker/router-component-store`](https://www.npmjs.com/package/@ngworker/router-component-store)
+<img src="logo.png" alt="Router Component Store" height="384px">
 
-<img src="https://github.com/ngworker/router-component-store/blob/main/logo.png" alt="Router Component Store" height="384px">
+A monorepo containing Angular router state management packages that provide strictly typed, lightweight alternatives to NgRx Router Store (`@ngrx/router-store`) and `ActivatedRoute`.
 
-A strictly typed lightweight alternative to NgRx Router Store (`@ngrx/router-store`) and `ActivatedRoute`.
+## Packages
 
-## Compatibility
-
-Required peer dependencies:
+This repository contains two main packages:
 
-- Angular 17.x
-- NgRx Component Store 17.x
-- RxJS >=7.5
-- TypeScript >=5.2
+### [`@ngworker/router-component-store`](packages/router-component-store/README.md)
 
-Published with partial Ivy compilation.
+A Component Store-based solution using observables:
 
-Find additional documentation in the [github.com/ngworker/router-component-store/docs](https://github.com/ngworker/router-component-store/tree/main/docs) directory.
+- **Package**: [`@ngworker/router-component-store`](https://www.npmjs.com/package/@ngworker/router-component-store)
+- **Technology**: NgRx Component Store (`@ngrx/component-store`) with RxJS observables
+- **Use Case**: When you prefer observable-based reactivity patterns
 
-## Guiding principles
+```typescript
+// Observable-based API
+export class HeroService {
+  #routerStore = inject(RouterStore);
 
-Router Component Store is meant as a lightweight alternative to NgRx Router Store that additionaly can be used as a replacement for `ActivatedRoute` at any route level.
+  url$ = this.#routerStore.url$; // Observable<string>
+  searchTerm$ = this.#routerStore.selectQueryParam('q'); // Observable<string | undefined>
+}
+```
 
-The following principles guide the development of Router Component Store.
+### [`@ngworker/router-signal-store`](packages/router-signal-store/README.md)
 
-- The global router store closely matches NgRx Router Store selectors
-- Local router stores closely match `ActivatedRoute` observable properties
-- Router state is immutable and serializable
-- The API is strictly and strongly typed
+A Signal Store-based solution using Angular Signals:
 
-## API
+- **Package**: [`@ngworker/router-signal-store`](https://www.npmjs.com/package/@ngworker/router-signal-store)
+- **Technology**: NgRx Signals (`@ngrx/signals`) with Angular Signals
+- **Use Case**: When you prefer signal-based reactivity patterns
 
-### RouterStore
+```typescript
+// Signal-based API
+export class HeroService {
+  #routerSignalStore = inject(RouterSignalStore);
 
-A `RouterStore` service has the following public properties.
+  url = this.#routerSignalStore.url; // Signal<string>
+  searchTerm = this.#routerSignalStore.selectQueryParam('q'); // Signal<string | undefined>
+}
+```
 
-| API                                                                                     | Description                                               |
-| --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `currentRoute$: Observable<MinimalActivatedRouteSnapshot>`                              | Select the current route.                                 |
-| `fragment$: Observable<string \| null>`                                                 | Select the current route fragment.                        |
-| `queryParams$: Observable<StrictQueryParams>`                                           | Select the current route query parameters.                |
-| `routeData$: Observable<StrictRouteData>`                                               | Select the current route data.                            |
-| `routeParams$: Observable<StrictRouteParams>`                                           | Select the current route parameters.                      |
-| `title$: Observable<string \| undefined>`                                               | Select the resolved route title.                          |
-| `url$: Observable<string>`                                                              | Select the current URL.                                   |
-| `selectQueryParam(param: string): Observable<string \| readonly string[] \| undefined>` | Select the specified query parameter.                     |
-| `selectRouteDataParam(key: string): Observable<unknown>`                                | Select the specified route data.                          |
-| `selectRouteParam(param: string): Observable<string \| undefined>`                      | Select the specified route parameter.                     |
-| `selectRouterEvents(...acceptedRouterEvents: RouterEvent[]): Observable<RouterEvent>`   | Select router events of the specified router event types. |
+## Common features
 
-A `RouterStore` service is provided by using either `provideGlobalRouterStore`or `provideLocalRouterStore`.
+Both packages provide:
 
-The _global_ `RouterStore` service is provided in a root environment injector and is never destroyed but can be injected in any injection context.
+✅ **Strictly Typed**: Full TypeScript support with strict typing  
+✅ **Lightweight**: Minimal bundle size impact  
+✅ **Drop-in Replacement**: For NgRx Router Store and `ActivatedRoute`  
+✅ **Global & Local Stores**: Application-wide and component-level usage  
+✅ **Immutable State**: Router state is immutable and serializable  
+✅ **Memory Safe**: Proper subscription management and cleanup
 
-It emits values similar to `@ngrx/router-store` selectors. A comparison is in the documentation.
+## Compatibility
 
-A _local_ `RouterStore` requires a component-level provider, follows the lifecycle of that component, and can be injected in declarables as well as other component-level services.
+Both packages follow Angular's recommended release pattern for Angular libraries. One major package version for every major Angular release.
 
-It emits values similar to `ActivatedRoute`. A comparison is in the documentation.
+Features released in minor versions of Angular and NgRx packages are not used until the following major version package release to ensure compatibility across minor versions.
 
-#### Global router store
+The packages require the same peer dependencies as their corresponding Angular and NgRx packages.
 
-An application-wide router store that can be injected in any injection context. Use `provideGlobalRouterStore` to provide it in a root environment injector.
+## Quick start
 
-Use a global router store instead of NgRx Router Store.
+### Observable-based (Router Component Store)
 
-Providing in a standalone Angular application:
+```bash
+npm install @ngworker/router-component-store
+```
 
 ```typescript
-// main.ts
-// (...)
 import { provideGlobalRouterStore } from '@ngworker/router-component-store';
 
 bootstrapApplication(AppComponent, {
   providers: [provideGlobalRouterStore()],
-}).catch((error) => console.error(error));
+});
 ```
 
-Providing in a classic Angular application:
+### Signal-based (Router Signal Store)
+
+```bash
+npm install @ngworker/router-signal-store
+```
 
 ```typescript
-// app.module.ts
-// (...)
-import { provideGlobalRouterStore } from '@ngworker/router-component-store';
+import { provideGlobalRouterSignalStore } from '@ngworker/router-signal-store';
 
-@NgModule({
-  // (...)
-  providers: [provideGlobalRouterStore()],
-})
-export class AppModule {}
+bootstrapApplication(AppComponent, {
+  providers: [provideGlobalRouterSignalStore()],
+});
 ```
 
-Usage in service:
+## API comparison
 
-```typescript
-// hero.service.ts
-// (...)
-import { RouterStore } from '@ngworker/router-component-store';
+| Feature          | Router Component Store                     | Router Signal Store                        |
+| ---------------- | ------------------------------------------ | ------------------------------------------ |
+| Current Route    | `currentRoute$: Observable<...>`           | `currentRoute: Signal<...>`                |
+| Query Parameters | `queryParams$: Observable<...>`            | `queryParams: Signal<...>`                 |
+| Route Parameters | `routeParams$: Observable<...>`            | `routeParams: Signal<...>`                 |
+| Route Data       | `routeData$: Observable<...>`              | `routeData: Signal<...>`                   |
+| URL              | `url$: Observable<string>`                 | `url: Signal<string>`                      |
+| Fragment         | `fragment$: Observable<...>`               | `fragment: Signal<...>`                    |
+| Title            | `title$: Observable<...>`                  | `title: Signal<...>`                       |
+| Router events    | `selectRouterEvents(...): Observable<...>` | _Not included to avoid an RxJS dependency_ |
 
-@Injectable({
-  providedIn: 'root',
-})
-export class HeroService {
-  #routerStore = inject(RouterStore);
+## Usage patterns
 
-  activeHeroId$: Observable<string | undefined> = this.#routerStore.selectRouteParam('id');
-}
-```
+### Global usage (application-wide)
 
-Usage in component:
+Both packages support global router stores for application-wide router state access:
 
 ```typescript
-// hero-detail.component.ts
-// (...)
-import { RouterStore } from '@ngworker/router-component-store';
-
-@Component({
-  // (...)
-})
-export class HeroDetailComponent {
+// Component Store
+@Injectable({ providedIn: 'root' })
+export class NavigationService {
   #routerStore = inject(RouterStore);
+  currentPath$ = this.#routerStore.url$;
+}
 
-  heroId$: Observable<string | undefined> = this.#routerStore.selectRouteParam('id');
+// Signal Store
+@Injectable({ providedIn: 'root' })
+export class NavigationService {
+  #routerSignalStore = inject(RouterSignalStore);
+  currentPath = this.#routerSignalStore.url;
 }
 ```
 
-#### Local router store
-
-A component-level router store. Can be injected in any directive, component,
-pipe, or component-level service. Explicitly provided in a component sub-tree
-using `Component.providers` or `Component.viewProviders`.
-
-Use a local router store instead of `ActivatedRoute`.
+### Local usage (component-level)
 
-Usage in component:
+Both packages support local router stores for component-specific router state:
 
 ```typescript
-// hero-detail.component.ts
-// (...)
-import { provideLocalRouterStore, RouterStore } from '@ngworker/router-component-store';
-
+// Component Store
 @Component({
-  // (...)
   providers: [provideLocalRouterStore()],
 })
-export class HeroDetailComponent {
+export class ProductComponent {
   #routerStore = inject(RouterStore);
+  productId$ = this.#routerStore.selectRouteParam('id');
+}
 
-  heroId$: Observable<string | undefined> = this.#routerStore.selectRouteParam('id');
+// Signal Store
+@Component({
+  providers: [provideLocalRouterSignalStore()],
+})
+export class ProductComponent {
+  #routerStore = inject(RouterSignalStore);
+  productId = this.#routerStore.selectRouteParam('id');
 }
 ```
 
-### Serializable router state
-
-Several of the Angular Router's types are recursive which means that they aren't serializable. The router stores exclusively use serializable types to support advanced state synchronization strategies.
+## Development
 
-#### MinimalActivatedRouteSnapshot
+This repository uses:
 
-The `MinimalActivatedRouteSnapshot` interface is used for the observable `RouterStore#currentRoute$` property. This interface is a serializable subset of the Angular Router's `ActivatedRouteSnapshot` class and has the following public properties.
+- **[Nx](https://nx.dev)** for monorepo, task, and CI management
+- **Angular**, **RxJS**, and **NgRx**
+- **TypeScript**
+- **Jest** for testing
+- **Prettier** and **ESLint** for code quality
 
-| API                                                 | Description                                      |
-| --------------------------------------------------- | ------------------------------------------------ |
-| `children: MinimalActivatedRouteSnapshot[]`         | The children of this route in the route tree.    |
-| `data: StrictRouteData`                             | The static and resolved data of this route.      |
-| `firstChild: MinimalActivatedRouteSnapshot \| null` | The first child of this route in the route tree. |
-| `fragment: string \| null`                          | The URL fragment shared by all routes.           |
-| `outlet: string`                                    | The outlet name of the route.                    |
-| `params: StrictRouteParams`                         | The matrix parameters scoped to this route.      |
-| `queryParams: StrictQueryParams`                    | The query parameters shared by all routes.       |
-| `routeConfig: Route \| null`                        | The configuration used to match this route.      |
-| `title: string \| undefined`                        | The resolved route title.                        |
-| `url: UrlSegment[]`                                 | The URL segments matched by this route.          |
+### Commands
 
-#### StrictQueryParams
+```bash
+# Install dependencies
+yarn install
 
-The `StrictQueryParams` type is used for query parameters in the `MinimalActivatedRouteSnapshot#queryParams` and `RouterStore#queryParams$` properties. It is a strictly typed version of the Angular Router's `Params` type where members are read-only and the `any` member type is replaced with `string | readonly string[] | undefined`.
+# Run tests
+yarn test
 
-`StrictQueryParams` has the following signature.
+# Run linting
+yarn lint
 
-```typescript
-export type StrictQueryParams = {
-  readonly [key: string]: string | readonly string[] | undefined;
-};
-```
+# Build packages
+yarn build
 
-#### StrictRouteData
+# Perform dead code analysis
+yarn knip
 
-The `StrictRouteData` interface is used for the `MinimalActivatedRouteSnapshot#data` and `RouterStore#routeData$` properties. This interface is a serializable subset of the Angular Router's `Data` type. In particular, the `symbol` index in the Angular Router's `Data` type is removed. Additionally, the `any` member type is replaced with `unknown` for stricter typing.
+# Run all CI checks
+yarn ci
 
-`StrictRouteData` has the following signature.
+# Check formatting
+yarn format:check
 
-```typescript
-export type StrictRouteData = {
-  readonly [key: string]: unknown;
-};
+# Format code
+yarn format
 ```
 
-#### StrictRouteParams
+## Documentation
 
-The `StrictRouteParams` type is used for route parameters in the `MinimalActivatedRouteSnapshot#params` and `RouterStore#routeParams$` properties. It is a strictly typed version of the Angular Router's `Params` type where members are read-only and the `any` member type is replaced with `string | undefined`.
+- [Router Component Store package](packages/router-component-store/README.md)
+- [Router Signal Store package](packages/router-signal-store/README.md)
+- [Additional documentation](docs/)
 
-`StrictRouteParams` has the following signature.
+## Contributing
 
-```typescript
-export type StrictRouteParams = {
-  readonly [key: string]: string | undefined;
-};
-```
+Contributions are welcome! Submit pull requests to the main branch.
+
+## License
+
+MIT © [ngworkers](https://github.com/ngworker)

docs/dependency-injection.md

@@ -43,10 +43,7 @@ To ensure injection of a local router store, use the `host` inject option.
 ```typescript
 // crisis-detail.component.ts
 // (...)
-import {
-  provideLocalRouterStore,
-  RouterStore,
-} from '@ngworker/router-component-store';
+import { provideLocalRouterStore, RouterStore } from '@ngworker/router-component-store';
 
 @Component({
   // (...)