Refactor hypermedia resource methods to support reactive URL loading and remove deprecated connection method

Author: danielmurrmann

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

@@ -7,11 +7,10 @@ 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, HasActionPipe],
+    imports: [ActionCardComponent, FlightConnectionFormComponent, FlightOperatorFormComponent, FlightTimesFormComponent, FlightPriceFormComponent],
     templateUrl: './flight-edit.component.html'
 })
 export class FlightEditComponent {

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

@@ -45,11 +45,13 @@ With this feature the following methods are added to the interface of the store:
 ### Load the Resource from an URL
 ```ts
 load<resourceName>FromUrl(url: string | null, fromCache?: boolean): Promise<void>
+load<resourceName>FromUrl(url: Signal<string | null>): EffectRef
 ```
-Loads the resource from the provided URL. 
+Loads the resource from the provided URL. Two overloads are available:
 
-* **url**: The URL from which the resource should be loaded. If `null` is provided the resource is reset to its initial value.
-* **fromCache**: Whether to load the resource even if the the current state is loaded from the same URL. If not provided, defaults to `false`.
+* When called with a **plain value** (`string | null`): loads the resource immediately and returns a `Promise<void>` that resolves when the request completes. Passing `null` resets the resource to its initial value.
+  * **fromCache**: When `true`, skips loading if the resource is already loaded from the same URL. Defaults to `false`.
+* When called with a **`Signal<string | null>`**: sets up a reactive effect that automatically reloads the resource whenever the signal's value changes, and returns an `EffectRef` that can be used to destroy the effect.
 
 ### Load the Resource from a Link
 ```ts
@@ -65,11 +67,3 @@ Loads the resource from the provided URL.
 reload<resourceName>(): Promise<void>
 ```
 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

@@ -50,11 +50,13 @@ With this feature the following methods are added to the interface of the store:
 ### Load the Resource from an URL
 ```ts
 load<resourceName>FromUrl(url: string | null, fromCache?: boolean): Promise<void>
+load<resourceName>FromUrl(url: Signal<string | null>): EffectRef
 ```
-Loads the resource from the provided URL. 
+Loads the resource from the provided URL. Two overloads are available:
 
-* **url**: The URL from which the resource should be loaded. If `null` is provided the resource is reset to its initial value.
-* **fromCache**: Whether to load the resource even if the the current state is loaded from the same URL. If not provided, defaults to `false`.
+* When called with a **plain value** (`string | null`): loads the resource immediately and returns a `Promise<void>` that resolves when the request completes. Passing `null` resets the resource to its initial value.
+  * **fromCache**: When `true`, skips loading if the resource is already loaded from the same URL. Defaults to `false`.
+* When called with a **`Signal<string | null>`**: sets up a reactive effect that automatically reloads the resource whenever the signal's value changes, and returns an `EffectRef` that can be used to destroy the effect.
 
 ### Load the Resource from a Link
 ```ts
@@ -69,12 +71,4 @@ Loads the resource from the provided URL.
 ```ts
 reload<resourceName>(): Promise<void>
 ```
-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.
+Reloads the resource from the last used URL.

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

@@ -88,7 +88,6 @@ 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();
     });
@@ -210,6 +209,75 @@ describe('withHypermediaResource', () => {
         expect(store.testModel.objProp.stringProp()).toBe('from Url Reloaded');
     });
 
+    it('skips loading if fromCache is true and resource is already loaded from the same url', async () => {
+        const resourceFromUrl: TestModel = {
+            numProp: 2,
+            objProp: { stringProp: 'from Url' }
+        };
+
+        const loadPromise = store.loadTestModelFromUrl('api/test-model');
+        httpTestingController.expectOne('api/test-model').flush(resourceFromUrl);
+        await loadPromise;
+
+        // second call with same url and fromCache=true — should not trigger a new request
+        await store.loadTestModelFromUrl('api/test-model', true);
+
+        httpTestingController.expectNone('api/test-model');
+        httpTestingController.verify();
+
+        expect(store.testModelState.isLoaded()).toBeTrue();
+        expect(store.testModel.objProp.stringProp()).toBe('from Url');
+    });
+
+    it('loads again if fromCache is true but url has changed', async () => {
+        const resourceFromUrl: TestModel = {
+            numProp: 2,
+            objProp: { stringProp: 'from Url' }
+        };
+
+        const resourceFromNewUrl: TestModel = {
+            numProp: 3,
+            objProp: { stringProp: 'from New Url' }
+        };
+
+        const loadPromise = store.loadTestModelFromUrl('api/test-model');
+        httpTestingController.expectOne('api/test-model').flush(resourceFromUrl);
+        await loadPromise;
+
+        // call with a different url and fromCache=true — should still load
+        const reloadPromise = store.loadTestModelFromUrl('api/test-model?v=2', true);
+        httpTestingController.expectOne('api/test-model?v=2').flush(resourceFromNewUrl);
+        httpTestingController.verify();
+        await reloadPromise;
+
+        expect(store.testModelState.url()).toBe('api/test-model?v=2');
+        expect(store.testModel.objProp.stringProp()).toBe('from New Url');
+    });
+
+    it('loads again if fromCache is false even when already loaded from the same url', async () => {
+        const resourceFromUrl: TestModel = {
+            numProp: 2,
+            objProp: { stringProp: 'from Url' }
+        };
+
+        const resourceReloaded: TestModel = {
+            numProp: 3,
+            objProp: { stringProp: 'reloaded' }
+        };
+
+        let loadPromise = store.loadTestModelFromUrl('api/test-model');
+        httpTestingController.expectOne('api/test-model').flush(resourceFromUrl);
+        await loadPromise;
+
+        // call with same url and fromCache=false (default) — should load again
+        loadPromise = store.loadTestModelFromUrl('api/test-model');
+        httpTestingController.expectOne('api/test-model').flush(resourceReloaded);
+        httpTestingController.verify();
+        await loadPromise;
+
+        expect(store.testModel.objProp.stringProp()).toBe('reloaded');
+    });
+
     it('gets the resource as patchable', () => {
         const resource = store.getTestModelAsPatchable();
 
@@ -264,16 +332,11 @@ describe('withHypermediaResource', () => {
         const req1 = httpTestingController.expectOne('api/test-model?first=1');
         expect(req1.cancelled).toBeTrue();
 
-        // flush second request first
+        // flush second request
         httpTestingController.expectOne('api/test-model?second=2').flush(resourceSecond);
         await request;
 
-        // after second resolves, store should reflect second response
-        expect(store.testModel.objProp.stringProp()).toBe('second response');
-
-        // assert that the resource still contains the data from the second url
         expect(store.testModel.objProp.stringProp()).toBe('second response');
-
         httpTestingController.verify();
     });
 
@@ -313,30 +376,7 @@ 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) => {
+    it('loads the resource reactively from a url signal and reloads when signal changes', (done: DoneFn) => {
         const resourceFirst: TestModel = {
             numProp: 2,
             objProp: { stringProp: 'first response' }
@@ -347,7 +387,7 @@ describe('withHypermediaResource', () => {
         };
 
         const urlSignal = signal('api/test-model?version=1');
-        store.connectTestModelToUrl(urlSignal);
+        store.loadTestModelFromUrl(urlSignal);
 
         TestBed.flushEffects();
 

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

@@ -1,5 +1,5 @@
-import { inject, Signal } from "@angular/core";
-import { SignalMethod, SignalStoreFeature, patchState, signalMethod, signalStoreFeature, withMethods, withState } from "@ngrx/signals";
+import { inject, isSignal, EffectRef, Signal } from "@angular/core";
+import { 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";
@@ -24,7 +24,10 @@ export type HypermediaResourceStoreState<ResourceName extends string, TResource>
     & HypermediaResourceState<ResourceName>;
 
 export type LoadHypermediaResourceFromUrlMethod<ResourceName extends string> = {
-    [K in ResourceName as `load${Capitalize<ResourceName>}FromUrl`]: (url: string | null, fromCache?: boolean) => Promise<void>
+    [K in ResourceName as `load${Capitalize<ResourceName>}FromUrl`]: {
+        (url: string | null, fromCache?: boolean): Promise<void>;
+        (url: Signal<string | null>): EffectRef;
+    }
 };
 
 export function generateLoadHypermediaResourceFromUrlMethodName(resourceName: string) {
@@ -39,14 +42,6 @@ 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>
 };
@@ -66,7 +61,6 @@ export function generateGetAsPatchableHypermediaResourceMethodName(resourceName:
 export type HypermediaResourceStoreMethods<ResourceName extends string, TResource> =
     LoadHypermediaResourceFromUrlMethod<ResourceName>
     & LoadHypermediaResourceFromLinkMethod<ResourceName>
-    & ConnectHypermediaResourceToUrlMethod<ResourceName>
     & ReloadHypermediaResourceMethod<ResourceName>
     & GetAsPatchableHypermediaResourceMethod<ResourceName, TResource>;
 
@@ -108,7 +102,6 @@ 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);
 
@@ -130,7 +123,7 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
 
             let currentRequestSub: Subscription | undefined;
 
-            const loadFromUrlMethod = (url: string | null, fromCache = false): Promise<void> => {
+            function loadFromUrl(url: string | null, fromCache = false): Promise<void> {
                 if (currentRequestSub) {
                     currentRequestSub.unsubscribe();
                     currentRequestSub = undefined;
@@ -140,7 +133,9 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
                         updateData(dataKey, initialValue),
                         updateState(stateKey, { url: '', isLoading: false, isLoaded: false }));
                     return Promise.resolve();
-                } else if (!fromCache || hateoasService.getLink(getData(store, dataKey), 'self')?.href !== url) {
+                } else if (fromCache && getState(store, stateKey).isLoaded && getState(store, stateKey).url === url) {
+                    return Promise.resolve();
+                } else {
                     patchState(store, updateState(stateKey, { url: '', isLoading: true }));
 
                     const request = requestService.requestWithObservable<TResource>('GET', url);
@@ -163,21 +158,28 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
                             }
                         });
                     });
-                } else {
-                    return Promise.resolve();
                 }
             };
 
+            const loadFromUrlReactive = signalMethod<string | null>(url => loadFromUrl(url).catch(() => undefined));
+
+            function loadFromUrlOverload(url: string | null, fromCache?: boolean): Promise<void>;
+            function loadFromUrlOverload(url: Signal<string | null>): EffectRef;
+            function loadFromUrlOverload(url: string | null | Signal<string | null>, fromCache?: boolean): Promise<void> | EffectRef {
+                if (isSignal(url)) return loadFromUrlReactive(url as Signal<string | null>);
+                return loadFromUrl(url as string | null, fromCache);
+            }
+
+            const loadFromUrlMethod = loadFromUrlOverload;
+
             const loadFromLinkMethod = async (linkRoot: unknown, linkName: string, params?: Record<string, unknown>): Promise<void> => {
                 const link = hateoasService.getLink(linkRoot, linkName);
                 if (link) {
                     const url = hateoasService.getUrl(linkRoot, linkName, params);
-                    await loadFromUrlMethod(url);
+                    await loadFromUrl(url);
                 }
             };
 
-            const connectToUrlMethod = signalMethod<string>(url => loadFromUrlMethod(url));
-
             const reloadMethod = (): Promise<void> => {
                 if (currentRequestSub) {
                     currentRequestSub.unsubscribe();
@@ -219,7 +221,6 @@ export function withHypermediaResource<ResourceName extends string, TResource>(r
             return {
                 [loadFromUrlMethodName]: loadFromUrlMethod,
                 [loadFromLinkMethodName]: loadFromLinkMethod,
-                [connectToUrlMethodName]: connectToUrlMethod,
                 [reloadMethodName]: reloadMethod,
                 [getAsPatchableMethodName]: getAsPatchableMethod
             };