Enhance flight edit component with reactive URL connection and update store features

Author: danielmurrmann

apps/playground/src/app/flight/flight-edit/flight-edit.component.html

@@ -6,27 +6,19 @@
 
 <div class="row">
     <div class="col">
-        <app-action-card #connection
-                         [disabled]="!store.updateFlightConnectionState.isAvailable()" 
-                         (save)="onUpdateConnection()">
+        <app-action-card #connection [disabled]="!store.updateFlightConnectionState.isAvailable()" (save)="onUpdateConnection()">
             <app-flight-connection-form [connection]="flightForm.connection" />
         </app-action-card>
-        <app-action-card #times
-                         [disabled]="!store.updateFlightTimesState.isAvailable()" 
-                         (save)="onUpdateTimes()">
+        <app-action-card #times [disabled]="!store.updateFlightTimesState.isAvailable()" (save)="onUpdateTimes()">
             <app-flight-times-form [times]="flightForm.times" />
         </app-action-card>
-        <app-action-card #operator
-                         [disabled]="!store.updateFlightOperatorState.isAvailable()" 
-                         (save)="onUpdateOperator()">
+        <app-action-card #operator [disabled]="!store.updateFlightOperatorState.isAvailable()" (save)="onUpdateOperator()">
             <app-flight-operator-form [aircrafts]="store.flightEditVm.aircrafts()" [operator]="flightForm.operator" />
         </app-action-card>
         @if(flightForm.price().value(); as flightPriceValue) {
-            <app-action-card #price
-                             [disabled]="!store.updateFlightPriceState.isAvailable()" 
-                             (save)="onUpdatePrice()">
-                <app-flight-price-form [price]="$any(flightForm.price)" />
-            </app-action-card>
+        <app-action-card #price [disabled]="!store.updateFlightPriceState.isAvailable()" (save)="onUpdatePrice()">
+            <app-flight-price-form [price]="$any(flightForm.price)" />
+        </app-action-card>
         }
     </div>
 </div>

apps/playground/src/app/flight/flight-edit/flight-edit.component.ts

@@ -7,10 +7,11 @@ import { FlightTimesFormComponent } from '../shared/flight-times-form/flight-tim
 import { FlightEditStore } from './flight-edit.store';
 import { flightSchema } from '../flight.entities';
 import { form } from '@angular/forms/signals';
