Updated documentation for new and changed functionality

danielmurrmann · danielmurrmann · commit a2e5edeb3d77 · 2025-12-18T17:43:58.000+01:00
diff --git a/doc/docs/guide/01-getting-started.md b/doc/docs/guide/01-getting-started.md
@@ -145,10 +145,10 @@ The `withHypermediaResource` feature also adds a property called `<ModelName>Sta
 ```ts
 // A signal toggling between true and false to indicate if the 
 // resource was loaded at least once from the backend
-const isLoadedSignal = this.store.flightModelState.isLoaded;
+const isLoadedSignal = store.flightModelState.isLoaded;
 // A signal toggling between true and false to indicate if an HTTP 
 // request is currently running to get the state of this resource
-const isLoadingSignal = this.store.flightModelState.isLoading;
+const isLoadingSignal = store.flightModelState.isLoading;
 ```
 
 ## 2. Make Mutations to the State
@@ -299,11 +299,11 @@ The `withHypermediaAction` adds a method with the specified name to the store to
 ```ts
 // A signal indicating if the action is available, means the specified 
 // metadata is available in the currently loaded resource.
-const isAvailableSignal = this.store.updateFlightConnectionState.isAvailable;
+const isAvailableSignal = store.updateFlightConnectionState.isAvailable;
 // A signal indicating if a request is currently running. Means a request
 // was sent to the backend and the client is waiting for the response. You
 // can use this e.g. for showing a loading spinner or progress bar in your UI.
-const isExecutingSignal = this.store.updateFlightConnectionState.isExecuting;
+const isExecutingSignal = store.updateFlightConnectionState.isExecuting;
 ```
 
 ## Full Example
diff --git a/doc/docs/guide/03-configuration/01-metadata-provider.md b/doc/docs/guide/03-configuration/01-metadata-provider.md
diff --git a/doc/docs/guide/03-configuration/02-login-redirect.md b/doc/docs/guide/03-configuration/02-login-redirect.md
diff --git a/doc/docs/guide/03-configuration/03-custom-headers.md b/doc/docs/guide/03-configuration/03-custom-headers.md
diff --git a/doc/docs/guide/03-configuration/04-anti-forgery.md b/doc/docs/guide/03-configuration/04-anti-forgery.md
diff --git a/doc/docs/guide/04-loading_features/01-withHypermediaResource.md b/doc/docs/guide/04-loading_features/01-withHypermediaResource.md
@@ -53,7 +53,7 @@ Loads the resource from the provided URL.
 
 ### Load the Resource from a Link
 ```ts
-load<resourceName>FromLink(linkRoot: unknown, linkName: string) => Promise<void>
+load<resourceName>FromLink(linkRoot: unknown, linkName: string): Promise<void>
 ```
 Loads the resource from the provided URL. 
 
diff --git a/doc/docs/guide/04-loading_features/02-withInitialHypermediaResource.md b/doc/docs/guide/04-loading_features/02-withInitialHypermediaResource.md
@@ -54,7 +54,7 @@ Loads the resource from the provided URL.
 
 ### Load the Resource from a Link
 ```ts
