@one-paragon/angular-utilities 2.8.4 → 2.8.6

package/src/http-request-state/documentation/REQUESTOR.md

@@ -1,616 +0,0 @@
-# Requestor (RequestStateStore) Documentation
-
-## Overview
-
-The `RequestStateStore` class (commonly referred to as a "Requestor") is a powerful state management solution for handling HTTP requests and their associated states in Angular applications. It provides a signal-based reactive approach to managing request states, handling errors and successes, and coordinating multiple concurrent requests.
-
-## Key Features
-
-- **Signal-based State Management**: Uses Angular signals for reactive state updates
-- **Multiple Request Strategies**: Supports concurrent, sequential, single-use, and cancel-previous patterns
-- **Automatic Lifecycle Management**: Integrates with Angular's `DestroyRef` for automatic cleanup
-- **Flexible Error Handling**: Multiple ways to handle errors with optional default handlers
-- **Success Callbacks**: Various patterns for handling successful responses
-- **Type-safe**: Full TypeScript support with generic type parameters
-- **Observable and Signal Support**: Works seamlessly with both observables and signals
-
-## Creating a Requestor
-
-### Using `createRequestor` (Recommended)
-
-```typescript
-import { createRequestor } from 'angular-utilities';
-import { HttpClient } from '@angular/common/http';
-
-// In a component or service
-export class UserService {
-  private http = inject(HttpClient);
-  
-  // Simple requestor
-  getUserRequestor = createRequestor(
-    (userId: number) => this.http.get<User>(`/api/users/${userId}`)
-  );
-  
-  // With projection (transforming response)
-  getTransformedUserRequestor = createRequestor(
-    (userId: number) => this.http.get<UserDTO>(`/api/users/${userId}`),
-    (dto) => this.mapToUser(dto) // Projection function
-  );
-  
-  // With options
-  getMultipleUsersRequestor = createRequestor(
-    (userIds: number[]) => this.http.post<User[]>('/api/users/batch', userIds),
-    { strategy: RequestStrategy.concurrent }
-  );
-}
-```
-
-### Using `RequestStateFactory`
-
-```typescript
-import { RequestStateFactory } from 'angular-utilities';
-
-@Component({
-  providers: [RequestStateFactory]
-})
-export class MyComponent {
-  private factory = inject(RequestStateFactory);
-  private http = inject(HttpClient);
-  
-  getUserRequestor = this.factory.create(
-    (userId: number) => this.http.get<User>(`/api/users/${userId}`)
-  );
-}
-```
-
-### Direct Instantiation (Advanced)
-
-```typescript
-// Must be in an injection context
-const requestor = new RequestStateStore(
-  (userId: number) => this.http.get<User>(`/api/users/${userId}`),
-  { strategy: RequestStrategy.cancelPrevious }
-);
-```
-
-## Type Parameters
-
-```typescript
-RequestStateStore<TParam, V, R, T>
-```
-
-- **`TParam`**: Array type of parameters accepted by the request function (e.g., `[number, string]`)
-- **`V`**: The raw response type from the request (e.g., `UserDTO`)
-- **`R`**: The projected response type (optional, defaults to `null`)
-- **`T`**: The final type (defaults to `V` if no projection, otherwise `R`)
-
-## Request Strategies
-
-### `RequestStrategy.cancelPrevious` (Default)
-
-Cancels the previous in-flight request when a new request is made (uses RxJS `switchMap`).
-
-```typescript
-const requestor = createRequestor(
-  (query: string) => this.http.get(`/api/search?q=${query}`),
-  { strategy: RequestStrategy.cancelPrevious }
-);
-
-// Only the last request will complete
-requestor.request('first');
-requestor.request('second'); // Cancels 'first'
-requestor.request('third');  // Cancels 'second'
-```
-
-### `RequestStrategy.concurrent`
-
-Allows multiple requests to run simultaneously (uses RxJS `mergeMap`).
-
-```typescript
-const requestor = createRequestor(
-  (userId: number) => this.http.get(`/api/users/${userId}`),
-  { strategy: RequestStrategy.concurrent }
-);
-
-// All three requests will execute
-requestor.request(1);
-requestor.request(2);
-requestor.request(3);
-```
-
-### `RequestStrategy.sequential`
-
-Queues requests and executes them one at a time (uses RxJS `concatMap`).
-
-```typescript
-const requestor = createRequestor(
-  (data: FormData) => this.http.post('/api/upload', data),
-  { strategy: RequestStrategy.sequential }
-);
-
-// Requests execute in order
-requestor.request(file1); // Executes immediately
-requestor.request(file2); // Waits for file1 to complete
-requestor.request(file3); // Waits for file2 to complete
-```
-
-### `RequestStrategy.singleUse`
-
-Allows only one request for the lifetime of the requestor. Must call `reset()` before making another request.
-
-```typescript
-const requestor = createRequestor(
-  () => this.http.post('/api/initialize', {}),
-  { strategy: RequestStrategy.singleUse }
-);
-
-requestor.request(); // Works
-requestor.request(); // Throws error!
-
-requestor.reset();
-requestor.request(); // Works again
-```
-
-## State Management
-
-### Signal-based State
-
-```typescript
-const requestor = createRequestor(
-  (id: number) => this.http.get<User>(`/api/users/${id}`)
-);
-
-// Access the full state
-const state = requestor.state(); // Signal<RequestResponse<[number], User>>
-
-// Access computed signals
-const status = requestor.$selectStatus();        // Signal<RequestStatus>
-const isLoading = requestor.$isInProgress();     // Signal<boolean>
-const isSuccess = requestor.$isSuccess();        // Signal<boolean>
-const isError = requestor.$isError();            // Signal<boolean>
-const response = requestor.$selectResponse();    // Signal<User | undefined>
-const error = requestor.$selectError();          // Signal<HttpErrorResponse | undefined>
-
-// Use in templates
-@Component({
-  template: `
-    @if (userRequestor.$isInProgress()) {
-      <app-loading />
-    } @else if (userRequestor.$isSuccess()) {
-      <app-user-details [user]="userRequestor.$selectResponse()!" />
-    } @else if (userRequestor.$isError()) {
-      <app-error [error]="userRequestor.$selectError()!" />
-    }
-  `
-})
-```
-
-### Observable-based State
-
-```typescript
-const requestor = createRequestor(
-  (id: number) => this.http.get<User>(`/api/users/${id}`)
-);
-
-// Observable streams
-requestor.state$             // Observable<RequestResponse<[number], User>>
-requestor.selectRequestState$ // Observable<RequestState<User>>
-requestor.selectResponse$    // Observable<User> (only emits on success)
-requestor.selectStatus$      // Observable<RequestStatus>
-requestor.selectError$       // Observable<HttpErrorResponse>
-```
-
-## Making Requests
-
-### Basic Request
-
-```typescript
-const requestor = createRequestor(
-  (userId: number) => this.http.get<User>(`/api/users/${userId}`)
-);
-
-// Make the request
-requestor.request(123);
-```
-
-### Auto Request
-
-Automatically make the request when the requestor is created (only works with no-parameter requests).
-
-```typescript
-const requestor = createRequestor(
-  () => this.http.get<Config>('/api/config'),
-  { autoRequest: true }
-);
-// Request is made immediately
-```
-
-### Request With Observable
-
-```typescript
-const userId$ = new BehaviorSubject<number>(1);
-
-requestor.requestWith(userId$.pipe(map(id => [id])));
-// Makes a request whenever userId$ emits
-// Must map to an array of parameters
-```
-
-### Request With Signal
-
-```typescript
-const userId = signal(1);
-const userIdArray = computed(() => [userId()]);
-
-requestor.requestWith(userIdArray);
-// Makes a request whenever userId changes
-// Must be a signal of an array of parameters
-```
-
-### Request On Signal Changes
-
-Track multiple signals and make requests when they change.
-
-```typescript
-const userId = signal(1);
-const includeDetails = signal(false);
-
-requestor.requestOn(userId, includeDetails);
-// Makes a request whenever userId or includeDetails change
-// Skips request if any signal is undefined
-```
-
-## Error Handling
-
-### Basic Error Handler
-
-```typescript
-const requestor = createRequestor(
-  (id: number) => this.http.get<User>(`/api/users/${id}`)
-).onError((error: HttpErrorResponse) => {
-  console.error('Request failed:', error);
-});
-
-requestor.request(123);
-```
-
-### Error with Response Parameters
-
-```typescript
-requestor.onErrorResponse((error, userId) => {
-  console.error(`Failed to load user ${userId}:`, error);
-});
-```
-
-### Error with Request Parameters Only
-
-```typescript
-requestor.onErrorRequest((userId) => {
-  console.log(`Request for user ${userId} failed`);
-});
-```
-
-### Error with Full Context
-
-```typescript
-requestor.onErrorWithRequest(({ error, requestParams }) => {
-  const [userId] = requestParams;
-  console.error(`User ${userId} request failed:`, error.message);
-});
-```
-
-### Default Error Handler
-
-```typescript
-// Use the globally configured error handler
-requestor.useDefaultErrorHandler();
-
-// Or configure globally in module/component providers
-{
-  provide: RequestStateStoreConfigToken,
-  useValue: {
-    defaultErrorHandling: (error) => {
-      this.toastr.error('Request failed', error.message);
-    },
-    useDefaultErrorHandler: true // Auto-apply to all requestors
-  }
-}
-```
-
-**Note:** See [RequestStateStoreConfig Documentation](./REQUEST-STATE-STORE-CONFIG.md) for complete details on configuring global error handlers.
-
-## Success Handling
-
-### Basic Success Handler
-
-```typescript
-const requestor = createRequestor(
-  (id: number) => this.http.delete(`/api/users/${id}`)
-).onSuccess(() => {
-  console.log('User deleted successfully');
-});
-
-requestor.request(123);
-```
-
-### Success with Response
-
-```typescript
-requestor.onSuccess((user: User) => {
-  console.log('Loaded user:', user.name);
-});
-```
-
-### Success with Response and Parameters
-
-```typescript
-requestor.onSuccessResponse((user, userId) => {
-  console.log(`Successfully loaded user ${userId}:`, user.name);
-});
-```
-
-### Success with Request Parameters
-
-```typescript
-requestor.onSuccessRequest((userId) => {
-  console.log(`Successfully processed user ${userId}`);
-});
-```
-
-### Success with Full Context
-
-```typescript
-requestor.onSuccessWithRequest(({ body, requestParams }) => {
-  const [userId] = requestParams;
-  console.log(`User ${userId}:`, body.name);
-});
-```
-
-### Success or Error Handler
-
-Execute callback on completion regardless of outcome.
-
-```typescript
-requestor.onSuccessOrError(() => {
-  console.log('Request completed');
-  this.hideLoadingSpinner();
-});
-```
-
-### Default Success Handler
-
-```typescript
-requestor.useDefaultSuccessHandler();
-// Logs 'Success' by default, or uses configured handler
-```
-
-**Note:** See [RequestStateStoreConfig Documentation](./REQUEST-STATE-STORE-CONFIG.md) for complete details on configuring global success handlers.
-
-## Advanced Patterns
-
-### Chaining Handlers
-
-```typescript
-const requestor = createRequestor(
-  (userId: number) => this.http.get<User>(`/api/users/${userId}`)
-)
-.onSuccess((user) => {
-  this.userCache.set(user.id, user);
-})
-.onError((error) => {
-  this.logger.error('Failed to load user', error);
-})
-.onSuccessOrError(() => {
-  this.loadingService.hide();
-});
-```
-
-### Resetting State
-
-```typescript
-requestor.reset(); // Resets to notStarted state
-```
-
-### Manual Cleanup
-
-```typescript
-requestor.destroy(); // Manually trigger cleanup
-```
-
-### Projection/Transformation
-
-Transform the response before it's stored in state.
-
-```typescript
-const requestor = createRequestor(
-  (id: number) => this.http.get<UserDTO>(`/api/users/${id}`),
-  (dto: UserDTO) => ({
-    id: dto.user_id,
-    name: `${dto.first_name} ${dto.last_name}`,
-    email: dto.email_address
-  } as User)
-);
-
-// The state will contain the transformed User, not UserDTO
-```
-
-### Cancellation Token
-
-```typescript
-const requestor = createRequestor(
-  (id: number | CancellationToken) => {
-    if (id instanceof CancellationToken) {
-      return of(null); // Handle cancellation
-    }
-    return this.http.get(`/api/users/${id}`);
-  },
-  { strategy: RequestStrategy.cancelPrevious }
-);
-
-requestor.request(new CancellationToken()); // Explicit cancellation
-```
-
-## Request State Types
-
-### `RequestStatus` Enum
-
-```typescript
-enum RequestStatus {
-  notStarted,  // Initial state
-  inProgress,  // Request is in flight
-  success,     // Request completed successfully
-  fail,        // Request failed
-  cancelled    // Request was cancelled
-}
-```
-
-### State Type Definitions
-
-```typescript
-type RequestStateNotStarted = { status: RequestStatus.notStarted }
-type RequestStateInProgress = { status: RequestStatus.inProgress }
-type RequestStateSuccess<T> = { status: RequestStatus.success; body: T }
-type RequestStateError = { status: RequestStatus.fail; error: any }
-type RequestStateCancelled = { status: RequestStatus.cancelled }
-
-type RequestState<T> = 
-  | RequestStateNotStarted
-  | RequestStateInProgress
-  | RequestStateSuccess<T>
-  | RequestStateError
-  | RequestStateCancelled
-```
-
-## Common Patterns
-
-### Loading Pattern
-
-```typescript
-@Component({
-  template: `
-    @if (users.$isInProgress()) {
-      <mat-spinner />
-    } @else if (users.$isSuccess()) {
-      <user-list [users]="users.$selectResponse()!" />
-    } @else if (users.$isError()) {
-      <error-message [error]="users.$selectError()!" />
-    }
-  `
-})
-export class UserListComponent {
-  private http = inject(HttpClient);
-  
-  users = createRequestor(
-    () => this.http.get<User[]>('/api/users'),
-    { autoRequest: true }
-  );
-}
-```
-
-### Master-Detail Pattern
-
-```typescript
-export class UserDetailComponent {
-  private http = inject(HttpClient);
-  private route = inject(ActivatedRoute);
-  
-  userId = toSignal(this.route.params.pipe(map(p => +p['id'])));
-  userIdArray = computed(() => [this.userId()]);
-  
-  user = createRequestor(
-    (id: number) => this.http.get<User>(`/api/users/${id}`)
-  ).requestWith(this.userIdArray);
-}
-```
-
-### Search Pattern
-
-```typescript
-export class SearchComponent {
-  searchTerm = signal('');
-  
-  searchResults = createRequestor(
-    (term: string) => this.http.get<SearchResult[]>(`/api/search?q=${term}`),
-    { strategy: RequestStrategy.cancelPrevious }
-  ).requestWith(
-    toObservable(this.searchTerm).pipe(
-      debounceTime(300),
-      map(term => [term])
-    )
-  );
-}
-```
-
-### Form Submission Pattern
-
-```typescript
-export class UserFormComponent {
-  saveUser = createRequestor(
-    (user: User) => this.http.post<User>('/api/users', user),
-    { strategy: RequestStrategy.singleUse }
-  )
-  .onSuccess((savedUser) => {
-    this.router.navigate(['/users', savedUser.id]);
-  })
-  .onError((error) => {
-    this.showErrorMessage(error.message);
-  });
-  
-  onSubmit(user: User) {
-    this.saveUser.request(user);
-  }
-}
-```
-
-## Migration from Observable Patterns
-
-### Before (Traditional Observable)
-
-```typescript
-export class UserService {
-  private loading$ = new BehaviorSubject<boolean>(false);
-  private error$ = new BehaviorSubject<HttpErrorResponse | null>(null);
-  private user$ = new BehaviorSubject<User | null>(null);
-  
-  getUser(id: number) {
-    this.loading$.next(true);
-    this.error$.next(null);
-    
-    this.http.get<User>(`/api/users/${id}`).subscribe({
-      next: (user) => {
-        this.user$.next(user);
-        this.loading$.next(false);
-      },
-      error: (error) => {
-        this.error$.next(error);
-        this.loading$.next(false);
-      }
-    });
-  }
-}
-```
-
-### After (With RequestStateStore)
-
-```typescript
-export class UserService {
-  private http = inject(HttpClient);
-  
-  userRequestor = createRequestor(
-    (id: number) => this.http.get<User>(`/api/users/${id}`)
-  );
-  
-  // Access via signals
-  isLoading = this.userRequestor.$isInProgress;
-  error = this.userRequestor.$selectError;
-  user = this.userRequestor.$selectResponse;
-  
-  getUser(id: number) {
-    this.userRequestor.request(id);
-  }
-}
-```
-
-## See Also
-
-- [createRequestor Function](./CREATE-REQUESTOR.md)
-- [RequestStateStoreConfig](./REQUEST-STATE-STORE-CONFIG.md)

