extended-dynamic-forms 0.2.1 → 0.3.0

package/dist/widgets/choice/providers/StaticDataSource.d.ts

@@ -0,0 +1,258 @@
+import { DataSourceProvider, DataSourceEventCallbacks } from './DataSourceProvider';
+import { ChoiceOption, StaticDataSourceConfig, SearchConfig, CacheConfig } from '../ChoiceWidget.types';
+
+/**
+ * Configuration interface for StaticDataSource
+ */
+export interface StaticDataSourceOptions {
+    /** Cache configuration (optional for static data, but maintains consistency) */
+    cache?: Partial<CacheConfig>;
+    /** Event callbacks for monitoring operations */
+    eventCallbacks?: DataSourceEventCallbacks;
+}
+/**
+ * Static data source provider for immediate, synchronous access to option arrays
+ *
+ * Provides in-memory option storage with immediate data availability.
+ * While static data doesn't require caching, this provider maintains
+ * consistency with async providers by supporting the caching interface.
+ *
+ * Key features:
+ * - Immediate data availability (no async loading required)
+ * - Option validation and error reporting
+ * - Support for option filtering and searching
+ * - Memory optimization for large option sets
+ * - Consistent interface with async providers
+ * - Integration with FormEventHub system
+ *
+ * @example Basic usage:
+ * ```typescript
+ * const config: StaticDataSourceConfig = {
+ *   type: 'static',
+ *   options: [
+ *     { label: 'Option 1', value: 'opt1' },
+ *     { label: 'Option 2', value: 'opt2' }
+ *   ]
+ * };
+ *
+ * const provider = new StaticDataSource(config);
+ * const options = await provider.fetchOptions();
+ * ```
+ *
+ * @example With search filtering:
+ * ```typescript
+ * const provider = new StaticDataSource(config);
+ * const filtered = provider.searchOptions('search term', {
+ *   enabled: true,
+ *   searchFields: ['label', 'description'],
+ *   caseSensitive: false
+ * });
+ * ```
+ *
+ * @example With option groups:
+ * ```typescript
+ * const config: StaticDataSourceConfig = {
+ *   type: 'static',
+ *   options: [
+ *     { label: 'Admin', value: 'admin', metadata: { group: 'roles' } },
+ *     { label: 'User', value: 'user', metadata: { group: 'roles' } },
+ *     { label: 'Manager', value: 'manager', metadata: { group: 'roles' } }
+ *   ]
+ * };
+ *
+ * const provider = new StaticDataSource(config);
+ * const grouped = provider.getGroupedOptions();
+ * ```
+ */
+export declare class StaticDataSource extends DataSourceProvider {
+    private readonly validatedOptions;
+    private readonly optionGroups;
+    /**
+     * Whether this provider supports real-time updates
+     * Static data can be updated in memory immediately
+     */
+    readonly supportsRealTime = true;
+    /**
+     * Creates a new StaticDataSource instance
+     *
+     * @param config - Static data source configuration
+     * @param options - Additional configuration options
+     * @throws Error if configuration or options are invalid
+     */
+    constructor(config: StaticDataSourceConfig, options?: StaticDataSourceOptions);
+    /**
+     * Fetch options from static data
+     *
+     * Since data is static and already validated, this method returns
+     * the pre-validated options immediately. The async interface is
+     * maintained for consistency with other data source providers.
+     *
+     * @returns Promise resolving to validated choice options
+     */
+    protected fetchData(): Promise<ChoiceOption[]>;
+    /**
+     * Generate cache key for static data
+     *
+     * Static data doesn't need caching since it's immediately available.
+     * We return null to disable caching and ensure fresh copies are always returned.
+     *
+     * @returns null to disable caching for static data
+     */
+    protected getCacheKey(): string | null;
+    /**
+     * Search and filter options based on search configuration
+     *
+     * Provides efficient in-memory searching with support for:
+     * - Multiple search fields (label, value, description)
+     * - Case-sensitive/insensitive matching
+     * - Custom filter functions
+     * - Optimized performance for large option sets
+     *
+     * @param searchTerm - Term to search for
+     * @param searchConfig - Search configuration options
+     * @returns Filtered array of options
+     *
+     * @example
+     * ```typescript
+     * const filtered = provider.searchOptions('admin', {
+     *   enabled: true,
+     *   searchFields: ['label', 'description'],
+     *   caseSensitive: false
+     * });
+     * ```
+     */
+    searchOptions(searchTerm: string, searchConfig: SearchConfig): ChoiceOption[];
+    /**
+     * Get options grouped by category/group
+     *
+     * Organizes options into groups based on metadata.group property.
+     * Returns a Map where keys are group names and values are option arrays.
+     * Options without a group are placed in an 'ungrouped' category.
+     *
+     * @returns Map of group names to option arrays
+     *
+     * @example
+     * ```typescript
+     * const grouped = provider.getGroupedOptions();
+     * for (const [groupName, options] of grouped) {
+     *   console.log(`${groupName}: ${options.length} options`);
+     * }
+     * ```
+     */
+    getGroupedOptions(): Map<string, ChoiceOption[]>;
+    /**
+     * Get options by specific group name
+     *
+     * @param groupName - Name of the group to retrieve
+     * @returns Array of options in the specified group
+     */
+    getOptionsByGroup(groupName: string): ChoiceOption[];
+    /**
+     * Get all available group names
+     *
+     * @returns Array of group names
+     */
+    getGroupNames(): string[];
+    /**
+     * Update static options in memory
+     *
+     * Provides real-time option updates for static data sources.
+     * This method validates new options and updates the internal cache.
+     *
+     * @param newOptions - New options array to replace existing options
+     * @throws Error if new options are invalid
+     *
+     * @example
+     * ```typescript
+     * const newOptions = [
+     *   { label: 'New Option 1', value: 'new1' },
+     *   { label: 'New Option 2', value: 'new2' }
+     * ];
+     *
+     * provider.updateOptions(newOptions);
+     * ```
+     */
+    updateOptions(newOptions: ChoiceOption[]): void;
+    /**
+     * Add new options to existing set
+     *
+     * @param additionalOptions - Options to add
+     * @throws Error if any new options are invalid
+     */
+    addOptions(additionalOptions: ChoiceOption[]): void;
+    /**
+     * Remove options by value
+     *
+     * @param values - Array of values to remove
+     * @returns Number of options removed
+     */
+    removeOptions(values: (string | number | boolean)[]): number;
+    /**
+     * Get option by value
+     *
+     * @param value - Value to search for
+     * @returns Option with matching value or null if not found
+     */
+    getOptionByValue(value: string | number | boolean): ChoiceOption | null;
+    /**
+     * Check if option exists with given value
+     *
+     * @param value - Value to check
+     * @returns True if option exists
+     */
+    hasOptionWithValue(value: string | number | boolean): boolean;
+    /**
+     * Get total number of options
+     *
+     * @returns Total option count
+     */
+    getOptionCount(): number;
+    /**
+     * Get memory usage statistics for large datasets
+     *
+     * @returns Memory usage information
+     */
+    getMemoryStats(): {
+        optionCount: number;
+        groupCount: number;
+        estimatedMemoryKB: number;
+    };
+    /**
+     * Override to ensure deep copying of metadata for static data
+     */
+    protected validateAndTransformData(data: ChoiceOption[]): ChoiceOption[];
+    /**
+     * No cleanup needed for static data, but method provided for consistency
+     */
+    protected cleanupResources(): void;
+    /**
+     * Validate the static data source configuration
+     */
+    private validateConfig;
+    /**
+     * Build option groups for efficient lookup
+     */
+    private buildOptionGroups;
+}
+/**
+ * Factory function to create StaticDataSource instances
+ *
+ * @param config - Static data source configuration
+ * @param options - Additional configuration options
+ * @returns New StaticDataSource instance
+ */
+export declare function createStaticDataSource(config: StaticDataSourceConfig, options?: StaticDataSourceOptions): StaticDataSource;
+/**
+ * Type guard to check if an option has a group
+ *
+ * @param option - Option to check
+ * @returns True if option has a group defined
+ */
+export declare function hasGroup(option: ChoiceOption): boolean;
+/**
+ * Utility to create grouped static options
+ *
+ * @param groups - Object mapping group names to option arrays
+ * @returns Flattened array of options with group metadata
+ */
+export declare function createGroupedOptions(groups: Record<string, Omit<ChoiceOption, 'metadata'>[]>): ChoiceOption[];

