http-request-manager 18.15.34 → 18.16.1

package/src/docs/MODELS_README.md

@@ -1,1264 +0,0 @@
-# Models Reference Guide
-
-Comprehensive reference for all data models used in the HTTP Request Manager library.
-
-## Model Pattern
-
-All models follow a consistent pattern with an interface and implementation class:
-
-```typescript
-export interface ModelNameInterface {
-  property1: string;
-  property2?: number;
-  property3: SomeType;
-}
-
-export class ModelNameModel implements ModelNameInterface {
-  constructor(
-    public property1: string = '',
-    public property2?: number,
-    public property3: SomeType
-  ) {}
-
-  static adapt(item?: any): ModelNameModel {
-    return new ModelNameModel(
-      item?.property1,
-      item?.property2,
-      item?.property3 ? SomeType.adapt(item.property3) : SomeType.adapt()
-    );
-  }
-}
-```
-
-**Key Features:**
-- ✅ Interface + Class pattern
-- ✅ Public constructor parameters
-- ✅ Default values for required fields
-- ✅ Static `adapt()` method for transformation
-- ✅ Type safety with TypeScript
-
----
-
-## HTTP Request Models
-
-### ApiRequest
-
-Configuration for HTTP requests.
-
-```typescript
-export interface ApiRequestInterface {
-  server: string;
-  path?: any[];
-  headers?: any;
-  adapter?: any;
-  mapper?: any;
-  polling?: number;
-  retry?: RetryOptions;
-  stream?: boolean;
-  streamType?: StreamType;
-  displayError?: boolean;
-  displaySuccess?: boolean;
-  successMessage?: string;
-  errorMessage?: string;
-  saveAs?: string;
-  fileContentHeader?: string;
-  ws?: WSOptions;
-  env?: string;
-  uploadFiles?: File | File[];
-  uploadFieldName?: string;
-  uploadHttpMethod?: 'POST' | 'PUT';
-  allowedTypes?: string[];
-  maxFileSize?: number;
-  maxTotalSize?: number;
-}
-
-export class ApiRequest implements ApiRequestInterface {
-  constructor(
-    public server = '',
-    public path?: any[],
-    public headers?: any,
-    public adapter?: any,
-    public mapper?: any,
-    public polling?: number,
-    public retry?: RetryOptions,
-    public stream?: boolean,
-    public streamType?: StreamType,
-    public displayError?: boolean,
-    public displaySuccess?: boolean,
-    public successMessage?: string,
-    public errorMessage?: string,
-    public saveAs?: string,
-    public fileContentHeader?: string,
-    public ws?: WSOptions,
-    public env?: string,
-    public uploadFiles?: File | File[],
-    public uploadFieldName?: string,
-    public uploadHttpMethod?: 'POST' | 'PUT',
-    public allowedTypes?: string[],
-    public maxFileSize?: number,
-    public maxTotalSize?: number,
-  ) {}
-
-  static adapt(item?: any): ApiRequest {
-    const server = Array.isArray(item?.server) ? item.server.join('/') : item?.server || '';
-    return new ApiRequest(
-      server,
-      item?.path ? item.path : [],
-      item?.headers ? item.headers : {},
-      item?.adapter,
-      item?.mapper,
-      item?.polling ? Math.floor(item.polling) : 0,
-      item?.retry ? RetryOptions.adapt(item.retry) : RetryOptions.adapt(),
-      item?.stream ? item.stream : false,
-      item?.streamType || StreamType.AI_STREAMING,
-      item?.displayError ? item.displayError : false,
-      item?.displaySuccess ? item.displaySuccess : false,
-      item?.successMessage,
-      item?.errorMessage,
-      item?.saveAs,
-      item?.fileContentHeader,
-      item?.ws,
-      item?.env || 'dev',
-      item?.uploadFiles,
-      item?.uploadFieldName,
-      item?.uploadHttpMethod,
-      Array.isArray(item?.allowedTypes) ? item.allowedTypes : [],
-      item?.maxFileSize,
-      item?.maxTotalSize,
-    );
-  }
-}
-```
-
-**Properties:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `server` | `string` | `''` | Base URL or server key for the request |
-| `path` | `any[]` | `[]` | Path segments to append to URL |
-| `headers` | `any` | `{}` | Custom headers for the request |
-| `adapter` | `Function` | `undefined` | Transform incoming response data |
-| `mapper` | `Function` | `undefined` | Transform outgoing request payload |
-| `polling` | `number` | `0` | Polling interval in seconds (0 = disabled) |
-| `retry` | `RetryOptions` | `{ times: 0, delay: 3 }` | Retry configuration |
-| `stream` | `boolean` | `false` | Enable streaming response handling |
-| `streamType` | `StreamType` | `AI_STREAMING` | Streaming format: `NDJSON`, `SSE`, or `AI_STREAMING` |
-| `displayError` | `boolean` | `false` | Show error toast notification |
-| `displaySuccess` | `boolean` | `false` | Show success toast notification |
-| `successMessage` | `string` | `undefined` | Custom success toast message |
-| `errorMessage` | `string` | `undefined` | Custom error toast message |
-| `saveAs` | `string` | `undefined` | Filename for file downloads |
-| `fileContentHeader` | `string` | `undefined` | Content-Disposition header value for downloads |
-| `ws` | `WSOptions` | `undefined` | WebSocket configuration for real-time sync |
-| `env` | `string` | `'dev'` | Environment for WebSocket channel naming |
-| `uploadFiles` | `File \| File[]` | `undefined` | Files to upload (set internally by `uploadRequest`) |
-| `uploadFieldName` | `string` | `undefined` | Form-data field name for uploaded files |
-| `uploadHttpMethod` | `'POST' \| 'PUT'` | `undefined` | HTTP method for upload requests |
-| `allowedTypes` | `string[]` | `[]` | Allowed MIME types for upload validation |
-| `maxFileSize` | `number` | `undefined` | Maximum per-file size in bytes |
-| `maxTotalSize` | `number` | `undefined` | Maximum total upload size in bytes |
-
-**Usage:**
-```typescript
-const request = ApiRequest.adapt({
-  server: 'https://api.example.com',
-  path: ['users', 123],
-  headers: { 'Authorization': 'Bearer token' },
-  adapter: User.adapt,
-  retry: { times: 3, delay: 2 }
-});
-```
-
-### RequestOptions
-
-Extended request configuration for state manager methods (`fetchRecords`, `fetchStream`, etc.).
-
-```typescript
-export interface RequestOptionsInterface {
-  path: any[];
-  headers: any;
-  forceRefresh?: boolean;
-  ignoreQueryParams?: string[];
-  queryParamsExpiresIn?: string | number;
-  watchParams?: string[];
-  watchExpiresAt?: number;
-}
-
-export class RequestOptions implements RequestOptionsInterface {
-  constructor(
-    public path: any[] = [],
-    public headers = {},
-    public forceRefresh?: boolean,
-    public ignoreQueryParams?: string[],
-    public queryParamsExpiresIn?: string | number,
-    public watchParams?: string[],
-    public watchExpiresAt?: number,
-  ) {}
-
-  static adapt(item?: any): RequestOptions {
-    return new RequestOptions(
-      item?.path,
-      item?.headers,
-      item?.forceRefresh,
-      Array.isArray(item?.ignoreQueryParams) ? item.ignoreQueryParams : [],
-      item?.queryParamsExpiresIn,
-      item?.watchParams,
-      item?.watchExpiresAt,
-    );
-  }
-}
-```
-
-**Properties:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `path` | `any[]` | `[]` | URL path segments |
-| `headers` | `any` | `{}` | Custom HTTP headers |
-| `forceRefresh` | `boolean` | `undefined` | Bypass query tracking and always make the API request |
-| `ignoreQueryParams` | `string[]` | `[]` | Query parameter keys to exclude from request-change tracking |
-| `queryParamsExpiresIn` | `string \| number` | `undefined` | Expiry duration for tracked query values (e.g., `'10s'`, `'5mn'`, `'1h'`) |
-| `watchParams` | `string[]` | `undefined` | Specific query keys to watch for change detection (variation mode) |
-| `watchExpiresAt` | `number` | `undefined` | Epoch timestamp when tracked values expire |
-
-**Usage:**
-```typescript
-service.fetchRecords(RequestOptions.adapt({
-  path: ['users'],
-  ignoreQueryParams: ['page', 'size'],
-  queryParamsExpiresIn: '10s',
-  forceRefresh: false
-}));
-```
-
-**Scope and behavior:**
-- Database enabled (`DatabaseStorage` configured): tracker is active and can prevent repeated identical API calls until expiry resets tracked values.
-- Database disabled: tracker is not enabled; requests go straight to API.
-- `forceRefresh: true` bypasses tracking and always makes the API request.
-
----
-
-## Configuration Models
-
-### ConfigOptions
-
-Global library configuration passed via `forRoot()`.
-
-```typescript
-export interface ConfigOptions {
-  httpRequestOptions?: ConfigHTTPOptions;
-  LocalStorageOptions?: ConfigLocalStorageOptions;
-}
-
-export class ConfigOptions implements ConfigOptions {
-  constructor(
-    public httpRequestOptions?: ConfigHTTPOptions,
-    public LocalStorageOptions?: ConfigLocalStorageOptions
-  ) {}
-
-  static adapt(item?: any): ConfigOptions {
-    return new ConfigOptions(
-      item?.httpRequestOptions ? ConfigHTTPOptions.adapt(item.httpRequestOptions) : undefined,
-      item?.LocalStorageOptions ? ConfigLocalStorageOptions.adapt(item.LocalStorageOptions) : undefined
-    );
-  }
-}
-```
-
-### ConfigHTTPOptions
-
-HTTP service configuration.
-
-```typescript
-export interface ConfigHTTPOptions {
-  server: string;
-  path?: any[];
-  headers?: any;
-  polling?: number;
-  retry?: RetryOptions;
-  stream?: boolean;
-  displayError?: boolean;
-  displaySuccess?: boolean;
-}
-
-export class ConfigHTTPOptions {
-  constructor(
-    public server: string = '',
-    public path?: any[],
-    public headers?: any,
-    public polling?: number,
-    public retry?: RetryOptions,
-    public stream?: boolean,
-    public displayError?: boolean,
-    public displaySuccess?: boolean,
-  ) {}
-
-  static adapt(item?: any): ConfigHTTPOptions {
-    return new ConfigHTTPOptions(
-      item?.server,
-      Array.isArray(item?.path) ? item.path : [],
-      item?.headers,
-      item?.polling,
-      item?.retry ? RetryOptions.adapt(item.retry) : undefined,
-      item?.stream,
-      item?.displayError,
-      item?.displaySuccess,
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-HttpRequestManagerModule.forRoot({
-  httpRequestOptions: {
-    server: 'https://api.example.com',
-    retry: { times: 3, delay: 2 },
-    displayError: true
-  }
-})
-```
-
-### ConfigLocalStorageOptions
-
-LocalStorage configuration.
-
-```typescript
-export interface ConfigLocalStorageOptions {
-  storageName: string;
-  storageSettingsName: string;
-  options?: SettingOptions;
-}
-
-export class ConfigLocalStorageOptions {
-  constructor(
-    public storageName: string = 'storage',
-    public storageSettingsName: string = 'global-storage',
-    public options?: SettingOptions
-  ) {}
-
-  static adapt(item?: any): ConfigLocalStorageOptions {
-    return new ConfigLocalStorageOptions(
-      item?.storageName,
-      item?.storageSettingsName,
-      item?.options ? SettingOptions.adapt(item.options) : undefined
-    );
-  }
-}
-```
-
-### ConfigToken
-
-Injection token type for configuration.
-
-```typescript
-export const CONFIG_SETTINGS_TOKEN = new InjectionToken<ConfigOptions>(
-  'HTTP_REQUEST_MANAGER_CONFIG'
-);
-```
-
-**Usage:**
-```typescript
-constructor(
-  @Inject(CONFIG_SETTINGS_TOKEN) private config?: ConfigOptions
-) {
-  // Use config
-}
-```
-
----
-
-## State Management Models
-
-### DataType
-
-Enum for data structure types.
-
-```typescript
-export enum DataType {
-  ARRAY = 'array',
-  OBJECT = 'object'
-}
-```
-
-**Usage:**
-```typescript
-// For list of records
-super(request, DataType.ARRAY);
-
-// For single object
-super(request, DataType.OBJECT);
-```
-
-### DatabaseStorage
-
-IndexedDB caching configuration.
-
-```typescript
-export interface DatabaseStorageInterface {
-  table: string;
-  expiresIn?: string;
-}
-
-export class DatabaseStorage {
-  constructor(
-    public table: string,
-    public expiresIn?: string
-  ) {}
-
-  static adapt(item?: any): DatabaseStorage {
-    return new DatabaseStorage(
-      item?.table,
-      item?.expiresIn
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-super(
-  ApiRequest.adapt({ path: ['users'] }),
-  DataType.ARRAY,
-  DatabaseStorage.adapt({
-    table: 'users',
-    expiresIn: '1h'
-  })
-);
-```
-
-### StateStorageOptions
-
-Persistent state configuration for StoreStateManagerService.
-
-```typescript
-export interface StateStorageOptionsInterface {
-  store: string;
-  options?: SettingOptions;
-  model?: Function;
-  version?: number;
-}
-
-export class StateStorageOptions {
-  constructor(
-    public store: string,
-    public options?: SettingOptions,
-    public model?: Function,
-    public version?: number
-  ) {}
-
-  static adapt(item?: any): StateStorageOptions {
-    return new StateStorageOptions(
-      item?.store,
-      item?.options ? SettingOptions.adapt(item.options) : undefined,
-      item?.model,
-      item?.version
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-export class AppStateService extends StoreStateManagerService<AppState> {
-  constructor() {
-    super(StateStorageOptions.adapt({
-      store: 'app-state',
-      options: {
-        storage: StorageType.GLOBAL,
-        encrypted: true,
-        expiresIn: '24h'
-      },
-      model: AppState.adapt,
-      version: 1
-    }));
-  }
-}
-```
-
----
-
-## WebSocket Models
-
-### WSOptions
-
-WebSocket connection configuration.
-
-```typescript
-export interface WSOptionsInterface {
-  wsServer: string;
-  id: string;
-  user?: any;
-  channels?: string[];
-  jwtToken?: string;
-}
-
-export class WSOptions {
-  constructor(
-    public wsServer: string,
-    public id: string,
-    public user?: any,
-    public channels?: string[],
-    public jwtToken?: string
-  ) {}
-
-  static adapt(item?: any): WSOptions {
-    return new WSOptions(
-      item?.wsServer,
-      item?.id,
-      item?.user,
-      Array.isArray(item?.channels) ? item.channels : [],
-      item?.jwtToken
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-const wsOptions = WSOptions.adapt({
-  wsServer: 'ws://localhost:8080',
-  id: 'my-channel',
-  user: { userId: 123, name: 'John' },
-  channels: ['notifications', 'updates']
-});
-
-wsManager.connect(wsOptions, 'jwt-token');
-```
-
-### StreamType
-
-Enum for streaming response types.
-
-```typescript
-export enum StreamType {
-  NDJSON = 'ndjson',
-  SSE = 'sse'
-}
-```
-
-### ChannelType
-
-Enum for channel prefixes.
-
-```typescript
-export enum ChannelType {
-  STATE = 'SYS',        // Private state sync
-  MESSAGE = 'PUB',      // Public messaging
-  NOTIFICATION = 'MES'  // Persistent notifications
-}
-```
-
-**Usage:**
-```typescript
-const privateChannel = createChannelName(ChannelType.STATE, 'user-123');
-// Result: 'SYS-user-123'
-
-const publicChannel = createChannelName(ChannelType.MESSAGE, 'general');
-// Result: 'PUB-general'
-
-const notificationChannel = createChannelName(ChannelType.NOTIFICATION, 'alerts');
-// Result: 'MES-alerts'
-```
-
-### ChannelMessage
-
-WebSocket message structure.
-
-```typescript
-export interface ChannelMessageInterface {
-  type: string;
-  channel: string;
-  content: any;
-  sessionId?: {
-    id: string;
-    name?: string;
-    email?: string;
-  };
-  timestamp?: number;
-}
-
-export class ChannelMessage {
-  constructor(
-    public type: string,
-    public channel: string,
-    public content: any,
-    public sessionId?: {
-      id: string;
-      name?: string;
-      email?: string;
-    },
-    public timestamp?: number
-  ) {}
-
-  static adapt(item?: any): ChannelMessage {
-    return new ChannelMessage(
-      item?.type,
-      item?.channel,
-      item?.content,
-      item?.sessionId ? {
-        id: item.sessionId.id,
-        name: item.sessionId.name,
-        email: item.sessionId.email
-      } : undefined,
-      item?.timestamp
-    );
-  }
-}
-```
-
-### WSUser
-
-WebSocket user information.
-
-```typescript
-export interface WSUserInterface {
-  id: string;
-  name?: string;
-  email?: string;
-  channels?: string[];
-}
-
-export class WSUser {
-  constructor(
-    public id: string,
-    public name?: string,
-    public email?: string,
-    public channels?: string[]
-  ) {}
-
-  static adapt(item?: any): WSUser {
-    return new WSUser(
-      item?.id,
-      item?.name,
-      item?.email,
-      Array.isArray(item?.channels) ? item.channels : []
-    );
-  }
-}
-```
-
-### CommunicationType
-
-Enum for WebSocket message types.
-
-```typescript
-export enum CommunicationType {
-  SUBSCRIBE = 'subscribe',
-  UNSUBSCRIBE = 'unsubscribe',
-  MESSAGE = 'message',
-  NOTIFICATION = 'notification',
-  BROADCAST = 'broadcast',
-  USER_LIST = 'user-list',
-  CHANNEL_CREATED = 'channel-created',
-  CHANNEL_DELETED = 'channel-deleted',
-  PRESENCE = 'presence',
-  HISTORY = 'history',
-  LAST_SEEN = 'last-seen'
-}
-```
-
----
-
-## Storage Models
-
-### StorageType
-
-Enum for storage scope.
-
-```typescript
-export enum StorageType {
-  GLOBAL = 'global',   // localStorage
-  SESSION = 'session'  // sessionStorage
-}
-```
-
-### SettingOptions
-
-Storage configuration options.
-
-```typescript
-export interface SettingOptionsInterface {
-  storage?: StorageType;
-  expires?: number;
-  expiresIn?: string;
-  encrypted?: boolean;
-}
-
-export class SettingOptions {
-  constructor(
-    public storage?: StorageType,
-    public expires?: number,
-    public expiresIn?: string,
-    public encrypted?: boolean
-  ) {}
-
-  static adapt(item?: any): SettingOptions {
-    return new SettingOptions(
-      item?.storage,
-      item?.expires,
-      item?.expiresIn,
-      item?.encrypted
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-// Encrypted localStorage with 7-day expiration
-SettingOptions.adapt({
-  storage: StorageType.GLOBAL,
-  encrypted: true,
-  expiresIn: '7d'
-});
-
-// Unencrypted sessionStorage
-SettingOptions.adapt({
-  storage: StorageType.SESSION,
-  encrypted: false
-});
-```
-
-### StorageData
-
-Internal storage data structure.
-
-```typescript
-export interface StorageDataInterface {
-  data: any;
-  settings: SettingOptions;
-  expires?: number;
-}
-```
-
----
-
-## Database Models
-
-### TableSchemaDef
-
-IndexedDB table schema definition.
-
-```typescript
-export interface TableSchemaDefInterface {
-  table: string;
-  schema: string;
-}
-
-export class TableSchemaDef {
-  constructor(
-    public table: string,
-    public schema: string
-  ) {}
-
-  static adapt(item?: any): TableSchemaDef {
-    return new TableSchemaDef(
-      item?.table,
-      item?.schema
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-const userTable = TableSchemaDef.adapt({
-  table: 'users',
-  schema: '++id, name, email, age, createdAt'
-});
-
-dbManager.createDatabaseTable(userTable).subscribe();
-```
-
-### Schema Examples
-
-```typescript
-// Simple auto-increment ID
-'++id'
-
-// Multiple indexes
-'++id, name, email'
-
-// Compound index
-'++id, [category+status]'
-
-// Multi-entry index
-'++id, tags' // tags is an array
-
-// Full schema example
-'++id, name, email, &username, [firstName+lastName], tags'
-```
-
----
-
-## Retry & Error Models
-
-### RetryOptions
-
-Retry configuration for HTTP requests.
-
-```typescript
-export interface RetryOptionsInterface {
-  times: number;
-  delay: number;
-}
-
-export class RetryOptions {
-  constructor(
-    public times: number = 0,
-    public delay: number = 3
-  ) {}
-
-  static adapt(item?: any): RetryOptions {
-    return new RetryOptions(
-      item?.times || 0,
-      item?.delay || 3
-    );
-  }
-}
-```
-
-**Usage:**
-```typescript
-// Retry 3 times with 2 second delay
-RetryOptions.adapt({ times: 3, delay: 2 });
-
-// No retry
-RetryOptions.adapt({ times: 0 });
-
-// Default retry
-RetryOptions.adapt(); // { times: 0, delay: 3 }
-```
-
-### ErrorSettings
-
-Error handling configuration for interceptors.
-
-```typescript
-export interface ErrorSettingsInterface {
-  displayError?: boolean;
-  displayWarning?: boolean;
-  customHandler?: (error: any) => void;
-}
-
-export class ErrorSettings {
-  constructor(
-    public displayError?: boolean,
-    public displayWarning?: boolean,
-    public customHandler?: (error: any) => void
-  ) {}
-}
-```
-
----
-
-## Utility Models
-
-### ObjectMerger
-
-Deep merge configuration.
-
-```typescript
-export interface MergeOptions {
-  clone?: boolean;
-  mergeArrays?: boolean;
-  customMerge?: (key: string, target: any, source: any) => any;
-}
-```
-
-**Usage:**
-```typescript
-const merged = objectMerger.deepMerge(obj1, obj2, {
-  clone: true,
-  mergeArrays: false
-});
-```
-
-### HeadersConfig
-
-Header configuration.
-
-```typescript
-export interface HeadersConfig {
-  'Content-Type'?: string;
-  'Accept-Language'?: string;
-  'Current-Date'?: string;
-  'Authorization'?: string;
-  [key: string]: string | undefined;
-}
-```
-
----
-
-## Model Adapters Pattern
-
-All models use the `adapt()` pattern for safe transformation:
-
-```typescript
-// Basic adaptation
-const user = User.adapt(apiResponse);
-
-// With nested objects
-const order = Order.adapt({
-  ...data,
-  customer: Customer.adapt(data.customer),
-  items: data.items.map(item => OrderItem.adapt(item))
-});
-
-// With defaults
-const config = ConfigOptions.adapt(userProvided || {});
-
-// Array adaptation
-const users = response.users.map(u => User.adapt(u));
-```
-
-### Adapter Functions
-
-Adapters can be passed to HTTP requests:
-
-```typescript
-const request = ApiRequest.adapt({
-  path: ['users'],
-  adapter: User.adapt  // Transform response
-});
-
-httpManager.getRequest(request).subscribe();
-// data$ will emit User[] instead of raw JSON
-```
-
-### Custom Adapters
-
-Create adapters for your models:
-
-```typescript
-export interface ProductInterface {
-  id: number;
-  name: string;
-  price: number;
-  category: Category;
-}
-
-export class Product implements ProductInterface {
-  constructor(
-    public id: number = 0,
-    public name: string = '',
-    public price: number = 0,
-    public category: Category
-  ) {}
-
-  static adapt(item?: any): Product {
-    return new Product(
-      item?.id,
-      item?.name,
-      item?.price,
-      item?.category ? Category.adapt(item.category) : Category.adapt()
-    );
-  }
-}
-```
-
----
-
-## Batch Request Models
-
-### BatchOptions
-
-Configuration for batch request execution.
-
-```typescript
-export interface BatchOptionsInterface {
-  mode?: 'sequential' | 'parallel';
-  stopOnError?: boolean;
-  concurrency?: number;
-  ignoreErrors?: boolean;
-  logErrors?: boolean;
-  displaySuccess?: boolean;
-  displayError?: boolean;
-}
-
-export class BatchOptions implements BatchOptionsInterface {
-  constructor(
-    public mode: 'sequential' | 'parallel' = 'sequential',
-    public stopOnError: boolean = false,
-    public concurrency: number = 3,
-    public ignoreErrors: boolean = false,
-    public logErrors: boolean = true,
-    public displaySuccess?: boolean,
-    public displayError?: boolean,
-  ) {}
-
-  static adapt(item?: any): BatchOptions {
-    return new BatchOptions(
-      item?.mode ?? 'sequential',
-      item?.stopOnError ?? false,
-      item?.concurrency ?? 3,
-      item?.ignoreErrors ?? false,
-      item?.logErrors !== false,
-      item?.displaySuccess ?? false,
-      item?.displayError ?? false,
-    );
-  }
-}
-```
-
-### BatchProgress
-
-Progress tracking for batch operations.
-
-```typescript
-export interface BatchProgress {
-  total: number;
-  pending: number;
-  completed: number;
-  failed: number;
-  percent: number;
-}
-```
-
-### BatchRequestState
-
-Per-request state within a batch operation.
-
-```typescript
-export type BatchRequestState<T> = 
-  | BatchPendingState
-  | BatchSuccessState<T>
-  | BatchErrorState;
-
-export interface BatchPendingState {
-  index: number;
-  request: any;
-  isPending: true;
-  data?: undefined;
-  error?: undefined;
-}
-
-export interface BatchSuccessState<T> {
-  index: number;
-  request: any;
-  isPending: false;
-  data: T;
-  error?: undefined;
-}
-
-export interface BatchErrorState {
-  index: number;
-  request: any;
-  isPending: false;
-  data?: undefined;
-  error: any;
-}
-```
-
-### BatchResult
-
-Result of a single request within a batch.
-
-```typescript
-export interface BatchResultInterface<T = any> {
-  request: any;
-  success: boolean;
-  data?: T;
-  error?: any;
-  index: number;
-  timestamp: number;
-}
-
-export class BatchResult<T = any> implements BatchResultInterface<T> {
-  constructor(
-    public request: any,
-    public success: boolean,
-    public data?: T,
-    public error?: any,
-    public index: number = 0,
-    public timestamp: number = Date.now(),
-  ) {}
-
-  static adapt<T>(item?: any): BatchResult<T> {
-    return new BatchResult<T>(
-      item?.request,
-      item?.success ?? false,
-      item?.data,
-      item?.error,
-      item?.index ?? 0,
-      item?.timestamp ?? Date.now(),
-    );
-  }
-}
-```
-
----
-
-## Upload Models
-
-### UploadValidationErrorModel
-
-Error returned when upload validation fails.
-
-```typescript
-export interface InvalidFileInfoInterface {
-  fileName: string;
-  fileSize: number;
-  fileType: string;
-  errors: string[];
-}
-
-export class InvalidFileInfoModel implements InvalidFileInfoInterface {
-  constructor(
-    public fileName: string = '',
-    public fileSize: number = 0,
-    public fileType: string = '',
-    public errors: string[] = []
-  ) {}
-
-  static adapt(item?: any): InvalidFileInfoModel {
-    return new InvalidFileInfoModel(
-      item?.fileName,
-      item?.fileSize,
-      item?.fileType,
-      Array.isArray(item?.errors) ? item.errors : []
-    );
-  }
-}
-
-export interface UploadValidationErrorInterface {
-  invalidFiles: InvalidFileInfoModel[];
-  validFilesCount: number;
-  totalFilesCount: number;
-}
-
-export class UploadValidationErrorModel implements UploadValidationErrorInterface {
-  constructor(
-    public invalidFiles: InvalidFileInfoModel[] = [],
-    public validFilesCount: number = 0,
-    public totalFilesCount: number = 0
-  ) {}
-
-  static adapt(item?: any): UploadValidationErrorModel {
-    return new UploadValidationErrorModel(
-      Array.isArray(item?.invalidFiles) ? item.invalidFiles.map((f: any) => InvalidFileInfoModel.adapt(f)) : [],
-      item?.validFilesCount,
-      item?.totalFilesCount
-    );
-  }
-}
-```
-
----
-
-## Query Parameter Tracking Models
-
-### QueryParamsTrackerOptions
-
-Options for the query parameter tracking system.
-
-```typescript
-export interface QueryParamsTrackerOptionsInterface {
-  mode?: 'exact' | 'variation';
-  watchParams?: string[];
-  watchExpiresAt?: string | number;
-  watchParamsExpire?: string | number;
-}
-
-export class QueryParamsTrackerOptionsModel implements QueryParamsTrackerOptionsInterface {
-  constructor(
-    public mode?: 'exact' | 'variation',
-    public watchParams?: string[],
-    public watchExpiresAt?: string | number,
-    public watchParamsExpire?: string | number
-  ) {}
-
-  static adapt(item?: any): QueryParamsTrackerOptionsModel {
-    return new QueryParamsTrackerOptionsModel(
-      item?.mode,
-      Array.isArray(item?.watchParams) ? item.watchParams : [],
-      item?.watchExpiresAt,
-      item?.watchParamsExpire
-    );
-  }
-}
-```
-
-**Properties:**
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `mode` | `'exact' \| 'variation'` | `undefined` | Tracking mode: `exact` matches full query hash, `variation` watches individual param values |
-| `watchParams` | `string[]` | `[]` | Specific query parameter keys to watch for changes |
-| `watchExpiresAt` | `string \| number` | `undefined` | Epoch timestamp or duration string when tracked values expire |
-| `watchParamsExpire` | `string \| number` | `undefined` | Alternative expiry duration for watched params (e.g., `'10s'`, `'5mn'`) |
-
-### NormalizedRequestOptions
-
-Internal normalized representation of request options.
-
-```typescript
-export type QueryValue = string;
-export type NormalizedQueryParams = Record<string, QueryValue>;
-
-export interface NormalizedRequestOptionsInterface {
-  pathKey: string;
-  query: NormalizedQueryParams;
-  hasQuery: boolean;
-}
-```
-
-### PathTrackerState
-
-Per-path tracking state for consumed query values.
-
-```typescript
-export interface PathTrackerStateInterface {
-  watchExpiresAt?: number;
-  consumedValuesByKey: Record<string, QueryValue[]>;
-}
-```
-
-### QueryTrackerState
-
-Top-level state for the query parameter tracking system.
-
-```typescript
-export interface QueryTrackerStateInterface {
-  paths: Record<string, PathTrackerStateInterface>;
-}
-```
-
----
-
-## Operation Models
-
-### OperationResultModel
-
-Result of a CRUD operation emitted after state changes.
-
-```typescript
-export interface OperationResultInterface {
-  success: boolean;
-  operation: 'CREATE' | 'UPDATE' | 'DELETE';
-}
-
-export class OperationResultModel implements OperationResultInterface {
-  constructor(
-    public success: boolean = false,
-    public operation: 'CREATE' | 'UPDATE' | 'DELETE' = 'UPDATE',
-  ) {}
-
-  static adapt(item?: any): OperationResultModel {
-    return new OperationResultModel(
-      item?.success ?? false,
-      item?.operation || 'UPDATE',
-    );
-  }
-}
-```
-
----
-
-## Related Documentation
-
-- [`Complete API Reference`](COMPLETE_API_REFERENCE.md) - Full API with methods
-- [`HTTP Manager`](HTTP_MANAGER_README.md) - HTTP service usage
-- [`State Manager`](HTTP_STATE_MANAGER_README.md) - State management
-- [`Architecture`](ARCHITECTURE.md) - System architecture