@radicalbit/formbit 1.2.1 → 2.1.0

package/dist/types/index.d.ts

@@ -1,41 +1,55 @@
 import { ObjectSchema, ValidationError as YupValidationError, ValidateOptions as YupValidateOptions } from 'yup';
 import { ACTIONS } from '../helpers/constants';
 /**
+ * @internal
  * @private
  */
 export type Action = keyof typeof ACTIONS;
 /**
- * Checks the given json against the form schema and returns and array of errors.
- * It returns undefined if the json is valid.
- *
+ * @internal
+ * Generic object with string keys.
  */
-export type Check<Values extends InitialValues> = (json: Form, options?: CheckFnOptions<Values>) => ValidationError[] | undefined;
+export type FormbitRecord = Record<string, unknown>;
+/** @deprecated Use {@link FormbitRecord} instead. Renamed to avoid shadowing the global `Object`. */
+export type Object = FormbitRecord;
 /**
- * Reset isDirty value to false
+ * @internal
  */
-export type ClearIsDirty = () => void;
+export type GenericCallback<Values extends InitialValues> = SuccessCallback<Values> | ErrorCallback<Values>;
 /**
- * Invoked in case of errors raised by validation
+ * @internal
  */
-export type ErrorCallback<Values extends InitialValues> = (writer: Writer<Values>, setError: SetError) => void;
+export type ValidationFormbitError = Pick<ValidationError, 'message' | 'path'>;
 /**
- * Invoked in case of errors raised by validation of check method
- *
+ * @internal
+ * @private
  */
-export type ErrorCheckCallback<Values extends InitialValues> = (json: Form, inner: ValidationError[], writer: Writer<Values>, setError: SetError) => void;
+export type WriteOrRemove<Values extends Form> = (path: keyof Values | string, value: unknown, options?: WriteFnOptions<Values>, action?: Action) => void;
 /**
- * Returns the error message for the given path if any.
- * It doesn't trigger any validation
- *
+ * @internal
+ * @private
  */
-export type ErrorFn = (path: string) => string | undefined;
+export type PrivateValidateForm<Values extends InitialValues> = (successCallback?: SuccessCallback<Values>, errorCallback?: ErrorCallback<Partial<Values>>, options?: {
+    options?: ValidateOptions;
+    isDirty?: boolean;
+}) => void;
+/**
+ * Base type for form values: a record of string keys with an optional `__metadata` field.
+ */
+export type FormbitValues = {
+    __metadata?: FormbitRecord;
+} & FormbitRecord;
+/** Object containing the updated form. */
+export type Form = FormbitValues;
+/** InitialValues used to set up formbit; also used to reset the form to its original version. */
+export type InitialValues = FormbitValues;
 /**
- * Object including all the registered errors messages since the last validation.
+ * Object including all the registered error messages since the last validation.
  * Errors are stored using the same path of the corresponding form values.
  *
  * @example
  * If the form object has this structure:
-* ```json
+ * ```json
  * {
  *   "age": 1
  * }
@@ -46,54 +60,20 @@ export type ErrorFn = (path: string) => string | undefined;
  *   "age": "Age must be greater then 18"
  * }
  * ```
- *
  */
 export type Errors = Record<string, string>;
