@bolttech/form-engine-core 0.0.1-beta.1

package/src/managers/field.d.ts

@@ -0,0 +1,294 @@
+import { Observable, Subject, Subscription } from 'rxjs';
+import { TApiConfig, TApiEvent, TApiResponse, TErrorMessages, TEvent, TFormatters, TMasks, TResetValueMethods, TValidationMethods, TVisibility } from '../types/schema';
+import { IComponentSchema } from '../interfaces/schema';
+import { IState } from '../interfaces/state';
+import { TEvents, TMutationEvents, TValueChangeEvent } from '../types/event';
+import { TMapper } from '../types/mapper';
+/**
+ * Represents a form field with observables for managing form state, validations, and API requests.
+ */
+declare class FormField {
+    name: string;
+    component: string;
+    path?: string;
+    children: string[];
+    validations?: TEvent<TValidationMethods>;
+    visibilityConditions?: TVisibility[];
+    resetValues?: TResetValueMethods[];
+    errorMessages?: TErrorMessages;
+    apiSchema?: TApiEvent;
+    formatters?: TFormatters;
+    masks?: TMasks;
+    valuePropName?: string;
+    errorMessagePropName?: string;
+    initialValue?: unknown;
+    mapper: TMapper<unknown>;
+    private _props;
+    private _value;
+    private _stateValue;
+    private _metadata;
+    private _visibility;
+    private _errors;
+    private _errorsString;
+    private _api;
+    private _valid;
+    propsSubject$: Subject<Record<string, unknown>>;
+    errorSubject$: Subject<string[]>;
+    valueSubject$: Subject<unknown>;
+    visibilitySubject$: Subject<boolean>;
+    apiSubject$: Subject<TApiResponse>;
+    apiResponseSubject$: Subject<{
+        key: string;
+    }>;
+    apiEventQueueSubject$: Subject<{
+        event: TEvents;
+    }>;
+    fieldState$: Observable<IState>;
+    fieldStateSubscription$: Subscription;
+    templateSubject$: Subject<{
+        key: string;
+        event: TMutationEvents;
+    }>;
+    dataSubject$: Subject<{
+        key: string;
+        event: TEvents;
+    }>;
+    validateVisibility: (payload: {
+        event: TEvents;
+        key: string;
+    }) => void;
+    resetValue: (payload: {
+        event: TEvents;
+        key: string;
+    }) => void;
+    valueChangeEvent: TValueChangeEvent;
+    /**
+     * Creates an instance of FormField.
+     *
+     * @param {object} options - Configuration options for the form field.
+     * @param {IComponentSchema} options.schemaComponent - The schema definition for the form field.
+     * @param {string} [options.path] - The path within the form field (used internally during recursion).
+     * @param {string[]} options.children - An array of children fields names.
+     * @param {Function} options.validateVisibility - A function to validate the visibility of the field.
+     * @param {Function} options.resetValue - A function to reset the field value.
+     * @param {unknown} [options.initialValue] - The initial value of the form field.
+     * @param {Subject<{ key: string }>} options.templateSubject$ - A subject for template updates.
+     */
+    constructor({ schemaComponent, path, children, validateVisibility, resetValue, initialValue, templateSubject$, apiResponseSubject$, dataSubject$, mapper, }: {
+        schemaComponent: IComponentSchema;
+        path?: string;
+        children: string[];
+        validateVisibility: (payload: {
+            event: TEvents;
+            key: string;
+        }) => void;
+        resetValue: (payload: {
+            event: TEvents;
+            key: string;
+        }) => void;
+        initialValue?: unknown;
+        templateSubject$: Subject<{
+            key: string;
+            event: TMutationEvents;
+        }>;
+        apiResponseSubject$: Subject<{
+            key: string;
+        }>;
+        dataSubject$: Subject<{
+            key: string;
+            event: TEvents;
+        }>;
+        mapper: TMapper<unknown>;
+    });
+    /**
+     * method to initialize all recycled Subjects and initialize Observers on field instance creation or rerender
+     */
+    initializeObservers(): void;
+    /**
+     * Observable function to emit api events debounced and distinct for each event type,
+     * avoiding previous events being cancelled by new events if they occur inside the debounce time interval
+     *
+     * @param {(event: { event: TEvents }) => TEvents} keyExtractor function that will pass the event key to the groupBy operator
+     * @param {number} debounceTimeMs time to wait for each individual event emmited
+     * @returns
+     */
+    debounceDistinct(keyExtractor: (event: {
+        event: TEvents;
+    }) => TEvents, debounceTimeMs: number): (source$: Observable<{
+        event: TEvents;
+    }>) => Observable<{
+        event: TEvents;
+    }>;
+    /**
+     * Retrieves the properties associated with the form field.
+     *
+     * @returns {Record<string, unknown>} - The properties of the form field.
+     */
+    get props(): Record<string, unknown>;
+    /**
+     * Sets the properties of the form field and notifies subscribers about the change.
+     *
+     * @param {Record<string, unknown>} props - The new properties to be set.
+     */
+    set props(props: Record<string, unknown>);
+    /**
+     * Retrieves the current state value of the form field.
+     *
+     * @returns {unknown} - The current state value of the form field.
+     */
+    get stateValue(): unknown;
+    get metadata(): unknown;
+    /**
+     * Retrieves the concatenated string of errors associated with the form field.
+     *
+     * @returns {string} - The concatenated string of errors.
+     */
+    get errorsString(): string;
+    /**
+     * Retrieves the current value of the form field.
+     *
+     * @returns {unknown} - The current value of the form field.
+     */
+    get value(): unknown;
+    /**
+     * Sets the value of the form field and notifies subscribers about the change.
+     *
+     * @param {unknown} value - The new value to be set.
+     */
+    set value(value: unknown);
+    /**
+     * Retrieves the visibility status of the form field.
+     *
+     * @returns {boolean} - The visibility status of the form field.
+     */
+    get visibility(): boolean;
+    /**
+     * Sets the visibility status of the form field and notifies subscribers about the change.
+     *
+     * @param {boolean} visible - The new visibility status to be set.
+     */
+    set visibility(visible: boolean);
+    /**
+     * Retrieves the validity status of the form field.
+     *
+     * @returns {boolean} - The validity status of the form field.
+     */
+    get valid(): boolean;
+    /**
+     * Retrieves the error messages associated with the form field.
+     *
+     * @returns {TErrorMessages} - The error messages associated with the form field.
+     */
+    get errors(): TErrorMessages;
+    /**
+     * Sets the error messages associated with the form field and notifies subscribers about the change.
+     *
+     * @param {TErrorMessages} errors - The new error messages to be set.
+     */
+    set errors(errors: TErrorMessages);
+    /**
+     * Retrieves the API response data associated with the form field.
+     *
+     * @returns {TApiResponse} - The API response data associated with the form field.
+     */
+    get api(): TApiResponse;
+    /**
+     * Sets the API response data associated with the form field and notifies subscribers about the change.
+     *
+     * @param {TApiResponse} response - The new API response data to be set.
+     */
+    set api(response: TApiResponse);
+    /**
+     * Mounts the form field by initializing necessary subjects and combining their streams.
+     *
+     * @param {object} mountOpts - Adapter mount options.
+     * @param {string} prop.valuePropName - Adapter value property name.
+     * @param {(event: unknown) => unknown} prop.valueChangeEvent - Adapter change event handler function
+     * @param {(value: unknown) => unknown} prop.valueSubscription - Adapter value change function
+     * @param {(payload: Partial<IState>) => unknown} prop.propsSubscription - Adapter prop change function
+     * @param {string} prop.errorMessagePropName - error message property name to set errors onto component
+     * @returns {void}
+     */
+    mountField({ valueSubscription, propsSubscription, }: {
+        valueSubscription: (value: unknown) => void;
+        propsSubscription: (payload: Partial<IState>) => void;
+    }): void;
+    /**
+     * Sets the value of the form field and emits associated events.
+     *
+     * @param {unknown} prop.value - The new value to be set.
+     * @param {TEvents} prop.event - The event associated with setting the value.
+     * @returns {void}
+     */
+    emitValue(prop: {
+        value: unknown | {
+            _value: unknown;
+            _stateValue: unknown;
+        };
+        event: TEvents;
+    }): void;
+    /**
+     * Emits events to trigger field-related actions such as validation, visibility checks, value resets, and API requests.
+     *
+     * @param {TEvents} event - The event type that triggers the field actions.
+     * @returns {void}
+     */
+    emitEvents({ event }: {
+        event: TEvents;
+    }): void;
+    /**
+     * Sets the validity state of the field based on the provided validation rules and triggers error message updates.
+     *
+     * @param {TEvents} event - The event type associated with the field action.
+     * @returns {void}
+     */
+    setFieldValidity({ event }: {
+        event: TEvents;
+    }): void;
+    /**
+     * Formats the field value using the specified formatters, if available.
+     *
+     * @param {unknown} value - The value to be formatted.
+     * @returns {unknown} - The formatted value.
+     */
+    formatValue(value: unknown): unknown;
+    /**
+     * Masks the field value using the specified masks, if available.
+     *
+     * @param {unknown} value - The value to be masked.
+     * @returns {unknown} - The masked value.
+     */
+    maskValue(value: unknown): unknown;
+    checkApiRequestValidations(config: TApiConfig): boolean;
+    /**
+     * Makes an API request based on the field's API configuration and event type, updating the field's API response data.
+     *
+     * @param {TEvents} event - The event type associated with the API request.
+     * @returns {Promise<void>}
+     */
+    apiRequest({ event }: {
+        event: TEvents;
+    }): Promise<void>;
+    /**
+     * Unsubscribes from all subject subscriptions associated with the field, cleaning up resources.
+     *
+     * @returns {void}
+     */
+    destroyField(): void;
+    /**
+     * Subscribes to changes in the field state and executes the provided callback function.
+     *
+     * @param {Function} callback - The callback function to be executed when the field state changes.
+     * @returns {void}
+     */
+    subscribeState(callback: (payload: Partial<IState>) => void): void;
+    /**
+     * Subscribes to changes in the field value and executes the provided callback function.
+     *
+     * @param {Function} callback - The callback function to be executed when the field value changes.
+     * @returns {void}
+     */
+    subscribeValue(callback: (value: unknown) => void): void;
+}
+type IFormField = FormField;
+export { IFormField, FormField };

