@one-paragon/angular-utilities 2.8.2 → 2.8.4

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

@@ -0,0 +1,667 @@
+# 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)