extended-dynamic-forms
Version:
Extended React JSON Schema Form (RJSF) v6 with custom components, widgets, templates, layouts, and form events
245 lines (243 loc) • 7.14 kB
TypeScript
import { ChoiceOption, ApiDataSourceConfig } from '../ChoiceWidget.types';
import { DataSourceProvider, RetryConfig, DataSourceEventCallbacks } from './DataSourceProvider';
/**
* Debounce configuration for search requests
*/
interface DebounceConfig {
/** Debounce delay in milliseconds */
delayMs: number;
/** Maximum wait time before forcing execution */
maxWaitMs?: number;
/** Whether to execute on leading edge */
leading?: boolean;
/** Whether to execute on trailing edge */
trailing?: boolean;
}
/**
* Response mapper utility for transforming API responses
*/
/**
* API Data Source Provider
*
* Provides robust API integration with caching, error handling, authentication,
* request debouncing, and response transformation capabilities.
*
* Features:
* - HTTP client with timeout, retry, and cancellation support
* - Request debouncing for search/filter scenarios
* - Configurable response transformation
* - Multiple authentication methods (Bearer, Basic, API Key)
* - Request/response interceptors
* - Performance monitoring and metrics
* - Memory-efficient caching with TTL
* - Network error recovery with exponential backoff
*
* @example
* ```typescript
* const apiConfig: ApiDataSourceConfig = {
* type: 'api',
* url: 'https://api.example.com/options',
* method: 'GET',
* responseMapper: {
* type: 'simple',
* simple: { arrayPath: 'data.items' }
* },
* auth: {
* type: 'bearer',
* credentials: 'your-token-here'
* }
* };
*
* const provider = new ApiDataSource(apiConfig);
* const options = await provider.fetchOptions();
* ```
*/
export declare class ApiDataSource extends DataSourceProvider {
private debounceConfig;
private config;
private httpClient;
private debouncedFetch?;
private lastRequestUrl?;
private searchParams?;
/**
* Whether this provider supports real-time updates
* API providers support real-time updates through polling or webhooks
*/
readonly supportsRealTime = true;
/**
* Constructor for ApiDataSource
*
* @param config - API data source configuration
* @param retryConfig - Retry configuration options
* @param eventCallbacks - Event callback functions
* @param debounceConfig - Debounce configuration for search requests
*/
constructor(config: ApiDataSourceConfig, retryConfig?: Partial<RetryConfig>, eventCallbacks?: DataSourceEventCallbacks, debounceConfig?: Partial<DebounceConfig>);
/**
* Fetch data from API with debouncing support
*
* This method automatically debounces requests for search/filter scenarios
* while providing immediate responses for regular data fetching.
*/
protected fetchData(): Promise<ChoiceOption[]>;
/**
* Update search parameters and trigger a new request
*
* @param params - Search/filter parameters
*/
setSearchParams(params: Record<string, string | number | boolean>): void;
/**
* Clear search parameters
*/
clearSearchParams(): void;
/**
* Cancel any pending debounced requests
*/
cancelPendingRequests(): void;
/**
* Flush any pending debounced requests immediately
*/
flushPendingRequests(): Promise<ChoiceOption[]> | undefined;
/**
* Generate cache key based on URL and parameters
*/
protected getCacheKey(): string | null;
/**
* Cleanup API-specific resources
*/
protected cleanupResources(): void;
/**
* Internal method for fetching data from API
*/
private fetchDataInternal;
/**
* Build complete request configuration
*/
private buildRequestConfig;
/**
* Build request URL
*/
private buildRequestUrl;
/**
* Build request parameters combining config params and search params
*/
private buildRequestParams;
/**
* Add authentication headers to request configuration
*/
private addAuthenticationHeaders;
/**
* Check if current request has search parameters
*/
private hasSearchParams;
/**
* Create HTTP client with configuration
*/
private createHttpClient;
/**
* Validate and normalize API configuration
*/
private validateAndNormalizeConfig;
/**
* Validate authentication configuration
*/
private validateAuthConfig;
/**
* Validate response mapper configuration
*/
private validateResponseMapper;
}
/**
* Utility function to create ApiDataSource with common configurations
*/
export declare function createApiDataSource(config: ApiDataSourceConfig, options?: {
retryConfig?: Partial<RetryConfig>;
eventCallbacks?: DataSourceEventCallbacks;
debounceConfig?: Partial<DebounceConfig>;
}): ApiDataSource;
/**
* Predefined response mappers for common API formats
*/
export declare const COMMON_RESPONSE_MAPPERS: {
/**
* Simple array response: [{ label: "Option 1", value: "opt1" }]
*/
readonly SIMPLE_ARRAY: {
readonly type: "simple";
readonly simple: {
readonly labelField: "label";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* Paginated response: { data: { items: [...] } }
*/
readonly PAGINATED_DATA: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "data.items";
readonly labelField: "label";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* REST API response: { results: [...] }
*/
readonly REST_RESULTS: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "results";
readonly labelField: "name";
readonly valueField: "id";
readonly disabledField: "active";
};
};
/**
* Nested object structure
*/
readonly NESTED_OBJECTS: {
readonly type: "nested";
readonly nested: {
readonly arrayPath: "data.options";
readonly paths: {
readonly label: "display.name";
readonly value: "identifier";
readonly disabled: "status.disabled";
readonly description: "display.description";
};
};
};
};
/**
* Authentication helper functions
*/
export declare const AUTH_HELPERS: {
/**
* Create Bearer token authentication configuration
*/
readonly bearer: (token: string) => {
type: "bearer";
credentials: string;
};
/**
* Create Basic authentication configuration
*/
readonly basic: (username: string, password: string) => {
type: "basic";
credentials: {
username: string;
password: string;
};
};
/**
* Create API key authentication configuration
*/
readonly apiKey: (key: string, headerName?: string) => {
type: "apiKey";
credentials: string;
headerName: string;
};
};
export {};