@bolttech/form-engine-core 1.0.10 → 1.1.0

package/src/types/template.d.ts

@@ -0,0 +1,65 @@
+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 {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.
+ * @property {string} destinationProperty - The property of the destination field.
+ * @property {string[]} destinationPath - The path to the destination property.
+ *
+ * @example
+ * ```typescript
+ * const subscribedTemplates: TSubscribedTemplates = {
+ *   originExpression: 'originField1 + originField2',
+ *   originScopeKeys: ['field','field'],
+ *   originPropertyKeys: ['value', 'props'],
+ *   originFieldKeys: ['originField1', 'originField2'],
+ *   destinationKey: 'resultField',
+ *   destinationProperty: 'value',
+ *   destinationPath: ['path', 'to', 'resultField']
+ * };
+ * ```
+ */
+type TSubscribedTemplates = {
+    originExpression: string;
+    originScopeKeys: TTemplateAvaliableScopes[];
+    originPropertyKeys: string[];
+    originFieldKeys: string[];
+    destinationKey: string;
+    destinationProperty: string;
+    destinationPath: string[];
+};
+/**
+ * @type TTemplateEvent
+ * Represents the event occuring on templates that changes property values.
+ *
+ * @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: TTemplateAvaliableScopes;
+    key?: string;
+    event: TMutationEvents;
+};
+export { TSubscribedTemplates, TTemplateEvent, TTemplateAvaliableScopes, TTemplateAvaliableScopesEnum };

package/src/types/utility.d.ts

@@ -0,0 +1,12 @@
+import { TFormValues } from './form';
+import { TValidationMethods } from './schema';
+export type AllowOnly<T, K extends keyof T> = Pick<T, K> & {
+    [P in keyof Omit<T, K>]?: never;
+};
+export type OneOf<T, K = keyof T> = K extends keyof T ? AllowOnly<T, K> : never;
+export type TValidationPayload = [
+    unknown,
+    TValidationMethods,
+    TFormValues<unknown>?
+];
+export type TValidationHandler = Record<string, (...args: TValidationPayload) => boolean>;

package/src/validations/creditCard.d.ts

@@ -0,0 +1,52 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Validates if a given value is a valid credit card number based on predefined validation methods.
+ *
+ * @param value - The value to be validated as a credit card number.
+ * @param validations - An object containing validation methods.
+ * @returns `true` if the value is either falsy or does not match a valid credit card type, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { isCreditCard } from './path/to/validationFunctions';
+ * import { validationMethods } from './path/to/validationConfig';
+ *
+ * const isValid = isCreditCard('4111111111111111', validationMethods);
+ * console.log(isValid); // Output: true or false based on validation
+ * ```
+ */
+export declare const isCreditCard: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Validates if a given security code matches the expected length for a specified credit card type.
+ *
+ * @param value - The security code to be validated.
+ * @param validations - An object containing validation methods, specifically with `isCreditCodeMatch` details.
+ * @returns `true` if the value is either falsy or if the validation methods are not provided. Otherwise, it checks if the security code length matches the expected length for the card type.
+ *
+ * @example
+ * ```typescript
+ * import { isCreditCodeMatch } from './path/to/validationFunctions';
+ * import { validationMethods } from './path/to/validationConfig';
+ *
+ * const isValid = isCreditCodeMatch('123', validationMethods);
+ * console.log(isValid); // Output: true or false based on validation
+ * ```
+ */
+export declare const isCreditCodeMatch: (value: string, validations: TValidationMethods) => boolean;
+/**
+ * Validates if a given value is a valid credit card number and checks if its length matches the expected lengths for the card type.
+ *
+ * @param value - The credit card number to be validated.
+ * @param validations - An object containing validation methods, specifically with `isCreditCardAndLength` details.
+ * @returns `true` if the value is either falsy or if the card number does not match any valid lengths for the card type, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { isCreditCardAndLength } from './path/to/validationFunctions';
+ * import { validationMethods } from './path/to/validationConfig';
+ *
+ * const isValid = isCreditCardAndLength('4111111111111111', validationMethods);
+ * console.log(isValid); // Output: true or false based on validation
+ * ```
+ */
+export declare const isCreditCardAndLength: (value: string, validations: TValidationMethods) => boolean;

package/src/validations/custom.d.ts

@@ -0,0 +1,27 @@
+import { TFormValues } from '../types/form';
+import { TValidationMethods } from '../types/schema';
+/**
+ * Executes a custom callback validation function if provided.
+ *
+ * @param value - The value to be validated.
+ * @param validations - An object containing validation methods, including a custom callback function.
+ * @param formValues - An object containing the form state, NOTE: validations might be dirty here
+ * @returns `true` if the custom callback validation function returns `true`, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { callback } from './path/to/validationFunctions';
+ *
+ * const validations = {
+ *   callback: (value) => typeof value === 'string' && value.length > 5
+ * };
+ *
+ * // Or from a JSON config
+ * const schema = {
+ *   validations: {
+ *     callback: (value) => typeof value === 'string' && value.length > 5
+ *   }
+ * };
+ * ```
+ */
+export declare const callback: (value: unknown, validations: TValidationMethods, { values, metadata }?: TFormValues<unknown>) => boolean;

package/src/validations/date.d.ts

@@ -0,0 +1,79 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * @function betweenDates
+ * Validates if a date value falls between two specified dates.
+ *
+ * @param {string} value - The date value to be validated in string format.
+ * @param {TValidationMethods} validations - The validation methods object containing the betweenDates validation rules.
+ * @returns {boolean} - Returns `true` if the date value fails the betweenDates validation, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * const validations = {
+ *   betweenDates: [
+ *     { origin: { value: '2023-01-01', format: 'yyyy-MM-dd' }, operator: '>=' },
+ *     { origin: { value: '2023-12-31', format: 'yyyy-MM-dd' }, operator: '<=' }
+ *   ]
+ * };
+ *
+ * const result1 = betweenDates('2023-06-01', validations);
+ * console.log(result1); // false (date is within the range)
+ *
+ * const result2 = betweenDates('2024-01-01', validations);
+ * console.log(result2); // true (date is outside the range)
+ * ```
+ */
+export declare const betweenDates: (value: string, validations: TValidationMethods) => boolean;
+/**
+ * @function date
+ * Validates a date value based on various date conditions and intervals.
+ *
+ * @param {string} value - The date value to be validated in string format.
+ * @param {TValidationMethods} validations - The validation methods object containing the date validation rules.
+ * @returns {boolean} - Returns `true` if the date validation fails, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * const validations = {
+ *   date: {
+ *     origin: {
+ *       value: '2023-01-01',
+ *       format: 'YYYY-MM-DD'
+ *     },
+ *     target: {
+ *       value: '2023-12-31',
+ *       format: 'YYYY-MM-DD'
+ *     },
+ *     operator: '<=',
+ *     onlyValidDate: true
+ *   }
+ * };
+ *
+ * const result1 = date('2023-06-01', validations);
+ * console.log(result1); // false (date is within the range)
+ *
+ * const result2 = date('2024-01-01', validations);
+ * console.log(result2); // true (date is outside the range)
+ * ```
+ */
+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.
+ *
+ * @param {string} value - The date value to be validated in string format.
+ * @param {TValidationMethods} validations - The validation methods object containing the validDate rule.
+ * @returns {boolean} - Returns `true` if the date is not valid, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * const validations = { validDate: 'MM-dd-yyyy' };
+ *
+ * const result1 = validDate('12-31-2023', validations);
+ * console.log(result1); // false (date is valid)
+ *
+ * const result2 = validDate('02-30-2023', validations);
+ * console.log(result2); // true (date is invalid)
+ * ```
+ */
+export declare const validDate: (value: string, validations: TValidationMethods) => boolean;

package/src/validations/document.d.ts

@@ -0,0 +1,25 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * General validation function for various document types based on the provided validation methods.
+ *
+ * @param value - The document value to validate.
+ * @param validations - An object containing validation methods.
+ * @returns `true` if the document is valid, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import validateDocument from './path/to/validationFunctions';
+ *
+ * const validations = {
+ *   document: {
+ *     type: 'NIF',
+ *     locale: 'pt-PT'
+ *   }
+ * };
+ *
+ * const isValid = validateDocument('123456789', validations);
+ * console.log(isValid); // Output: true or false based on validation
+ * ```
+ */
+declare const _default: (value: string, validations: TValidationMethods) => boolean;
+export default _default;

package/src/validations/handler.d.ts

@@ -0,0 +1,2 @@
+import { TValidationHandler } from '../types/utility';
+export declare const validations: TValidationHandler;

package/src/validations/length.d.ts

@@ -0,0 +1,39 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Validates the length of a value based on the provided validation rules.
+ *
+ * @param value - The value to be validated. Can be of any type but will be converted to a string for length validation.
+ * @param validations - An object containing the length validation rules.
+ * @returns `true` if the value meets the length validation rule, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import validateLength from './path/to/validationFunctions';
+ *
+ * const validations = {
+ *   length: {
+ *     target: 5,
+ *     rule: 'equal'
+ *   }
+ * };
+ *
+ * const isValid = validateLength('hello', validations);
+ * console.log(isValid); // Output: true
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   inputValue: 'test',
+ *   validations: {
+ *     length: {
+ *       target: 4,
+ *       rule: 'equal'
+ *     }
+ *   }
+ * };
+ *
+ * const isValid = validateLength(config.inputValue, config.validations);
+ * console.log(isValid); // Output: true or false based on validation
+ * ```
+ */
+declare const _default: (value: unknown, validations: TValidationMethods) => boolean;
+export default _default;

package/src/validations/list.d.ts

@@ -0,0 +1,32 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Checks if a value is included in the specified array within the validation rules.
+ *
+ * @param value - The value to be checked.
+ * @param validations - An object containing validation methods, including an array of allowed values.
+ * @returns `true` if the value is included in the array, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { includes } from './path/to/validationFunctions';
+ *
+ * const validations = {
+ *   includes: ['apple', 'banana', 'cherry']
+ * };
+ *
+ * const isValid = includes('banana', validations);
+ * console.log(isValid); // Output: true
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   inputValue: 'apple',
+ *   validations: {
+ *     includes: ['apple', 'banana', 'cherry']
+ *   }
+ * };
+ *
+ * const isValid = includes(config.inputValue, config.validations);
+ * console.log(isValid); // Output: true or false based on validation
+ * ```
+ */
+export declare const includes: (value: unknown, validations?: TValidationMethods | null) => boolean;