package/src/http-request-state/helpers.ts

@@ -1,30 +0,0 @@
-import { RequestState, RequestStateError, RequestStateInProgress, RequestStateNotStarted, RequestStateSuccess, RequestStatus } from "./types";
-
-export function isErrorState<T>(state: RequestState<T>): state is RequestStateError {
-  return state.status === RequestStatus.fail;
-}
-
-export function isSuccessState<T>(state: RequestState<T>): state is RequestStateSuccess<T> {
-  return state.status === RequestStatus.success;
-}
-
-export function isSuccessOrErrorState<T>(state: RequestState<T>): state is (RequestStateSuccess<T> | RequestStateError) {
-  return state.status === RequestStatus.success || state.status === RequestStatus.fail;
-}
-
-export function createSuccess<T>(body: T): RequestStateSuccess<T> {
-  return { status: RequestStatus.success, body };
-}
-
-export function createFailure(error: any): RequestStateError {
-  return { status: RequestStatus.fail, error };
-}
-
-export const notStarted: RequestStateNotStarted = { status: RequestStatus.notStarted };
-
-
-export const inProgress: RequestStateInProgress = { status: RequestStatus.inProgress };
-
-export function statusIsSuccessOrInProgress( status: RequestStatus) {
-  return [RequestStatus.success, RequestStatus.inProgress].includes(status);
-}