-/**
- * Object containing the updated form
- */
-export type Form = {
-    __metadata?: Object;
-} & Object;
-export type GenericCallback<Values extends InitialValues> = SuccessCallback<Values> | ErrorCallback<Values>;
-/**
- *  Initialize the form with new initial values
- */
-export type Initialize<Values extends InitialValues> = (values: Partial<Values>) => void;
-/**
- *  InitialValues used to setup formbit, used also to reset the form to the original version.
- *
- */
-export type InitialValues = {
-    __metadata?: Object;
-} & Object;
-/**
- * Returns true if the form is Dirty (user already interacted with the form), false otherwise.
- *
- */
-export type IsDirty = boolean;
-/**
- * Returns true if the form is NOT valid
- * It doesn't perform any validation, it checks if any errors are present
- */
-export type IsFormInvalid = () => boolean;
-/**
- * Returns true id the form is valid
- * It doesn't perform any validation, it checks if any errors are present
- */
-export type IsFormValid = () => boolean;
 /**
  * Object including all the values that are being live validated.
- * Usually fields that fail validation (using one of the method that triggers validation)
- * will automatically set to be live-validated.
+ * Usually fields that fail validation (using one of the methods that triggers validation)
+ * will automatically be set to live-validated.
  *
  * A value/path is live-validated when validated at every change of the form.
  *
- * By default no field is live-validated
+ * By default no field is live-validated.
  *
  * @example
  * If the form object has this structure:
-* ```json
+ * ```json
  * {
  *   "age": 1
  * }
@@ -101,169 +81,121 @@ export type IsFormValid = () => boolean;
  * and age is a field that is being live-validated, liveValidation object will look like this
  * ```json
  * {
- *   "age": "Age must be greater then 18"
+ *   "age": true
  * }
  * ```
- *
  */
 export type LiveValidation = Record<string, true>;
 /**
- * Returns true if live validation is active for the given path
- *
- */
-export type LiveValidationFn = (path: string) => true | undefined;
-/**
- * Generic object with string as keys
- *
- */
-export type Object = Record<string, unknown>;
-/**
- * @private
+ * Internal form state storing all the data of the form (except the validation schema).
  */
-export type PrivateValidateForm<Values extends InitialValues> = (successCallback?: SuccessCallback<Values>, errorCallback?: ErrorCallback<Partial<Values>>, options?: {
-    options?: ValidateOptions;
-    isDirty?: boolean;
-}) => void;
-/**
- *
- * This method updates the form state deleting value and set isDirty to true.
- *
- * After writing, it validates all the paths contained into pathsToValidate (if any)
- * and all the fields that have the live validation active.
- *
- *
- */
-export type Remove<Values extends InitialValues> = (path: string, options?: WriteFnOptions<Values>) => void;
-/**
- * Reset form to the initial state.
- * Errors and liveValidation are set back to empty objects.
- * isDirty is set back to false
- *
- */
-export type ResetForm = () => void;
+export type FormState<Values extends InitialValues> = {
+    form: Values;
+    initialValues: Values;
+    errors: Errors;
+    liveValidation: LiveValidation;
+    isDirty: boolean;
+};
+/** @deprecated Use {@link FormState} instead. */
+export type Writer<Values extends InitialValues> = FormState<Values>;
 /**
  * Type imported from the yup library.
- * It represents any validation schema created with the yup.object() method
+ * It represents any validation schema created with the yup.object() method.
  *
  * Link to the Yup documentation {@link https://github.com/jquense/yup}
- *
  */
 export type ValidationSchema<Values extends InitialValues> = ObjectSchema<Values>;
 /**
- * Set a message(value) to the given error path.
+ * Type imported from the yup library.
+ * It represents the object with all the options that can be passed to the internal yup validation method.
  *
+ * Link to the Yup documentation {@link https://github.com/jquense/yup}
  */
-export type SetError = (path: string, value: string) => void;
+export type ValidateOptions = YupValidateOptions;
 /**
- * Override the current schema with the given one.
+ * Type imported from the yup library.
+ * It represents the error object returned when a validation fails.
  *
+ * Link to the Yup documentation {@link https://github.com/jquense/yup}
  */
-export type SetSchema<Values extends InitialValues> = (newSchema: ValidationSchema<Values>) => void;
+export type ValidationError = YupValidationError;
 /**
- * Perform a validation against the current form object, and execute the successCallback if the validation pass
- * otherwise it executes the errorCallback
- *
+ * Success callback invoked by some formbit methods when the operation is successful.
  */
-export type SubmitForm<Values extends InitialValues> = (successCallback: SuccessSubmitCallback<Values>, errorCallback?: ErrorCallback<Partial<Values>>, options?: ValidateOptions) => void;
+export type SuccessCallback<Values extends InitialValues> = (writer: FormState<Values>, setError: SetError) => void;
 /**
- * Success callback invoked by some formbit methods when the operation is successful.
- *
+ * Invoked in case of errors raised by validation.
  */
