@bolttech/form-engine-core 1.0.1-beta.2 → 1.0.1

package/src/types/schema.d.ts

@@ -1,10 +1,24 @@
-/// <reference types="node" />
 /** @virtual */
 import { TCurrencyCode, TCurrencyLocalCode } from '@gaignoux/currency';
 import { OutgoingHttpHeaders } from 'http2';
 import { TEvents } from './event';
 import { TFormValues } from './form';
 import { ALLOWED_RESET_PROPS_MUTATIONS } from '../constants/constants';
+type TAllowedResetPropsMutations = (typeof ALLOWED_RESET_PROPS_MUTATIONS)[number];
+/**
+ * @type TAllowedResetPropsMutationsEnum
+ * Represents the allowed properties to be changed on resetPropertyValues.
+ *
+ * @property {never} api - api property
+ * @property {never} apiSchema - apiSchema property
+ * @property {never} props - props property
+ * @property {never} validations - validations property
+ * @property {never} visibilityConditions - visibilityConditions property
+ * @property {never} resetValues - resetValues property
+ *
+ * @interface
+ */
+type TAllowedResetPropsMutationsEnum = Record<TAllowedResetPropsMutations, never>;
 /**
  * @type TLengthValidation
  * Represents the validation rules based on the length of the input.
@@ -118,7 +132,7 @@ type TDateOperatorsValidation = '<' | '>' | '===' | '>=' | '<=' | '!==' | '!!ori
 type TConditionsValidationSet = {
     forceDefinedOrigin?: boolean;
     forceDefinedTarget?: boolean;
-    origin?: string | number | boolean;
+    origin?: string | number | boolean | null;
     condition: TDateOperatorsValidation;
     target?: string | number | boolean;
 };
@@ -398,36 +412,67 @@ type TDateValidation = {
  * ```
  */
 type TValidationMethods = {
+    /** Maximum value or length. */
     max?: number;
+    /** Minimum value or length. */
     min?: number;
+    /** Minimum value or length. */
     lessThan?: number;
+    /** Minimum value or length. */
     greaterThan?: number;
+    /** Length validation rule. */
     length?: TLengthValidation;
+    /** Indicates if the field is required. */
     required?: boolean;
+    /** Specific value to match. */
     value?: unknown;
+    /** Regular expression for validation. */
     regex?: string;
+    /** Indicates if the value should be a valid email. */
     email?: boolean;
+    /** Indicates if the value should be a valid URL. */
     url?: boolean;
+    /** Indicates if the value should contain only letters. */
     onlyLetters?: boolean;
+    /** Indicates if spaces are not allowed. */
     notAllowSpaces?: boolean;
+    /** Custom validation callback function. */
     callback?: TCallbackValidation;
+    /** Indicates if the value should be a number. */
     isNumber?: boolean;
+    /** Indicates if the value should be a boolean or a string that can be converted to a boolean. */
     bool?: boolean | string;
+    /** Indicates if the value should exist or match a specific existence condition. */
     exists?: boolean | string;
+    /** Indicates if there should be no extra spaces. */
     hasNoExtraSpaces?: boolean;
+    /** Indicates if the field should not be empty. */
     notEmpty?: boolean;
+    /** Validation rule for range between two values. */
     between?: TBetweenValidation;
+    /** Indicates if the value should be sequential. */
     sequential?: boolean;
+    /** Indicates if the value should not be repeated. */
     repeated?: boolean;
+    /** Array of values that should be included. */
     includes?: (string | number)[];
+    /** Array of valid credit card numbers. */
     isCreditCard?: string[];
+    /** Validation rule for credit card matching. */
     isCreditCodeMatch?: TCreditCardMatch;
+    /** Array of valid credit card numbers with length check. */
     isCreditCardAndLength?: string[];
+    /** Document validation rule. */
     document?: TDocumentValidation;
+    /** Conditional validation rules. */
     conditions?: TConditionsValidation;
+    /** Multiple validation rules combined with a logical rule. */
     multipleValidations?: TMultipleValidation;
+    /** Validation rule for checking if a date falls between two dates. */
     betweenDates?: TBetweenDatesValidation;
+    /** Validation rule for date values. */
     date?: TDateValidation;
+    /** Validation rule for valid date formats. */
     validDate?: TDateFormatsValidation;
 };
 /**
@@ -446,9 +491,7 @@ type TValidationMethods = {
  *   },
  * };
  */