package/src/http-request-state/http-state-module.ts

@@ -1,23 +0,0 @@
-import { NgModule } from '@angular/core';
-import { HttpSuccessStateDirective } from './directives/http-success-state-directive';
-import { HttpRequestStateDirective } from './directives/request-state-directive';
-import { HttpErrorStateDirective } from './directives/http-error-state-directive';
-import { HttpInProgressStateDirective } from './directives/http-inProgress-state-directive';
-import { HttpNotStartedStateDirective } from './directives/http-notStarted-state-directive';
-
-@NgModule({
-  imports: [
-    HttpSuccessStateDirective,
-    HttpRequestStateDirective,
-    HttpErrorStateDirective,
-    HttpInProgressStateDirective,
-    HttpNotStartedStateDirective,
-  ],
-  exports: [
-    HttpSuccessStateDirective,
-    HttpRequestStateDirective,
-    HttpErrorStateDirective,
-    HttpInProgressStateDirective,
-    HttpNotStartedStateDirective,
-  ]
-}) export class HttpRequestModule { }

package/src/http-request-state/index.ts

@@ -1,7 +0,0 @@
-export * from './helpers';
-export * from './request-state';
-export * from './http-state-module';
-export * from './RequestStateFactory';
-export * from './RequestStateStore';
-export * from './types';
-export * from './deprecated'

package/src/http-request-state/models/view-context.ts

@@ -1,18 +0,0 @@
-import { RequestStatus } from "../types";
-
-export interface HttpRequestStateViewContext<T> {
-  $implicit?: HttpRequestStateAny<T>;
-  state?: HttpRequestStateAny<T>;
-  status: {
-    inProgress: boolean;
-    notStarted: boolean;
-    success: boolean;
-    error: boolean;
-  };
-}
-
-export type HttpRequestStateAny<T> = {
-  status: RequestStatus;
-  body?: T;
-  error?: any;
-}