-export type SuccessCallback<Values extends InitialValues> = (writer: Writer<Values>, setError: SetError) => void;
+export type ErrorCallback<Values extends InitialValues> = (writer: FormState<Values>, setError: SetError) => void;
 /**
  * Success callback invoked by the check method when the operation is successful.
- *
  */
-export type SuccessCheckCallback<Values extends InitialValues> = (json: Form, writer: Writer<Values>, setError: SetError) => void;
+export type CheckSuccessCallback<Values extends InitialValues> = (json: Form, writer: FormState<Values>, setError: SetError) => void;
+/** @deprecated Use {@link CheckSuccessCallback} instead. */
+export type SuccessCheckCallback<Values extends InitialValues> = CheckSuccessCallback<Values>;
 /**
- * Success callback invoked by the submit method when the validation is successful.
- * Is the right place to send your data to the backend.
- *
+ * Invoked in case of errors raised by validation of check method.
  */
-export type SuccessSubmitCallback<Values extends InitialValues> = (writer: Writer<Values | Omit<Values, '__metadata'>>, setError: SetError, clearIsDirty: ClearIsDirty) => void;
+export type CheckErrorCallback<Values extends InitialValues> = (json: Form, inner: ValidationError[], writer: FormState<Values>, setError: SetError) => void;
+/** @deprecated Use {@link CheckErrorCallback} instead. */
+export type ErrorCheckCallback<Values extends InitialValues> = CheckErrorCallback<Values>;
 /**
- *
- * This method only validate the specified path. Do not check for fields that have the
- * live validation active.
+ * Success callback invoked by the submit method when the validation is successful.
+ * Is the right place to send your data to the backend.
  */
+export type SubmitSuccessCallback<Values extends InitialValues> = (writer: FormState<Values | Omit<Values, '__metadata'>>, setError: SetError, clearIsDirty: () => void) => void;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type ErrorFn = (path: string) => string | undefined;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type IsFormValid = () => boolean;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type IsFormInvalid = () => boolean;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type ClearIsDirty = () => void;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type ResetForm = () => void;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type LiveValidationFn = (path: string) => true | undefined;
+/** @deprecated Inlined into {@link FormbitObject}. */
+export type IsDirty = boolean;
+/** See {@link FormbitObject.check}. */
+export type Check<Values extends InitialValues> = (json: Form, options?: CheckFnOptions<Values>) => ValidationError[] | undefined;
+/** See {@link FormbitObject.initialize}. */
+export type Initialize<Values extends InitialValues> = (values: Partial<Values>) => void;
+/** See {@link FormbitObject.remove}. */
+export type Remove<Values extends InitialValues> = (path: string, options?: WriteFnOptions<Values>) => void;
+/** See {@link FormbitObject.setError}. */
+export type SetError = (path: string, value: string) => void;
+/** See {@link FormbitObject.setSchema}. */
+export type SetSchema<Values extends InitialValues> = (newSchema: ValidationSchema<Values>) => void;
+/** See {@link FormbitObject.submitForm}. */
+export type SubmitForm<Values extends InitialValues> = (successCallback: SubmitSuccessCallback<Values>, errorCallback?: ErrorCallback<Partial<Values>>, options?: ValidateOptions) => void;
+/** See {@link FormbitObject.validate}. */
 export type Validate<Values extends InitialValues> = (path: string, options?: ValidateFnOptions<Values>) => void;
-/**
- *
- * This method only validate the specified paths. Do not check for fields that have the
- * live validation active.
- */
+/** See {@link FormbitObject.validateAll}. */
 export type ValidateAll<Values extends InitialValues> = (paths: string[], options?: ValidateFnOptions<Values>) => void;