-type TGenericValidationRule = {
-    [key: string]: TValidationMethods;
-};
+type TGenericValidationRule = Record<string, TValidationMethods>;
 /**
  * @type {TValidationMethods | TGenericValidationRule} TSchemaValidation
  * Represents the schema validation which can be either a set of validation methods or a generic validation rule.
@@ -469,6 +512,7 @@ type TGenericValidationRule = {
  *     minLength: 8,
  *   },
  * };
+ * @interface
  */
 type TSchemaValidation = TValidationMethods | TGenericValidationRule;
 /**
@@ -506,33 +550,44 @@ type TSplitterFormatterValue = {
  * @property {number} [maxLength] - Truncates the input value to a specified maximum length if necessary.
  *
  * @example
- * ```typescript
- * const formatters: TFormatters = {
- *   dotEvery3chars: true,
- *   capitalize: true,
- *   uppercase: true,
- *   onlyNumbers: true,
- *   regex: '^[a-zA-Z0-9]+$',
- *   gapsCreditCard: [' ', ' '],
- *   callback: (value) => value.toString().toUpperCase(),
- *   splitter: [{ value: '-', position: 3 }],
- *   trim: true,
- *   maxLength: 15
- * };
+ * ```json
+ * {
+ *   formatters: {
+ *      dotEvery3chars: true,
+ *      capitalize: true,
+ *      uppercase: true,
+ *      onlyNumbers: true,
+ *      regex: '^[a-zA-Z0-9]+$',
+ *      gapsCreditCard: [' ', ' '],
+ *      callback: (value) => value.toString().toUpperCase(),
+ *      splitter: [{ value: '-', position: 3 }],
+ *      trim: true,
+ *      maxLength: 15
+ *   }
+ * }
  * ```
  */
 type TFormatters = {
+    /** Add a dot every 3 characters. */
     dotEvery3chars?: boolean;
+    /** Capitalize the value. */
     capitalize?: boolean;
+    /** Convert the value to uppercase. */
     uppercase?: boolean;
+    /** Allow only numbers. */
     onlyNumbers?: boolean;
+    /** Allow only letters. */
     onlyLetters?: boolean;
+    /** Allow only float numbers with specific precision and decimal. */
     onlyFloatNumber?: Pick<TCurrencyMask, 'precision' | 'decimal'>;
+    /** Regular expression for formatting. */
     regex?: string;
-    gapsCreditCard?: string[];
-    callback?: (value: unknown) => unknown;
+    gapsCreditCard?: string[] | boolean;
+    callback?: ((value: unknown) => unknown) | null;
     splitter?: TSplitterFormatterValue[];
+    /** Removes whitespace from both ends of this string and returns a new string, without modifying the original string. */
     trim?: boolean;
+    /** Truncates the input value to a specified maximum length if necessary. */
     maxLength?: number;
 };
 /**
@@ -612,15 +667,24 @@ type TMaskGeneric = {
  * ```
  */
 type TMasks = {
+    /** Mask for currency values. */
     currency?: TCurrencyMask;
+    /** Array of generic masks. */
     generic?: TMaskGeneric[];
-    custom?: string;
+    /** Custom mask pattern. */
+    custom?: string | null;
+    /** Mask for securing credit card values. */
     secureCreditCard?: boolean;
+    /** Mask for card values. */
     card?: boolean;
+    /** Mask for card date values. */
     cardDate?: boolean;
+    /** Mask for FEIN (Federal Employer Identification Number). */
     fein?: boolean;
+    /** Value to replace all matches. */
     replaceAll?: string | number;
-    callback?(value: unknown): string;
+    /** Custom mask callback function. */
+    callback?: (value: unknown) => string;
 };
 /**
  * @type TVisibility
@@ -645,29 +709,57 @@ type TVisibility = {
     showOnlyIfTrue?: boolean;
     validations: TSchemaValidation;
     fields: string[] | string;
-    events: Partial<TEvents>[];
+    events: TEvents[];
 };
 /**
  * @type TResetValueMethods
- * Extends TVisibility with methods to reset values.
+ * @extends TVisibility with methods to reset values.
+ * @summary schema method to reset values from event
+ * much cool such wow
+ *
+ * @property {unknown[] | unknown} resettledValue - The values to reset.
+ * @property {Partial<TEvents>[]} events - events that will react to the value reset
+ * @property {string | string[]} fields - fields that will react to the value reset
+ * @property {TSchemaValidation} validations - validations to trigger the property reset
  *
- * @property {string[] | string} resettledValue - The values to reset.
  *
  * @example
  * ```typescript
  * const resetValueMethods: TResetValueMethods = {
  *   validations: { required: true },
  *   fields: ['fieldName'],
- *   resettledValue: ['']
+ *   resettledValue: [''],
+ *   events: ['ON_FIELD_CHANGE]
  * };
  * ```
+ * @interface
  */
 type TResetValueMethods = Omit<TVisibility, 'showOnlyIfTrue' | 'validations'> & {
     resettledValue: unknown[] | unknown;
     validations?: TSchemaValidation;
 };
