@one-paragon/angular-utilities 2.8.4 → 2.8.6

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

@@ -1,667 +0,0 @@
-# createRequestor Function Documentation
-
-## Overview
-
-`createRequestor` is a standalone function that creates a `RequestStateStore` instance (requestor) for managing HTTP request state in Angular applications. It provides a convenient way to create requestors outside of the Angular dependency injection context, making it ideal for use in components, services, and other contexts.
-
-## Function Signature
-
-```typescript
-// Basic usage - no projection
-function createRequestor<TParam extends any[], V>(
-  req: RequestFactory<TParam, V>,
-  options?: RequestCreatorOptions<TParam>
-): RequestStateStore<TParam, V>
-
-// With projection - transforms the response
-function createRequestor<TParam extends any[], V, R, T = R>(
-  req: RequestFactory<TParam, V>,
-  project: (v: V) => R,
-  options?: RequestCreatorOptions<TParam>
-): RequestStateStore<TParam, V, T>
-```
-
-### Type Parameters
-
-- **`TParam`**: Array type representing the parameters the request function accepts (e.g., `[number]`, `[string, number]`)
-- **`V`**: The raw response type returned by the HTTP request (e.g., `UserDTO`)
-- **`R`**: The projected/transformed response type (only when using projection)
-- **`T`**: The final type stored in state (defaults to `V` without projection, or `R` with projection)
-
-### Parameters
-
-- **`req`**: A function that takes parameters and returns an `Observable`. Typically an HTTP request.
-  ```typescript
-  RequestFactory<TParam, V> = (...params: [...TParam]) => Observable<V>
-  ```
-
-- **`project`** _(optional)_: A transformation function to map the raw response to a different type.
-  ```typescript
-  (v: V) => R
-  ```
-
-- **`options`** _(optional)_: Configuration options for the requestor.
-  ```typescript
-  interface RequestCreatorOptions<TParam> {
-    strategy?: RequestStrategy;
-    autoRequest?: boolean;  // Only if TParam is empty array
-    injector?: Injector;    // Provide custom injector
-  }
-  ```
-
-## Return Value
-
-Returns a `RequestStateStore<TParam, V, R, T>` instance configured with the provided request function and options.
-
-## Injection Context
-
-`createRequestor` must be called within an Angular injection context OR you must provide an `injector` in the options.
-
-### Valid Contexts
-
-```typescript
-// ✅ In component/service constructor
-export class UserComponent {
-  constructor() {
-    this.userRequestor = createRequestor(
-      (id: number) => this.http.get<User>(`/api/users/${id}`)
-    );
-  }
-}
-
-// ✅ In component/service field initializer
-export class UserComponent {
-  private http = inject(HttpClient);
-  
-  userRequestor = createRequestor(
-    (id: number) => this.http.get<User>(`/api/users/${id}`)
-  );
-}
-
-// ✅ With custom injector
-export class UserComponent {
-  private injector = inject(Injector);
-  
-  createUserRequestor() {
-    return createRequestor(
-      (id: number) => this.http.get<User>(`/api/users/${id}`),
-      { injector: this.injector }
-    );
-  }
-}
-
-// ✅ In runInInjectionContext
-export class UserComponent {
-  private injector = inject(Injector);
-  
-  createLater() {
-    runInInjectionContext(this.injector, () => {
-      return createRequestor(
-        (id: number) => this.http.get<User>(`/api/users/${id}`)
-      );
-    });
-  }
-}
-```
-
-### Invalid Contexts
-
-```typescript
-// ❌ Outside injection context without injector
-function createUserRequestor() {
-  // Error: createRequestor() must be used in an Injection Context
-  return createRequestor(
-    (id: number) => inject(HttpClient).get<User>(`/api/users/${id}`)
-  );
-}
-```
-
-## Basic Usage
-
-### Simple Request (No Parameters)
-
-```typescript
-import { createRequestor } from 'angular-utilities';
-import { inject } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-
-export class ConfigService {
-  private http = inject(HttpClient);
-  
-  // Request with no parameters
-  configRequestor = createRequestor(
-    () => this.http.get<AppConfig>('/api/config')
-  );
-  
-  loadConfig() {
-    this.configRequestor.request();
-  }
-}
-```
-
-### Request with Single Parameter
-
-```typescript
-export class UserService {
-  private http = inject(HttpClient);
-  
-  userRequestor = createRequestor(
-    (userId: number) => this.http.get<User>(`/api/users/${userId}`)
-  );
-  
-  loadUser(id: number) {
-    this.userRequestor.request(id);
-  }
-}
-```
-
-### Request with Multiple Parameters
-
-```typescript
-export class SearchService {
-  private http = inject(HttpClient);
-  
-  searchRequestor = createRequestor(
-    (query: string, page: number, pageSize: number) => 
-      this.http.get<SearchResults>(
-        `/api/search?q=${query}&page=${page}&size=${pageSize}`
-      )
-  );
-  
-  search(query: string, page: number = 1, pageSize: number = 20) {
-    this.searchRequestor.request(query, page, pageSize);
-  }
-}
-```
-
-## With Projection
-
-Projection allows you to transform the response before it's stored in state.
-
-### Basic Projection
-
-```typescript
-interface UserDTO {
-  user_id: number;
-  first_name: string;
-  last_name: string;
-  email_address: string;
-}
-
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-export class UserService {
-  private http = inject(HttpClient);
-  
-  userRequestor = createRequestor(
-    (id: number) => this.http.get<UserDTO>(`/api/users/${id}`),
-    (dto: UserDTO): User => ({
-      id: dto.user_id,
-      name: `${dto.first_name} ${dto.last_name}`,
-      email: dto.email_address
-    })
-  );
-}
-```
-
-### Projection with Options
-
-```typescript
-userRequestor = createRequestor(
-  (id: number) => this.http.get<UserDTO>(`/api/users/${id}`),
-  (dto: UserDTO): User => this.transformUser(dto),
-  { strategy: RequestStrategy.cancelPrevious }
-);
-```
-
-## Request Strategies
-
-### Cancel Previous (Default)
-
-Cancels in-flight requests when a new request is made. Ideal for search/autocomplete.
-
-```typescript
-const searchRequestor = createRequestor(
-  (query: string) => this.http.get(`/api/search?q=${query}`),
-  { strategy: RequestStrategy.cancelPrevious }
-);
-```
-
-### Concurrent
-
-Allows multiple requests to execute simultaneously.
-
-```typescript
-const userRequestor = createRequestor(
-  (userId: number) => this.http.get(`/api/users/${userId}`),
-  { strategy: RequestStrategy.concurrent }
-);
-
-// All requests execute in parallel
-userRequestor.request(1);
-userRequestor.request(2);
-userRequestor.request(3);
-```
-
-### Sequential
-
-Queues requests and executes them one at a time in order.
-
-```typescript
-const uploadRequestor = createRequestor(
-  (file: File) => this.http.post('/api/upload', file),
-  { strategy: RequestStrategy.sequential }
-);
-
-// Requests execute in order
-uploadRequestor.request(file1);
-uploadRequestor.request(file2); // Waits for file1
-uploadRequestor.request(file3); // Waits for file2
-```
-
-### Single Use
-
-Only allows one request for the lifetime of the requestor. Must call `reset()` to make another request.
-
-```typescript
-const initRequestor = createRequestor(
-  () => this.http.post('/api/initialize', {}),
-  { strategy: RequestStrategy.singleUse }
-);
-
-initRequestor.request(); // OK
-initRequestor.request(); // Error!
-initRequestor.reset();   // Reset state
-initRequestor.request(); // OK again
-```
-
-## Auto Request
-
-Automatically execute the request when the requestor is created. Only available for requests with no parameters.
-
-```typescript
-const configRequestor = createRequestor(
-  () => this.http.get<Config>('/api/config'),
-  { autoRequest: true }
-);
-// Request executes immediately upon creation
-```
-
-## Custom Injector
-
-Provide a custom injector when creating the requestor outside an injection context.
-
-```typescript
-export class DynamicRequestService {
-  private injector = inject(Injector);
-  
-  createDynamicRequestor(endpoint: string) {
-    // Create requestor outside injection context
-    return createRequestor(
-      () => this.http.get(endpoint),
-      { injector: this.injector }
-    );
-  }
-}
-```
-
-## Comparison with RequestStateFactory
-
-### Using `createRequestor` (Recommended)
-
-```typescript
-export class UserComponent {
-  private http = inject(HttpClient);
-  
-  // Direct creation - cleaner and more modern
-  userRequestor = createRequestor(
-    (id: number) => this.http.get<User>(`/api/users/${id}`)
-  );
-}
-```
-
-### Using `RequestStateFactory`
-
-```typescript
-@Component({
-  providers: [RequestStateFactory] // Must provide in component/module
-})
-export class UserComponent {
-  private factory = inject(RequestStateFactory);
-  private http = inject(HttpClient);
-  
-  // Factory method - requires provider
-  userRequestor = this.factory.create(
-    (id: number) => this.http.get<User>(`/api/users/${id}`)
-  );
-}
-```
-
-**Benefits of `createRequestor`:**
-- No need to provide `RequestStateFactory` in component/module
-- More concise and functional
-- Better tree-shaking
-- Easier to test
-
-**When to use `RequestStateFactory`:**
-- Need centralized lifecycle management across multiple requestors
-- Want to batch cleanup operations
-- Working with older Angular patterns
-
-## Common Patterns
-
-### Component with Master-Detail
-
-```typescript
-@Component({
-  selector: 'app-user-detail',
-  template: `
-    @if (user.$isInProgress()) {
-      <mat-spinner />
-    } @else if (user.$isSuccess()) {
-      <h1>{{ user.$selectResponse()?.name }}</h1>
-      <p>{{ user.$selectResponse()?.email }}</p>
-    }
-  `
-})
-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 with Debounce
-
-```typescript
-@Component({
-  selector: 'app-search',
-  template: `
-    <input [ngModel]="searchTerm()" (ngModelChange)="searchTerm.set($event)" />
-    
-    @if (results.$isSuccess()) {
-      @for (item of results.$selectResponse(); track item.id) {
-        <div>{{ item.name }}</div>
-      }
-    }
-  `
-})
-export class SearchComponent {
-  private http = inject(HttpClient);
-  
-  searchTerm = signal('');
-  
-  results = createRequestor(
-    (term: string) => this.http.get<Item[]>(`/api/search?q=${term}`),
-    { strategy: RequestStrategy.cancelPrevious }
-  ).requestWith(
-    toObservable(this.searchTerm).pipe(
-      debounceTime(300),
-      filter(term => term.length >= 3),
-      map(term => [term])
-    )
-  );
-}
-```
-
-### Form Submission with Error Handling
-
-```typescript
-@Component({
-  selector: 'app-user-form',
-  template: `
-    <form (ngSubmit)="onSubmit()">
-      <!-- form fields -->
-      <button type="submit" [disabled]="saveUser.$isInProgress()">
-        @if (saveUser.$isInProgress()) {
-          Saving...
-        } @else {
-          Save User
-        }
-      </button>
-    </form>
-  `
-})
-export class UserFormComponent {
-  private http = inject(HttpClient);
-  private router = inject(Router);
-  private snackBar = inject(MatSnackBar);
-  
-  saveUser = createRequestor(
-    (user: User) => this.http.post<User>('/api/users', user)
-  )
-  .onSuccess((savedUser) => {
-    this.snackBar.open('User saved successfully', 'Close', { duration: 3000 });
-    this.router.navigate(['/users', savedUser.id]);
-  })
-  .onError((error) => {
-    this.snackBar.open(`Error: ${error.message}`, 'Close', { duration: 5000 });
-  });
-  
-  onSubmit() {
-    if (this.form.valid) {
-      this.saveUser.request(this.form.value);
-    }
-  }
-}
-```
-
-### Multiple Dependent Requests
-
-```typescript
-export class UserDashboardComponent {
-  private http = inject(HttpClient);
-  
-  userId = signal(1);
-  userIdArray = computed(() => [this.userId()]);
-  
-  // First request
-  user = createRequestor(
-    (id: number) => this.http.get<User>(`/api/users/${id}`)
-  ).requestWith(this.userIdArray);
-  
-  // Second request depends on first
-  userPosts = createRequestor(
-    (userId: number) => this.http.get<Post[]>(`/api/users/${userId}/posts`)
-  ).requestWith(this.userIdArray);
-  
-  // Third request depends on first
-  userComments = createRequestor(
-    (userId: number) => this.http.get<Comment[]>(`/api/users/${userId}/comments`)
-  ).requestWith(this.userIdArray);
-}
-```
-
-### Combining Multiple Signals
-
-```typescript
-export class ReportComponent {
-  private http = inject(HttpClient);
-  
-  startDate = signal(new Date());
-  endDate = signal(new Date());
-  reportType = signal('summary');
-  
-  // Combine multiple signals
-  report = createRequestor(
-    (start: Date, end: Date, type: string) => 
-      this.http.get(`/api/reports?start=${start}&end=${end}&type=${type}`)
-  ).requestOn(this.startDate, this.endDate, this.reportType);
-  // Automatically makes a new request when any signal changes
-}
-```
-
-### Polling Pattern
-
-```typescript
-export class StatusComponent implements OnInit {
-  private http = inject(HttpClient);
-  
-  status = createRequestor(
-    () => this.http.get<Status>('/api/status'),
-    { strategy: RequestStrategy.sequential }
-  );
-  
-  ngOnInit() {
-    // Poll every 5 seconds
-    interval(5000).pipe(
-      takeUntilDestroyed()
-    ).subscribe(() => {
-      this.status.request();
-    });
-  }
-}
-```
-
-## Error Handling
-
-The `createRequestor` function returns a requestor that can be chained with error handlers.
-
-```typescript
-const userRequestor = createRequestor(
-  (id: number) => this.http.get<User>(`/api/users/${id}`)
-)
-.onError((error) => {
-  console.error('Failed to load user:', error);
-})
-.useDefaultErrorHandler(); // Use global error handler if configured
-```
-
-See the [Requestor Documentation](./REQUESTOR.md#error-handling) for complete error handling patterns.
-
-## Success Handling
-
-Chain success handlers for side effects after successful requests.
-
-```typescript
-const deleteUserRequestor = createRequestor(
-  (id: number) => this.http.delete(`/api/users/${id}`)
-)
-.onSuccess(() => {
-  this.showSuccessMessage('User deleted');
-  this.refreshUserList();
-});
-```
-
-See the [Requestor Documentation](./REQUESTOR.md#success-handling) for complete success handling patterns.
-
-## Testing
-
-### Testing Components with Requestors
-
-```typescript
-describe('UserComponent', () => {
-  let component: UserComponent;
-  let httpMock: HttpTestingController;
-  
-  beforeEach(() => {
-    TestBed.configureTestingModule({
-      imports: [HttpClientTestingModule],
-      declarations: [UserComponent]
-    });
-    
-    component = TestBed.createComponent(UserComponent).componentInstance;
-    httpMock = TestBed.inject(HttpTestingController);
-  });
-  
-  it('should load user', () => {
-    const mockUser: User = { id: 1, name: 'John', email: 'john@test.com' };
-    
-    component.userRequestor.request(1);
-    
-    const req = httpMock.expectOne('/api/users/1');
-    expect(req.request.method).toBe('GET');
-    req.flush(mockUser);
-    
-    expect(component.userRequestor.$isSuccess()).toBe(true);
-    expect(component.userRequestor.$selectResponse()).toEqual(mockUser);
-  });
-  
-  it('should handle error', () => {
-    component.userRequestor.request(999);
-    
-    const req = httpMock.expectOne('/api/users/999');
-    req.error(new ProgressEvent('error'), { status: 404, statusText: 'Not Found' });
-    
-    expect(component.userRequestor.$isError()).toBe(true);
-  });
-  
-  afterEach(() => {
-    httpMock.verify();
-  });
-});
-```
-
-### Mocking Requestors in Tests
-
-```typescript
-describe('UserDashboardComponent', () => {
-  let component: UserDashboardComponent;
-  
-  beforeEach(() => {
-    // Create a mock requestor
-    const mockRequestor = {
-      request: jasmine.createSpy('request'),
-      $isSuccess: signal(true),
-      $selectResponse: signal({ id: 1, name: 'Test User' }),
-      $isInProgress: signal(false),
-      $isError: signal(false)
-    } as any;
-    
-    TestBed.configureTestingModule({
-      declarations: [UserDashboardComponent],
-      providers: [
-        { provide: UserService, useValue: { userRequestor: mockRequestor } }
-      ]
-    });
-    
-    component = TestBed.createComponent(UserDashboardComponent).componentInstance;
-  });
-  
-  it('should display user data', () => {
-    expect(component.userService.userRequestor.$selectResponse()?.name)
-      .toBe('Test User');
-  });
-});
-```
-
-## Best Practices
-
-### Using `createRequestor` over `RequestStateFactory`**: It's more modern and requires less boilerplate.
-
-2. **Create requestors as class properties**: Define them at the class level for easy access.
-   ```typescript
-   export class UserComponent {
-     userRequestor = createRequestor(...);
-   }
-   ```
-
-3. **Remember `requestWith` takes an array**: When using `requestWith`, ensure your observable/signal emits an array of parameters.
-
-3. **Choose appropriate strategies**: Match the strategy to your use case (cancelPrevious for search, concurrent for independent operations).
-
-4. **Use projection for transformation**: Keep transformation logic in the requestor rather than in components.
-
-5. **Chain handlers fluently**: Take advantage of method chaining for clean code.
-
-6. **Provide custom injector when needed**: If creating outside injection context, always provide an injector.
-
-7. **Type your responses**: Always specify generic types for compile-time safety.
-
-8. **Use signals for reactivity**: Prefer signal-based state access (`$selectResponse()`) over observables in templates.
-
-## See Also
-
-- [Requestor (RequestStateStore) Documentation](./REQUESTOR.md)
-- [RequestStateFactory Documentation](./REQUEST-STATE-FACTORY.md)
-- [Request State Types](./REQUEST-STATE-TYPES.md)