-load<resourceName>FromLink(linkRoot: unknown, linkName: string) => Promise<void>
+load<resourceName>FromLink(linkRoot: unknown, linkName: string): Promise<void>
 ```
 Loads the resource from the provided URL. 
 
diff --git a/doc/docs/guide/04-loading_features/03-withLinkedHypermediaResource.md b/doc/docs/guide/04-loading_features/03-withLinkedHypermediaResource.md
@@ -8,8 +8,8 @@ Creates a resource in the store which loads depending on a signal pointing to a
 ## API
 ```ts
 function withLinkedHypermediaResource<ResourceName extends string, TResource, Input extends SignalStoreFeatureResult>(
-    resourceName: ResourceName, initialValue: TResource, linkRootFn: ResourceLinkRootFn<Input>, linkMetaName: string): 
-    SignalStoreFeature;
+    resourceName: ResourceName, initialValue: TResource, linkRootFn: ResourceLinkRootFn<Input>, linkMetaName: string
+    ): SignalStoreFeature;
 ```
 
 * **resourceName**: The name of how the resource will be declared in the store.
diff --git a/doc/docs/guide/05-state_mutation_features/01-withWritableStateCopy.md b/doc/docs/guide/05-state_mutation_features/01-withWritableStateCopy.md
@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+---
+
+# withWritableStateCopy
+Creates a writable copy of selected state signals. The copy is linked to the original signals. If the state original signals change, the writable copy will reflect those changes. Writing to the writable copy will not update the original state signals. Furthermore the wiritable copy is also a deep signal so that you get fine grained reactivity when working with your copy.
+
+## API
+```ts
+function withWritableStateCopy<Input extends SignalStoreFeatureResult, StateSelection extends ObjectWithSignalsForStateCopy>(
+    stateMapFn: (store: StateSignals<Input['state']>) => StateSelection
+): SignalStoreFeature;
+```
+
+* **stateMapFn**: A selector function that receives the store's state signals and returns an object describing which signals (and nested signal objects) should be exposed as a writable copy. The object can also contain nested objects, which will be recursively mapped. The result of the function shall comply with the following type definition:
+
+  ```ts
+  type ObjectWithSignalsForStateCopy = {
+      [key: string]: Signal<unknown> | ObjectWithSignalsForStateCopy;
+  }
+  ```
+
+## Props
+This feature adds a set of properties to the interface of the store that are created with the following type definition:
+
+```ts
+type WritableStateCopy<State extends ObjectWithSignalsForStateCopy> = {
+  [Key in keyof State]: State[Key] extends ObjectWithSignalsForStateCopy ? 
+  WritableStateCopy<State[Key]> 
+  : State[Key] extends Signal<infer InnerType> ? 
+  WritableDeepSignal<InnerType> : never;
+};
+```
+In short this means that each signal you put to the `ObjectWithSignalsForStateCopy` will be mapped to a `WritableDeepSignal<InnerType>`, where `InnerType` is the type contained in the original signal. Nested objects will be recursively mapped to the same shape.
+
diff --git a/doc/docs/guide/05-state_mutation_features/02-withDeepWritableStateCopy.md b/doc/docs/guide/05-state_mutation_features/02-withDeepWritableStateCopy.md
@@ -0,0 +1,39 @@
+---
+sidebar_position: 2
+---
+
+# withExperimentalDeepWritableStateCopy
+Creates a writable copy of selected state signals. The copy is linked to the original signals. If the original state signals change, the writable copy will reflect those changes. Writing to the writable copy will not update the original state signals. Furthermore the wiritable copy is also a deep writable signal so that you get fine grained reactivity when working with your copy and additionally you can write deeply nested properties.
+
+:::warning
+This feature is experimental and might change or be removed in future versions.
+:::
+
+## API
+```ts
+function withExperimentalDeepWritableStateCopy<Input extends SignalStoreFeatureResult, StateSelection extends ObjectWithSignalsForStateCopy>(
+    stateMapFn: (store: StateSignals<Input['state']>) => StateSelection
+): SignalStoreFeature;
+```
+
+* **stateMapFn**: A selector function that receives the store's state signals and returns an object describing which signals (and nested signal objects) should be exposed as a deep writable copy. The object can also contain nested objects, which will be recursively mapped. The result of the function shall comply with the following type definition:
+
+    ```ts
+    type ObjectWithSignalsForDeepStateCopy = {
+        [key: string]: Signal<unknown> | ObjectWithSignalsForDeepStateCopy;
+    }
+    ```
+
+## Props
+This feature adds a set of properties to the interface of the store that are created with the following type definition:
+
+```ts
+type DeepWritableStateCopy<State extends ObjectWithSignalsForDeepStateCopy> = {
+    [Key in keyof State]: State[Key] extends ObjectWithSignalsForDeepStateCopy ? 
+    DeepWritableStateCopy<State[Key]> 
+    : State[Key] extends Signal<infer InnerType> ? 
+    DeepWritableSignal<InnerType> : never;
+};
+```
+In short this means that each signal you put to the `ObjectWithSignalsForDeepStateCopy` will be mapped to a `DeepWritableSignal<InnerType>`, where `InnerType` is the type contained in the original signal. Nested objects will be recursively mapped to the same shape.
+
diff --git a/doc/docs/guide/05-state_mutation_features/03-withDeepWritableStateDelegate.md b/doc/docs/guide/05-state_mutation_features/03-withDeepWritableStateDelegate.md
@@ -0,0 +1,39 @@
+---
+sidebar_position: 3
+---
+
+# withExperimentalDeepWritableStateDelegate
+Create a writable signals that are linked to the original state signals. If the original state signals change, the writable signals will reflect those changes. Writing to the writable signals will directly update the original state signals. Furthermore the wiritable signals are also deep writable signals so that you get fine grained reactivity when working with them and additionally you can write deeply nested properties.
+
+:::warning
+This feature is experimental and might change or be removed in future versions.
+:::
+
+## API
+```ts
+function withExperimentalDeepWritableStateDelegate<Input extends SignalStoreFeatureResult, StateSelection extends ObjectWithDeepWritableSignals>(
+    stateMapFn: SelectStateFn<Input, StateSelection>
+): SignalStoreFeature
+```
+
+* **stateMapFn**: A selector function that receives the store's state delegates as writable signals and returns an object describing which signals (and nested signal objects) should be exposed as a deep writable delegates. The object can also contain nested objects. The result of the function shall comply with the following type definition:
+
+    ```ts
+    type ObjectWithDeepWritableSignals = {
+        [key: string]: WritableSignal<unknown> | DeepWritableSignal<object> | ObjectWithDeepWritableSignals;
+    }
+    ```
+
+## Props
+This feature adds a set of properties to the interface of the store that are created with the following type definition:
+
+```ts
+type DeepWritableStateDelegate<State extends ObjectWithDeepWritableSignals> = {
+    [Key in keyof State]: State[Key] extends ObjectWithDeepWritableSignals ? 
+    DeepWritableStateDelegate<State[Key]> 
+    : State[Key] extends Signal<infer InnerType> ? 
+    DeepWritableSignal<InnerType> : never;
+};
+```
+In short this means that each signal you put to the `ObjectWithDeepWritableSignals` will be mapped to a `DeepWritableStateDelegate<InnerType>`, where `InnerType` is the type contained in the original signal. Nested objects will be recursively mapped to the same shape.
+
diff --git a/doc/docs/guide/06-action_features/01-withHypermediaAction.md b/doc/docs/guide/06-action_features/01-withHypermediaAction.md
@@ -0,0 +1,46 @@
+# withHypermediaAction
+Create an action in the store that can use hypermedia on a single object to perform an action.
+
+## API
+```ts
+function withHypermediaAction<ActionName extends string, Input extends SignalStoreFeatureResult>(
+    actionName: ActionName, linkRootFn: ActionLinkRootFn<Input>, actionMetaName: string
+    ): SignalStoreFeature
+```
+* **actionName**: The name of how the action will be declared in the store.
+* **linkRootFn**: A function that receives the store state and props and returns an object the action shall be connected with and which contains the metadata about the action.
+* **actionMetaName**: The name of how the action is named in the meta information of the selected object.
+
+## State
+With this feature the following state properties are added to the interface of the store:
+
+### Action Meta State
+```ts
+<actionName>State: DeepSignal<
+    {
+        method: '' | 'PUT' | 'POST' | 'DELETE'
+        href: string
+        isAvailable: boolean
+        isExecuting: boolean 
+        hasError: boolean
+        error: unknown
+    }>
+```
+A deep signal containing meta information about the action.
+
+* **method**: The HTTP method that will be used when executing the action.
+* **href**: The URL to which the action will sent the connected object when executed.
+* **isAvailable**: Whether the action is currently available (means the action meta name was found in the metadata of the connected object).
+* **isExecuting**: Whether the action is currently being executed (means a request is in progress).
+* **hasError**: Whether the last execution of the action resulted in an error.
+* **error**: The error that occurred during the last execution of the action or undefined if no error occurred.
+
+## Methods
+
+With this feature the following methods are added to the interface of the store:
+
+### Execute the Action
+```ts
+<actionName>(): Promise<HttpResponse<unknown>>
+```
+Executes the action by sending the connected object to the URL and HTTP method defined in the action metadata.
diff --git a/doc/docs/guide/06-action_features/02-withHypermediaCollectionAction.md b/doc/docs/guide/06-action_features/02-withHypermediaCollectionAction.md
@@ -0,0 +1,60 @@
+# withHypermediaCollectionAction
+Create an action in the store that can use hypermedia on a collection of objects to perform an action.
+
+## API
+```ts
+function withHypermediaCollectionAction<ActionName extends string, Input extends SignalStoreFeatureResult, ArrayResource extends Resource>(
+    actionName: ActionName, 
+    linkRootFn: CollectionActionLinkRootFn<Input, ArrayResource>, 
+    actionMetaName: string, 
+    options: Partial<CollectionActionOptions<ArrayResource>> = {}
+    ): SignalStoreFeature
+```
+* **actionName**: The name of how the action will be declared in the store.
+* **linkRootFn**: A function that receives the store state and props and returns an collection of objects the action shall be connected with and which contain the metadata about the action.
+* **actionMetaName**: The name of how the action is named in the meta information of the selected objects within the collection.
+* **options**: Additional options for the collection action to specifiy which key holds a unique identifier for each object in the collection and which key in the collection objects holds the actual resource data. This parameter has the followning type definition:
+    ```ts
+    type CollectionActionOptions<ArrayResource extends Resource> = {
+        idLookup: (arrayResource: ArrayResource) => CollectionKey;
+        resourceLookup: (arrayResource: ArrayResource) => Resource;
+    }
+    ```
+    If no options are provided, by default the `idLookup` function returns the value of the `id` property of the collection object and the `resourceLookup` function returns the collection object itself.
+
+
+## State
+With this feature the following state properties are added to the interface of the store:
+
+### Action Meta State
+```ts
+<actionName>State: DeepSignal<
+    { 
+        method: Record<CollectionKey, '' | 'PUT' | 'POST' | 'DELETE'>
+        href: Record<CollectionKey, string>
+        isAvailable: Record<CollectionKey, boolean>
+        isExecuting: Record<CollectionKey, boolean> 
+        hasError: Record<CollectionKey, boolean>
+        error: Record<CollectionKey, unknown>
+    }>
+```
+A deep signal containing meta information about the action. Each property is a record where the key is the unique identifier of the object in the collection and the value contains the respective information for that object. The values within the records are as follows:
+
+* **method**: The HTTP method that will be used when executing the action.
+* **href**: The URL to which the action will sent the connected object when executed.
+* **isAvailable**: Whether the action is currently available (means the action meta name was found in the metadata of the connected object).
+* **isExecuting**: Whether the action is currently being executed (means a request is in progress).
+* **hasError**: Whether the last execution of the action resulted in an error.
+* **error**: The error that occurred during the last execution of the action or undefined if no error occurred.
+
+## Methods
+
+With this feature the following methods are added to the interface of the store:
+
+### Execute the Action
+```ts
+<actionName>(id: CollectionKey): Promise<HttpResponse<unknown>>
+```
+Executes the action by sending the a specific object of the collection to the URL with the HTTP method defined in the action metadata.
+
+* **id**: The unique identifier of the object in the collection for which the action shall be executed.
diff --git a/doc/sidebars.ts b/doc/sidebars.ts
@@ -37,6 +37,23 @@ const sidebars: SidebarsConfig = {
         'guide/loading_features/withLinkedHypermediaResource'
       ],
     },
+    {
+      type: 'category',
+      label: 'State Mutation Features',
+      items: [
+        'guide/state_mutation_features/withWritableStateCopy',
+        'guide/state_mutation_features/withDeepWritableStateCopy',
+        'guide/state_mutation_features/withDeepWritableStateDelegate'
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Action Features',
+      items: [
+        'guide/action_features/withHypermediaAction',
+        'guide/action_features/withHypermediaCollectionAction'
+      ],
+    },
     'guide/pipes'
   ]
 
diff --git a/libs/ngrx-hateoas/package.json b/libs/ngrx-hateoas/package.json
@@ -1,10 +1,10 @@
 {
   "name": "@angular-architects/ngrx-hateoas",
-  "version": "21.0.0-beta.0",
+  "version": "21.0.0-rc.0",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
-    "@ngrx/signals": "^21.0.0-beta.0"
+    "@ngrx/signals": "^21.0.0-rc.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
diff --git a/libs/ngrx-hateoas/src/lib/store-features/with-hypermedia-collection-action.ts b/libs/ngrx-hateoas/src/lib/store-features/with-hypermedia-collection-action.ts
@@ -43,10 +43,6 @@ export function generateExecuteHypermediaCollectionActionMethodName(actionName:
     return actionName;
 }
 
-export function generateConnectHypermediaCollectionActionMethodName(actionName: string) {
-    return `_connect${actionName.charAt(0).toUpperCase() + actionName.slice(1)}`;
-}
-
 export type HypermediaCollectionActionMethods<ActionName extends string> = ExecuteHypermediaCollectionActionMethod<ActionName>
 
 type StoreForCollectionActionLinkRoot<Input extends SignalStoreFeatureResult> = StateSignals<Input['state']> & Input['props'];
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -21,7 +21,7 @@
     "@angular/platform-browser": "^21.0.5",
     "@angular/platform-browser-dynamic": "^21.0.5",
     "@angular/router": "^21.0.5",
-    "@ngrx/signals": "21.0.0-beta.0",
+    "@ngrx/signals": "21.0.0-rc.0",
     "bootstrap": "5.3.3",
     "rxjs": "~7.8.2",
     "tslib": "^2.3.0"