+import { HasActionPipe } from '@angular-architects/ngrx-hateoas';
 
 @Component({
     selector: 'app-flight-edit',
-    imports: [ActionCardComponent, FlightConnectionFormComponent, FlightOperatorFormComponent, FlightTimesFormComponent, FlightPriceFormComponent],
+    imports: [ActionCardComponent, FlightConnectionFormComponent, FlightOperatorFormComponent, FlightTimesFormComponent, FlightPriceFormComponent, HasActionPipe],
     templateUrl: './flight-edit.component.html'
 })
 export class FlightEditComponent {
@@ -22,6 +23,7 @@ export class FlightEditComponent {
   _operatorCard = viewChild.required<ActionCardComponent>('operator');
   _priceCard = viewChild<ActionCardComponent>('price');
 
+
   async onUpdateConnection() {
     try {
       await this.store.updateFlightConnection();
@@ -31,27 +33,27 @@ export class FlightEditComponent {
     }
   }
 
-  onUpdateTimes() {
+  async onUpdateTimes() {
     try {
-      this.store.updateFlightTimes();
+      await this.store.updateFlightTimes();
       this._timesCard().showSuccess();
     } catch {
       this._timesCard().showError();
     }
   }
 
-  onUpdateOperator() {
+  async onUpdateOperator() {
     try {
-      this.store.updateFlightOperator();
+      await this.store.updateFlightOperator();
       this._operatorCard().showSuccess();
     } catch {
       this._operatorCard().showError();
     }
   }
 
-  onUpdatePrice() {
+  async onUpdatePrice() {
     try {
-      this.store.updateFlightPrice();
+      await this.store.updateFlightPrice();
       this._priceCard()?.showSuccess();
     } catch {
       this._priceCard()?.showError();

apps/playground/src/app/flight/flight-edit/flight-edit.store.ts

@@ -1,5 +1,5 @@
 import { withHypermediaResource, withHypermediaAction, withWritableStateCopy, withExperimentalDeepWritableStateCopy, withExperimentalDeepWritableStateDelegate } from "@angular-architects/ngrx-hateoas";
-import { signalStore } from "@ngrx/signals";
+import { signalStore, withMethods } from "@ngrx/signals";
 import { Aircraft, Flight, initialFlight } from "../flight.entities";
 
 export type FlightEditVm = {
@@ -15,39 +15,42 @@ export const initialFlightEditVm: FlightEditVm = {
 export const FlightEditStore = signalStore(
   { providedIn: 'root' },
   withHypermediaResource('flightEditVm', initialFlightEditVm),
-  withWritableStateCopy(store => ({
-    localFlight: store.flightEditVm.flight
-  })),
+  withWritableStateCopy(store => ({ localFlight: store.flightEditVm.flight })),
   withHypermediaAction('updateFlightConnection', store => store.localFlight.connection, 'update'),
   withHypermediaAction('updateFlightTimes', store => store.localFlight.times, 'update'),
   withHypermediaAction('updateFlightOperator', store => store.localFlight.operator, 'update'),
-  withHypermediaAction('updateFlightPrice', store => store.localFlight.price, 'update')
+  withHypermediaAction('updateFlightPrice', store => store.localFlight.price, 'update'),
+  withMethods(store => ({
+    reset() {
+      store.localFlight.set(store.flightEditVm.flight());
+    }
+  }))
 );
 
 
 // Option 1: Reading a resource from server, creating a writable copy, and sending back the copy to the server
 export const FlightEditViewStore1 = signalStore(
   { providedIn: 'root' },
   withHypermediaResource('flightEditVm', initialFlightEditVm),
-  withWritableStateCopy(store => ({ writableFlightConnection: store.flightEditVm.flight.connection })),
-  withHypermediaAction('updateFlightConnection', store => store.writableFlightConnection, 'update'),
+  withWritableStateCopy(store => ({ writableFlightConnectionCopy: store.flightEditVm.flight.connection })),
+  withHypermediaAction('updateFlightConnection', store => store.writableFlightConnectionCopy, 'update'),
 );
 
 // Option 2: Reading a resource from server, creating a deep writable copy (suited for template driven forms),
 // and sending back the copy to the server
 export const FlightEditViewStore2 = signalStore(
   { providedIn: 'root' },
   withHypermediaResource('flightEditVm', initialFlightEditVm),
-  withExperimentalDeepWritableStateCopy(store => ({ deepWritableFlightConnection: store.flightEditVm.flight.connection })),
-  withHypermediaAction('updateFlightConnection', store => store.deepWritableFlightConnection, 'update'),
+  withExperimentalDeepWritableStateCopy(store => ({ deepWritableFlightConnectionCopy: store.flightEditVm.flight.connection })),
+  withHypermediaAction('updateFlightConnection', store => store.deepWritableFlightConnectionCopy, 'update'),
 );
 
 // Option 3: Reading a resource from server, creating a delegate that directly modifies the "main" state of the store,
 // and sending back parts of the main state to the server
-export const FlightEditViewStore = signalStore(
+export const FlightEditViewStore3 = signalStore(
   { providedIn: 'root' },
   withHypermediaResource('flightEditVm', initialFlightEditVm),
-  withExperimentalDeepWritableStateDelegate(store => ({ delegatedDeepWritableFlightConnection: store.flightEditVm.flight.connection })),
-  withHypermediaAction('updateFlightConnection', store => store.delegatedDeepWritableFlightConnection, 'update'),
+  withExperimentalDeepWritableStateDelegate(store => ({ deepWritableFlightConnectionDelegate: store.flightEditVm.flight.connection })),
+  withHypermediaAction('updateFlightConnection', store => store.flightEditVm.flight.connection, 'update'),
 );
 

doc/docs/guide/04-loading_features/01-withHypermediaResource.md

@@ -64,4 +64,12 @@ Loads the resource from the provided URL.
 ```ts
 reload<resourceName>(): Promise<void>
 ```
-Reloads the resource from the last used URL.
+Reloads the resource from the last used URL.
+
+### Connect the Resource to a URL Signal
+```ts
+connect<resourceName>ToUrl(url: string | Signal<string>): EffectRef
+```
+Reactively connects the resource to a URL signal. Whenever the signal emits a new URL value, the resource is automatically loaded from that URL. If a plain `string` is passed instead of a signal, the resource is loaded once from that URL.
+
+* **url**: A `Signal<string>` whose value is used as the URL. Whenever the signal changes, the resource is reloaded automatically. Can also be a plain `string` for a one-time load.

doc/docs/guide/04-loading_features/02-withInitialHypermediaResource.md

@@ -8,12 +8,16 @@ Creates a resource in the store which gets automatically loaded when an instance
 ## API
 ```ts
 function withInitialHypermediaResource<ResourceName extends string, TResource>(
-    resourceName: ResourceName, initialValue: TResource, url: string | (() => string)): SignalStoreFeature;
+    resourceName: ResourceName, initialValue: TResource, url: string | Promise<string> | (() => string | Promise<string>)): SignalStoreFeature;
 ```
 
 * **resourceName**: The name of how the resource will be declared in the store.
 * **initialValue**: The initial value of the resource before it is loaded from a URL.
-* **url**: The URL from which the resource will be loaded. Can also be a function returning a string. If a function is provided, it will be executed at the time the store is created.
+* **url**: The URL from which the resource will be loaded. Accepts four forms:
+  - A `string`: the URL is used directly at store creation time.
+  - A `Promise<string>`: the promise is awaited and the resolved value is used as the URL.
+  - A function returning a `string`: the function is called at store creation time, allowing injection of Angular services (e.g. `() => inject(MyToken)`).
+  - A function returning a `Promise<string>`: the function is called at store creation time and the resulting promise is awaited before loading. Useful for asynchronous URL resolution via injected services.
 
 ## State
 With this feature the following state properties are added to the interface of the store:
@@ -65,4 +69,12 @@ Loads the resource from the provided URL.
 ```ts
 reload<resourceName>(): Promise<void>
 ```
-Reloads the resource from the last used URL.
+Reloads the resource from the last used URL.
+
+### Connect the Resource to a URL Signal
+```ts
+connect<resourceName>ToUrl(url: string | Signal<string>): EffectRef
+```
+Reactively connects the resource to a URL signal. Whenever the signal emits a new URL value, the resource is automatically loaded from that URL. If a plain `string` is passed instead of a signal, the resource is loaded once from that URL.
+
+* **url**: A `Signal<string>` whose value is used as the URL. Whenever the signal changes, the resource is reloaded automatically. Can also be a plain `string` for a one-time load.

libs/ngrx-hateoas/src/lib/store-features/with-deep-writable-state-copy.ts

@@ -2,7 +2,7 @@ import { isSignal, linkedSignal, Signal } from "@angular/core";
 import { signalStoreFeature, SignalStoreFeature, SignalStoreFeatureResult, StateSignals, withProps } from "@ngrx/signals";
 import { deepWritableFromSignal, DeepWritableSignal } from "../util/deep-writeable-signal";
 
-type StoreForDeepWritableStateCopy<Input extends SignalStoreFeatureResult> = StateSignals<Input['state']>;
+type StoreForDeepWritableStateCopy<Input extends SignalStoreFeatureResult> = StateSignals<Input['state']> & Input['props'];
 
 export type ObjectWithSignalsForDeepStateCopy = {
     [key: string]: Signal<unknown> | ObjectWithSignalsForDeepStateCopy;

libs/ngrx-hateoas/src/lib/store-features/with-hypermedia-resource.spec.ts

@@ -4,7 +4,7 @@ import { HttpTestingController, provideHttpClientTesting } from '@angular/common
 import { signalStore } from '@ngrx/signals';
 import { withHypermediaResource } from './with-hypermedia-resource';
 import { provideHateoas } from '../provide';
-import { provideZonelessChangeDetection } from '@angular/core';
+import { provideZonelessChangeDetection, signal } from '@angular/core';
 
 type RootModel = {
     apiName: string
@@ -88,6 +88,7 @@ describe('withHypermediaResource', () => {
     it('has correct resource methods', () => {
         expect(store.loadTestModelFromLink).toBeDefined();
         expect(store.loadTestModelFromUrl).toBeDefined();
+        expect(store.connectTestModelToUrl).toBeDefined();
         expect(store.reloadTestModel).toBeDefined();
         expect(store.getTestModelAsPatchable).toBeDefined();
     });
@@ -312,4 +313,62 @@ describe('withHypermediaResource', () => {
         httpTestingController.verify();
     });
 
+    it('connects resource to a static url and loads it', (done: DoneFn) => {
+        const resourceFromUrl: TestModel = {
+            numProp: 2,
+            objProp: { stringProp: 'from connect' }
+        };
+
+        store.connectTestModelToUrl('api/test-model');
+
+        expect(store.testModelState.isLoading()).toBeTrue();
+        expect(store.testModelState.isLoaded()).toBeFalse();
+
+        httpTestingController.expectOne('api/test-model').flush(resourceFromUrl);
+        httpTestingController.verify();
+
+        setTimeout(() => {
+            expect(store.testModelState.url()).toBe('api/test-model');
+            expect(store.testModelState.isLoading()).toBeFalse();
+            expect(store.testModelState.isLoaded()).toBeTrue();
+            expect(store.testModel.objProp.stringProp()).toBe('from connect');
+            done();
+        }, 0);
+    });
+
+    it('connects resource reactively to a url signal and reloads when signal changes', (done: DoneFn) => {
+        const resourceFirst: TestModel = {
+            numProp: 2,
+            objProp: { stringProp: 'first response' }
+        };
+        const resourceSecond: TestModel = {
+            numProp: 3,
+            objProp: { stringProp: 'second response' }
+        };
+
+        const urlSignal = signal('api/test-model?version=1');
+        store.connectTestModelToUrl(urlSignal);
+
+        TestBed.flushEffects();
+
+        expect(store.testModelState.isLoading()).toBeTrue();
+        httpTestingController.expectOne('api/test-model?version=1').flush(resourceFirst);
+
+        setTimeout(() => {
+            expect(store.testModel.objProp.stringProp()).toBe('first response');
+
+            urlSignal.set('api/test-model?version=2');
+            TestBed.flushEffects();
+
+            expect(store.testModelState.isLoading()).toBeTrue();
+            httpTestingController.expectOne('api/test-model?version=2').flush(resourceSecond);
+
+            setTimeout(() => {
+                expect(store.testModel.objProp.stringProp()).toBe('second response');
+                httpTestingController.verify();
+                done();
+            }, 0);
+        }, 0);
+    });
+
 });

libs/ngrx-hateoas/src/lib/store-features/with-hypermedia-resource.ts

@@ -1,5 +1,5 @@
 import { inject, Signal } from "@angular/core";
-import { SignalStoreFeature, patchState, signalStoreFeature, withMethods, withState } from "@ngrx/signals";
+import { SignalMethod, SignalStoreFeature, patchState, signalMethod, signalStoreFeature, withMethods, withState } from "@ngrx/signals";
 import { DeepPatchableSignal, toDeepPatchableSignal } from "../util/deep-patchable-signal";
 import { HateoasService } from "../services/hateoas.service";
 import { RequestService } from "../services/request.service";
@@ -39,6 +39,14 @@ export function generateLoadHypermediaResourceFromLinkMethodName(resourceName: s
     return `load${resourceName.charAt(0).toUpperCase() + resourceName.slice(1)}FromLink`;
 }
 
+export type ConnectHypermediaResourceToUrlMethod<ResourceName extends string> = {
+    [K in ResourceName as `connect${Capitalize<ResourceName>}ToUrl`]: SignalMethod<string>
+};
+
+export function generateConnectHypermediaResourceToUrlMethodName(resourceName: string) {
+    return `connect${resourceName.charAt(0).toUpperCase() + resourceName.slice(1)}ToUrl`;
+}
+
 export type ReloadHypermediaResourceMethod<ResourceName extends string> = {
     [K in ResourceName as `reload${Capitalize<ResourceName>}`]: () => Promise<void>
 };
@@ -58,6 +66,7 @@ export function generateGetAsPatchableHypermediaResourceMethodName(resourceName:
 export type HypermediaResourceStoreMethods<ResourceName extends string, TResource> =
     LoadHypermediaResourceFromUrlMethod<ResourceName>
     & LoadHypermediaResourceFromLinkMethod<ResourceName>
+    & ConnectHypermediaResourceToUrlMethod<ResourceName>
     & ReloadHypermediaResourceMethod<ResourceName>
     & GetAsPatchableHypermediaResourceMethod<ResourceName, TResource>;
 
@@ -99,6 +108,7 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
     const stateKey = `${resourceName}State`;
     const loadFromUrlMethodName = generateLoadHypermediaResourceFromUrlMethodName(resourceName);
     const loadFromLinkMethodName = generateLoadHypermediaResourceFromLinkMethodName(resourceName);
+    const connectToUrlMethodName = generateConnectHypermediaResourceToUrlMethodName(resourceName);
     const reloadMethodName = generateReloadHypermediaResourceMethodName(resourceName);
     const getAsPatchableMethodName = generateGetAsPatchableHypermediaResourceMethodName(resourceName);
 
@@ -166,6 +176,8 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
                 }
             };
 
+            const connectToUrlMethod = signalMethod<string>(url => loadFromUrlMethod(url));
+
             const reloadMethod = (): Promise<void> => {
                 if (currentRequestSub) {
                     currentRequestSub.unsubscribe();
@@ -207,6 +219,7 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
             return {
                 [loadFromUrlMethodName]: loadFromUrlMethod,
                 [loadFromLinkMethodName]: loadFromLinkMethod,
+                [connectToUrlMethodName]: connectToUrlMethod,
                 [reloadMethodName]: reloadMethod,
                 [getAsPatchableMethodName]: getAsPatchableMethod
             };

libs/ngrx-hateoas/src/lib/store-features/with-initial-hypermedia-resource.spec.ts

@@ -29,6 +29,16 @@ const TestStoreWithInjectedUrl = signalStore(
     withInitialHypermediaResource('rootModel', initialRootModel, () => inject(ROOT_URL))
 );
 
+const TestStoreWithPromiseUrl = signalStore(
+    { providedIn: 'root' },
+    withInitialHypermediaResource('rootModel', initialRootModel, Promise.resolve('/api/promised'))
+);
+
+const TestStoreWithAsyncResolverUrl = signalStore(
+    { providedIn: 'root' },
+    withInitialHypermediaResource('rootModel', initialRootModel, () => Promise.resolve('/api/async-resolved'))
+);
+
 describe('withInitialHypermediaResource', () => {
 
     let httpTestingController: HttpTestingController;
@@ -65,4 +75,38 @@ describe('withInitialHypermediaResource', () => {
             done();
         }, 0);
     });
+
+    it('requests model from promise url automatically and provides correct states', (done: DoneFn) => {
+        const store = TestBed.inject(TestStoreWithPromiseUrl);
+        // isLoading is not immediately true because loadFromUrl is called after the promise resolves
+        expect(store.rootModelState.isLoaded()).toBeFalse();
+        expect(store.rootModelState.isLoading()).toBeFalse();
+        setTimeout(() => {
+            expect(store.rootModelState.isLoading()).toBeTrue();
+            httpTestingController.expectOne('/api/promised').flush(initialRootModel);
+            httpTestingController.verify();
+            setTimeout(() => {
+                expect(store.rootModelState.isLoaded()).toBeTrue();
+                expect(store.rootModelState.isLoading()).toBeFalse();
+                done();
+            }, 0);
+        }, 0);
+    });
+
+    it('requests model from async resolver url automatically and provides correct states', (done: DoneFn) => {
+        const store = TestBed.inject(TestStoreWithAsyncResolverUrl);
+        // isLoading is not immediately true because loadFromUrl is called after the promise resolves
+        expect(store.rootModelState.isLoaded()).toBeFalse();
+        expect(store.rootModelState.isLoading()).toBeFalse();
+        setTimeout(() => {
+            expect(store.rootModelState.isLoading()).toBeTrue();
+            httpTestingController.expectOne('/api/async-resolved').flush(initialRootModel);
+            httpTestingController.verify();
+            setTimeout(() => {
+                expect(store.rootModelState.isLoaded()).toBeTrue();
+                expect(store.rootModelState.isLoading()).toBeFalse();
+                done();
+            }, 0);
+        }, 0);
+    });
 });