formap/dist/index.d.ts

HTML forms to data, a better alternative to FormData()

import { type JSONValue, type JSONValidMap, type JSONValidObject } from "json-types2";
export * from "maps-diff";
export interface IFormToSerializableOptions {
    mutator?: IFormMapMutatorFunction;
    append?: IFormAppend;
    prepend?: IFormAppend;
}
export declare const formDataToObject: (fd: FormData) => {
    [k: string]: FormDataEntryValue | FormDataEntryValue[];
};
export declare const formById: (formId: string) => HTMLFormElement;
export declare const formDataToJson: (fd: FormData) => string;
export declare const formToJson: (form: HTMLFormElement) => string;
export declare const formToJsonById: (formId: string) => string;
export declare const mapToObject: {
    <T = any>(entries: Iterable<readonly [PropertyKey, T]>): {
        [k: string]: T;
    };
    (entries: Iterable<readonly any[]>): any;
};
export declare const formToObject: (form: HTMLFormElement, options?: IFormToSerializableOptions) => {
    [k: string]: JSONValue;
};
export declare const formToObjectById: (formId: string, options?: IFormToSerializableOptions) => {
    [k: string]: JSONValue;
};
export declare const formToMapById: (formId: string, options?: IFormToSerializableOptions) => JSONValidMap;
/**
 * Represents a function that mutates a key-value pair. The function **must** return a value, or the key-value pair will be deleted.
 * The value is also deleted if the function returns `undefined`.
 * @param key - The key to be mutated.
 * @param value - The value to be mutated.
 * @returns The mutated value.
 */
export type IFormMapMutatorFunction = (key: string, value: JSONValue) => JSONValue;
export type IFormAppend = JSONValidMap | JSONValidObject;
/**
 * Converts an HTML form element into a Map object, where the keys are the names of the form inputs
 * and the values are the corresponding values of the form inputs.
 *
 * @param formElement - The HTML form element to be converted.
 * @param options - (Optional) An object containing the following options:
 *   - mutator: A function that mutates key-value pairs. The function **must** return a value, or all the key-value pairs will be deleted.
 *     The value is also deleted if the function returns `undefined`.
 *   - append: A map or object containing additional key-value pairs to be appended to the resulting map.
 *   - prepend: A map or object containing additional key-value pairs to be prepended to the resulting map.
 * @returns A Map object containing the form input names as keys and their corresponding values as values.
 *
 * @remarks
 * This function supports the following:
 * - HTML form elements names.
 * - Text inputs, text-areas, checkboxes, radio buttons, and select elements.
 * - Multiple select elements (returns an array of selected values).
 * - Custom mutator function to modify the values before they are added to the map.
 * - Appending additional key-value pairs to the resulting map.
 * - Prepending additional key-value pairs to the resulting map.
 * - Custom form elements with a `getValue()` method that returns the value of the element.
 *
 * This function does not support the following:
 * - HTML form inputs without a `name` attribute.
 * - File inputs (returns an empty string for file inputs).
 *
 * If the form element contains multiple inputs with the same name, the values will be added to the map as an array.
 *
 * It also supports and tries to call a `getValue()` method on the form's children, if it exists.
 * This is useful for custom form elements that need to do some processing before returning their value.
 * The value returned by `getValue()` should be JSON-serializable.
 *
 * @example
 * // Example 1: Converting a simple form with text inputs
 * const formElement = document.getElementById("myForm") as HTMLFormElement;
 * const formMap = FormToMap(formElement);
 * // Output: Map { "firstName" => "John", "lastName" => "Doe" }
 *
 * @example
 * // Example 2: Converting a form with checkboxes and radio buttons
 * const formElement = document.getElementById("myForm") as HTMLFormElement;
 * const formMap = FormToMap(formElement);
 * // Output: Map { "color" => "blue", "size" => "medium", "agree" => true }
 *
 * @example
 * // Example 3: Converting a form with a multiple select element
 * const formElement = document.getElementById("myForm") as HTMLFormElement;
 * const formMap = FormToMap(formElement);
 * // Output: Map { "fruits" => ["apple", "banana", "orange"] }
 *
 * @example
 * // Example 4: Using a custom mutator function
 * const formElement = document.getElementById("myForm") as HTMLFormElement;
 * const mutator = (key: string, value: string | string[]) => typeof value === "string" ? value.toUpperCase() : value;
 * const formMap = FormToMap(formElement, { mutator });
 * // Output: Map { "firstName" => "JOHN", "lastName" => "DOE" }
 *
 * @example
 * // Example 5: Appending additional key-value pairs
 * const formElement = document.getElementById("myForm") as HTMLFormElement;
 * const append = { additionalKey: "additionalValue" };
 * const formMap = FormToMap(formElement, { append });
 * // Output: Map { "firstName" => "John", "lastName" => "Doe", "additionalKey" => "additionalValue" }
 *
 * @example
 * // Example 6: Prepending additional key-value pairs
 * const formElement = document.getElementById("myForm") as HTMLFormElement;
 * const append = { additionalKey: "additionalValue" };
 * const formMap = FormToMap(formElement, { prepend });
 * // Output: Map { "additionalKey" => "additionalValue", "firstName" => "John", "lastName" => "Doe" }
 */
export declare function formToMap(formElement: HTMLFormElement, { mutator, append, prepend }?: IFormToSerializableOptions): JSONValidMap;