-/**
- * This method validates the entire form and set the corresponding errors if any.
- *
- */
+/** See {@link FormbitObject.validateForm}. */
 export type ValidateForm<Values extends InitialValues> = (successCallback?: SuccessCallback<Values>, errorCallback?: ErrorCallback<Values>, options?: ValidateOptions) => void;
-export type ValidationFormbitError = Pick<ValidationError, 'message' | 'path'>;
-/**
- * Type imported from the yup library.
- * It represents the object with all the options that can be passed to the internal yup validation method,
- *
- * Link to the Yup documentation {@link https://github.com/jquense/yup}
- *
- */
-export type ValidateOptions = YupValidateOptions;
-/**
- *
- * This method update the form state writing $value into the $path, setting isDirty to true.
- *
- * After writing, it validates all the paths contained into $pathsToValidate (if any)
- * and all the fields that have the live validation active.
- */
+/** See {@link FormbitObject.write}. */
 export type Write<Values extends InitialValues> = (path: keyof Values | string, value: unknown, options?: WriteFnOptions<Values>) => void;
-/**
- * This method takes an array of [path, value] and update the form state writing
- * all those values into the specified paths.
- *
- * It set isDirty to true.
- *
- * After writing, it validate all the paths contained into $pathToValidate and all
- * the fields that have the live validation active.
- *
- */
+/** See {@link FormbitObject.writeAll}. */
 export type WriteAll<Values extends InitialValues> = (arr: WriteAllValue<Values>[], options?: WriteFnOptions<Values>) => void;
