@angular-architects/ngrx-toolkit 20.3.0 → 20.4.0

package/index.d.ts

@@ -3,6 +3,7 @@ import { StateSource, patchState as patchState$1, WritableStateSource, PartialSt
 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 { HttpHeaders, HttpContext, HttpParams, HttpProgressEvent } from '@angular/common/http';
 
 /**
  * Provides the configuration options for connecting to the Redux DevTools Extension.
@@ -955,16 +956,9 @@ 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> = {
+type MutationResult<Result> = {
     status: 'success';
-    value: T;
+    value: Result;
 } | {
     status: 'error';
     error: unknown;
@@ -972,6 +966,90 @@ type MutationResult<T> = {
     status: 'aborted';
 };
 type MutationStatus = 'idle' | 'pending' | 'error' | 'success';
+type Mutation<Parameter, Result> = {
+    (params: Parameter): Promise<MutationResult<Result>>;
+    status: Signal<MutationStatus>;
+    value: Signal<Result | undefined>;
+    isPending: Signal<boolean>;
+    isSuccess: Signal<boolean>;
+    error: Signal<unknown>;
+    hasValue(): this is Mutation<Exclude<Parameter, undefined>, Result>;
+};
+
+type Operation<Parameter, Result> = (param: Parameter) => Result;
+interface RxMutationOptions<Parameter, Result> {
+    operation: Operation<Parameter, Observable<Result>>;
+    onSuccess?: (result: Result, param: Parameter) => void;
+    onError?: (error: unknown, param: Parameter) => 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.
+ *
+ * The returned mutation can be called as an async function and returns a Promise.
+ * This promise informs about whether the mutation was successful, failed, or aborted
+ * (due to switchMap or exhaustMap semantics).
+ *
+ * The mutation also provides several Signals such as error, status or isPending (see below).
+ *
+ * Example usage without Store:
+ *
+ * ```typescript
+ * const counterSignal = signal(0);
+ *
+ * const increment = rxMutation({
+ *   operation: (param: Param) => {
+ *     return calcSum(this.counterSignal(), param.value);
+ *   },
+ *   operator: concatOp,
+ *   onSuccess: (result) => {
+ *     this.counterSignal.set(result);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Error occurred:', error);
+ *   },
+ * });
+ *
+ * const error = increment.error;
+ * const isPending = increment.isPending;
+ * const status = increment.status;
+ * const value = increment.value;
+ * const hasValue = increment.hasValue;
+ *
+ * async function incrementCounter() {
+ *     const result = await increment({ value: 1 });
+ *     if (result.status === 'success') {
+ *       console.log('Success:', result.value);
+ *     }
+ *     if (result.status === 'error') {
+ *       console.log('Error:', result.error);
+ *     }
+ *     if (result.status === 'aborted') {
+ *       console.log('Operation aborted');
+ *     }
+ * }
+ *
+ * function calcSum(a: number, b: number): Observable<number> {
+ *   return of(result).pipe(delay(500));
+ * }
+ * ```
+ *
+ * @param options
+ * @returns the actual mutation function along tracking data as properties/methods
+ */
+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>;
@@ -1019,61 +1097,6 @@ type NamedMutationResult<T extends MutationsDictionary> = EmptyFeatureResult & {
  */
 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;
@@ -1213,5 +1236,88 @@ 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>;
 
-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 };
+type HttpMutationRequest = {
+    url: string;
+    method: string;
+    body?: unknown;
+    headers?: HttpHeaders | Record<string, string | string[]>;
+    context?: HttpContext;
+    reportProgress?: boolean;
+    params?: HttpParams | Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>;
+    withCredentials?: boolean;
+    credentials?: RequestCredentials;
+    keepalive?: boolean;
+    priority?: RequestPriority;
+    cache?: RequestCache;
+    mode?: RequestMode;
+    redirect?: RequestRedirect;
+    transferCache?: {
+        includeHeaders?: string[];
+    } | boolean;
+};
+type HttpMutationOptions<Parameter, Result> = Omit<RxMutationOptions<Parameter, NoInfer<Result>>, 'operation'> & {
+    request: (param: Parameter) => HttpMutationRequest;
+    parse?: (response: unknown) => Result;
+};
+type HttpMutation<Parameter, Result> = Mutation<Parameter, Result> & {
+    uploadProgress: Signal<HttpProgressEvent | undefined>;
+    downloadProgress: Signal<HttpProgressEvent | undefined>;
+    headers: Signal<HttpHeaders | undefined>;
+    statusCode: Signal<string | undefined>;
+};
+/**
+ * Creates an HTTP mutation.
+ *
+ * ```typescript
+ * export type Params = {
+ *   value: number;
+ * };
+ *
+ * export type CounterResponse = {
+ *   // httpbin.org echos the request using the
+ *   // json property
+ *   json: { counter: number };
+ * };
+ *
+ * const simpleSaveUser = httpMutation({
+ *   request: (userData: AddUserEntry) => ({
+ *     url: 'api/users',
+ *     body: userData,
+ *   }),
+ *   parse: Boolean,
+ * })
+ *
+ * const saveUser = httpMutation({
+ *   request: (p: Params) => ({
+ *     url: `https://httpbin.org/post`,
+ *     method: 'POST',
+ *     body: { counter: p.value },
+ *     headers: { 'Content-Type': 'application/json' },
+ *   }),
+ *   onSuccess: (response: CounterResponse) => {
+ *     console.log('Counter sent to server:', response);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Failed to send counter:', error);
+ *   },
+ * });
+ *
+ * const result = await this.saveUser({ value: 17 });
+ * if (result.status === 'success') {
+ *   console.log('Successfully saved to server:', result.value);
+ * }
+ * else if (result.status === 'error') {
+ *   console.log('Failed to save:', result.error);
+ * }
+ * else {
+ *   console.log('Operation aborted');
+ * }
+ * ```
+ *
+ * @param options The options for the HTTP mutation.
+ * @returns The HTTP mutation.
+ */
+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, NamedCallStateSignals, NamedCallStateSlice, NamedDataServiceComputed, NamedDataServiceMethods, NamedDataServiceState, NamedMutationResult, NamedPaginationServiceSignals, NamedPaginationServiceState, NormalizedUndoRedoOptions, Operation, Page, PaginationServiceSignals, PaginationServiceState, ReduxDevtoolsConfig, RxMutationOptions, SetCallState, SetPaginationState, StackItem, SyncConfig };

package/package.json

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