package/src/managers/form.d.ts

@@ -0,0 +1,224 @@
+import { IFormField } from './field';
+import { Subject, Subscription } from 'rxjs';
+import { IComponentSchema, IFormSchema } from '../interfaces/schema';
+import { TSubscribedTemplates } from '../types/template';
+import { TEvents, TMutationEvents } from '../types/event';
+import { TFormEntry, TFormValues } from '../types/form';
+import { TMapper } from '../types/mapper';
+/**
+ * Represents the core logic for managing a form, including field management, validation, and submission.
+ */
+declare class FormCore {
+    schema?: IFormSchema;
+    fields: Map<string, IFormField>;
+    initialValues?: Record<string, unknown>;
+    private _iVars;
+    templateSubject$: Subject<{
+        key: string;
+        event: TMutationEvents;
+    }>;
+    submitSubject$: Subject<TFormValues>;
+    apiResponseSubject$: Subject<{
+        key: string;
+    }>;
+    dataSubject$: Subject<{
+        key: string;
+        event: TEvents;
+    }>;
+    dataCallbackSubscription$: Subscription;
+    subscribedTemplates: TSubscribedTemplates[];
+    action?: string;
+    method?: string;
+    mappers: TMapper<unknown>[];
+    onSubmit?: (data: TFormValues) => void;
+    /**
+     * Creates an instance of FormCore.
+     *
+     * @param {TFormEntry & Omit<IFormSchema, 'components'>} entry - Configuration options for the form.
+     * @param {IFormSchema} entry.schema - The schema definition for the form.
+     * @param {Record<string, unknown> | IFormSchema.initialValues} [entry.initialValues] - Initial values for the form fields.
+     * @param {string} [entry.action] - The action attribute of the form.
+     * @param {string} [entry.method] - The method attribute of the form.
+     * @param {IFormSchema.iVars} [entry.iVars] - The internal variables of the form.
+     * @param {(data: TFormValues) => void} [entry.onSubmit] - A callback function to handle form submission.
+     * @param {((payload: {field: string;data: TFormValues;}) => void) | undefined} [entry.onData] - A callback function to handle data emission.
+     */
+    constructor(entry: TFormEntry & Omit<IFormSchema, 'components'>);
+    /**
+     * Retrieves the internal variables (iVars) of the form.
+     *
+     * @returns {Record<string, unknown>} - The internal variables of the form.
+     */
+    get iVars(): Record<string, unknown>;
+    /**
+     * Sets the internal variables (iVars) of the form and notifies subscribers about the change.
+     *
+     * @param {Record<string, unknown>} payload - The new internal variables to be set.
+     */
+    set iVars(payload: Record<string, unknown>);
+    /**
+     * Checks if the form is valid by validating all form fields.
+     *
+     * @returns {boolean} True if the form is valid; otherwise, false.
+     */
+    get isValid(): boolean;
+    /**
+     * Subscribes to templates for dynamic updates.
+     */
+    subscribeTemplates(): void;
+    /**
+     *
+     * @param {(payload: { field: string; data: TFormValues }) => void} callback callback function to call on data
+     */
+    subscribeData(callback: (payload: {
+        field: string;
+        data: TFormValues;
+    }) => void): void;
+    /**
+     * Gets the value of a property from a field.
+     *
+     * @param {object} options - Options for getting the value.
+     * @param {string} options.key - The key of the field.
+     * @param {string} options.property - The property to retrieve.
+     * @param {string[]} options.path - The path to the property if it's nested.
+     * @returns {unknown | undefined} The value of the property, or undefined if the field doesn't exist.
+     */
+    getValue({ key, property, path, }: {
+        key: string;
+        property: string;
+        path: string[];
+    }): unknown | undefined;
+    /**
+     * Sets the value of a property in a field.
+     *
+     * @param {object} options - Options for setting the value.
+     * @param {string} options.key - The key of the field.
+     * @param {string} options.property - The property to set.
+     * @param {string[]} options.path - The path to the property if it's nested.
+     * @param {unknown} options.originKey - field that called templating
+     * @param {unknown} options.value - The value to set.
+     * @param {TMutationEvents} options.event - Internal Event for template Handling.
+     */
+    setValue({ key, property, path, originKey, value, }: {
+        key: string;
+        property: string;
+        path: string[];
+        originKey: string;
+        value: unknown;
+        event: TMutationEvents;
+    }): void;
+    /**
+     * Extracts parameters from an expression.
+     *
+     * @param {string} expression - The expression containing parameters.
+     * @returns {string[]} An array of extracted parameters.
+     */
+    extractParams(expression: string): string[];
+    /**
+     * Replaces expressions marked by ${...} in the expression string with the provided values.
+     *
+     * @param {string} expression - The expression string containing the marked expressions.
+     * @param {string[]} values - The values to be inserted into the marked expressions.
+     * @returns {string} The expression string with the replacements made.
+     */
+    replaceExpression(expression: string, values: string[]): string;
+    /**
+     * Checks if an expression string contains string concatenation within a marked expression.
+     *
+     * @param {string} expression - The expression string to be checked.
+     * @returns {boolean} True if the expression contains string concatenation, otherwise false.
+     */
+    hasStringConcatenation(expression: string): boolean;
+    /**
+     * Refreshes templates with updated values.
+     *
+     * @param {object} options - Options for refreshing templates.
+     * @param {string} options.key - The key of the field triggering the update.
+     * @param {TMutationEvents} options.event - Internal event descriptor to handle templating.
+     */
+    refreshTemplates({ key, event }: {
+        key: string;
+        event: TMutationEvents;
+    }): void;
+    /**
+     * Refreshes api observed fields.
+     *
+     * @param {object} options - Options for refreshing api.
+     * @param {string} options.key - The key of the field triggering the update.
+     */
+    refreshApi({ key }: {
+        key: string;
+    }): string;
+    /**
+     * Validates and collects the names of form fields in the provided schema structure.
+     *
+     * @param {IComponentSchema[]} [struct] - The schema structure of the form components.
+     * @param {string[]} [indexes=[]] - An array to collect the names of the form fields.
+     * @returns {string[]} - An array of form field names.
+     * @throws {Error} - Throws an error if a field name matches the reserved name defined by `IVARPROPNAME`.
+     * @private
+     */
+    private static checkIndexes;
+    /**
+     * Validates visibility conditions for a given event and updates field visibility accordingly.
+     *
+     * @param {object} options - Options for validating visibility.
+     * @param {TEvents} options.event - The event triggering visibility validation.
+     * @param {string} options.key - The key of the field.
+     */
+    validateVisibility({ event, key }: {
+        event: TEvents;
+        key: string;
+    }): void;
+    /**
+     * Resets field values based on reset conditions defined in the schema.
+     *
+     * @param {object} options - Options for resetting field values.
+     * @param {TEvents} options.event - The event triggering the reset.
+     * @param {string} options.key - The key of the field.
+     */
+    resetValue({ event, key }: {
+        event: TEvents;
+        key: string;
+    }): void;
+    /**
+     * Serializes the schema structure to create form fields.
+     *
+     * @param {IComponentSchema[]} [struct] - The schema structure to serialize.
+     * @param {string} [path] - The path of the parent component.
+     */
+    serializeStructure(struct?: IComponentSchema[], path?: string): void;
+    /**
+     * Refreshes form fields based on changes in the schema structure.
+     *
+     * @param {IComponentSchema[]} struct - The updated schema structure.
+     */
+    refreshFields(struct: IComponentSchema[]): void;
+    /**
+     * Gets a form field by its key.
+     *
+     * @param {object} options - Options for getting the form field.
+     * @param {string} options.key - The key of the form field.
+     * @returns {IFormField | undefined} The form field, or undefined if not found.
+     */
+    getField({ key }: {
+        key: string;
+    }): IFormField | undefined;
+    /**
+     * Prints the current values of all form fields.
+     */
+    printValues(): void;
+    /**
+     * Gets the current values of all form fields.
+     *
+     * @returns {TFormValues} The current form values.
+     */
+    getFormValues(): TFormValues;
+    /**
+     * Submits the form by triggering form field events and invoking the onSubmit callback.
+     */
+    submit(): void;
+    destroy(): void;
+}
+type TFormCore = FormCore;
+export { TFormCore, FormCore };

