@angular-architects/ngrx-toolkit 20.4.2 → 20.6.0

package/index.d.ts

@@ -2,7 +2,7 @@ import * as _ngrx_signals from '@ngrx/signals';
 import { StateSource, patchState as patchState$1, WritableStateSource, PartialStateUpdater, SignalStoreFeature, EmptyFeatureResult, SignalStoreFeatureResult, StateSignals } from '@ngrx/signals';
 import { ValueProvider, Signal, ProviderToken, WritableSignal, Injector, ResourceStatus, Resource, ResourceRef } from '@angular/core';
 import { Observable, ObservableInput, OperatorFunction, ObservedValueOf } from 'rxjs';
-import { EntityId, NamedEntityState } from '@ngrx/signals/entities';
+import { EntityId, NamedEntityState, EntityState as EntityState$1, EntityProps, NamedEntityProps } from '@ngrx/signals/entities';
 import { HttpHeaders, HttpContext, HttpParams, HttpProgressEvent } from '@angular/common/http';
 
 /**
@@ -53,7 +53,7 @@ type DevtoolsOptions = {
  * We use them (function calls) instead of a config object,
  * because of tree-shaking.
  */
-type DevtoolsFeature = {
+type DevtoolsFeature$1 = {
     [DEVTOOLS_FEATURE]: true;
 } & Partial<DevtoolsOptions>;
 
@@ -83,7 +83,7 @@ type DevtoolsFeature = {
  * ```
  *
  */
-declare function withDisabledNameIndices(): DevtoolsFeature;
+declare function withDisabledNameIndices(): DevtoolsFeature$1;
 
 /**
  * It tracks all state changes of the State, including intermediary updates
@@ -114,7 +114,7 @@ declare function withDisabledNameIndices(): DevtoolsFeature;
  *
  * Without `withGlitchTracking`, the DevTools would only show the final value of 3.
  */
-declare function withGlitchTracking(): DevtoolsFeature;
+declare function withGlitchTracking(): DevtoolsFeature$1;
 
 /**
  * Allows you to define a function to map the state.
@@ -143,7 +143,7 @@ declare function withGlitchTracking(): DevtoolsFeature;
  *
  * @param map function which maps the state
  */
-declare function withMapper<State extends object>(map: (state: State) => Record<string, unknown>): DevtoolsFeature;
+declare function withMapper<State extends object>(map: (state: State) => Record<string, unknown>): DevtoolsFeature$1;
 
 /**
  * Renames the name of a store how it appears in the Devtools.
@@ -166,6 +166,7 @@ declare const patchState: PatchFn;
  */
 declare function updateState<State extends object>(stateSource: WritableStateSource<State>, action: string, ...updaters: Array<Partial<NoInfer<State>> | PartialStateUpdater<NoInfer<State>>>): void;
 
+type DevtoolsFeature = DevtoolsFeature$1;
 declare global {
     interface Window {
         __REDUX_DEVTOOLS_EXTENSION__: ReduxDevtoolsExtension | undefined;
@@ -1049,54 +1050,6 @@ interface RxMutationOptions<Parameter, Result> {
  */
 declare function rxMutation<Parameter, Result>(optionsOrOperation: RxMutationOptions<Parameter, Result> | Operation<Parameter, Observable<Result>>): Mutation<Parameter, Result>;
 
-type MutationsDictionary = Record<string, Mutation<any, any>>;
-type MethodsDictionary = Record<string, Function>;
-type NamedMutationProps<T extends MutationsDictionary> = {
-    [Prop in keyof T as `${Prop & string}IsPending`]: Signal<boolean>;
-} & {
-    [Prop in keyof T as `${Prop & string}Status`]: Signal<MutationStatus>;
-} & {
-    [Prop in keyof T as `${Prop & string}Error`]: Signal<Error | undefined>;
-};
-type NamedMutationMethods<T extends MutationsDictionary> = {
-    [Prop in keyof T as `${Prop & string}`]: T[Prop] extends Mutation<infer P, infer R> ? Mutation<P, R> : never;
-};
-type NamedMutationResult<T extends MutationsDictionary> = EmptyFeatureResult & {
-    props: NamedMutationProps<T>;
-    methods: NamedMutationMethods<T>;
-};
-/**
- * Adds mutation methods to the store. Also, for each mutation method, several
- * Signals are added informing about the mutation's status and errors.
- *
- * ```typescript
- * export type Params = {
- *   value: number;
- * };
- *
- * export const CounterStore = signalStore(
- *   { providedIn: 'root' },
- *   withState({ counter: 0 }),
- *   withMutations((store) => ({
- *     increment: rxMutation({ ... }),
- *   })),
- * );
- * ```
- *
- * There are several types of mutations. In the example shown, an {@link module:rx-mutation.rxMutation | rxMutation}
- * leveraging RxJS is used
- *
- * For the defined `increment` mutation, several the following properties and
- * methods are added to the store:
- * - `increment(params: Params): Promise<MutationResult<number>>`: The mutation method.
- * - `incrementIsPending`: A signal indicating if the mutation is in progress.
- * - `incrementStatus`: A signal representing the current status of the mutation.
- * - `incrementError`: A signal containing any error that occurred during the mutation.
- *
- * @param mutationsFactory
- */
-declare function withMutations<Input extends SignalStoreFeatureResult, Result extends MutationsDictionary>(mutationsFactory: (store: Input['props'] & Input['methods'] & WritableStateSource<Input['state']> & StateSignals<Input['state']>) => Result): SignalStoreFeature<Input, NamedMutationResult<Result>>;
-
 type ResourceResult<T> = {
     state: {
         value: T;
@@ -1236,6 +1189,165 @@ type MappedResource<Store extends Record<string, unknown>, Name extends string>
  */
 declare function mapToResource<Name extends ResourceNames<Store>, Store extends Record<string, unknown>>(store: Store, name: Name): MappedResource<Store, Name>;
 
+/**
+ * @experimental
+ * @description
+ *
+ * Integrates array-based `Resource` data into Entity-style state for NgRx SignalStore.
+ * This feature builds on {@link withResource} to provide an entity view over
+ * array resources.
+ *
+ * - For a single (unnamed) resource: exposes `value`, `status`, `error`, `isLoading`
+ *   from the underlying resource (via `withResource`), and derives
+ *   `ids`, `entityMap`, and `entities` via `withLinkedState`/`withComputed`.
+ * - For multiple (named) resources: registers each resource by name and exposes
+ *   the same members prefixed with the resource name, e.g. `todosIds`,
+ *   `todosEntityMap`, `todosEntities`, along with `todosValue`, `todosStatus`, etc.
+ *
+ * No effects are used. All derived signals are linked to the resource's value
+ * through `withLinkedState`, so entity updaters such as `addEntity`, `updateEntity`,
+ * and `removeEntity` mutate the store's entity view without directly writing to the
+ * resource. The source of truth remains the resource value.
+ *
+ * @usageNotes
+ *
+ * Unnamed resource example:
+ *
+ * ```ts
+ * type Todo = { id: number; title: string; completed: boolean };
+ *
+ * const Store = signalStore(
+ *   { providedIn: 'root' },
+ *   withEntityResources(() =>
+ *     resource({ loader: () => Promise.resolve([] as Todo[]), defaultValue: [] }),
+ *   ),
+ * );
+ *
+ * const store = TestBed.inject(Store);
+ * store.status();    // 'idle' | 'loading' | 'resolved' | 'error'
+ * store.value();     // Todo[]
+ * store.ids();       // EntityId[]
+ * store.entityMap(); // Record<EntityId, Todo>
+ * store.entities();  // Todo[]
+ *
+ * // Works with @ngrx/signals/entities updaters
+ * patchState(store, addEntity({ id: 1, title: 'X', completed: false }));
+ * ```
+ *
+ * Named resources example:
+ *
+ * ```ts
+ * const Store = signalStore(
+ *   { providedIn: 'root' },
+ *   withEntityResources(() => ({
+ *     todos: resource({ loader: () => Promise.resolve([] as Todo[]), defaultValue: [] }),
+ *     projects: resource({ loader: () => Promise.resolve([] as { id: number; name: string }[]), defaultValue: [] }),
+ *   })),
+ * );
+ *
+ * const store = TestBed.inject(Store);
+ * store.todosValue();
+ * store.todosIds();
+ * store.todosEntityMap();
+ * store.todosEntities();
+ * patchState(store, addEntity({ id: 2, title: 'Y', completed: true }, { collection: 'todos' }));
+ * ```
+ *
+ * @see {@link withResource}
+ */
+declare function withEntityResources<Input extends SignalStoreFeatureResult, Entity extends {
+    id: EntityId;
+}>(resourceFactory: (store: Input['props'] & Input['methods'] & StateSignals<Input['state']>) => ResourceRef<readonly Entity[] | Entity[] | undefined>): SignalStoreFeature<Input, EntityResourceResult<Entity>>;
+declare function withEntityResources<Input extends SignalStoreFeatureResult, Dictionary extends EntityDictionary>(resourceFactory: (store: Input['props'] & Input['methods'] & StateSignals<Input['state']>) => Dictionary): SignalStoreFeature<Input, NamedEntityResourceResult<Dictionary>>;
+/**
+ * @internal
+ * @description
+ *
+ * Type composition notes: we intentionally do not duplicate or re-declare
+ * types that already exist in `@ngrx/signals/entities` or in this library's
+ * `with-resource` feature. Instead, we compose the resulting API via
+ * intersections of those public contracts.
+ *
+ * Rationale:
+ * - Keeps our types in sync with upstream sources and avoids drift.
+ * - Reduces maintenance overhead and duplication.
+ * - Ensures consumers benefit automatically from upstream typing fixes.
+ *
+ * Concretely:
+ * - For unnamed resources we return `ResourceResult<Entity>` intersected with
+ *   `EntityState<Entity>` and `EntityProps<Entity>`.
+ * - For named resources we return `NamedResourceResult<T>` intersected with
+ *   `NamedEntityState<E, Name>` and `NamedEntityProps<E, Name>` for each entry.
+ */
+type EntityResourceResult<Entity> = {
+    state: ResourceResult<Entity>['state'] & EntityState$1<Entity>;
+    props: ResourceResult<Entity>['props'] & EntityProps<Entity>;
+    methods: ResourceResult<Entity>['methods'];
+};
+type ArrayElement<T> = T extends readonly (infer E)[] | (infer E)[] ? E : never;
+type InferEntityFromSignal<T> = T extends Signal<infer V> ? ArrayElement<V> : never;
+type MergeUnion<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type EntityDictionary = Record<string, ResourceRef<readonly unknown[] | unknown[] | undefined>>;
+type MergeNamedEntityStates<T extends EntityDictionary> = MergeUnion<{
+    [Prop in keyof T]: Prop extends string ? InferEntityFromSignal<T[Prop]['value']> extends infer E ? E extends never ? never : NamedEntityState<E, Prop> : never : never;
+}[keyof T]>;
+type MergeNamedEntityProps<T extends EntityDictionary> = MergeUnion<{
+    [Prop in keyof T]: Prop extends string ? InferEntityFromSignal<T[Prop]['value']> extends infer E ? E extends never ? never : NamedEntityProps<E, Prop> : never : never;
+}[keyof T]>;
+type NamedEntityResourceResult<T extends EntityDictionary> = {
+    state: NamedResourceResult<T>['state'] & MergeNamedEntityStates<T>;
+    props: NamedResourceResult<T>['props'] & MergeNamedEntityProps<T>;
+    methods: NamedResourceResult<T>['methods'];
+};
+
+type MutationsDictionary = Record<string, Mutation<any, any>>;
+type MethodsDictionary = Record<string, Function>;
+type NamedMutationProps<T extends MutationsDictionary> = {
+    [Prop in keyof T as `${Prop & string}IsPending`]: Signal<boolean>;
+} & {
+    [Prop in keyof T as `${Prop & string}Status`]: Signal<MutationStatus>;
+} & {
+    [Prop in keyof T as `${Prop & string}Error`]: Signal<Error | undefined>;
+};
+type NamedMutationMethods<T extends MutationsDictionary> = {
+    [Prop in keyof T as `${Prop & string}`]: T[Prop] extends Mutation<infer P, infer R> ? Mutation<P, R> : never;
+};
+type NamedMutationResult<T extends MutationsDictionary> = EmptyFeatureResult & {
+    props: NamedMutationProps<T>;
+    methods: NamedMutationMethods<T>;
+};
+/**
+ * Adds mutation methods to the store. Also, for each mutation method, several
+ * Signals are added informing about the mutation's status and errors.
+ *
+ * ```typescript
+ * export type Params = {
+ *   value: number;
+ * };
+ *
+ * export const CounterStore = signalStore(
+ *   { providedIn: 'root' },
+ *   withState({ counter: 0 }),
+ *   withMutations((store) => ({
+ *     increment: rxMutation({ ... }),
+ *   })),
+ * );
+ * ```
+ *
+ * There are several types of mutations. In the example shown, an {@link module:rx-mutation.rxMutation | rxMutation}
+ * leveraging RxJS is used
+ *
+ * For the defined `increment` mutation, several the following properties and
+ * methods are added to the store:
+ * - `increment(params: Params): Promise<MutationResult<number>>`: The mutation method.
+ * - `incrementIsPending`: A signal indicating if the mutation is in progress.
+ * - `incrementStatus`: A signal representing the current status of the mutation.
+ * - `incrementError`: A signal containing any error that occurred during the mutation.
+ *
+ * @param mutationsFactory
+ */
+declare function withMutations<Input extends SignalStoreFeatureResult, Result extends MutationsDictionary>(mutationsFactory: (store: Input['props'] & Input['methods'] & WritableStateSource<Input['state']> & StateSignals<Input['state']>) => Result): SignalStoreFeature<Input, NamedMutationResult<Result>>;
+
 type HttpMutationRequest = {
     url: string;
     method: string;
@@ -1319,5 +1431,5 @@ type HttpMutation<Parameter, Result> = Mutation<Parameter, Result> & {
  */
 declare function httpMutation<Parameter, Result>(optionsOrRequest: HttpMutationOptions<Parameter, Result> | ((param: Parameter) => HttpMutationRequest)): HttpMutation<Parameter, Result>;
 
-export { capitalize, concatOp, createEffects, createPageArray, createReducer, deriveCallStateKeys, emptyFeature, exhaustOp, firstPage, getCallStateKeys, getCollectionArray, getDataServiceKeys, getUndoRedoKeys, gotoPage, httpMutation, mapToResource, mergeOp, nextPage, noPayload, patchState, payload, previousPage, provideDevtoolsConfig, renameDevtoolsName, rxMutation, setError, setLoaded, setLoading, setMaxPageNavigationArrayItems, setPageSize, setResetState, switchOp, updateState, withCallState, withConditional, withDataService, withDevToolsStub, withDevtools, withDisabledNameIndices, withFeatureFactory, withGlitchTracking, withImmutableState, withIndexedDB, withIndexedDB as withIndexeddb, withLocalStorage, withMapper, withMutations, withPagination, withRedux, withReset, withResource, withSessionStorage, withStorageSync, withUndoRedo };
-export type { CallState, CallStateSignals, CallStateSlice, DataService, DataServiceComputed, DataServiceMethods, DataServiceState, Entity, Filter, HttpMutation, HttpMutationOptions, HttpMutationRequest, MethodsDictionary, Mutation, MutationResult, MutationStatus, NamedCallStateSignals, NamedCallStateSlice, NamedDataServiceComputed, NamedDataServiceMethods, NamedDataServiceState, NamedMutationResult, NamedPaginationServiceSignals, NamedPaginationServiceState, NormalizedUndoRedoOptions, Operation, Page, PaginationServiceSignals, PaginationServiceState, ReduxDevtoolsConfig, RxMutationOptions, SetCallState, SetPaginationState, StackItem, SyncConfig };
+export { capitalize, concatOp, createEffects, createPageArray, createReducer, deriveCallStateKeys, emptyFeature, exhaustOp, firstPage, getCallStateKeys, getCollectionArray, getDataServiceKeys, getUndoRedoKeys, gotoPage, httpMutation, mapToResource, mergeOp, nextPage, noPayload, patchState, payload, previousPage, provideDevtoolsConfig, renameDevtoolsName, rxMutation, setError, setLoaded, setLoading, setMaxPageNavigationArrayItems, setPageSize, setResetState, switchOp, updateState, withCallState, withConditional, withDataService, withDevToolsStub, withDevtools, withDisabledNameIndices, withEntityResources, withFeatureFactory, withGlitchTracking, withImmutableState, withIndexedDB, withIndexedDB as withIndexeddb, withLocalStorage, withMapper, withMutations, withPagination, withRedux, withReset, withResource, withSessionStorage, withStorageSync, withUndoRedo };
+export type { CallState, CallStateSignals, CallStateSlice, DataService, DataServiceComputed, DataServiceMethods, DataServiceState, DevtoolsFeature, Entity, EntityDictionary, EntityResourceResult, Filter, HttpMutation, HttpMutationOptions, HttpMutationRequest, MethodsDictionary, Mutation, MutationResult, MutationStatus, NamedCallStateSignals, NamedCallStateSlice, NamedDataServiceComputed, NamedDataServiceMethods, NamedDataServiceState, NamedEntityResourceResult, NamedMutationResult, NamedPaginationServiceSignals, NamedPaginationServiceState, NormalizedUndoRedoOptions, Operation, Page, PaginationServiceSignals, PaginationServiceState, ReduxDevtoolsConfig, RxMutationOptions, SetCallState, SetPaginationState, StackItem, SyncConfig };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@angular-architects/ngrx-toolkit",
-  "version": "20.4.2",
+  "version": "20.6.0",
   "license": "MIT",
   "repository": {
     "type": "GitHub",
     "url": "https://github.com/angular-architects/ngrx-toolkit"
   },
   "peerDependencies": {
-    "@angular/core": "^20.0.0",
-    "@angular/common": "^20.0.0",
-    "@ngrx/signals": "^20.0.0",
-    "@ngrx/store": "^20.0.0",
+    "@angular/core": "^20.0.0 || ^21.0.0",
+    "@angular/common": "^20.0.0 || ^21.0.0",
+    "@ngrx/signals": "^20.0.0 || ^21.0.0",
+    "@ngrx/store": "^20.0.0 || ^21.0.0",
     "rxjs": "^7.0.0"
   },
   "peerDependenciesMeta": {