package/dist/widgets/choice/providers/WebSocketDataSource.d.ts

@@ -0,0 +1,310 @@
+import { DataSourceProvider, DataSourceEventCallbacks } from './DataSourceProvider';
+import { ChoiceOption, WebSocketDataSourceConfig, WebSocketMessage, CacheConfig } from '../ChoiceWidget.types';
+
+/**
+ * Configuration interface for WebSocketDataSource
+ */
+export interface WebSocketDataSourceOptions {
+    /** Cache configuration (for offline support) */
+    cache?: Partial<CacheConfig>;
+    /** Event callbacks for monitoring operations */
+    eventCallbacks?: DataSourceEventCallbacks;
+}
+/**
+ * Connection states for WebSocket
+ */
+export declare enum WebSocketConnectionState {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    RECONNECTING = "reconnecting",
+    FAILED = "failed"
+}
+/**
+ * WebSocket data source provider for real-time option updates
+ *
+ * Provides real-time data synchronization through WebSocket connections.
+ * Supports automatic reconnection, heartbeat monitoring, and offline caching.
+ *
+ * Key features:
+ * - Real-time option updates from server
+ * - Automatic reconnection with exponential backoff
+ * - Heartbeat monitoring for connection health
+ * - Request-response pattern with message correlation
+ * - Search request debouncing
+ * - Offline cache for resilience
+ * - Authentication support (Bearer, Query, Header)
+ *
+ * @example Basic usage:
+ * ```typescript
+ * const config: WebSocketDataSourceConfig = {
+ *   type: 'websocket',
+ *   url: 'ws://localhost:8080/choices',
+ *   auth: {
+ *     type: 'bearer',
+ *     credentials: 'your-token'
+ *   }
+ * };
+ *
+ * const provider = new WebSocketDataSource(config);
+ * const options = await provider.fetchOptions();
+ * ```
+ *
+ * @example Real-time search:
+ * ```typescript
+ * const config: WebSocketDataSourceConfig = {
+ *   type: 'websocket',
+ *   url: 'ws://localhost:8080/choices',
+ *   messageHandling: {
+ *     enableRealtimeSearch: true,
+ *     searchDebounceMs: 300
+ *   }
+ * };
+ *
+ * const provider = new WebSocketDataSource(config);
+ * provider.setSearchParams({ search: 'query' });
+ * const results = await provider.fetchOptions();
+ * ```
+ */
+export declare class WebSocketDataSource extends DataSourceProvider {
+    private readonly config;
+    private websocket;
+    private connectionState;
+    private reconnectAttempts;
+    private heartbeatInterval;
+    private responseTimeout;
+    private searchTimeout;
+    private pendingRequests;
+    private currentOptions;
+    private currentSearchParams;
+    /**
+     * Whether this provider supports real-time updates
+     * WebSocket providers always support real-time updates
+     */
+    readonly supportsRealTime = true;
+    /**
+     * Creates a new WebSocketDataSource instance
+     *
+     * @param config - WebSocket data source configuration
+     * @param options - Additional configuration options
+     * @throws Error if configuration is invalid
+     */
+    constructor(config: WebSocketDataSourceConfig, options?: WebSocketDataSourceOptions);
+    /**
+     * Fetch options from WebSocket data source
+     *
+     * Establishes connection if needed and requests current options.
+     * Returns cached data immediately if available and fresh.
+     *
+     * @returns Promise resolving to choice options
+     * @throws Error if connection fails or request times out
+     */
+    protected fetchData(): Promise<ChoiceOption[]>;
+    /**
+     * Generate cache key for WebSocket data source
+     *
+     * @returns Cache key string including URL and search parameters
+     */
+    protected getCacheKey(): string | null;
+    /**
+     * Set search parameters for real-time search
+     *
+     * @param params - Search parameters to apply
+     */
+    setSearchParams(params: Record<string, string | number | boolean>): void;
+    /**
+     * Clear search parameters
+     */
+    clearSearchParams(): void;
+    /**
+     * Get current connection state
+     *
+     * @returns Current WebSocket connection state
+     */
+    getConnectionState(): WebSocketConnectionState;
+    /**
+     * Force reconnection to WebSocket server
+     *
+     * @returns Promise that resolves when reconnection is complete
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Send a message to the WebSocket server
+     *
+     * @param message - Message to send
+     * @throws Error if not connected
+     */
+    sendMessage(message: WebSocketMessage): void;
+    /**
+     * Subscribe to real-time option updates
+     *
+     * @param callback - Function to call when options are updated
+     * @returns Unsubscribe function
+     */
+    subscribeToUpdates(callback: (options: ChoiceOption[]) => void): () => void;
+    /**
+     * Cleanup WebSocket resources
+     */
+    protected cleanupResources(): void;
+    /**
+     * Validate WebSocket configuration
+     */
+    private validateConfig;
+    /**
+     * Normalize configuration with defaults
+     */
+    private normalizeConfig;
+    /**
+     * Ensure WebSocket connection is established
+     */
+    private ensureConnection;
+    /**
+     * Establish WebSocket connection
+     */
+    private connect;
+    /**
+     * Build connection URL with authentication
+     */
+    private buildConnectionUrl;
+    /**
+     * Authenticate the WebSocket connection
+     */
+    private authenticateConnection;
+    /**
+     * Request initial options from server
+     */
+    private requestInitialOptions;
+    /**
+     * Handle incoming WebSocket messages
+     */
+    private handleMessage;
+    /**
+     * Handle search response messages
+     */
+    private handleSearchResponse;
+    /**
+     * Handle options update messages (real-time updates)
+     */
+    private handleOptionsUpdate;
+    /**
+     * Handle options add messages
+     */
+    private handleOptionsAdd;
+    /**
+     * Handle options remove messages
+     */
+    private handleOptionsRemove;
+    /**
+     * Handle options patch messages
+     */
+    private handleOptionsPatch;
+    /**
+     * Handle error messages from server
+     */
+    private handleErrorMessage;
+    /**
+     * Handle heartbeat messages
+     */
+    private handleHeartbeat;
+    /**
+     * Handle WebSocket connection close
+     */
+    private handleConnectionClose;
+    /**
+     * Handle WebSocket connection errors
+     */
+    private handleConnectionError;
+    /**
+     * Schedule reconnection with exponential backoff
+     */
+    private scheduleReconnection;
+    /**
+     * Start heartbeat monitoring
+     */
+    private startHeartbeat;
+    /**
+     * Debounce search requests
+     */
+    private debounceSearch;
+    /**
+     * Send search request to server
+     */
+    private sendSearchRequest;
+    /**
+     * Transform response data using configured mapper
+     */
+    private transformResponseData;
+    /**
+     * Apply simple response mapper
+     */
+    private applySimpleMapper;
+    /**
+     * Apply nested response mapper
+     */
+    private applyNestedMapper;
+    /**
+     * Get cached data safely
+     */
+    private getWebSocketCachedData;
+    /**
+     * Set cached data safely
+     */
+    private setWebSocketCachedData;
+    /**
+     * Generate unique message ID
+     */
+    private generateMessageId;
+}
+/**
+ * Factory function to create WebSocketDataSource instances
+ *
+ * @param config - WebSocket data source configuration
+ * @param options - Additional configuration options
+ * @returns New WebSocketDataSource instance
+ */
+export declare function createWebSocketDataSource(config: WebSocketDataSourceConfig, options?: WebSocketDataSourceOptions): WebSocketDataSource;
+/**
+ * Common WebSocket authentication helpers
+ */
+export declare const WS_AUTH_HELPERS: {
+    /**
+     * Bearer token authentication
+     */
+    bearer: (token: string) => {
+        type: "bearer";
+        credentials: string;
+    };
+    /**
+     * Query parameter authentication
+     */
+    query: (token: string, paramName?: string) => {
+        type: "query";
+        credentials: string;
+        paramName: string;
+    };
+    /**
+     * Header-based authentication
+     */
+    header: (token: string, headerName?: string) => {
+        type: "header";
+        credentials: string;
+        paramName: string;
+    };
+};
+/**
+ * Common WebSocket message helpers
+ */
+export declare const WS_MESSAGE_HELPERS: {
+    /**
+     * Create a search request message
+     */
+    searchRequest: (searchParams?: Record<string, unknown>, messageId?: string) => WebSocketMessage;
+    /**
+     * Create a heartbeat ping message
+     */
+    heartbeatPing: (messageId?: string) => WebSocketMessage;
+    /**
+     * Create an options update message
+     */
+    optionsUpdate: (options: ChoiceOption[], messageId?: string) => WebSocketMessage;
+};

