add documentation for utill functions

reports/api-extractor.md

@@ -339,7 +339,7 @@ export type FormSubmitHandler<TFieldValues extends FieldValues> = (payload: {
     method?: 'post' | 'put' | 'delete';
 }) => unknown | Promise<unknown>;
 
-// @public (undocumented)
+// @public
 export const get: <T>(object: T, path?: string, defaultValue?: unknown) => any;
 
 // @public (undocumented)
@@ -531,7 +531,7 @@ export type ResolverSuccess<TFieldValues extends FieldValues = FieldValues> = {
     errors: {};
 };
 
-// @public (undocumented)
+// @public
 export const set: (object: FieldValues, path: string, value?: unknown) => FieldValues;
 
 // @public (undocumented)

src/logic/generateId.ts

@@ -1,3 +1,7 @@
+/** 
+ Generates a unique identifier string in the UUID v4 format. 
+ NOT for serious cryptography.
+ */
 export default () => {
   const d =
     typeof performance === 'undefined' ? Date.now() : performance.now() * 1000;

src/logic/getFocusFieldName.ts

@@ -1,6 +1,24 @@
 import { FieldArrayMethodProps, InternalFieldName } from '../types';
 import isUndefined from '../utils/isUndefined';
-
+/**
+ * Constructs the focus name for a field array 
+ * based on the given parameters. If the `shouldFocus`
+ * option is true or undefined, it returns a focus name.
+ * The focus name is constructed based on the 
+ * `focusName` option, the `name` parameter, 
+ * and either the `focusIndex` option or the provided `index`.
+ * If `shouldFocus` is false, it returns an empty string.
+ *
+ * @example
+ * getFocusName('field', 2, { shouldFocus: true });
+ * Output: "field.2."
+ *
+ * getFocusName('field', 2, { shouldFocus: true, focusName: 'apple' });
+ * Output: "apple"
+ *
+ * getFocusName('field', 2, { shouldFocus: false });
+ // Output: ""
+ */
 export default (
   name: InternalFieldName,
   index: number,

src/logic/getValidationModes.ts

@@ -1,6 +1,19 @@
 import { VALIDATION_MODE } from '../constants';
 import { Mode, ValidationModeFlags } from '../types';
 
+/**
+ * Constructs validation mode flags based on the provided mode.
+ * This function returns an object with flags indicating which
+ * validation mode is active.
+ * @remarks If no mode is provided, it defaults to `onSubmit`.
+ *
+ * @example
+ * const flags = getValidationModeFlags(VALIDATION_MODE.onBlur);
+ * Output: { isOnBlur: true, ...<other>false}
+ *
+ * getValidationModeFlags();
+ * Output: { isOnSubmit: true, <other>false}
+ */
 export default (mode?: Mode): ValidationModeFlags => ({
   isOnSubmit: !mode || mode === VALIDATION_MODE.onSubmit,
   isOnBlur: mode === VALIDATION_MODE.onBlur,

src/logic/iterateFieldsByAction.ts

@@ -2,6 +2,34 @@ import { FieldRefs, InternalFieldName, Ref } from '../types';
 import { get } from '../utils';
 import isObject from '../utils/isObject';
 
+/**
+ * Iterates over field references and performs
+ * an action on each field. This function traverses
+ * through the field references, applying the given
+ * action to each field.
+ * @remarks The traversal can be limited to specific field names,
+ * and it can be aborted early based on the action's return value.
+ *
+ * @example
+ * const fields = {
+ *   field1: {
+ *     _f: {
+ *       ref: document.createElement('input'),
+ *       name: 'field1',
+ *     }},
+ *   field2: {
+ *     _f: {
+ *       refs: [document.createElement('input')],
+ *       name: 'field2',
+ *     }}};
+ *
+ * iterateFieldsByAction(fields, (ref, name) => {
+ *   console.log(name, ref);
+ * });
+ * Output:
+ *  field1 <input>
+ *  field2 <input>
+ */
 const iterateFieldsByAction = (
   fields: FieldRefs,
   action: (ref: Ref, name: string) => 1 | undefined | void,

src/utils/append.ts

@@ -1,5 +1,9 @@
 import convertToArrayPayload from './convertToArrayPayload';
 
+/**
+ * Add given value or array of values to the end of given array.
+ * @returns {T[]} A new array with the appended value(s).
+ */
 export default <T>(data: T[], value: T | T[]): T[] => [
   ...data,
   ...convertToArrayPayload(value),

src/utils/cloneObject.ts

@@ -1,7 +1,11 @@
 import isObject from './isObject';
 import isPlainObject from './isPlainObject';
 import isWeb from './isWeb';
-
+/**
+ * Deeply clones a given object,
+ * including handling special types like Date and Set.
+ * It also handles arrays and plain objects.
+ */
 export default function cloneObject<T>(data: T): T {
   let copy: any;
   const isArray = Array.isArray(data);

src/utils/compact.ts

@@ -1,2 +1,10 @@
+/**
+ * @description Removes falsy values from an array.
+ * @returns {TValue[]} A new array with all falsy values removed.
+ * @example
+ * const array = [0, 1, false, 2, '', 3, null, undefined, NaN, 4];
+ * const compactedArray = compact(array);
+ * compactedArray // Output: [1, 2, 3, 4]
+ */
 export default <TValue>(value: TValue[]) =>
   Array.isArray(value) ? value.filter(Boolean) : [];

src/utils/convertToArrayPayload.ts

@@ -1 +1,4 @@
+/**
+ * Put's given value into an array if it's not already an array.
+ */
 export default <T>(value: T) => (Array.isArray(value) ? value : [value]);

src/utils/createSubject.ts

@@ -1,20 +1,41 @@
+/**
+ * Implementation of an observable pattern.
+ * This pattern is used for implementing
+ * a publisher-subscriber system, where subscribers (observers)
+ * can listen to events or data changes
+ * emitted by a subject (observable).
+ */
 import { Noop } from '../types';
 
+/**
+ * Observer that has a next method.
+ * This method is called when new data is emitted.
+ */
 export type Observer<T> = {
   next: (value: T) => void;
 };
-
+/**
+ * A type representing a subscription that
+ * has an unsubscribe method. This method is used
+ * to stop receiving updates from the subject.
+ */
 export type Subscription = {
   unsubscribe: Noop;
 };
 
+/**
+ * A type representing a subject that can be observed.
+ * It has an array of observers, methods to subscribe
+ * and unsubscribe observers, and a method to
+ * emit data to all observers.
+ */
 export type Subject<T> = {
   readonly observers: Observer<T>[];
   subscribe: (value: Observer<T>) => Subscription;
   unsubscribe: Noop;
 } & Observer<T>;
 
-export default <T>(): Subject<T> => {
+export default function createSubject<T>(): Subject<T> {
   let _observers: Observer<T>[] = [];
 
   const next = (value: T) => {
@@ -44,4 +65,4 @@ export default <T>(): Subject<T> => {
     subscribe,
     unsubscribe,
   };
-};
+}

src/utils/deepEqual.ts

@@ -2,7 +2,26 @@ import isObject from '../utils/isObject';
 
 import isDateObject from './isDateObject';
 import isPrimitive from './isPrimitive';
-
+/**
+ * Compares two values deeply to determine
+ * if they are equal. Handles primitives,
+ * dates, objects, and arrays.
+ *
+ * @example
+ * const obj1 = { a: 1, b: { c: 2 } };
+ * const obj2 = { a: 1, b: { c: 2 } };
+ * deepEqual(obj1, obj2)    // Output: true
+ *
+ * const obj3 = { a: 1, b: { c: 3 } };
+ * deepEqual(obj1, obj3)    // Output: false
+ *
+ * const date1 = new Date(2020, 1, 1);
+ * const date2 = new Date(2020, 1, 1);
+ * deepEqual(date1, date2) // Output: true
+ *
+ * @remarks This function compares complex
+ * structures including nested objects and arrays.
+ */
 export default function deepEqual(object1: any, object2: any) {
   if (isPrimitive(object1) || isPrimitive(object2)) {
     return object1 === object2;

src/utils/deepMerge.ts

@@ -1,6 +1,20 @@
 import isObject from './isObject';
 import isPrimitive from './isPrimitive';
 
+/**
+ * Deeply merges two objects. If either target or
+ * source is a primitive, the source is returned.
+ * Otherwise, recursively merges properties of the
+ * source object into the target object.
+ * @remarks This function mutates the target object.
+ * @remarks uses source keys for iteration
+ *
+ * @example
+ * const target = { a: 1, b: { c: 3 } };
+ * const source = { b: { d: 4 }, e: 5 };
+ * const result = deepMerge(target, source);
+ * result // Output: { a: 1, b: { c: 3, d: 4 }, e: 5 }
+ */
 export default function deepMerge<
   T extends Record<keyof T, any>,
   U extends Record<keyof U, any>,

src/utils/fillEmptyArray.ts

@@ -1,2 +1,7 @@
+/**
+ * Converts an array to an array of
+ * `undefined` * values, or returns `undefined` if
+ * the input is not an array.
+ */
 export default <T>(value: T | T[]): undefined[] | undefined =>
   Array.isArray(value) ? value.map(() => undefined) : undefined;

src/utils/get.ts

@@ -3,6 +3,18 @@ import isNullOrUndefined from './isNullOrUndefined';
 import isObject from './isObject';
 import isUndefined from './isUndefined';
 
+/**
+ * Safely retrieves the value at a given
+ * path within an object. If the value is not found or
+ * is undefined, it returns the provided default value.
+ * @example
+ * ```typescript
+ * const obj = { a: { b: { c: 42 }}};
+ * getNestedValue(obj, 'a.b.c')              // Output: 42
+ * getNestedValue(obj, 'a.b.x', 'default')   // Output: 'default'
+ * getNestedValue(obj, 'a.b.c.d', 'default') // Output: 'default'
+ * ```
+ */
 export default <T>(object: T, path?: string, defaultValue?: unknown): any => {
   if (!path || !isObject(object)) {
     return defaultValue;

src/utils/insert.ts

@@ -1,5 +1,8 @@
 import convertToArrayPayload from './convertToArrayPayload';
 
+/**
+ * Insert value or values into specific index,
+ */
 export default function insert<T>(data: T[], index: number): (T | undefined)[];
 export default function insert<T>(
   data: T[],

src/utils/isEmptyObject.ts

@@ -2,5 +2,9 @@ import { EmptyObject } from '../types';
 
 import isObject from './isObject';
 
+/**
+ * Checks if the given value is an object
+ * with no own properties
+ */
 export default (value: unknown): value is EmptyObject =>
   isObject(value) && !Object.keys(value).length;

src/utils/isKey.ts

@@ -1 +1,9 @@
+/**
+ * Checks if a string is a valid key consisting of alphanumeric
+ * characters and underscores.
+ * @remarks (\w qualify _ as a valid character)
+ * @example
+ * isKey("valid_key")    // Output: true
+ * isKey("invalid key!") // Output: false
+ */
 export default (value: string) => /^\w*$/.test(value);

src/utils/isMessage.ts

@@ -1,4 +1,12 @@
 import { Message } from '../types';
 import isString from '../utils/isString';
-
+/**
+ * Checks if the given value is a string
+ * and therefore qualifies as a `Message`.
+ * @example
+ * const val1 = "Hello, world!";
+ * const val2 = 123;
+ * isMessage(val1) // Output: true
+ * isMessage(val2) // Output: false
+ */
 export default (value: unknown): value is Message => isString(value);

src/utils/noop.ts

@@ -1 +1,4 @@
+/**
+ * No operation function.
+ */
 export default function noop() {}

src/utils/objectHasFunction.ts

@@ -1,5 +1,7 @@
 import isFunction from './isFunction';
-
+/**
+ * Checks if an object contains at least one function as a property.
+ */
 export default <T>(data: T): boolean => {
   for (const key in data) {
     if (isFunction(data[key])) {

src/utils/prepend.ts

@@ -1,5 +1,7 @@
 import convertToArrayPayload from './convertToArrayPayload';
-
+/**
+ * Add's value or an array of values to the beginning of an array.
+ */
 export default <T>(data: T[], value: T | T[]): T[] => [
   ...convertToArrayPayload(value),
   ...convertToArrayPayload(data),

src/utils/remove.ts

@@ -1,7 +1,15 @@
 import compact from './compact';
 import convertToArrayPayload from './convertToArrayPayload';
 import isUndefined from './isUndefined';
-
+/**
+ * Removes elements from an array at the
+ * specified index or indexes. If no index is provided,
+ * an empty array is returned.
+ * @example
+ * const arr = ['a', 'b', 'c', 'd'];
+ * removeElements(arr, [1, 3]); // Output: ['a', 'c']
+ * removeElements(arr, 2);      // Output: ['a', 'b', 'd']
+ */
 function removeAtIndexes<T>(data: T[], indexes: number[]): T[] {
   let i = 0;
   const temp = [...data];

src/utils/set.ts

@@ -4,6 +4,16 @@ import isKey from './isKey';
 import isObject from './isObject';
 import stringToPath from './stringToPath';
 
+/**
+ * Sets the value at the specified path of the object.
+ * If a portion of the path does not exist, it is created.
+ * @example
+ * ```typescript
+ * const object = {};
+ * setValueAtPath(object, 'a.b.c', 42);
+ * Output: { a: { b: { c: 42 } } }
+ * ```
+ */
 export default (object: FieldValues, path: string, value?: unknown) => {
   let index = -1;
   const tempPath = isKey(path) ? [path] : stringToPath(path);

src/utils/sleep.ts

@@ -1,2 +1,6 @@
+/**
+ * Promises that resolves after given amount of time.
+ * in milliseconds.
+ */
 export default (ms: number) =>
   new Promise((resolve) => setTimeout(resolve, ms));