-/**
-*
-* This method updates the form state deleting multiple values, setting isDirty to true.
-*
-*/
+/** See {@link FormbitObject.removeAll}. */
 export type RemoveAll<Values extends InitialValues> = (arr: string[], options?: WriteFnOptions<Values>) => void;
 /**
  * Tuple of [key, value] pair.
- *
  */
 export type WriteAllValue<Values extends InitialValues> = [keyof Values | string, unknown];
 /**
- * @private
- */
-export type WriteOrRemove<Values extends Form> = (path: keyof Values | string, value: unknown, options?: WriteFnOptions<Values>, action?: Action) => void;
-/**
- * Internal form state storing all the data of the form (except the validation schema)
- *
- */
-export type Writer<Values extends InitialValues> = {
-    form: Values;
-    initialValues: Values;
-    errors: Errors;
-    liveValidation: LiveValidation;
-    isDirty: IsDirty;
-};
-/**
- * Options object to change the behavior of the check method
- *
+ * Options object to change the behavior of the check method.
  */
 export type CheckFnOptions<Values extends InitialValues> = {
-    successCallback?: SuccessCheckCallback<Values>;
-    errorCallback?: ErrorCheckCallback<Values>;
+    successCallback?: CheckSuccessCallback<Values>;
+    errorCallback?: CheckErrorCallback<Values>;
     options?: ValidateOptions;
 };
 /**
- * Options object to change the behavior of the validate methods
- *
+ * Options object to change the behavior of the validate methods.
  */
 export type ValidateFnOptions<Values extends InitialValues> = {
     successCallback?: SuccessCallback<Partial<Values>>;
@@ -271,160 +203,131 @@ export type ValidateFnOptions<Values extends InitialValues> = {
     options?: ValidateOptions;
 };
 /**
- * Type imported from the yup library.
- * It represents the error object returned when a validation fails
- *
- * Link to the Yup documentation {@link https://github.com/jquense/yup}
- *
- */
-export type ValidationError = YupValidationError;
-/**
- * Options object to change the behavior of the write methods
- *
+ * Options object to change the behavior of the write methods.
  */
 export type WriteFnOptions<Values extends InitialValues> = {
     noLiveValidation?: boolean;
     pathsToValidate?: string[];
 } & ValidateFnOptions<Values>;
 /**
- * Object returned by useFormbit() and useFormbitContextHook()
+ * Object returned by useFormbit() and useFormbitContextHook().
  * It contains all the data and methods needed to handle the form.
- *
  */
 export type FormbitObject<Values extends InitialValues> = {
     /**
-     * Checks the given json against the form schema and returns and array of errors.
-     * It returns undefined if the json is valid.
-     *
+     * Object containing the updated form.
      */
-    check: Check<Partial<Values>>;
-    /**
-     * Returns the error message for the given path if any.
-     * It doesn't trigger any validation
-     *
-     */
-    error: ErrorFn;
+    form: Partial<Values>;
     /**
-     * Object including all the registered errors messages since the last validation.
+     * Object including all the registered error messages since the last validation.
      * Errors are stored using the same path of the corresponding form values.
      *
      * @example
      * If the form object has this structure:
-    * ```json
-    * {
-    *   "age": 1
-    * }
-    * ```
-    * and age is a non valid field, errors object will look like this
-    * ```json
-    * {
-    *   "age": "Age must be greater then 18"
-    * }
-    * ```
-    *
-    */
+     * ```json
+     * {
+     *   "age": 1
+     * }
+     * ```
+     * and age is a non valid field, errors object will look like this
+     * ```json
+     * {
+     *   "age": "Age must be greater then 18"
+     * }
+     * ```
+     */
     errors: Errors;
     /**
-     * Object containing the updated form
+     * Returns true if the form is Dirty (user already interacted with the form), false otherwise.
      */
-    form: Partial<Values>;
+    isDirty: boolean;
     /**
-     *  Initialize the form with new initial values
+     * Returns the error message for the given path if any.
+     * It doesn't trigger any validation.
      */
-    initialize: Initialize<Values>;
+    error: (path: string) => string | undefined;
     /**
-     * Returns true if the form is Dirty (user already interacted with the form), false otherwise.
-     *
+     * Returns true if the form is valid.
+     * It doesn't perform any validation, it checks if any errors are present.
      */
-    isDirty: boolean;
+    isFormValid: () => boolean;
     /**
-     * Returns true if the form is NOT valid
-     * It doesn't perform any validation, it checks if any errors are present
+     * Returns true if the form is NOT valid.
+     * It doesn't perform any validation, it checks if any errors are present.
      */
-    isFormInvalid: IsFormInvalid;
+    isFormInvalid: () => boolean;
     /**
-     * Returns true id the form is valid
-     * It doesn't perform any validation, it checks if any errors are present
+     * Returns true if live validation is active for the given path.
      */
-    isFormValid: IsFormValid;
+    liveValidation: (path: string) => true | undefined;
     /**
-     * Returns true if live validation is active for the given path
+     * Checks the given json against the form schema and returns an array of errors.
+     * It returns undefined if the json is valid.
+     */
+    check: Check<Partial<Values>>;
+    /**
+     * This method updates the form state writing $value into the $path, setting isDirty to true.
+     *
+     * After writing, it validates all the paths contained into $pathsToValidate (if any)
+     * and all the fields that have the live validation active.
      */
-    liveValidation: LiveValidationFn;
+    write: Write<Values>;
     /**
+     * This method takes an array of [path, value] and updates the form state writing
+     * all those values into the specified paths.
+     *
+     * It sets isDirty to true.
      *
+     * After writing, it validates all the paths contained into $pathToValidate and all
+     * the fields that have the live validation active.
+     */
+    writeAll: WriteAll<Values>;
+    /**
      * This method updates the form state deleting value, setting isDirty to true.
      *
      * After writing, it validates all the paths contained into pathsToValidate (if any)
      * and all the fields that have the live validation active.
-     *
-     *
      */
     remove: Remove<Values>;
+    /**
+     * This method updates the form state deleting multiple values, setting isDirty to true.
+     */
+    removeAll: RemoveAll<Values>;
+    /**
+     * Initialize the form with new initial values.
+     */
+    initialize: Initialize<Values>;
     /**
      * Reset form to the initial state.
      * Errors and liveValidation are set back to empty objects.
-     * isDirty is set back to false
-     *
+     * isDirty is set back to false.
      */
-    resetForm: ResetForm;
+    resetForm: () => void;
     /**
-     * Set a message(value) to the given error path.
-     *
+     * Set a message (value) to the given error path.
      */
     setError: SetError;
     /**
      * Override the current schema with the given one.
-     *
      */
     setSchema: SetSchema<Values>;
     /**
-     * Perform a validation against the current form object, and execute the successCallback if the validation pass
-     * otherwise it executes the errorCallback
-     *
-     */
-    submitForm: SubmitForm<Values>;
-    /**
-     *
-     * This method only validate the specified path. Do not check for fields that have the
+     * This method only validates the specified path. Does not check for fields that have the
      * live validation active.
      */
     validate: Validate<Values>;
     /**
-     *
-     * This method only validate the specified paths. Do not check for fields that have the
+     * This method only validates the specified paths. Does not check for fields that have the
      * live validation active.
      */
     validateAll: ValidateAll<Values>;
     /**
-     * This method validates the entire form and set the corresponding errors if any.
-     *
+     * This method validates the entire form and sets the corresponding errors if any.
      */
     validateForm: ValidateForm<Partial<Values>>;
     /**
-     *
-     * This method update the form state writing $value into the $path, setting isDirty to true.
-     *
-     * After writing, it validates all the paths contained into $pathsToValidate (if any)
-     * and all the fields that have the live validation active.
+     * Perform a validation against the current form object, and execute the successCallback if the validation passes,
+     * otherwise it executes the errorCallback.
      */
-    write: Write<Values>;
-    /**
-     *
-     *
-     * This method takes an array of [path, value] and update the form state writing
-     * all those values into the specified paths.
-     *
-     * It set isDirty to true.
-     *
-     * After writing, it validate all the paths contained into $pathToValidate and all
-     * the fields that have the live validation active.
-     */
-    writeAll: WriteAll<Values>;
-    /**
-     *
-     * This method updates the form state deleting multiple values, setting isDirty to true.
-     *
-     */
-    removeAll: RemoveAll<Values>;
+    submitForm: SubmitForm<Values>;
 };

package/dist/use-execute-callbacks.d.ts

@@ -1,4 +1,4 @@
-import { GenericCallback, InitialValues, SetError, Writer } from './types';
+import { FormState, GenericCallback, SetError } from './types';
 /**
  * useExecuteCallbacks
  *
@@ -7,5 +7,5 @@ import { GenericCallback, InitialValues, SetError, Writer } from './types';
  *
  *
  */
-declare const _default: <Values extends InitialValues>(writer: Writer<Values>, setError: SetError) => (uuid: string, cb?: GenericCallback<Partial<Values>>) => void;
+declare const _default: <Values extends import("./types").FormbitValues>(writer: FormState<Values>, setError: SetError) => (uuid: string, cb?: GenericCallback<Partial<Values>>) => void;
 export default _default;

package/dist/use-formbit.d.ts

@@ -3,5 +3,5 @@ type UseFormbitParams<Values extends InitialValues> = {
     initialValues?: Partial<Values>;
     yup: ValidationSchema<Values>;
 };
-declare const _default: <Values extends InitialValues>({ initialValues, yup: schema }: UseFormbitParams<Values>) => FormbitObject<Values>;
+declare const _default: <Values extends import("./types").FormbitValues>({ initialValues, yup: schema }: UseFormbitParams<Values>) => FormbitObject<Values>;
 export default _default;

package/dist/validate-sync-all.d.ts

@@ -1,2 +1,2 @@
-import { Form, InitialValues, ValidateOptions, ValidationFormbitError, ValidationSchema } from './types';
-export declare const validateSyncAll: <Values extends InitialValues>(paths: string[], schema: ValidationSchema<Values>, form: Form, options?: ValidateOptions) => ValidationFormbitError[];
+import { Form, ValidateOptions, ValidationFormbitError, ValidationSchema } from './types';
+export declare const validateSyncAll: <Values extends import("./types").FormbitValues>(paths: string[], schema: ValidationSchema<Values>, form: Form, options?: ValidateOptions) => ValidationFormbitError[];