package/src/validations/logical.d.ts

@@ -0,0 +1,75 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Validates that a value is required.
+ *
+ * @param {unknown} value - The value to be validated.
+ * @param {TValidationMethods} validations - The validation methods object containing the required validation rule.
+ * @returns {boolean} - Returns `true` if the value is required and is empty or not provided, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * // Assume validations is an object with a required property
+ * const validations = { required: true };
+ *
+ * // Returns true because the value is required and is empty
+ * const result1 = required('', validations);
+ * console.log(result1); // true
+ *
+ * // Returns false because the value is required and is provided
+ * const result2 = required('text', validations);
+ * console.log(result2); // false
+ *
+ * // Returns false because the required validation rule is not set
+ * const result3 = required('', { required: false });
+ * console.log(result3); // false
+ * ```
+ */
+export declare const required: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Validates that a value matches a boolean rule. Useful with iVars property.
+ *
+ * @param _
+ * @param {TValidationMethods} validations - The validation methods object containing the boolean validation rule.
+ * @returns {boolean} - Returns `true` if the boolean validation rule is set and fails, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * // Assume validations is an object with a bool property
+ * const validations = { bool: true };
+ *
+ * // Returns true because the boolean validation rule is set to fail
+ * const result1 = bool(null, validations);
+ * console.log(result1); // true
+ *
+ * // Returns false because the boolean validation rule is not set
+ * const result2 = bool(null, { bool: false });
+ * console.log(result2); // false
+ * ```
+ */
+export declare const bool: (_: unknown, validations: TValidationMethods | null) => boolean;
+/**
+ * Validates that a value exists. Useful with iVars property.
+ *
+ * @param {unknown} value - The value to be validated.
+ * @param {TValidationMethods} validations - The validation methods object containing the exists validation rule.
+ * @returns {boolean} - Returns `true` if the value does not exist when the exists rule is set, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * // Assume validations is an object with an exists property
+ * const validations = { exists: true };
+ *
+ * // Returns true because the value does not exist
+ * const result1 = exists(null, validations);
+ * console.log(result1); // true
+ *
+ * // Returns false because the value exists
+ * const result2 = exists('text', validations);
+ * console.log(result2); // false
+ *
+ * // Returns false because the exists validation rule is not set
+ * const result3 = exists(null, { exists: false });
+ * console.log(result3); // false
+ * ```
+ */
+export declare const exists: (value: unknown, validations: TValidationMethods) => boolean;