package/src/managers/formGroup.d.ts

@@ -0,0 +1,64 @@
+import { TFormValues } from '../types/form';
+import { TFormCore } from './form';
+/**
+ * Represents a group that manages multiple forms.
+ */
+declare class FormGroup {
+    forms: Map<string, TFormCore>;
+    /**
+     * Creates an instance of FormGroup.
+     */
+    constructor();
+    /**
+     * Adds a form instance to the form group.
+     *
+     * @param {object} options - Options for adding a form.
+     * @param {string} options.key - The key associated with the form instance.
+     * @param {TFormCore} options.formInstance - The instance of the form to add.
+     */
+    addForm({ key, formInstance }: {
+        key: string;
+        formInstance: TFormCore;
+    }): void;
+    /**
+     * Retrieves a form instance from the form group.
+     *
+     * @param {object} options - Options for retrieving a form.
+     * @param {string} options.key - The key associated with the form instance.
+     * @returns {TFormCore | undefined} The instance of the form, if found; otherwise, undefined.
+     */
+    getForm({ key }: {
+        key: string;
+    }): import("./form").FormCore | undefined;
+    /**
+     * Removes a form instance from the form group.
+     *
+     * @param {object} options - Options for removing a form.
+     * @param {string} options.key - The key associated with the form instance to remove.
+     */
+    removeForm({ key }: {
+        key: string;
+    }): void;
+    /**
+     * Checks if the specified key already exists in the form group.
+     *
+     * @param {object} options - Options for checking the key.
+     * @param {string} options.key - The key to check.
+     * @throws {Error} Throws an error if the key already exists in the form group.
+     */
+    checkIndexes({ key }: {
+        key: string;
+    }): void;
+    /**
+     * Prints the form group instance to the console.
+     */
+    printFormGroupInstance(): void;
+    /**
+     * Prototype submit function to multiple forms
+     * @param {string[]} indexes form indexes to be submitted
+     * @returns
+     */
+    submitMultipleFormsByIndex(indexes: string[]): TFormValues;
+}
+type TFormGroup = FormGroup;
+export { TFormGroup, FormGroup };

