@angular-architects/ngrx-toolkit 19.2.3 → 19.4.0

package/src/lib/mutation/http-mutation.spec.ts

@@ -0,0 +1,473 @@
+import { HttpEventType, provideHttpClient } from '@angular/common/http';
+import {
+  HttpTestingController,
+  provideHttpClientTesting,
+} from '@angular/common/http/testing';
+import { signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { HttpMutation, httpMutation } from './http-mutation';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+interface CreateUserRequest {
+  name: string;
+  email: string;
+}
+
+interface AddUserEntry {
+  firstname: string;
+  name: string;
+  email: string;
+}
+
+describe('httpMutation', () => {
+  let httpTestingController: HttpTestingController;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [provideHttpClient(), provideHttpClientTesting()],
+    });
+
+    httpTestingController = TestBed.inject(HttpTestingController);
+  });
+
+  afterEach(() => {
+    httpTestingController.verify();
+  });
+
+  it('should create httpMutation instance', () => {
+    const createUser = TestBed.runInInjectionContext(() =>
+      httpMutation<CreateUserRequest, User>({
+        request: (userData) => ({
+          url: '/api/users',
+          method: 'POST',
+          body: userData,
+        }),
+      }),
+    );
+
+    expect(createUser).toBeDefined();
+    expect(createUser.status()).toBe('idle');
+    expect(createUser.isPending()).toBe(false);
+  });
+
+  it('should perform successful POST request using shorthand syntax', () => {
+    const createUser = TestBed.runInInjectionContext(() =>
+      httpMutation<CreateUserRequest, User>((userData) => ({
+        url: '/api/users',
+        method: 'POST',
+        body: userData,
+      })),
+    );
+
+    expect(createUser.status()).toBe('idle');
+    expect(createUser.isPending()).toBe(false);
+
+    const newUser = { name: 'John Doe', email: 'john@example.com' };
+    createUser(newUser);
+
+    expect(createUser.isPending()).toBe(true);
+    expect(createUser.status()).toBe('pending');
+
+    const req = httpTestingController.expectOne('/api/users');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual(newUser);
+
+    const mockUser: User = {
+      id: 1,
+      name: 'John Doe',
+      email: 'john@example.com',
+    };
+    req.flush(mockUser);
+
+    expect(createUser.status()).toBe('success');
+    expect(createUser.isPending()).toBe(false);
+    expect(createUser.value()).toEqual(mockUser);
+  });
+
+  it('should perform successful POST request', () => {
+    const userSignal = signal<User | null>(null);
+
+    const createUser = TestBed.runInInjectionContext(() =>
+      httpMutation<CreateUserRequest, User>({
+        request: (userData) => ({
+          url: '/api/users',
+          method: 'POST',
+          body: userData,
+        }),
+        onSuccess: (user) => {
+          userSignal.set(user);
+        },
+      }),
+    );
+
+    expect(createUser.status()).toBe('idle');
+    expect(createUser.isPending()).toBe(false);
+
+    const newUser = { name: 'John Doe', email: 'john@example.com' };
+    createUser(newUser);
+
+    expect(createUser.isPending()).toBe(true);
+    expect(createUser.status()).toBe('pending');
+
+    const req = httpTestingController.expectOne('/api/users');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual(newUser);
+
+    const mockUser: User = {
+      id: 1,
+      name: 'John Doe',
+      email: 'john@example.com',
+    };
+    req.flush(mockUser);
+
+    expect(createUser.status()).toBe('success');
+    expect(createUser.isPending()).toBe(false);
+    expect(createUser.value()).toEqual(mockUser);
+    expect(userSignal()).toEqual(mockUser);
+  });
+
+  it('should handle HTTP errors', () => {
+    let errorCaptured: unknown = null;
+
+    const createUser = TestBed.runInInjectionContext(() =>
+      httpMutation<CreateUserRequest, User>({
+        request: (userData) => ({
+          url: '/api/users',
+          method: 'POST',
+          body: userData,
+        }),
+        onError: (error) => {
+          errorCaptured = error;
+        },
+      }),
+    );
+
+    const invalidUser = { name: '', email: 'invalid-email' };
+    createUser(invalidUser);
+
+    const req = httpTestingController.expectOne('/api/users');
+    expect(req.request.body).toEqual(invalidUser);
+    req.flush(
+      { message: 'Validation failed' },
+      { status: 400, statusText: 'Bad Request' },
+    );
+
+    expect(createUser.status()).toBe('error');
+    expect(createUser.error()).toBeDefined();
+    expect(errorCaptured).toBeDefined();
+  });
+
+  it('should perform successful POST request with upload and download', () => {
+    const createdUserSignal = signal<User | null>(null);
+
+    const createUser = TestBed.runInInjectionContext(() =>
+      httpMutation<CreateUserRequest, User>({
+        request: (userData) => ({
+          url: '/api/users',
+          method: 'POST',
+          body: userData,
+          headers: { 'Content-Type': 'application/json' },
+          reportProgress: true,
+        }),
+        onSuccess: (user) => {
+          createdUserSignal.set(user);
+        },
+      }),
+    );
+
+    expect(createUser.status()).toBe('idle');
+    expect(createUser.uploadProgress()).toBeUndefined();
+    expect(createUser.downloadProgress()).toBeUndefined();
+
+    const newUser = { name: 'Jane Doe', email: 'jane@example.com' };
+    createUser(newUser);
+
+    expect(createUser.isPending()).toBe(true);
+    expect(createUser.status()).toBe('pending');
+
+    const req = httpTestingController.expectOne('/api/users');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual(newUser);
+    expect(req.request.headers.get('Content-Type')).toBe('application/json');
+
+    req.event({
+      type: HttpEventType.UploadProgress,
+      loaded: 50,
+      total: 100,
+    });
+
+    expect(createUser.uploadProgress()).toEqual({
+      type: HttpEventType.UploadProgress,
+      loaded: 50,
+      total: 100,
+    });
+
+    req.event({
+      type: HttpEventType.DownloadProgress,
+      loaded: 80,
+      total: 100,
+    });
+
+    expect(createUser.downloadProgress()).toEqual({
+      type: HttpEventType.DownloadProgress,
+      loaded: 80,
+      total: 100,
+    });
+
+    const mockCreatedUser: User = { id: 2, ...newUser };
+    req.flush(mockCreatedUser);
+
+    expect(createUser.status()).toBe('success');
+    expect(createUser.isPending()).toBe(false);
+    expect(createUser.value()).toEqual(mockCreatedUser);
+    expect(createdUserSignal()).toEqual(mockCreatedUser);
+  });
+
+  it('should perform successful DELETE request', () => {
+    let deletedUserId: number | null = null;
+
+    const deleteUser = TestBed.runInInjectionContext(() =>
+      httpMutation<number, { success: boolean; message: string }>({
+        request: (userId) => ({
+          url: `/api/users/${userId}`,
+          method: 'DELETE',
+          headers: { Authorization: 'Bearer token123' },
+        }),
+        onSuccess: (response) => {
+          deletedUserId = response.success ? 1 : null;
+        },
+      }),
+    );
+
+    expect(deleteUser.status()).toBe('idle');
+    expect(deleteUser.isPending()).toBe(false);
+
+    deleteUser(1);
+
+    expect(deleteUser.isPending()).toBe(true);
+    expect(deleteUser.status()).toBe('pending');
+
+    const req = httpTestingController.expectOne('/api/users/1');
+    expect(req.request.method).toBe('DELETE');
+    expect(req.request.headers.get('Authorization')).toBe('Bearer token123');
+    expect(req.request.body).toBeNull();
+
+    const mockResponse = {
+      success: true,
+      message: 'User deleted successfully',
+    };
+    req.flush(mockResponse);
+
+    expect(deleteUser.status()).toBe('success');
+    expect(deleteUser.isPending()).toBe(false);
+    expect(deleteUser.value()).toEqual(mockResponse);
+    expect(deletedUserId).toBe(1);
+  });
+
+  it('should handle DELETE request with error', () => {
+    let errorCaptured: unknown = null;
+
+    const deleteUser = TestBed.runInInjectionContext(() =>
+      httpMutation<number, { success: boolean }>({
+        request: (userId) => ({
+          url: `/api/users/${userId}`,
+          method: 'DELETE',
+        }),
+        onError: (error) => {
+          errorCaptured = error;
+        },
+      }),
+    );
+
+    deleteUser(999);
+
+    const req = httpTestingController.expectOne('/api/users/999');
+    expect(req.request.method).toBe('DELETE');
+
+    req.flush(
+      { error: 'Forbidden', message: 'You cannot delete this user' },
+      { status: 403, statusText: 'Forbidden' },
+    );
+
+    expect(deleteUser.status()).toBe('error');
+    expect(deleteUser.error()).toBeDefined();
+    expect(errorCaptured).toBeDefined();
+  });
+
+  it('should track large data upload with progress', () => {
+    interface LargeDataUpload {
+      title: string;
+      content: string;
+      metadata: {
+        author: string;
+        tags: string[];
+        size: number;
+      };
+    }
+
+    const uploadData = TestBed.runInInjectionContext(() =>
+      httpMutation<
+        LargeDataUpload,
+        { id: string; title: string; uploadedSize: number }
+      >({
+        request: (data) => ({
+          url: '/api/documents',
+          method: 'POST',
+          body: data,
+          headers: { 'Content-Type': 'application/json' },
+          reportProgress: true,
+        }),
+      }),
+    );
+
+    const mockData: LargeDataUpload = {
+      title: 'Large Document',
+      content:
+        'This is a very large document content with lots of text data...',
+      metadata: {
+        author: 'John Doe',
+        tags: ['important', 'document', 'large'],
+        size: 1024000,
+      },
+    };
+
+    expect(uploadData.uploadProgress()).toBeUndefined();
+    expect(uploadData.downloadProgress()).toBeUndefined();
+
+    uploadData(mockData);
+
+    const req = httpTestingController.expectOne('/api/documents');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual(mockData);
+    expect(req.request.headers.get('Content-Type')).toBe('application/json');
+
+    req.event({
+      type: HttpEventType.UploadProgress,
+      loaded: 256000,
+      total: 1024000,
+    });
+
+    expect(uploadData.uploadProgress()).toEqual({
+      type: HttpEventType.UploadProgress,
+      loaded: 256000,
+      total: 1024000,
+    });
+
+    req.event({
+      type: HttpEventType.UploadProgress,
+      loaded: 768000,
+      total: 1024000,
+    });
+
+    expect(uploadData.uploadProgress()).toEqual({
+      type: HttpEventType.UploadProgress,
+      loaded: 768000,
+      total: 1024000,
+    });
+
+    req.event({
+      type: HttpEventType.UploadProgress,
+      loaded: 1024000,
+      total: 1024000,
+    });
+
+    const mockResponse = {
+      id: 'doc-456',
+      title: 'Large Document',
+      uploadedSize: 1024000,
+    };
+
+    req.flush(mockResponse);
+
+    expect(uploadData.status()).toBe('success');
+    expect(uploadData.value()).toEqual(mockResponse);
+  });
+
+  it('can be explicitly typed', () => {
+    TestBed.runInInjectionContext(() => {
+      httpMutation<AddUserEntry, boolean>((userData: AddUserEntry) => ({
+        url: 'api/users',
+        method: 'POST',
+        body: userData,
+      })) satisfies HttpMutation<AddUserEntry, boolean>;
+    });
+  });
+
+  it('can be implicitly typed via request and parse', () => {
+    TestBed.runInInjectionContext(() => {
+      httpMutation({
+        request: (userData: AddUserEntry) => ({
+          url: 'api/users',
+          method: 'POST',
+          body: userData,
+        }),
+        parse: Boolean,
+      }) satisfies HttpMutation<AddUserEntry, boolean>;
+    });
+  });
+
+  it('can be implicitly typed via a request without a body, and parse', () => {
+    TestBed.runInInjectionContext(() => {
+      httpMutation({
+        request: (id: number) => ({
+          url: `api/users/${id}`,
+          method: 'DELETE',
+        }),
+        parse: Boolean,
+      }) satisfies HttpMutation<number, boolean>;
+    });
+  });
+
+  it('can not be implicitly typed with both onSuccess and parse having different types', () => {
+    TestBed.runInInjectionContext(() => {
+      httpMutation({
+        request: (userData: AddUserEntry) => ({
+          url: 'api/users',
+          method: 'POST',
+          body: userData,
+        }),
+        parse: Boolean,
+        // @ts-expect-error onSuccess need to use the type of parse
+        onSuccess: (result: { userId: number }) => {
+          console.log('User created:', result);
+        },
+      });
+    });
+  });
+
+  it('can be implicitly typed with both onSuccess and parse having same type', () => {
+    TestBed.runInInjectionContext(() => {
+      httpMutation({
+        request: (userData: AddUserEntry) => ({
+          url: 'api/users',
+          method: 'POST',
+          body: userData,
+        }),
+        parse: (result) => result as { id: number },
+        onSuccess: (result) => {
+          console.log('User created:', result);
+        },
+      }) satisfies HttpMutation<AddUserEntry, { id: number }>;
+    });
+  });
+
+  it('can be implicitly typed by defining onSuccess only', () => {
+    TestBed.runInInjectionContext(() => {
+      httpMutation({
+        request: (userData: AddUserEntry) => ({
+          url: 'api/users',
+          method: 'POST',
+          body: userData,
+        }),
+        onSuccess: (result: { id: number }) => {
+          console.log('User created:', result);
+        },
+      }) satisfies HttpMutation<AddUserEntry, { id: number }>;
+    });
+  });
+});