package/src/validations/multiple.d.ts

@@ -0,0 +1,31 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Validates that a value meets multiple validation rules.
+ *
+ * @param {number | string | boolean} value - The value to be validated.
+ * @param {TValidationMethods} methods - The validation methods object containing the multipleValidations rule set.
+ * @returns {boolean} - Returns `true` if the value meets the specified multiple validation rules, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * // Assume validations is an object with a multipleValidations property
+ * const validations = {
+ *   multipleValidations: {
+ *     rule: 'AND',
+ *     validations: {
+ *       required: true,
+ *       isNumber: true
+ *     }
+ *   }
+ * };
+ *
+ * // Returns true because both required and isNumber validations pass
+ * const result1 = multipleValidations(123, validations);
+ * console.log(result1); // true
+ *
+ * // Returns false because the value is not a number
+ * const result2 = multipleValidations('abc', validations);
+ * console.log(result2); // false
+ * ```
+ */
+export declare const multipleValidations: (value: number | string | boolean, methods: TValidationMethods) => boolean;

package/src/validations/namedRule.d.ts

@@ -0,0 +1,22 @@
+import { TValidationMethods } from '../types/schema';
+import { TValidationHandler } from '../types/utility';
+/**
+ * Validates a given value based on specified validation methods inside a custom named validation.
+ *
+ * @param {unknown} value - The value to be validated.
+ * @param {TValidationMethods} methods - The validation methods to be applied.
+ * @param {TValidationHandler} validations - An object containing every validation methods to be executed.
+ * @returns {boolean} - Returns true if any of the validation methods pass, otherwise false.
+ *
+ * @example
+ * const value = 'example@example.com';
+ * const methods = {
+ *   required: true,
+ *   email: true
+ * };
+ *
+ * const isValid = validateValue(value, methods);
+ * console.log(isValid); // Output: true
+ */
+declare const _default: (value: unknown, methods: TValidationMethods, validations: TValidationHandler) => boolean;
+export default _default;

package/src/validations/number.d.ts

@@ -0,0 +1,145 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Validates if a value exceeds the maximum allowed value.
+ *
+ * @param value - The value to be checked.
+ * @param validations - An object containing the maximum value for validation.
+ * @returns `true` if the value exceeds the maximum, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { max } from './path/to/validationFunctions';
+ *
+ * const validations = { max: 10 };
+ *
+ * const isValid = max(15, validations);
+ * console.log(isValid); // Output: true
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   inputValue: '8',
+ *   validations: { max: 10 }
+ * };
+ *
+ * const isValid = max(config.inputValue, config.validations);
+ * console.log(isValid); // Output: false
+ * ```
+ */
+export declare const max: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Validates if a value is less than the minimum allowed value.
+ *
+ * @param value - The value to be checked.
+ * @param validations - An object containing the minimum value for validation.
+ * @returns `true` if the value is less than the minimum, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { min } from './path/to/validationFunctions';
+ *
+ * const validations = { min: 5 };
+ *
+ * const isValid = min(3, validations);
+ * console.log(isValid); // Output: true
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   inputValue: '8',
+ *   validations: { min: 10 }
+ * };
+ *
+ * const isValid = min(config.inputValue, config.validations);
+ * console.log(isValid); // Output: true
+ * ```
+ */
+export declare const min: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Validates if a value falls within a specified range.
+ *
+ * @param value - The value to be checked.
+ * @param validations - An object containing the range (start and end) for validation.
+ * @returns `true` if the value falls within the range, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { between } from './path/to/validationFunctions';
+ *
+ * const validations = { between: { start: 5, end: 10 } };
+ *
+ * const isValid = between(7, validations);
+ * console.log(isValid); // Output: true
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   inputValue: '4',
+ *   validations: { between: { start: 5, end: 10 } }
+ * };
+ *
+ * const isValid = between(config.inputValue, config.validations);
+ * console.log(isValid); // Output: false
+ * ```
+ */
+export declare const between: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Checks if a given value is less than a specified threshold.
+ *
+ * @param value - The value to be checked. This value will be converted to a number.
+ * @param validations - An object containing validation methods, specifically the `lessThan` property which holds the threshold value.
+ * @returns Returns `false` if the `lessThan` threshold is not provided or if the value is not a valid number. Otherwise, returns `true` if the value is greater than or equal to the `lessThan` threshold.
+ *
+ * @example
+ * ```typescript
+ * const validations = { lessThan: 10 };
+ * console.log(lessThan(5, validations)); // true
+ * console.log(lessThan(15, validations)); // false
+ * ```
+ */
+export declare const lessThan: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Checks if a given value is greater than a specified threshold.
+ *
+ * @param value - The value to be checked. This value will be converted to a number.
+ * @param validations - An object containing validation methods, specifically the `greaterThan` property which holds the threshold value.
+ * @returns Returns `false` if the `greaterThan` threshold is not provided or if the value is not a valid number. Otherwise, returns `true` if the value is less than or equal to the `greaterThan` threshold.
+ *
+ * @example
+ * ```typescript
+ * const validations = { greaterThan: 10 };
+ * console.log(greaterThan(15, validations)); // true
+ * console.log(greaterThan(5, validations)); // false
+ * ```
+ */
+export declare const greaterThan: (value: unknown, validations: TValidationMethods) => boolean;
+/**
+ * Validates if a value contains sequential numbers.
+ *
+ * @param value - The value to be checked.
+ * @param validations - An object containing the validation methods.
+ * @returns `true` if the value contains sequential numbers, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * import { sequential } from './path/to/validationFunctions';
+ *
+ * const validations = { sequential: true };
+ *
+ * const isValid = sequential('12345', validations);
+ * console.log(isValid); // Output: true
+ *
+ * // Using in a React component
+ * const MyComponent = ({ inputValue }) => {
+ *   const isValid = sequential(inputValue, validations);
+ *   return <div>{isValid ? 'Valid' : 'Invalid'}</div>;
+ * };
+ *
+ * // Using from a JSON config
+ * const config = {
+ *   inputValue: '98765',
+ *   validations: { sequential: true }
+ * };
+ *
+ * const isValid = sequential(config.inputValue, config.validations);
+ * console.log(isValid); // Output: true
+ * ```
+ */
+export declare const sequential: (value: unknown, validations: TValidationMethods) => boolean;

