extended-dynamic-forms
Version:
Extended React JSON Schema Form (RJSF) v6 with custom components, widgets, templates, layouts, and form events
343 lines (341 loc) • 10.5 kB
TypeScript
import { ChoiceOption, ResponseMapper, ResponseMapperConfig } from '../ChoiceWidget.types';
/**
* Error thrown when response mapping fails
*/
export declare class ResponseMappingError extends Error {
readonly path?: string | undefined;
readonly index?: number | undefined;
readonly originalError?: Error | undefined;
constructor(message: string, path?: string | undefined, index?: number | undefined, originalError?: Error | undefined);
}
/**
* Validate a single choice option
*
* @param option - The option to validate
* @param index - The index in the array for error reporting
* @returns Validated ChoiceOption
* @throws ResponseMappingError if validation fails
*/
export declare function validateChoiceOption(option: unknown, index: number): ChoiceOption;
/**
* Validate an array of choice options
*
* @param options - Array to validate
* @returns Validated ChoiceOption array
* @throws ResponseMappingError if validation fails
*/
export declare function validateChoiceOptions(options: unknown): ChoiceOption[];
/**
* Get a nested value from an object using dot notation
*
* @param obj - Object to extract value from
* @param path - Dot notation path (e.g., 'data.items')
* @returns The value at the path or undefined
*
* @example
* ```typescript
* const obj = { data: { items: [1, 2, 3] } };
* getNestedValue(obj, 'data.items'); // [1, 2, 3]
* ```
*/
export declare function getNestedValue(obj: unknown, path: string): unknown;
/**
* Set a nested value in an object using dot notation
*
* @param obj - Object to set value in
* @param path - Dot notation path
* @param value - Value to set
* @returns New object with value set (immutable)
*/
export declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
/**
* Extract array from response data using a path
*
* @param data - Response data
* @param arrayPath - Path to array (optional)
* @returns Extracted array
* @throws ResponseMappingError if array not found
*/
export declare function extractArrayFromResponse(data: unknown, arrayPath?: string): unknown[];
/**
* Map a simple response structure to ChoiceOption array
*
* @param data - Response data
* @param config - Simple mapper configuration
* @returns Mapped ChoiceOption array
*
* @example
* ```typescript
* const data = { items: [{ name: 'Option 1', id: 1 }] };
* const options = mapSimpleResponse(data, {
* arrayPath: 'items',
* labelField: 'name',
* valueField: 'id'
* });
* ```
*/
export declare function mapSimpleResponse(data: unknown, config?: NonNullable<ResponseMapperConfig['simple']>): ChoiceOption[];
/**
* Map a nested response structure to ChoiceOption array
*
* @param data - Response data
* @param config - Nested mapper configuration
* @returns Mapped ChoiceOption array
*
* @example
* ```typescript
* const data = {
* response: {
* data: [
* {
* info: { displayName: 'Option 1' },
* meta: { identifier: 'opt1', active: false }
* }
* ]
* }
* };
*
* const options = mapNestedResponse(data, {
* arrayPath: 'response.data',
* paths: {
* label: 'info.displayName',
* value: 'meta.identifier',
* disabled: 'meta.active'
* }
* });
* ```
*/
export declare function mapNestedResponse(data: unknown, config: NonNullable<ResponseMapperConfig['nested']>): ChoiceOption[];
/**
* Create a custom response mapper with validation
*
* @param mapper - Custom mapper function
* @returns Wrapped mapper with validation
*
* @example
* ```typescript
* const customMapper = createCustomMapper((data: any) => {
* return data.options.map((opt: any) => ({
* label: opt.text || opt.name,
* value: opt.key || opt.id,
* disabled: !opt.enabled
* }));
* });
* ```
*/
export declare function createCustomMapper(mapper: ResponseMapper): ResponseMapper;
/**
* Main response mapper that handles all mapper types
*
* @param data - Response data to map
* @param config - Response mapper configuration
* @returns Mapped ChoiceOption array
* @throws ResponseMappingError if mapping fails
*/
export declare function mapResponse(data: unknown, config: ResponseMapperConfig): ChoiceOption[];
/**
* Predefined response mappers for common API patterns
*/
export declare const COMMON_MAPPERS: {
/**
* Simple flat array: [{ label: "Option", value: "opt" }]
*/
readonly SIMPLE_ARRAY: {
readonly type: "simple";
readonly simple: {
readonly labelField: "label";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* Name/ID pattern: [{ name: "Option", id: 1 }]
*/
readonly NAME_ID: {
readonly type: "simple";
readonly simple: {
readonly labelField: "name";
readonly valueField: "id";
readonly disabledField: "disabled";
};
};
/**
* Title/Key pattern: [{ title: "Option", key: "opt" }]
*/
readonly TITLE_KEY: {
readonly type: "simple";
readonly simple: {
readonly labelField: "title";
readonly valueField: "key";
readonly disabledField: "disabled";
};
};
/**
* Text/Value pattern: [{ text: "Option", value: "opt" }]
*/
readonly TEXT_VALUE: {
readonly type: "simple";
readonly simple: {
readonly labelField: "text";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* Display/Code pattern: [{ display: "Option", code: "OPT" }]
*/
readonly DISPLAY_CODE: {
readonly type: "simple";
readonly simple: {
readonly labelField: "display";
readonly valueField: "code";
readonly disabledField: "disabled";
};
};
};
/**
* Paginated response mappers for common pagination patterns
*/
export declare const PAGINATED_MAPPERS: {
/**
* Standard paginated: { data: [...], total: 100, page: 1 }
*/
readonly DATA_ARRAY: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "data";
readonly labelField: "label";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* Results pattern: { results: [...], count: 100 }
*/
readonly RESULTS_ARRAY: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "results";
readonly labelField: "name";
readonly valueField: "id";
readonly disabledField: "disabled";
};
};
/**
* Items pattern: { items: [...], totalItems: 100 }
*/
readonly ITEMS_ARRAY: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "items";
readonly labelField: "label";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* Nested data: { data: { items: [...] }, meta: {...} }
*/
readonly NESTED_DATA_ITEMS: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "data.items";
readonly labelField: "label";
readonly valueField: "value";
readonly disabledField: "disabled";
};
};
/**
* Response wrapper: { response: { data: [...] } }
*/
readonly RESPONSE_DATA: {
readonly type: "simple";
readonly simple: {
readonly arrayPath: "response.data";
readonly labelField: "name";
readonly valueField: "id";
readonly disabledField: "disabled";
};
};
};
/**
* Helper function to create a mapper for active/inactive patterns
*
* @param config - Configuration for active field mapping
* @returns ResponseMapperConfig
*
* @example
* ```typescript
* const mapper = createActiveMapper({
* arrayPath: 'users',
* labelField: 'fullName',
* valueField: 'userId',
* activeField: 'isActive',
* invertActive: false // true = active when false
* });
* ```
*/
export declare function createActiveMapper(config: {
arrayPath?: string;
labelField: string;
valueField: string;
activeField: string;
invertActive?: boolean;
}): ResponseMapperConfig;
/**
* Create a mapper pipeline that applies multiple transformations
*
* @param mappers - Array of mapper functions to apply in sequence
* @returns Combined mapper function
*
* @example
* ```typescript
* const pipeline = createMapperPipeline([
* // First extract and map basic structure
* (data) => mapSimpleResponse(data, { arrayPath: 'users' }),
* // Then filter out inactive users
* (options) => options.filter(opt => !opt.disabled),
* // Finally sort by label
* (options) => options.sort((a, b) => a.label.localeCompare(b.label))
* ]);
* ```
*/
export declare function createMapperPipeline(mappers: Array<ResponseMapper | ((options: ChoiceOption[]) => ChoiceOption[])>): ResponseMapper;
/**
* Filter helper to remove disabled options
*
* @param options - Options to filter
* @returns Filtered options
*/
export declare function filterEnabledOptions(options: ChoiceOption[]): ChoiceOption[];
/**
* Sort helper to sort options by label
*
* @param options - Options to sort
* @param locale - Locale for comparison (optional)
* @returns Sorted options
*/
export declare function sortByLabel(options: ChoiceOption[], locale?: string): ChoiceOption[];
/**
* Sort helper to sort options by value
*
* @param options - Options to sort
* @returns Sorted options
*/
export declare function sortByValue(options: ChoiceOption[]): ChoiceOption[];
/**
* Group helper to add group metadata to options
*
* @param options - Options to group
* @param groupBy - Function to determine group for each option
* @returns Options with group metadata
*/
export declare function groupOptions(options: ChoiceOption[], groupBy: (option: ChoiceOption) => string): ChoiceOption[];
/**
* Transform helper to add additional metadata
*
* @param options - Options to transform
* @param transform - Transform function
* @returns Transformed options
*/
export declare function transformOptions(options: ChoiceOption[], transform: (option: ChoiceOption, index: number) => ChoiceOption): ChoiceOption[];