package/src/lib/mutation/http-mutation.ts

@@ -0,0 +1,172 @@
+import {
+  HttpClient,
+  HttpContext,
+  HttpEventType,
+  HttpHeaders,
+  HttpParams,
+  HttpProgressEvent,
+  HttpResponse,
+} from '@angular/common/http';
+import { inject, Signal, signal } from '@angular/core';
+import { defer, filter, map, tap } from 'rxjs';
+import { Mutation } from './mutation';
+import { rxMutation, RxMutationOptions } from './rx-mutation';
+
+// The HttpClient defines these types as part of the method signature and
+// not as a named type
+export 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;
+};
+
+export type HttpMutationOptions<Parameter, Result> = Omit<
+  RxMutationOptions<Parameter, NoInfer<Result>>,
+  'operation'
+> & {
+  request: (param: Parameter) => HttpMutationRequest;
+  parse?: (response: unknown) => Result;
+};
+
+export 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.
+ *
+ * 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.
+ */
+export function httpMutation<Parameter, Result>(
+  optionsOrRequest:
+    | HttpMutationOptions<Parameter, Result>
+    | ((param: Parameter) => HttpMutationRequest),
+): HttpMutation<Parameter, Result> {
+  const httpClient = inject(HttpClient);
+
+  const options =
+    typeof optionsOrRequest === 'function'
+      ? { request: optionsOrRequest }
+      : optionsOrRequest;
+
+  const parse = options.parse ?? ((raw: unknown) => raw as Result);
+
+  const uploadProgress = signal<HttpProgressEvent | undefined>(undefined);
+  const downloadProgress = signal<HttpProgressEvent | undefined>(undefined);
+  const headers = signal<HttpHeaders | undefined>(undefined);
+  const statusCode = signal<string | undefined>(undefined);
+
+  const mutation = rxMutation({
+    ...options,
+    operation: (param: Parameter) => {
+      const httpRequest = options.request(param);
+
+      return defer(() => {
+        uploadProgress.set(undefined);
+        downloadProgress.set(undefined);
+        headers.set(undefined);
+        statusCode.set(undefined);
+
+        return httpClient
+          .request<Result>(httpRequest.method, httpRequest.url, {
+            ...httpRequest,
+            observe: 'events',
+            responseType: 'json',
+          })
+          .pipe(
+            tap((response) => {
+              if (response.type === HttpEventType.UploadProgress) {
+                uploadProgress.set(response);
+              } else if (response.type === HttpEventType.DownloadProgress) {
+                downloadProgress.set(response);
+              }
+            }),
+            filter((event) => event instanceof HttpResponse),
+            tap((response) => {
+              headers.set(response.headers);
+              statusCode.set(response.status.toString());
+            }),
+            map((event) => parse(event.body)),
+          );
+      });
+    },
+  }) as HttpMutation<Parameter, Result>;
+
+  mutation.uploadProgress = uploadProgress;
+  mutation.downloadProgress = downloadProgress;
+  mutation.statusCode = statusCode;
+  mutation.headers = headers;
+
+  return mutation;
+}

package/src/lib/mutation/mutation.ts

@@ -0,0 +1,26 @@
+import { Signal } from '@angular/core';
+
+export type MutationResult<Result> =
+  | {
+      status: 'success';
+      value: Result;
+    }
+  | {
+      status: 'error';
+      error: unknown;
+    }
+  | {
+      status: 'aborted';
+    };
+
+export type MutationStatus = 'idle' | 'pending' | 'error' | 'success';
+
+export 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>;
+};