Added documentation for loading features with small api improvements

Author: danielmurrmann

apps/playground/src/app/core/core.routes.ts

@@ -11,5 +11,5 @@ export const CORE_ROUTES: Routes = [{
 }, {
     path: 'home',
     component: HomeComponent,
-    canActivate: [ () => whenTrue(inject(HomeStore).homeVmState.initiallyLoaded) ]
+    canActivate: [ () => whenTrue(inject(HomeStore).homeVmState.isLoaded) ]
 }];

apps/playground/src/app/flight/flight.routes.ts

@@ -28,5 +28,5 @@ export const FLIHGT_ROUTES: Routes = [{
 }, {
     path: "create",
     component: FlightCreateComponent,
-    canActivate: [() => whenTrue(inject(FlightCreateStore).flightCreateVmState.initiallyLoaded)]
+    canActivate: [() => whenTrue(inject(FlightCreateStore).flightCreateVmState.isLoaded)]
 }];

doc/docs/guide/01-getting-started.md

@@ -114,7 +114,7 @@ export const initialFlight: Flight = {
 ```
 
 ## 1. Load a Resource from the Backend into the Store
-To load a resource from the backend into the NgRx Signal Store you can use the `withHypermediaResource` feature from **ngrx-hateoas**. This feature adds state, metastate and methods to the store to work with this resource. The following snippet shows how to set up a signal store for the flight resource:
+To load a resource from the backend into the NgRx Signal Store you can use the `withHypermediaResource(<ModelName>, <InitialState>)` feature from **ngrx-hateoas**. This feature adds state, metastate and methods to the store to work with this resource. The following snippet shows how to set up a signal store for the flight resource:
 
 ```ts
 import { signalStore } from '@ngrx/signals';
@@ -126,21 +126,21 @@ export const FlightEditStore = signalStore(
 );
 ```
 
-The store can be injected in your Angular component, a router activator or a router resolver. The `withHypermediaResource` add a method called `load<ModelName>FromUrl` which load the resource from the backend into the store. In our case the model name is `flightModel`. Also a property called `flightModel` is added to the store which holds the current state of the resource in form a NgRx deep signal. The following code snippet shows how to inject the store, load data from the backend and access the singals holding the data;
+The store can be injected in your Angular component, a router activator or a router resolver. The `withHypermediaResource` adds a method called `load<ModelName>FromUrl` which loads the resource from the backend into the store. In our case the model name is `flightModel`. Also a property named with the provided `<ModelName>`, in our case `flightModel` is added to the store which holds the current state of the resource in form a NgRx deep signal. The following code snippet shows how to inject the store, load data from the backend and access the singals holding the data;
 
 ```ts
 // Inject the store using Angular's inject function
 store = inject(FlightEditStore);
 
 // Load the flight resource from the backend into the store via an async call
-await this.store.loadFlightModelFromUrl('/api/flights/123');
+await store.loadFlightModelFromUrl('/api/flights/123');
 
 // Access signals holding data from the store
-const idSignal = this.store.flightModel.id;
-const connectionSignal = this.store.flightModel.connection;
+const idSignal = store.flightModel.id;
+const connectionSignal = store.flightModel.connection;
 
 ```
-The `withHypermediaResource` feature also adds a property called `<modelName>State` to the store which holds metastate information about the resource. This can be used to e.g. show loading spinners in the UI while the resource is loaded from the backend. The following code snippet shows how to access some of the metastate signals:
+The `withHypermediaResource` feature also adds a property called `<ModelName>State` to the store which holds metastate information about the resource. This can be used to e.g. show loading spinners in the UI while the resource is loaded from the backend. The following code snippet shows how to access some of the metastate signals:
 
 ```ts
 // A signal toggling between true and false to indicate if the 
@@ -194,8 +194,12 @@ export const FlightEditStore = signalStore(
 
 You can now set a new state of the connection object by using the `writableFlightConnection` signal on the store like this: `store.writableFlightConnection.set(<new value>)`.
 
+:::info
+The store properties created by the `withWritableStateCopy` feature are writable signals and are deep signals at the same time. Therefore you can get fine grained signals from the state copy the same way as you get them from the store state itself.
+:::
+
 ### Option 3: Use a Deep Writable State Copy
-In case you want want to bind your state to a template driven form you can use the `withExperimentalDeepWritableStateCopy` feature from **ngrx-hateoas**. While `withWritableStateCopy` creates a writable signal for the root object only, the `withExperimentalDeepWritableStateCopy` feature creates a deep writable signal which allows you to set each key of the object individually. This is especiall helpfull in cases where you want to bind your data to a form with the help of `ngModel`. The following code snippet shows how to set up the store with this feature:
+While `withWritableStateCopy` creates a writable signal for the root object only, the `withExperimentalDeepWritableStateCopy` feature creates a deep writable signal which allows you to set each key of the object individually. This is especiall helpfull in cases where you want to bind your data to a form with the help of `ngModel`. The following code snippet shows how to set up the store with this feature:
 
 ```ts
 import { signalStore, withMethods, patchState } from "@ngrx/signals";
@@ -211,14 +215,14 @@ export const FlightEditStore = signalStore(
 );
 ```
 
-You can now set a new state of the connection object by using the `writableFlightConnection` signal on the store like this: `store.writableFlightConnection.from.set('<new value>')`.
+You can now set a new state of individual prperties of the connection object by using the `writableFlightConnection` signal on the store like this: `store.writableFlightConnection.from.set('<new value>')`.
 
 :::info
 This feature is currently experimental and might change in future releases.
 :::
 
 ### Option 4: Use a Deep Writable State Delegate
-If you want to have a writalbe signal in the interface of your store which directly modifies the state in the store you can use the `withExperimentalDeepWritableStateDelegate` feature from **ngrx-hateoas**. This feature creates a writable signal graph which directly modifies the state in the store when you call `set` on it. Because it is a deep writable it works well with template driven forms as well as signal firms. The following code snippet shows how to set up the store with this feature:
+If you want to have a writalbe signal in the interface of your store which directly modifies the state in the store you can use the `withExperimentalDeepWritableStateDelegate` feature from **ngrx-hateoas**. This feature creates a writable signal graph which directly modifies the state in the store when you call `set` on it. Because it is a deep writable it works well with template driven forms as well as signal forms. The following code snippet shows how to set up the store with this feature:
 
 ```ts
 import { signalStore, withMethods, patchState } from "@ngrx/signals";
@@ -263,7 +267,7 @@ To send changed state back to the server you can use the `withHypermediaAction`
 The `_actions` key holds the metadata for the actions available for this object. In this case there is an action called `update` which uses the HTTP verb `PUT` to send the updated connection object back to the server to the specified URL in the `href` property.
 
 :::info
-If your metadata have different names or structure you can customize this via the `HateoasConfig` when you provide the **ngrx-hateoas** services in your application. For this have a look into the [Metadata Provider](./configuration/01-metadata-provider.md) section.
+If your metadata has different names or a different structure you can customize this via the `HateoasConfig` when you provide the **ngrx-hateoas** services in your application. For this have a look into the [Metadata Provider](./configuration/01-metadata-provider.md) section.
 :::
 
 The following code snippet shows how to set up the store with an action that sends back the changed connection object to the server using the metadata provided in the resource:
@@ -282,7 +286,7 @@ export const FlightEditStore = signalStore(
     withHypermediaAction('updateFlightConnection', store => store.writableFlightConnection, 'update')
 );
 ```
-Through the `withHypermediaAction` feature a method called `updateFlightConnection` is added to the store which can be called to send the connection object pointed to by the lambda in the second argument back to the server. The following code snippet shows how to call this method:
+Through the `withHypermediaAction(<MethodName>, <LambdaToAffectedState>, <ActionName>)` feature a method called `updateFlightConnection` is added to the store which can be called to send the connection object pointed to by the lambda in the second argument back to the server. The following code snippet shows how to call this method:
 
 ```ts
 await this.store.updateFlightConnection();
@@ -357,7 +361,7 @@ export const FlightEditStore = signalStore(
 ```
 
 The  store, as shown in the previous code sample is able to do the following things:
-* read the JSON from backend into the store and provide it as state by providing a url
+* read the JSON from backend into the store and provide it as reactive deep signal
 * rectively read a linked json object triggered by changes from the main object
 * provide writable copies of parts of the state
 * provide metastate about the requests to the backend (e.g. such as if a request is currently running)

doc/docs/guide/02-concept.md

@@ -86,7 +86,7 @@ You don't need to follow the exact same layout as in the example to embed metada
 
 ## What is HATEOAS?
 
-HATEOAS (Hypermedia as the Engine of Application State) is an architectural paradigm that allows clients to dynamically navigate resources through hyperlinks provided in responses. Possible state changes are provided via actions. Hyperlinks and actions are metadata sent next to the actual payload. Instead of hardcoding API endpoints, clients rely on these links to discover available actions and related resources. For example, if a user is not allowed to navigate to a linked resource or execute an action, the server would not send this metainformation to the client within its response. Finally, the client has the full state of the resource available, the actual payload, and information to related data and possible actions (or state changes). This approach decouples the client from the server, keeps domain logic away from the client and enables more flexible and evolvable APIs.
+HATEOAS (Hypermedia as the Engine of Application State) is an architectural paradigm that allows clients to dynamically navigate resources through hyperlinks provided in responses. Possible state changes are provided via actions. Hyperlinks and actions are metadata sent next to the actual payload. Instead of hardcoding API endpoints, clients rely on these links to discover available actions and related resources. For example, if a user is not allowed to navigate to a linked resource or execute an action, the server would not send this metainformation to the client within its response. Finally, the client has the full state of the resource available, the actual payload and information to related data and possible actions (or state changes). This approach decouples the client from the server, keeps domain logic away from the client and enables more flexible and evolvable APIs.
 
 ## Hypermedia at the Backend
 To create hypermedia responses you can use community libraries for the different technologies:

doc/docs/guide/configuration/01-metadata-provider.md

@@ -67,8 +67,11 @@ To use a custom hypermedia JSON format with **ngrx-hateoas** you have to impleme
 export interface MetadataProvider {
     isMetadataKey(keyName: string): boolean;
     linkLookup(resource: unknown, linkName: string): ResourceLink | undefined;
+    getAllLinks(resource: unknown): ResourceLink[];
     actionLookup(resource: unknown, actionName: string): ResourceAction | undefined;
+    getAllActions(resource: unknown): ResourceAction[];
     socketLookup(resource: unknown, socketName: string): ResourceSocket | undefined;
+    getAllSockets(resource: unknown): ResourceSocket[];
 }
 ```
 
@@ -94,7 +97,7 @@ Lets imagine our hypermedia JSON looks like the following:
         "_metadata": {
             "_link_aLinkToAResource": { "href": "/api/..." },
             "_action_anActionOnSubobject": { "href": "/api/...", "verb": "PUT" },
-            "_sockets_aSocketForSubobject": { "href": "/api/...", "event": "newMessageForSubobject" }
+            "_socket_aSocketForSubobject": { "href": "/api/...", "event": "newMessageForSubobject" }
         }
     },
     "_metadata": {
@@ -115,15 +118,39 @@ const customMetadataProvider: MetadataProvider = {
     linkLookup(resource: unknown, linkName: string): ResourceLink | undefined {
         return resource['_metadata']?.['_link_' + linkName];
     },
+    getAllLinks(resource: unknown): ResourceLink[]; {
+        const linksMetadata = resource['_metadata'];
+        if(!linksMetadata) return [];
+        return Object.keys(linksMetadata)
+                     .filter(key => key.startsWith('_link_'))
+                     .map(key => linksMetadata[key]);
+    },
     actionLookup(resource: unknown, actionName: string): ResourceAction | undefined {
         const actionMetadata = resource['_metadata']?.['_action_' + actionName];
         // ResourceAction has the two keys href and method, 
         // therefore we have to bring the metadata into the correct format
         if(actionMetadata) return { href: actionMetadata.href, method: actionMetadata.verb };
         else return undefined;
     },
+    getAllActions(resource: unknown): ResourceAction[] {
+        const actionsMetadata = resource['_metadata'];
+        if(!actionsMetadata) return [];
+        return Object.keys(actionsMetadata)
+                     .filter(key => key.startsWith('_action_'))
+                     .map(key => {
+                         const actionMetadata = actionsMetadata[key];
+                         return { href: actionMetadata.href, method: actionMetadata.verb };
+                     });
+    },
     socketLookup(resource: unknown, socketName: string): ResourceSocket | undefined {
         return resource['_metadata']?.['_socket_' + socketName];
+    },
+    getAllSockets(resource: unknown): ResourceSocket[] {
+        const socketsMetadata = resource['_metadata'];
+        if(!socketsMetadata) return [];
+        return Object.keys(socketsMetadata)
+                     .filter(key => key.startsWith('_socket_'))
+                     .map(key => socketsMetadata[key]);
     }
 }
 ```

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

@@ -0,0 +1,67 @@
+---
+sidebar_position: 1
+---
+
+# withHypermediaResource
+Creates a resource in the store.
+
+## API
+```ts
+function withHypermediaResource<ResourceName extends string, TResource>(
+    resourceName: ResourceName, initialValue: TResource): 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.
+
+## State
+With this feature the following state properties are added to the interface of the store:
+
+### Resource State
+```ts
+<resourceName>: DeepSignal<TResource>
+```
+A deep signal containing the data of the resource.
+
+### Resource Meta State
+```ts
+<resourceName>State: DeepSignal<
+    {
+        url: string,
+        isLoading: boolean,
+        isLoaded: boolean
+    }>
+```
+A deep signal containing meta information about the resource.
+
+* **url**: The URL from which the resource was last loaded.
+* **isLoading**: Whether the resource is currently being loaded.
+* **isLoaded**: Whether the resource currently in the state was loaded from the server.
+
+## Methods
+
+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>
+```
+Loads the resource from the provided URL. 
+
+* **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`.
+
+### Load the Resource from a Link
+```ts
+load<resourceName>FromLink(linkRoot: unknown, linkName: string) => Promise<void>
+```
+Loads the resource from the provided URL. 
+
+* **linkRoot**: An object containing the link to use.
+* **linkName**: The name of the link to use to load the resource.
+
+### Reload the Resource
+```ts
+reload<resourceName>(): Promise<void>
+```
+Reloads the resource from the last used URL.

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

@@ -0,0 +1,68 @@
+---
+sidebar_position: 2
+---
+
+# withInitialHypermediaResource
+Creates a resource in the store which gets automatically loaded when an instance of the store is created.
+
+## API
+```ts
+function withInitialHypermediaResource<ResourceName extends string, TResource>(
+    resourceName: ResourceName, initialValue: TResource, url: string | (() => 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.
+
+## State
+With this feature the following state properties are added to the interface of the store:
+
+### Resource State
+```ts
+<resourceName>: DeepSignal<TResource>
+```
+A deep signal containing the data of the resource.
+
+### Resource Meta State
+```ts
+<resourceName>State: DeepSignal<
+    {
+        url: string,
+        isLoading: boolean,
+        isLoaded: boolean
+    }>
+```
+A deep signal containing meta information about the resource.
+
+* **url**: The URL from which the resource was last loaded.
+* **isLoading**: Whether the resource is currently being loaded.
+* **isLoaded**: Whether the resource currently in the state was loaded from the server.
+
+## Methods
+
+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>
+```
+Loads the resource from the provided URL. 
+
+* **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`.
+
+### Load the Resource from a Link
+```ts
+load<resourceName>FromLink(linkRoot: unknown, linkName: string) => Promise<void>
+```
+Loads the resource from the provided URL. 
+
+* **linkRoot**: An object containing the link to use.
+* **linkName**: The name of the link to use to load the resource.
+
+### Reload the Resource
+```ts
+reload<resourceName>(): Promise<void>
+```
+Reloads the resource from the last used URL.