package/src/masks/creditCard.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Applies a secure mask to a credit card number, hiding most of its digits.
+ *
+ * @param value - The credit card number to be masked.
+ * @returns The masked credit card number.
+ *
+ * @example
+ * ```typescript
+ * import { secureCreditCard } from './path/to/creditCardFunctions';
+ *
+ * const maskedCardNumber = secureCreditCard('1234567890123456');
+ * console.log(maskedCardNumber); // Output: '1xxxxxxxxxxxx456'
+ * ```
+ */
+export declare const secureCreditCard: (value: string) => string;
+/**
+ * Formats a credit card number by inserting spaces every four characters.
+ *
+ * @param value - The credit card number to be formatted.
+ * @returns The formatted credit card number.
+ *
+ * @example
+ * ```typescript
+ * import { card } from './path/to/creditCardFunctions';
+ *
+ * const formattedCardNumber = card('1234567890123456');
+ * console.log(formattedCardNumber); // Output: '1234 5678 9012 3456'
+ * ```
+ */
+export declare const card: (value: string) => string;
+/**
+ * Formats a credit card expiration date (MM/YY).
+ *
+ * @param value - The expiration date to be formatted (in MMYY or MM/YY format).
+ * @returns The formatted expiration date.
+ *
+ * @example
+ * ```typescript
+ * import { cardDate } from './path/to/creditCardFunctions';
+ *
+ * const formattedCardDate = cardDate('1223');
+ * console.log(formattedCardDate); // Output: '12/23'
+ * ```
+ */
+export declare const cardDate: (value: string) => string;
+/**
+ * Formats a credit card FEIN (Federal Employer Identification Number) in a specific format.
+ *
+ * @param value - The FEIN to be formatted.
+ * @returns The formatted FEIN.
+ *
+ * @example
+ * ```typescript
+ * import { fein } from './path/to/creditCardFunctions';
+ *
+ * const formattedFEIN = fein('123456789');
+ * console.log(formattedFEIN); // Output: '12-3456789'
+ * ```
+ */
+export declare const fein: (value: string) => string;

