@one-paragon/angular-utilities 2.8.4 → 2.8.5

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

@@ -1,191 +0,0 @@
-# HTTP Request State Documentation
-
-## Overview
-
-This directory contains comprehensive documentation for the HTTP Request State management system in Angular Utilities. This system provides a signal-based, reactive approach to managing HTTP request states, errors, and success handling.
-
-## Documentation Files
-
-### Core Concepts
-
-1. **[REQUESTOR.md](./REQUESTOR.md)** - Complete guide to using requestors (RequestStateStore instances)
-   - Overview of features and capabilities
-   - Request strategies (concurrent, sequential, cancelPrevious, singleUse)
-   - State management with signals and observables
-   - Making requests and handling responses
-   - Error and success handling patterns
-   - Common usage patterns and best practices
-   - Migration guide from traditional observable patterns
-
-2. **[CREATE-REQUESTOR.md](./CREATE-REQUESTOR.md)** - Documentation for the `createRequestor` function
-   - Function signatures and type parameters
-   - Injection context requirements
-   - Basic and advanced usage examples
-   - Request strategies and configuration
-   - Projection/transformation patterns
-   - Testing strategies
-   - Comparison with RequestStateFactory
-
-3. **[REQUEST-STATE-STORE-CONFIG.md](./REQUEST-STATE-STORE-CONFIG.md)** - Global configuration options
-   - RequestStateStoreConfig interface
-   - Setting up default error handlers
-   - Setting up default success handlers
-   - Application-wide and component-level configuration
-   - Integration with notification/toast services
-   - Error tracking and logging patterns
-   - Testing with configuration
-
-## Quick Start
-
-### Creating a Simple Requestor
-
-```typescript
-import { createRequestor } from 'angular-utilities';
-import { inject } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-
-export class UserComponent {
-  private http = inject(HttpClient);
-  
-  // Create a requestor
-  userRequestor = createRequestor(
-    (userId: number) => this.http.get<User>(`/api/users/${userId}`)
-  );
-  
-  // Make a request
-  loadUser(id: number) {
-    this.userRequestor.request(id);
-  }
-}
-```
-
-### Using in Templates
-
-```typescript
-@Component({
-  template: `
-    @if (userRequestor.$isInProgress()) {
-      <app-loading />
-    } @else if (userRequestor.$isSuccess()) {
-      <h1>{{ userRequestor.$selectResponse()?.name }}</h1>
-    } @else if (userRequestor.$isError()) {
-      <app-error [error]="userRequestor.$selectError()!" />
-    }
-  `
-})
-```
-
-### With Error and Success Handlers
-
-```typescript
-saveUser = createRequestor(
-  (user: User) => this.http.post<User>('/api/users', user)
-)
-.onSuccess((savedUser) => {
-  this.router.navigate(['/users', savedUser.id]);
-})
-.onError((error) => {
-  this.showErrorMessage(error.message);
-});
-```
-
-## Key Features
-
-- **Signal-based State Management**: Reactive state updates using Angular signals
-- **Multiple Request Strategies**: Concurrent, sequential, cancel-previous, and single-use patterns
-- **Automatic Lifecycle Management**: Integrates with Angular's DestroyRef for cleanup
-- **Flexible Error Handling**: Multiple patterns for handling errors
-- **Type-safe**: Full TypeScript support with generic type parameters
-- **Observable and Signal Support**: Works with both reactive paradigms
-- **Projection/Transformation**: Built-in response transformation support
-
-## Request Strategies
-
-| Strategy | Behavior | Use Case |
-|----------|----------|----------|
-| `cancelPrevious` (default) | Cancels in-flight requests | Search, autocomplete |
-| `concurrent` | Runs all requests simultaneously | Independent operations |
-| `sequential` | Queues and executes in order | Ordered operations, uploads |
-| `singleUse` | One request only (must reset) | Initialization, one-time actions |
-
-## State Access Patterns
-
-### Using Signals (Recommended)
-
-```typescript
-requestor.$selectStatus()      // Signal<RequestStatus>
-requestor.$isInProgress()      // Signal<boolean>
-requestor.$isSuccess()         // Signal<boolean>
-requestor.$isError()           // Signal<boolean>
-requestor.$selectResponse()    // Signal<T | undefined>
-requestor.$selectError()       // Signal<HttpErrorResponse | undefined>
-```
-
-### Using Observables
-
-```typescript
-requestor.state$               // Observable<RequestResponse<TParam, T>>
-requestor.selectRequestState$  // Observable<RequestState<T>>
-requestor.selectResponse$      // Observable<T>
-requestor.selectStatus$        // Observable<RequestStatus>
-requestor.selectError$         // Observable<HttpErrorResponse>
-```
-
-## Common Patterns
-
-### Master-Detail Pattern
-
-```typescript
-userId = signal(1);
-userIdArray = computed(() => [this.userId()]);
-
-user = createRequestor(
-  (id: number) => this.http.get<User>(`/api/users/${id}`)
-).requestWith(this.userIdArray);
-```
-
-### Search with Debounce
-
-```typescript
-searchTerm = signal('');
-
-results = createRequestor(
-  (term: string) => this.http.get(`/api/search?q=${term}`),
-  { strategy: RequestStrategy.cancelPrevious }
-).requestWith(
-  toObservable(this.searchTerm).pipe(
-    debounceTime(300),
-    map(term => [term])
-  )
-);
-```
-
-### Form Submission
-
-```typescript
-saveForm = createRequestor(
-  (data: FormData) => this.http.post('/api/save', data)
-)
-.onSuccess(() => this.router.navigate(['/success']))
-.onError((error) => this.showError(error));
-```
-
-
-## Additional Resources
-
-- [Angular Signals Documentation](https://angular.dev/guide/signals)
-- [RxJS Operators](https://rxjs.dev/guide/operators)
-- [HttpClient Guide](https://angular.dev/guide/http)
-
-## Contributing
-
-When contributing to this system:
-1. Maintain backward compatibility
-2. Add tests for new features
-3. Update documentation
-4. Follow TypeScript best practices
-5. Consider performance implications
-
-## Support
-
-For issues, questions, or contributions, please refer to the main repository documentation.