@angular-architects/ngrx-toolkit 20.0.3 → 20.3.0

package/index.d.ts

@@ -1,7 +1,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 } from '@angular/core';
-import { Observable } from 'rxjs';
+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';
 
 /**
@@ -941,5 +941,277 @@ type StoreForFactory<Input extends SignalStoreFeatureResult> = StateSignals<Inpu
  */
 declare function withFeatureFactory<Input extends SignalStoreFeatureResult, Output extends SignalStoreFeatureResult>(factoryFn: (store: StoreForFactory<Input>) => SignalStoreFeature<Input, Output>): SignalStoreFeature<Input, Output>;
 
-export { capitalize, createEffects, createPageArray, createReducer, deriveCallStateKeys, emptyFeature, firstPage, getCallStateKeys, getCollectionArray, getDataServiceKeys, getUndoRedoKeys, gotoPage, nextPage, noPayload, patchState, payload, previousPage, provideDevtoolsConfig, renameDevtoolsName, setError, setLoaded, setLoading, setMaxPageNavigationArrayItems, setPageSize, setResetState, updateState, withCallState, withConditional, withDataService, withDevToolsStub, withDevtools, withDisabledNameIndices, withFeatureFactory, withGlitchTracking, withImmutableState, withIndexedDB, withIndexedDB as withIndexeddb, withLocalStorage, withMapper, withPagination, withRedux, withReset, withSessionStorage, withStorageSync, withUndoRedo };
-export type { CallState, CallStateSignals, CallStateSlice, DataService, DataServiceComputed, DataServiceMethods, DataServiceState, Entity, Filter, NamedCallStateSignals, NamedCallStateSlice, NamedDataServiceComputed, NamedDataServiceMethods, NamedDataServiceState, NamedPaginationServiceSignals, NamedPaginationServiceState, NormalizedUndoRedoOptions, Page, PaginationServiceSignals, PaginationServiceState, ReduxDevtoolsConfig, SetCallState, SetPaginationState, StackItem, SyncConfig };
+type RxJsFlatteningOperator = <T, O extends ObservableInput<unknown>>(project: (value: T, index: number) => O) => OperatorFunction<T, ObservedValueOf<O>>;
+/**
+ * A wrapper for an RxJS flattening operator.
+ * This wrapper informs about whether the operator has exhaust semantics or not.
+ */
+type FlatteningOperator = {
+    rxJsOperator: RxJsFlatteningOperator;
+    exhaustSemantics: boolean;
+};
+declare const switchOp: FlatteningOperator;
+declare const mergeOp: FlatteningOperator;
+declare const concatOp: FlatteningOperator;
+declare const exhaustOp: FlatteningOperator;
+
+type Mutation<P, R> = {
+    (params: P): Promise<MutationResult<R>>;
+    status: Signal<MutationStatus>;
+    isPending: Signal<boolean>;
+    error: Signal<unknown>;
+};
+type MutationsDictionary = Record<string, Mutation<any, any>>;
+type MutationResult<T> = {
+    status: 'success';
+    value: T;
+} | {
+    status: 'error';
+    error: unknown;
+} | {
+    status: 'aborted';
+};
+type MutationStatus = 'idle' | 'pending' | 'error' | 'success';
+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 Func<P, R> = (params: P) => R;
+interface RxMutationOptions<P, R> {
+    operation: Func<P, Observable<R>>;
+    onSuccess?: (result: R, params: P) => void;
+    onError?: (error: unknown, params: P) => void;
+    operator?: FlatteningOperator;
+    injector?: Injector;
+}
+/**
+ * Creates a mutation that leverages RxJS.
+ *
+ * For each mutation the following options can be defined:
+ * - `operation`: A function that defines the mutation logic. It returns an Observable.
+ * - `onSuccess`: A callback that is called when the mutation is successful.
+ * - `onError`: A callback that is called when the mutation fails.
+ * - `operator`: An optional wrapper of an RxJS flattening operator. By default `concat` sematics are used.
+ * - `injector`: An optional Angular injector to use for dependency injection.
+ *
+ * The `operation` is the only mandatory option.
+ *
+ * ```typescript
+ * export type Params = {
+ *   value: number;
+ * };
+ *
+ * export const CounterStore = signalStore(
+ *   { providedIn: 'root' },
+ *   withState({ counter: 0 }),
+ *   withMutations((store) => ({
+ *     increment: rxMutation({
+ *       operation: (params: Params) => {
+ *         return calcSum(store.counter(), params.value);
+ *       },
+ *       operator: concatOp,
+ *       onSuccess: (result) => {
+ *         console.log('result', result);
+ *         patchState(store, { counter: result });
+ *       },
+ *       onError: (error) => {
+ *         console.error('Error occurred:', error);
+ *       },
+ *     }),
+ *   })),
+ * );
+ *
+ * function calcSum(a: number, b: number): Observable<number> {
+ *   return of(a + b);
+ * }
+ * ```
+ *
+ * @param options
+ * @returns
+ */
+declare function rxMutation<P, R>(options: RxMutationOptions<P, R>): Mutation<P, R>;
+
+type ResourceResult<T> = {
+    state: {
+        value: T;
+    };
+    props: {
+        status: Signal<ResourceStatus>;
+        error: Signal<Error | undefined>;
+        isLoading: Signal<boolean>;
+    };
+    methods: {
+        hasValue(): this is Resource<Exclude<T, undefined>>;
+        _reload(): boolean;
+    };
+};
+type ResourceDictionary = Record<string, ResourceRef<unknown>>;
+type NamedResourceResult<T extends ResourceDictionary> = {
+    state: {
+        [Prop in keyof T as `${Prop & string}Value`]: T[Prop]['value'] extends Signal<infer S> ? S : never;
+    };
+    props: {
+        [Prop in keyof T as `${Prop & string}Status`]: Signal<ResourceStatus>;
+    } & {
+        [Prop in keyof T as `${Prop & string}Error`]: Signal<Error | undefined>;
+    } & {
+        [Prop in keyof T as `${Prop & string}IsLoading`]: Signal<boolean>;
+    };
+    methods: {
+        [Prop in keyof T as `${Prop & string}HasValue`]: () => this is Resource<Exclude<T[Prop]['value'], undefined>>;
+    } & {
+        [Prop in keyof T as `_${Prop & string}Reload`]: () => boolean;
+    };
+};
+/**
+ * @experimental
+ * @description
+ *
+ * Integrates a `Resource` into the SignalStore and makes the store instance
+ * implement the `Resource` interface.
+ *
+ * The resource’s value is stored under the `value` key in the state
+ * and is exposed as a `DeepSignal`.
+ *
+ * It can also be updated via `patchState`.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * const UserStore = signalStore(
+ *   withState({ userId: undefined as number | undefined }),
+ *   withResource(({ userId }) =>
+ *     httpResource<User>(() =>
+ *       userId === undefined ? undefined : `/users/${userId}`
+ *     )
+ *   )
+ * );
+ *
+ * const userStore = new UserStore();
+ * userStore.value(); // User | undefined
+ * ```
+ *
+ * @param resourceFactory A factory function that receives the store's state signals,
+ * methods, and props. Needs to return a `ResourceRef`.
+ */
+declare function withResource<Input extends SignalStoreFeatureResult, ResourceValue>(resourceFactory: (store: Input['props'] & Input['methods'] & StateSignals<Input['state']>) => ResourceRef<ResourceValue>): SignalStoreFeature<Input, ResourceResult<ResourceValue>>;
+/**
+ * @experimental
+ * @description
+ *
+ * Integrates multiple resources into the SignalStore. Each resource is
+ * registered by name, which is used as a prefix when spreading the members
+ * of `Resource` onto the store.
+ *
+ * Each resource’s value is part of the state, stored under the `value` key
+ * with the resource name as prefix. Values are exposed as `DeepSignal`s and
+ * can be updated via `patchState`.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * const UserStore = signalStore(
+ *   withState({ userId: undefined as number | undefined }),
+ *   withResource(({ userId }) => ({
+ *     list: httpResource<User[]>(() => '/users', { defaultValue: [] }),
+ *     detail: httpResource<User>(() =>
+ *       userId === undefined ? undefined : `/users/${userId}`
+ *     ),
+ *   }))
+ * );
+ *
+ * const userStore = new UserStore();
+ * userStore.listValue(); // []
+ * userStore.detailValue(); // User | undefined
+ * ```
+ *
+ * @param resourceFactory A factory function that receives the store's props,
+ * methods, and state signals. It must return a `Record<string, ResourceRef>`.
+ */
+declare function withResource<Input extends SignalStoreFeatureResult, Dictionary extends ResourceDictionary>(resourceFactory: (store: Input['props'] & Input['methods'] & StateSignals<Input['state']>) => Dictionary): SignalStoreFeature<Input, NamedResourceResult<Dictionary>>;
+type NamedResource<Name extends string, T> = {
+    [Prop in `${Name}Value`]: Signal<T>;
+} & {
+    [Prop in `${Name}Status`]: Signal<ResourceStatus>;
+} & {
+    [Prop in `${Name}Error`]: Signal<Error | undefined>;
+} & {
+    [Prop in `${Name}IsLoading`]: Signal<boolean>;
+} & {
+    [Prop in `${Name}HasValue`]: () => boolean;
+};
+type IsValidResourceName<Name extends string, Store extends Record<string, unknown>> = Store[`${Name}Value`] extends Signal<infer S> ? Store extends NamedResource<Name, S> ? true : false : false;
+type ResourceNames<Store extends Record<string, unknown>> = keyof {
+    [Prop in keyof Store as Prop extends `${infer Name}Value` ? IsValidResourceName<Name, Store> extends true ? Name : never : never]: Store[Prop] extends Signal<infer S> ? S : never;
+};
+type MappedResource<Store extends Record<string, unknown>, Name extends string> = Resource<Store[`${Name}Value`] extends Signal<infer S> ? S : never>;
+/**
+ * @experimental
+ * @description
+ *
+ * Maps a named resource to type `Resource<T>`.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * const store = signalStore(
+ *   withState({ userId: undefined as number | undefined }),
+ *   withResource(({ userId }) => ({
+ *     user: httpResource<User[]>(() => '/users', { defaultValue: [] }),
+ *   }))
+ * );
+ * const userResource = mapToResource(store, 'user');
+ * userResource satisfies Resource<User[]>;
+ * ```
+ *
+ * @param store The store instance to map the resource to.
+ * @param name The name of the resource to map.
+ * @returns `ResourceRef<T>`
+ */
+declare function mapToResource<Name extends ResourceNames<Store>, Store extends Record<string, unknown>>(store: Store, name: Name): MappedResource<Store, Name>;
+
+export { capitalize, concatOp, createEffects, createPageArray, createReducer, deriveCallStateKeys, emptyFeature, exhaustOp, firstPage, getCallStateKeys, getCollectionArray, getDataServiceKeys, getUndoRedoKeys, gotoPage, 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, Func, MethodsDictionary, Mutation, MutationResult, MutationStatus, NamedCallStateSignals, NamedCallStateSlice, NamedDataServiceComputed, NamedDataServiceMethods, NamedDataServiceState, NamedMutationResult, NamedPaginationServiceSignals, NamedPaginationServiceState, NormalizedUndoRedoOptions, Page, PaginationServiceSignals, PaginationServiceState, ReduxDevtoolsConfig, RxMutationOptions, SetCallState, SetPaginationState, StackItem, SyncConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-architects/ngrx-toolkit",
-  "version": "20.0.3",
+  "version": "20.3.0",
   "license": "MIT",
   "repository": {
     "type": "GitHub",