extended-dynamic-forms
Version:
Extended React JSON Schema Form (RJSF) v6 with custom components, widgets, templates, layouts, and form events
259 lines (257 loc) • 8.57 kB
TypeScript
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[];