decantr 0.9.0

package/src/form/index.js

@@ -0,0 +1,804 @@
+/**
+ * Decantr Form State Management
+ * Enterprise-grade reactive form handling built on Decantr signals.
+ *
+ * @module decantr/form
+ *
+ * Exports:
+ *   createForm(config)        — Create a reactive form instance
+ *   validators                — Built-in validator factories
+ *   useFormField(form, name)  — Hook for binding custom components
+ */
+import { createSignal, createEffect, createMemo, batch } from '../state/index.js';
+
+// ─── HELPERS ─────────────────────────────────────────────────────
+
+/** @param {any} v @returns {boolean} */
+function _empty(v) {
+  if (v == null) return true;
+  if (typeof v === 'string') return v.trim() === '';
+  if (Array.isArray(v)) return v.length === 0;
+  if (typeof v === 'number') return false;
+  if (typeof v === 'boolean') return false;
+  return false;
+}
+
+/** Shallow-clone plain object or return value as-is */
+function _clone(v) {
+  if (v && typeof v === 'object' && !Array.isArray(v)) return { ...v };
+  if (Array.isArray(v)) return [...v];
+  return v;
+}
+
+/** Simple deep-equal for plain values/objects/arrays */
+function _eq(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) { if (!_eq(a[i], b[i])) return false; }
+    return true;
+  }
+  if (typeof a === 'object') {
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    for (const k of ka) { if (!_eq(a[k], b[k])) return false; }
+    return true;
+  }
+  return false;
+}
+
+/** Debounce a function by `ms` milliseconds. Returns wrapped fn + cancel. */
+function _debounce(fn, ms) {
+  let id = null;
+  function debounced(...args) {
+    if (id !== null) clearTimeout(id);
+    id = setTimeout(() => { id = null; fn(...args); }, ms);
+  }
+  debounced.cancel = () => { if (id !== null) { clearTimeout(id); id = null; } };
+  return debounced;
+}
+
+// ─── VALIDATORS ──────────────────────────────────────────────────
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * Built-in validator factories. Each returns a validator function:
+ * `(value, allValues) => string|null` (sync) or `Promise<string|null>` (async).
+ *
+ * @namespace
+ */
+export const validators = {
+  /**
+   * Value must be truthy (non-empty string, non-null, non-undefined).
+   * @param {string} [msg='Required']
+   * @returns {(value: any) => string|null}
+   */
+  required(msg) {
+    const m = msg || 'Required';
+    return (v) => _empty(v) ? m : null;
+  },
+
+  /**
+   * String length must be >= n.
+   * @param {number} n
+   * @param {string} [msg]
+   * @returns {(value: any) => string|null}
+   */
+  minLength(n, msg) {
+    const m = msg || `Must be at least ${n} characters`;
+    return (v) => (typeof v === 'string' && v.length < n) ? m : null;
+  },
+
+  /**
+   * String length must be <= n.
+   * @param {number} n
+   * @param {string} [msg]
+   * @returns {(value: any) => string|null}
+   */
+  maxLength(n, msg) {
+    const m = msg || `Must be at most ${n} characters`;
+    return (v) => (typeof v === 'string' && v.length > n) ? m : null;
+  },
+
+  /**
+   * Numeric value must be >= n.
+   * @param {number} n
+   * @param {string} [msg]
+   * @returns {(value: any) => string|null}
+   */
+  min(n, msg) {
+    const m = msg || `Must be at least ${n}`;
+    return (v) => (typeof v === 'number' && v < n) ? m : null;
+  },
+
+  /**
+   * Numeric value must be <= n.
+   * @param {number} n
+   * @param {string} [msg]
+   * @returns {(value: any) => string|null}
+   */
+  max(n, msg) {
+    const m = msg || `Must be at most ${n}`;
+    return (v) => (typeof v === 'number' && v > n) ? m : null;
+  },
+
+  /**
+   * Value must match regex pattern.
+   * @param {RegExp} regex
+   * @param {string} [msg]
+   * @returns {(value: any) => string|null}
+   */
+  pattern(regex, msg) {
+    const m = msg || `Invalid format`;
+    return (v) => (typeof v === 'string' && !regex.test(v)) ? m : null;
+  },
+
+  /**
+   * Must be a valid email address.
+   * @param {string} [msg]
+   * @returns {(value: any) => string|null}
+   */
+  email(msg) {
+    const m = msg || 'Invalid email address';
+    return (v) => (typeof v === 'string' && v.length > 0 && !EMAIL_RE.test(v)) ? m : null;
+  },
+
+  /**
+   * Value must equal another field's current value.
+   * @param {string} fieldName — name of the field to match
+   * @param {string} [msg]
+   * @returns {(value: any, allValues: Object) => string|null}
+   */
+  match(fieldName, msg) {
+    const m = msg || `Must match ${fieldName}`;
+    return (v, all) => (!_eq(v, all[fieldName])) ? m : null;
+  },
+
+  /**
+   * Custom synchronous validator.
+   * `fn` should return `true` if valid or an error string if invalid.
+   * @param {(value: any, allValues: Object) => true|string} fn
+   * @param {string} [msg] — fallback message if fn returns non-string falsy
+   * @returns {(value: any, allValues: Object) => string|null}
+   */
+  custom(fn, msg) {
+    return (v, all) => {
+      const result = fn(v, all);
+      if (result === true) return null;
+      if (typeof result === 'string') return result;
+      return msg || 'Invalid';
+    };
+  },
+
+  /**
+   * Async validator. `fn` should return a Promise resolving to `true` or error string.
+   * Automatically debounced (300ms) when used in a form.
+   * @param {(value: any, allValues: Object) => Promise<true|string>} fn
+   * @param {string} [msg]
+   * @returns {(value: any, allValues: Object) => Promise<string|null>}
+   */
+  async(fn, msg) {
+    const validator = async (v, all) => {
+      const result = await fn(v, all);
+      if (result === true) return null;
+      if (typeof result === 'string') return result;
+      return msg || 'Invalid';
+    };
+    /** @type {any} */ (validator)._async = true;
+    return validator;
+  },
+};
+
+// ─── FIELD INSTANCE ──────────────────────────────────────────────
+
+/**
+ * @typedef {Object} FieldConfig
+ * @property {any} [value] — initial value
+ * @property {Array<Function>} [validators] — array of validator functions
+ * @property {Function} [transform] — (rawValue) => transformedValue, applied on setValue
+ */
+
+/**
+ * Creates a single reactive field instance.
+ * @param {string} name
+ * @param {FieldConfig} config
+ * @param {Function} getFormValues — () => all form values (for cross-field validators)
+ * @param {'onChange'|'onBlur'|'onSubmit'} validateOn
+ * @returns {FieldInstance}
+ */
+function _createField(name, config, getFormValues, validateOn) {
+  const initial = config.value !== undefined ? config.value : '';
+  const fieldValidators = config.validators || [];
+  const transform = config.transform || null;
+
+  const [value, _setValue] = createSignal(_clone(initial));
+  const [errors, setErrors] = createSignal(/** @type {string[]} */ ([]));
+  const [touched, setTouched] = createSignal(false);
+
+  /** @type {Function|null} */
+  let _asyncDebounced = null;
+
+  // Separate sync and async validators
+  const syncValidators = fieldValidators.filter(v => !/** @type {any} */ (v)._async);
+  const asyncValidators = fieldValidators.filter(v => /** @type {any} */ (v)._async);
+
+  /** Run sync validators, return error strings */
+  function _runSync(val, allValues) {
+    /** @type {string[]} */
+    const errs = [];
+    for (let i = 0; i < syncValidators.length; i++) {
+      const msg = syncValidators[i](val, allValues);
+      if (msg) errs.push(msg);
+    }
+    return errs;
+  }
+
+  /** Run all validators (sync + async), return error strings */
+  async function _runAll(val, allValues) {
+    const errs = _runSync(val, allValues);
+    // Only run async validators if sync passes (short-circuit)
+    if (errs.length === 0 && asyncValidators.length > 0) {
+      const results = await Promise.all(asyncValidators.map(v => v(val, allValues)));
+      for (const msg of results) {
+        if (msg) errs.push(msg);
+      }
+    }
+    return errs;
+  }
+
+  /** Trigger validation based on mode; called internally */
+  function _triggerValidation(mode) {
+    if (validateOn === 'onSubmit' && mode !== 'submit') return;
+    if (validateOn === 'onBlur' && mode === 'change') return;
+
+    const val = value();
+    const allValues = getFormValues();
+
+    // Sync validators run immediately
+    const syncErrs = _runSync(val, allValues);
+
+    if (asyncValidators.length > 0 && syncErrs.length === 0) {
+      // Debounce async validators
+      if (!_asyncDebounced) {
+        _asyncDebounced = _debounce(async () => {
+          const allErrs = await _runAll(value(), getFormValues());
+          setErrors(allErrs);
+        }, 300);
+      }
+      // Set sync errors first (empty), then kick off async
+      setErrors(syncErrs);
+      _asyncDebounced();
+    } else {
+      // Cancel any pending async validation
+      if (_asyncDebounced) _asyncDebounced.cancel();
+      setErrors(syncErrs);
+    }
+  }
+
+  function setValue(v) {
+    const raw = typeof v === 'function' ? v(value()) : v;
+    const transformed = transform ? transform(raw) : raw;
+    _setValue(transformed);
+    _triggerValidation('change');
+  }
+
+  function setTouchedFn() {
+    if (!touched()) setTouched(true);
+    _triggerValidation('blur');
+  }
+
+  function setError(msg) {
+    setErrors(msg ? [msg] : []);
+  }
+
+  function reset(val) {
+    const resetVal = val !== undefined ? val : _clone(initial);
+    batch(() => {
+      _setValue(resetVal);
+      setErrors([]);
+      setTouched(false);
+    });
+    if (_asyncDebounced) _asyncDebounced.cancel();
+  }
+
+  /** Validate field imperatively. Returns true if valid. */
+  async function validate() {
+    const allErrs = await _runAll(value(), getFormValues());
+    setErrors(allErrs);
+    return allErrs.length === 0;
+  }
+
+  // Derived signals
+  const error = createMemo(() => { const e = errors(); return e.length > 0 ? e[0] : null; });
+  const valid = createMemo(() => errors().length === 0);
+  const dirty = createMemo(() => !_eq(value(), initial));
+
+  /** @type {FieldInstance} */
+  const field = {
+    name,
+    value,
+    error,
+    errors,
+    touched,
+    dirty,
+    valid,
+    setValue,
+    setTouched: setTouchedFn,
+    setError,
+    reset,
+    validate,
+    /**
+     * Returns a props object for binding to Decantr form components.
+     * Compatible with Input, Select, Textarea, Checkbox, Switch, etc.
+     * @returns {{ value: Function, onchange: Function, onblur: Function, error: Function }}
+     */
+    bind() {
+      return {
+        value,
+        onchange: (v) => setValue(typeof v === 'object' && v !== null && v.target ? v.target.value : v),
+        onblur: () => setTouchedFn(),
+        error,
+      };
+    },
+  };
+
+  return field;
+}
+
+// ─── FIELD ARRAY ─────────────────────────────────────────────────
+
+/**
+ * Creates a reactive field array for repeatable form sections.
+ * Each item in the array is a plain value (or object). The array itself
+ * is stored as a signal so consumers can react to structural changes.
+ *
+ * @param {string} name
+ * @param {any[]} initial
+ * @returns {FieldArrayInstance}
+ */
+function _createFieldArray(name, initial) {
+  const [items, setItems] = createSignal(initial ? [...initial] : []);
+
+  return {
+    /** Signal getter for the array of items. */
+    items,
+
+    /** @returns {number} Current array length. */
+    length: createMemo(() => items().length),
+
+    /** Append a value to the end. @param {any} value */
+    append(value) { setItems(prev => [...prev, _clone(value)]); },
+
+    /** Prepend a value to the beginning. @param {any} value */
+    prepend(value) { setItems(prev => [_clone(value), ...prev]); },
+
+    /** Remove item at index. @param {number} index */
+    remove(index) {
+      setItems(prev => {
+        const next = [...prev];
+        next.splice(index, 1);
+        return next;
+      });
+    },
+
+    /** Move item from one index to another. @param {number} from @param {number} to */
+    move(from, to) {
+      setItems(prev => {
+        const next = [...prev];
+        const [item] = next.splice(from, 1);
+        next.splice(to, 0, item);
+        return next;
+      });
+    },
+
+    /** Swap two items by index. @param {number} a @param {number} b */
+    swap(a, b) {
+      setItems(prev => {
+        const next = [...prev];
+        const tmp = next[a];
+        next[a] = next[b];
+        next[b] = tmp;
+        return next;
+      });
+    },
+
+    /** Replace item at index with a new value. @param {number} index @param {any} value */
+    replace(index, value) {
+      setItems(prev => {
+        const next = [...prev];
+        next[index] = _clone(value);
+        return next;
+      });
+    },
+  };
+}
+
+// ─── CREATE FORM ─────────────────────────────────────────────────
+
+/**
+ * Create a reactive form instance.
+ *
+ * @param {Object} config
+ * @param {Object} config.fields — `{ fieldName: { value?, validators?, transform? } }`
+ * @param {Function} [config.onSubmit] — `async (values, form) => void`
+ * @param {Function} [config.validate] — `(values) => errors` — cross-field validation returning `{ fieldName: string[] }`
+ * @param {'onChange'|'onBlur'|'onSubmit'} [config.validateOn='onBlur']
+ * @returns {FormInstance}
+ *
+ * @example
+ * const form = createForm({
+ *   fields: {
+ *     email: { value: '', validators: [validators.required(), validators.email()] },
+ *     password: { value: '', validators: [validators.required(), validators.minLength(8)] },
+ *   },
+ *   validateOn: 'onBlur',
+ *   async onSubmit(values) { await api.login(values); },
+ * });
+ *
+ * // Bind to Decantr components
+ * Input({ type: 'email', ...form.field('email').bind() })
+ * Input({ type: 'password', ...form.field('password').bind() })
+ * Button({ onclick: () => form.submit() }, 'Login')
+ */
+export function createForm(config) {
+  const { fields: fieldConfigs = {}, onSubmit, validate: crossValidate, validateOn = 'onBlur' } = config;
+
+  const [isSubmitting, setIsSubmitting] = createSignal(false);
+  const [isSubmitted, setIsSubmitted] = createSignal(false);
+  const [submitCount, setSubmitCount] = createSignal(0);
+
+  /** @type {Map<string, FieldInstance>} */
+  const _fields = new Map();
+
+  /** @type {Map<string, FieldArrayInstance>} */
+  const _fieldArrays = new Map();
+
+  /** @type {Array<{name: string|null, cb: Function, dispose: Function|null}>} */
+  const _watchers = [];
+
+  // ── Values getter (reads all field signals) ──
+
+  function getValues() {
+    /** @type {Record<string, any>} */
+    const vals = {};
+    for (const [name, f] of _fields) {
+      vals[name] = f.value();
+    }
+    // Include field array values
+    for (const [name, fa] of _fieldArrays) {
+      vals[name] = fa.items();
+    }
+    return vals;
+  }
+
+  // ── Field creation / access ──
+
+  /**
+   * Get or create a FieldInstance by name.
+   * @param {string} name
+   * @returns {FieldInstance}
+   */
+  function field(name) {
+    let f = _fields.get(name);
+    if (!f) {
+      const cfg = fieldConfigs[name] || {};
+      f = _createField(name, cfg, getValues, validateOn);
+      _fields.set(name, f);
+    }
+    return f;
+  }
+
+  // Initialize all configured fields eagerly
+  for (const name of Object.keys(fieldConfigs)) {
+    field(name);
+  }
+
+  // ── Fields proxy ──
+  // Allows `form.fields.email.value()` syntax
+
+  const fields = new Proxy(/** @type {any} */ ({}), {
+    get(_, prop) {
+      if (typeof prop === 'string') return field(prop);
+      return undefined;
+    },
+  });
+
+  // ── Derived form-level signals ──
+
+  const errors = createMemo(() => {
+    /** @type {Record<string, string[]>} */
+    const errs = {};
+    for (const [name, f] of _fields) {
+      const fieldErrs = f.errors();
+      if (fieldErrs.length > 0) errs[name] = fieldErrs;
+    }
+    return errs;
+  });
+
+  const isValid = createMemo(() => {
+    for (const [, f] of _fields) {
+      if (!f.valid()) return false;
+    }
+    return true;
+  });
+
+  const isDirty = createMemo(() => {
+    for (const [, f] of _fields) {
+      if (f.dirty()) return true;
+    }
+    return false;
+  });
+
+  const values = createMemo(() => getValues());
+
+  // ── Actions ──
+
+  /**
+   * Run all field validators + cross-field validation.
+   * @returns {Promise<boolean>} true if form is valid
+   */
+  async function validate() {
+    const results = await Promise.all(
+      [..._fields.values()].map(f => f.validate())
+    );
+    const allValid = results.every(Boolean);
+
+    // Cross-field validation
+    if (crossValidate) {
+      const crossErrors = crossValidate(getValues());
+      if (crossErrors && typeof crossErrors === 'object') {
+        for (const [name, errs] of Object.entries(crossErrors)) {
+          const f = _fields.get(name);
+          if (f) {
+            const fieldErrs = Array.isArray(errs) ? errs : [errs];
+            if (fieldErrs.length > 0) {
+              // Merge with existing errors
+              f.setError(fieldErrs[0]);
+              return false;
+            }
+          }
+        }
+      }
+    }
+
+    return allValid;
+  }
+
+  /**
+   * Submit the form. Runs all validators, sets isSubmitting, calls onSubmit if valid.
+   * @returns {Promise<void>}
+   */
+  async function submit() {
+    setSubmitCount(c => c + 1);
+
+    // Touch all fields on submit
+    batch(() => {
+      for (const [, f] of _fields) f.setTouched();
+    });
+
+    const valid = await validate();
+    if (!valid) return;
+
+    if (!onSubmit) return;
+
+    setIsSubmitting(true);
+    try {
+      await onSubmit(getValues(), form);
+      setIsSubmitted(true);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  /**
+   * Reset all fields. Optionally provide new initial values.
+   * @param {Object} [newValues] — partial or full values to reset to
+   */
+  function reset(newValues) {
+    batch(() => {
+      for (const [name, f] of _fields) {
+        f.reset(newValues ? newValues[name] : undefined);
+      }
+      setIsSubmitted(false);
+      setSubmitCount(0);
+    });
+  }
+
+  /**
+   * Set multiple field values at once.
+   * @param {Object} partial — `{ fieldName: value }`
+   */
+  function setValues(partial) {
+    batch(() => {
+      for (const [name, val] of Object.entries(partial)) {
+        field(name).setValue(val);
+      }
+    });
+  }
+
+  /**
+   * Set errors on multiple fields at once.
+   * @param {Object} errs — `{ fieldName: string|string[] }`
+   */
+  function setErrors(errs) {
+    batch(() => {
+      for (const [name, msg] of Object.entries(errs)) {
+        const f = _fields.get(name);
+        if (f) f.setError(Array.isArray(msg) ? msg[0] : msg);
+      }
+    });
+  }
+
+  /**
+   * Get or create a FieldArrayInstance by name.
+   * @param {string} name
+   * @returns {FieldArrayInstance}
+   */
+  function fieldArray(name) {
+    let fa = _fieldArrays.get(name);
+    if (!fa) {
+      const cfg = fieldConfigs[name];
+      const initial = cfg && Array.isArray(cfg.value) ? cfg.value : [];
+      fa = _createFieldArray(name, initial);
+      _fieldArrays.set(name, fa);
+    }
+    return fa;
+  }
+
+  /**
+   * Watch a specific field for value changes.
+   * @param {string} fieldName
+   * @param {(value: any, prevValue: any) => void} callback
+   * @returns {Function} unsubscribe
+   */
+  function watch(fieldName, callback) {
+    const f = field(fieldName);
+    let prev = f.value();
+    const dispose = createEffect(() => {
+      const next = f.value();
+      if (!_eq(next, prev)) {
+        const old = prev;
+        prev = next;
+        callback(next, old);
+      }
+    });
+    const entry = { name: fieldName, cb: callback, dispose };
+    _watchers.push(entry);
+    return () => {
+      const idx = _watchers.indexOf(entry);
+      if (idx >= 0) _watchers.splice(idx, 1);
+      if (dispose) dispose();
+    };
+  }
+
+  /**
+   * Watch all fields for any value change.
+   * @param {(values: Object) => void} callback
+   * @returns {Function} unsubscribe
+   */
+  function watchAll(callback) {
+    const dispose = createEffect(() => {
+      const v = values();
+      callback(v);
+    });
+    const entry = { name: null, cb: callback, dispose };
+    _watchers.push(entry);
+    return () => {
+      const idx = _watchers.indexOf(entry);
+      if (idx >= 0) _watchers.splice(idx, 1);
+      if (dispose) dispose();
+    };
+  }
+
+  /** @type {FormInstance} */
+  const form = {
+    field,
+    fields,
+    values,
+    errors,
+    isValid,
+    isDirty,
+    isSubmitting,
+    isSubmitted,
+    submitCount,
+    submit,
+    reset,
+    setValues,
+    setErrors,
+    validate,
+    fieldArray,
+    watch,
+    watchAll,
+  };
+
+  return form;
+}
+
+// ─── USE FORM FIELD ──────────────────────────────────────────────
+
+/**
+ * Hook for binding a form field to a custom component.
+ * Returns reactive getters and handlers for value, error, touched, and blur.
+ *
+ * @param {FormInstance} form
+ * @param {string} fieldName
+ * @returns {{ value: Function, setValue: Function, error: Function, touched: Function, onBlur: Function }}
+ *
+ * @example
+ * function MyCustomInput(form, name) {
+ *   const { value, setValue, error, onBlur } = useFormField(form, name);
+ *   const input = h('input', { value: value(), onblur: onBlur });
+ *   createEffect(() => { input.value = value(); });
+ *   input.addEventListener('input', (e) => setValue(e.target.value));
+ *   return input;
+ * }
+ */
+export function useFormField(form, fieldName) {
+  const f = form.field(fieldName);
+  return {
+    value: f.value,
+    setValue: f.setValue,
+    error: f.error,
+    errors: f.errors,
+    touched: f.touched,
+    dirty: f.dirty,
+    valid: f.valid,
+    onBlur: f.setTouched,
+    bind: f.bind,
+  };
+}
+
+// ─── TYPE DEFINITIONS (JSDoc) ────────────────────────────────────
+
+/**
+ * @typedef {Object} FieldInstance
+ * @property {string} name
+ * @property {() => any} value — Signal getter for current value
+ * @property {() => string|null} error — First error or null
+ * @property {() => string[]} errors — All error messages
+ * @property {() => boolean} touched — Whether field has been blurred
+ * @property {() => boolean} dirty — Whether value differs from initial
+ * @property {() => boolean} valid — Whether field has no errors
+ * @property {(v: any) => void} setValue
+ * @property {() => void} setTouched
+ * @property {(msg: string) => void} setError
+ * @property {(val?: any) => void} reset
+ * @property {() => Promise<boolean>} validate
+ * @property {() => {value: Function, onchange: Function, onblur: Function, error: Function}} bind
+ */
+
+/**
+ * @typedef {Object} FieldArrayInstance
+ * @property {() => any[]} items — Signal getter for array of items
+ * @property {() => number} length — Reactive item count
+ * @property {(value: any) => void} append
+ * @property {(value: any) => void} prepend
+ * @property {(index: number) => void} remove
+ * @property {(from: number, to: number) => void} move
+ * @property {(a: number, b: number) => void} swap
+ * @property {(index: number, value: any) => void} replace
+ */
+
+/**
+ * @typedef {Object} FormInstance
+ * @property {(name: string) => FieldInstance} field
+ * @property {Object} fields — Proxy for field access via dot notation
+ * @property {() => Object} values — All current values
+ * @property {() => Object} errors — All errors `{ fieldName: string[] }`
+ * @property {() => boolean} isValid
+ * @property {() => boolean} isDirty
+ * @property {() => boolean} isSubmitting
+ * @property {() => boolean} isSubmitted
+ * @property {() => number} submitCount
+ * @property {() => Promise<void>} submit
+ * @property {(values?: Object) => void} reset
+ * @property {(partial: Object) => void} setValues
+ * @property {(errors: Object) => void} setErrors
+ * @property {() => Promise<boolean>} validate
+ * @property {(name: string) => FieldArrayInstance} fieldArray
+ * @property {(fieldName: string, callback: Function) => Function} watch
+ * @property {(callback: Function) => Function} watchAll
+ */