+/**
+ * @type TResetPathMethods
+ * Method to reset some field properties other than component props or field value
+ *
+ * @property {TAllowedResetPropsMutations} property property to be changed, ex: api, resetValues, etc..
+ * @property {string} path path where the property to be changed is located
+ * @property {string} field field that will recieve the property change
+ * @property {unknown} resettledValue value to be replaced onto the property
+ * @property {TSchemaValidation} validations validations rules to be validated to change the property value
+ * @property {Partial<TEvents>[]} events events to listen to apply this change
+ *
+ * @example
+ * ```typescript
+ * const resetValueMethods: TResetValueMethods = {
+ *   validations: { required: true },
+ *   fields: ['fieldName'],
+ *   resettledValue: ['']
+ * };
+ * ```
+ */
 type TResetPathMethods = {
-    property: (typeof ALLOWED_RESET_PROPS_MUTATIONS)[number];
+    property: TAllowedResetPropsMutations;
     path: string;
     field: string;
     resettledValue: unknown;
@@ -703,15 +795,25 @@ type TResetPathMethods = {
  * ```
  */
 type TApiConfig = {
+    /** The HTTP method for the request. */
     method: 'GET' | 'POST';
+    /** The URL for the request. */
     url: string;
+    /** The body payload for the request. */
     body?: Record<string, unknown>;
+    /** The headers for the request. */
     headers?: OutgoingHttpHeaders;
+    /** Query parameters for the request. */
     queryParams?: Record<string, string>;
+    /** The path to extract the result from the response. */
     resultPath?: string;
+    /** The fallback value if the request fails. */
     fallbackValue?: unknown;
+    /** Validation conditions to execute the API call. */
     preConditions?: TSchemaValidation;
+    /** Blocks request when field validation fails. */
     blockRequestWhenInvalid?: boolean;
+    /** Custom transform callback for the request payload. */
     transform?: {
         callback(callbackPayload: {
             payload: unknown;
@@ -732,7 +834,10 @@ type TProps = Record<string, unknown>;
  * @property {Partial<Record<TEvents, string[]>>} eventMessages - The messages to be displayed for specific validation events.
  * @property {TErrorMessages} messages - The general error messages for validation methods.
  *
+ * @interface
+ *
  * @example
+ * ```typescript
  * const validations: TValidations = {
  *   methods: {
  *     max: 100,
@@ -750,15 +855,45 @@ type TProps = Record<string, unknown>;
  *     regex: 'Value does not match the pattern',
  *   },
  * };
+ * ```
  */
 type TValidations = {
     methods: TSchemaValidation;
-    eventMessages?: Partial<Record<TEvents, Partial<keyof TValidationMethods | (string & NonNullable<unknown>)>[]>>;
+    eventMessages?: TEventMessages;
     messages?: TErrorMessages;
 };
+/**
+ * @type TValidations
+ * Represents the validation configuration for form fields, including methods, event-specific messages, and error messages.
+ *
+ * @property {TSchemaValidation} methods - The validation methods to be applied.
+ * @property {Partial<Record<TEvents, string[]>>} eventMessages - The messages to be displayed for specific validation events.
+ * @property {TErrorMessages} messages - The general error messages for validation methods.
+ *
+ * @example
+ * ```typescript
+ * const eventMessages: {
+ *     ON_FIELD_MOUNT: ['required'],
+ *     ON_FIELD_CHANGE: ['regex', 'required'],
+ *     ON_FIELD_BLUR: ['max', 'required'],
+ *   },
+ * ```
+ * @interface
+ */
+type TEventMessages = Partial<Record<TEvents, TEventMessagesValidationMethods[]>>;
+/**
+ * @type TEventMessagesValidationMethods
+ *
+ * allowed validation methods to trigger the event messages desc
+ *
+ * @property {keyof TValidationMethods | TAnyKey;} TEventMessagesValidationMethods - allowed validation methods to trigger the event messages
+ */
+type TEventMessagesValidationMethods = keyof TValidationMethods | TAnyKey;
+type TAnyKey = string & NonNullable<unknown>;
 /**
  * @type TErrorMessages
  * Represents the error messages for different validation methods.
+ * @property {string} default - the message to display regardless the validation
  *
  * @example
  * ```typescript
@@ -768,14 +903,9 @@ type TValidations = {
  *   default: 'Default error message'
  * };
  * ```
+ * @interface
  */
-type TErrorMessages = {
-    [K in keyof TSchemaValidation]?: string;
-} & {
-    default?: string;
-} & {
-    [key: string]: string;
-};
+type TErrorMessages = Partial<Record<keyof TSchemaValidation | 'default' | (string & NonNullable<unknown>), string>>;
 /**
  * Represents an event configuration with a specific type.
  *
@@ -785,13 +915,49 @@ type TErrorMessages = {
  */
 type TEvent<T> = {
     config: T;
-    events: Partial<TEvents>[];
+    events: TEvents[];
 };
 /**
  * Represents the API event configurations.
  *
  * @property {TEvent<TApiConfig>} [defaultConfig] - The default event configuration.
  * @property {Record<string, TEvent<TApiConfig>>} [configs] - Named event configurations.
+ *
+ * @example
+ * ```typescript
+ * const apiEvent: TApiEvent = {
+ *   defaultConfig: {
+ *     config: {
+ *       method: 'POST',
+ *       url: 'https://api.example.com/data',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       resultPath: 'data.results',
+ *       fallbackValue: [],
+ *       preConditions: {
+ *         required: true,
+ *       },
+ *       blockRequestWhenInvalid: true,
+ *     },
+ *     events: ['ON_FIELD_MOUNT', 'ON_FIELD_CHANGE'],
+ *   },
+ *   configs: {
+ *     example_config_name: {
+ *       config: {
+ *         method: 'POST',
+ *         url: 'https://api.example.com/data',
+ *         headers: { 'Content-Type': 'application/json' },
+ *         resultPath: 'data.results',
+ *         fallbackValue: [],
+ *         preConditions: {
+ *           required: true,
+ *         },
+ *         blockRequestWhenInvalid: true,
+ *       },
+ *       events: ['ON_FIELD_MOUNT', 'ON_FIELD_CHANGE'],
+ *     },
+ *   },
+ * };
+ * ```
  */
 type TApiEvent = {
     defaultConfig?: TEvent<TApiConfig>;
@@ -825,6 +991,7 @@ type TApiResponse = {
  * Represents the schema config structure
  *
  * @property {number} defaultAPIdebounceTimeMS - default API debounce time between request events.
+ * @property {boolean} defaultLogVerbose - flag to turn warning log messages on client.
  * @property {number} [defaultStateRefreshTimeMS] - default state refresh between events side effects.
  */
 type TSchemaFormConfig = {
@@ -832,4 +999,4 @@ type TSchemaFormConfig = {
     defaultStateRefreshTimeMS?: number;
     defaultLogVerbose?: boolean;
 };
-export { TApiConfig, TErrorMessages, TValidations, TMasks, TProps, TResetValueMethods, TResetPathMethods, TFormatters, TValidationMethods, TGenericValidationRule, TSchemaValidation, TEvent, TVisibility, TApiEvent, TApiResponsePayload, TApiResponse, TSchemaFormConfig, TLengthValidation, TCreditCardMatch, TDocumentValidation, TCallbackValidation, TBetweenValidation, TMaskGeneric, TSplitterFormatterValue, TCurrencyMask, TDateOperatorsValidation, TConditionsValidationSet, TConditionsValidation, TMultipleValidation, TAvailableValidations, TDateValidation, TBetweenDatesValidation, TDateFormatsValidation, TDateInterval, };
+export { TApiConfig, TErrorMessages, TValidations, TMasks, TProps, TResetValueMethods, TResetPathMethods, TFormatters, TValidationMethods, TGenericValidationRule, TSchemaValidation, TEvent, TVisibility, TApiEvent, TApiResponsePayload, TApiResponse, TSchemaFormConfig, TLengthValidation, TCreditCardMatch, TDocumentValidation, TCallbackValidation, TBetweenValidation, TMaskGeneric, TSplitterFormatterValue, TCurrencyMask, TDateOperatorsValidation, TConditionsValidationSet, TConditionsValidation, TMultipleValidation, TAvailableValidations, TDateValidation, TBetweenDatesValidation, TDateFormatsValidation, TDateInterval, TEventMessages, TEventMessagesValidationMethods, TAllowedResetPropsMutationsEnum, };

package/src/types/template.d.ts

@@ -1,11 +1,26 @@
-import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
 import { TMutationEvents } from './event';
+import { TEMPLATE_AVALIABLE_SCOPES } from '../constants/constants';
+type TTemplateAvaliableScopes = (typeof TEMPLATE_AVALIABLE_SCOPES)[number];
+/**
+ * @type TTemplateAvaliableScopesEnum
+ * Represents the different types of events that can occur on form fields.
+ * @property {never} fields - scope related to field content ex: '${fields.fieldName.value}'
+ * @property {never} iVars - scope related to iVars content ex: '${iVars.test}'
+ * @property {never} form - scope related to form content ex: '${form.valid}'
+ *
+ * @example
+ * ```typescript
+ * const scope: TTemplateAvaliableScopesEnum = 'fields';
+ * ```
+ * @interface
+ */
+type TTemplateAvaliableScopesEnum = Record<TTemplateAvaliableScopes, never>;
 /**
  * @type TSubscribedTemplates
  * Represents the subscribed templates for dynamic updates.
  *
  * @property {string} originExpression - The expression to evaluate.
- * @property {(typeof TEMPLATE_AVALIABLE_SCOPES)[number][]} originScopeKeys - Origin scope of the updated template value
+ * @property {TTemplateAvaliableScopes[]} originScopeKeys - Origin scope of the updated template value
  * @property {string[]} originPropertyKeys - The properties of the origin fields.
  * @property {string[]} originFieldKeys - The keys of the origin fields.
  * @property {string} destinationKey - The key of the destination field.
@@ -27,7 +42,7 @@ import { TMutationEvents } from './event';
  */
 type TSubscribedTemplates = {
     originExpression: string;
-    originScopeKeys: (typeof TEMPLATE_AVALIABLE_SCOPES)[number][];
+    originScopeKeys: TTemplateAvaliableScopes[];
     originPropertyKeys: string[];
     originFieldKeys: string[];
     destinationKey: string;
@@ -38,13 +53,13 @@ type TSubscribedTemplates = {
  * @type TTemplateEvent
  * Represents the event occuring on templates that changes property values.
  *
- * @property {(typeof TEMPLATE_AVALIABLE_SCOPES)[number]} scope - template scope triggering the event.
+ * @property {TTemplateAvaliableScopes} scope - template scope triggering the event.
  * @property {string} key - field triggering the template refresh
  * @property {TMutationEvents} event - template event triggering the template refresh.
  */
 type TTemplateEvent = {
-    scope: (typeof TEMPLATE_AVALIABLE_SCOPES)[number];
+    scope: TTemplateAvaliableScopes;
     key?: string;
     event: TMutationEvents;
 };
-export { TSubscribedTemplates, TTemplateEvent };
+export { TSubscribedTemplates, TTemplateEvent, TTemplateAvaliableScopes, TTemplateAvaliableScopesEnum };

package/src/validations/date.d.ts

@@ -56,7 +56,7 @@ export declare const betweenDates: (value: string, validations: TValidationMetho
  * console.log(result2); // true (date is outside the range)
  * ```
  */
-export declare const date: (value: string, validations: TValidationMethods) => boolean;
+export declare const date: (value: string | null, validations: TValidationMethods) => boolean;
 /**
  * @function validDate
  * Validates that a date string is a valid date according to the given format.

package/src/validations/list.d.ts

@@ -29,4 +29,4 @@ import { TValidationMethods } from '../types/schema';
  * console.log(isValid); // Output: true or false based on validation
  * ```
  */
-export declare const includes: (value: unknown, validations: TValidationMethods) => boolean;
+export declare const includes: (value: unknown, validations?: TValidationMethods | null) => boolean;

package/src/validations/logical.d.ts

@@ -46,7 +46,7 @@ export declare const required: (value: unknown, validations: TValidationMethods)
  * console.log(result2); // false
  * ```
  */
-export declare const bool: (_: unknown, validations: TValidationMethods) => boolean;
+export declare const bool: (_: unknown, validations: TValidationMethods | null) => boolean;
 /**
  * Validates that a value exists. Useful with iVars property.
  *

package/src/validations/string.d.ts

@@ -50,4 +50,4 @@ export declare const notEmpty: (value: unknown, validations: TValidationMethods)
  * console.log(result3); // false
  * ```
  */
-export declare const value: (value: unknown, validations: TValidationMethods) => boolean;
+export declare const value: (value: unknown, validations?: TValidationMethods) => boolean;