package/dist/widgets/choice/providers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Choice Widget Data Source Providers
+ *
+ * This module provides data source providers for the Choice Widget,
+ * enabling flexible data sourcing from various backends including
+ * static data, APIs, and other external sources.
+ */
+export { DataSourceProvider, type RetryConfig, type DataSourceMetrics, type DataSourceEventCallbacks, DEFAULT_RETRY_CONFIG, createSimpleHash, validateChoiceOptions, } from './DataSourceProvider';
+export { StaticDataSource, type StaticDataSourceOptions, createStaticDataSource, hasGroup, createGroupedOptions, } from './StaticDataSource';
+export { ApiDataSource, createApiDataSource, COMMON_RESPONSE_MAPPERS, AUTH_HELPERS, } from './ApiDataSource';
+export { WebSocketDataSource, createWebSocketDataSource, WebSocketConnectionState, type WebSocketDataSourceOptions, WS_AUTH_HELPERS, WS_MESSAGE_HELPERS, } from './WebSocketDataSource';
+export type { ChoiceOption, LoadingState, ErrorState, CacheConfig, StaticDataSourceConfig, ApiDataSourceConfig, WebSocketDataSourceConfig, SearchConfig, DataSourceConfig, ChoiceDataProvider, ChoiceCache, ResponseMapper, ResponseMapperConfig, HttpMethod, WebSocketMessage, WebSocketMessageType, } from '../ChoiceWidget.types';

package/dist/widgets/choice/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './responseMappers';