package/src/validations/object.d.ts

@@ -0,0 +1,44 @@
+import { TValidationMethods } from '../types/schema';
+/**
+ * Validates that a value meets specified conditions.
+ *
+ * @param {number | string | boolean} value - The value to be validated.
+ * @param {TValidationMethods} validations - The validation methods object containing the conditions validation rule.
+ * @returns {boolean} - Returns `true` if the value meets the specified conditions, otherwise `false`.
+ *
+ * @example
+ * ```typescript
+ * // Assume validations is an object with a conditions property
+ * const validations = {
+ *   conditions: {
+ *     rule: 'and',
+ *     set: [
+ *       { condition: '===', origin: 10, target: 10 },
+ *       { condition: '!==', origin: 5, target: 3 }
+ *     ]
+ *   }
+ * };
+ *
+ * // Returns true because both conditions are met
+ * const result1 = conditions(10, validations);
+ * console.log(result1); // true
+ *
+ * // Returns false because the second condition is not met
+ * const result2 = conditions(5, validations);
+ * console.log(result2); // false
+ *
+ * // Returns true because at least one condition is met with 'or' rule
+ * const orValidations = {
+ *   conditions: {
+ *     rule: 'or',
+ *     set: [
+ *       { condition: '===', origin: 10, target: 5 },
+ *       { condition: '!==', origin: 5, target: 3 }
+ *     ]
+ *   }
+ * };
+ * const result3 = conditions(10, orValidations);
+ * console.log(result3); // true
+ * ```
+ */
+export declare const conditions: (value: number | string | boolean, validations: TValidationMethods) => boolean;