package/src/masks/generic.d.ts

@@ -0,0 +1,39 @@
+import { TMasks } from '../types/schema';
+/**
+ * Applies multiple generic masks to a string based on the provided mask configuration.
+ *
+ * @param value - The value to be masked.
+ * @param masks - An object containing the mask configuration.
+ * @returns The masked value.
+ *
+ * @example
+ * ```typescript
+ * import maskValue from './path/to/maskFunctions';
+ *
+ * const masks = {
+ *   generic: [
+ *     { from: 2, to: 4, mask: '*' },
+ *     { from: 7, to: 9, mask: '#' }
+ *   ]
+ * };
+ *
+ * const maskedValue = maskValue('123456789', masks);
+ * console.log(maskedValue); // Output: '1**45###9'
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   value: 'abcdefghij',
+ *   masks: {
+ *     generic: [
+ *       { from: 3, to: 6, mask: '*' },
+ *       { from: 8, to: 10, mask: '#' }
+ *     ]
+ *   }
+ * };
+ *
+ * const maskedValue = maskValue(config.value, config.masks);
+ * console.log(maskedValue); // Output: 'ab***gh###'
+ * ```
+ */
+declare const _default: (value: string, masks: TMasks) => string;
+export default _default;

package/src/masks/handler.d.ts

@@ -0,0 +1,2 @@
+import { TMasks } from '../types/schema';
+export declare const masks: Record<keyof TMasks, (value: unknown, masks?: TMasks) => unknown>;