toolbox-x 1.0.0

package/dist/dom.mjs

@@ -0,0 +1,429 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { a as isNonEmptyString, d as isString } from "./primitives-KsFUp3kQ.mjs";
+import { j as isValidArray, v as isEmptyObject, w as isNotEmptyObject } from "./specials-uhDuRg8H.mjs";
+import { t as isDateLike } from "./guards-DdyU4h4o.mjs";
+import { _ as isOriginFileObj, a as flattenObjectKeyValue, d as isCustomFile, f as isCustomFileArray, g as isFileUpload, h as isFileOrBlob, l as parseObjectValues, m as isFileList, p as isFileArray, v as isValidFormData } from "./objectify-CDs0Fbr1.mjs";
+import { a as deepParsePrimitives } from "./utils-ClW9LA6f.mjs";
+
+//#region src/dom/query.ts
+/**
+* * Utility to generate query parameters from an object.
+*
+* @param params - Object containing query parameters.
+* @returns A query string as a URL-encoded string, e.g., `?key1=value1&key2=value2`.
+*
+* @example
+* generateQueryParams({ key1: 'value1', key2: 42 }); // "?key1=value1&key2=42"
+* generateQueryParams({ key1: ['value1', 'value2'], key2: 42 }); // "?key1=value1&key1=value2&key2=42"
+* generateQueryParams({ key1: '', key2: null }); // ""
+* generateQueryParams({ key1: true, key2: false }); // "?key1=true&key2=false"
+* generateQueryParams({ filters: { category: 'laptop', price: 1000 } }); // "?category=laptop&price=1000"
+*/
+function generateQueryParams(params = {}) {
+	const flattenedParams = flattenObjectKeyValue(params);
+	const queryParams = Object.entries(flattenedParams)?.filter(([_, value]) => value != null && !(isString(value) && value?.trim() === ""))?.flatMap(([key, value]) => Array.isArray(value) ? value?.filter((v) => v != null && !(isString(v) && v.trim() === ""))?.map((v) => `${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`) : `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`).join("&");
+	return queryParams ? `?${queryParams}` : "";
+}
+/**
+* * Get query params as standard `JavaScript` Object `Record<string, string>`. You can define the type by passing a type argument.
+*
+* - **Note:** *Extracts query parameters from the current URL (window.location.search).*
+*
+* @returns Query string as key-value paired object. `Record<string, string>`.
+*/
+function getQueryParams() {
+	return Object.fromEntries(new URLSearchParams(window?.location?.search));
+}
+/**
+* * Update query params in the browser URL with given key and value.
+* @param key Key for the query to update.
+* @param value Value to updated against the given key.
+*/
+function updateQueryParam(key, value) {
+	const url = new URL(window.location.href);
+	url.searchParams.set(key, value);
+	window.history.replaceState({}, "", url?.toString());
+}
+/**
+* Parses a query string (with optional `?` prefix) into an object.
+* Supports multiple values for the same key by returning arrays.
+* Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
+*
+* @remarks This utility is designed to parse generic string, for literal use, try {@link parseQueryStringLiteral}.
+*
+* - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+*
+* @param query - The query string to parse.
+* @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
+* @returns An object where keys are strings and values can be string, array, number, boolean, or null/undefined.
+*/
+function parseQueryString(query, parsePrimitives = true) {
+	const params = new URLSearchParams(query.startsWith("?") ? query.slice(1) : query);
+	const entries = {};
+	for (const [key, value] of params.entries()) if (key in entries) {
+		const current = entries[key];
+		const array = Array.isArray(current) ? [...current, value] : [current, value];
+		entries[key] = parsePrimitives ? deepParsePrimitives(array) : array;
+	} else entries[key] = value;
+	return parsePrimitives ? parseObjectValues(entries) : entries;
+}
+/**
+* Parses a query string (with optional `?` prefix) into an object.
+* Supports multiple values for the same key by returning arrays.
+* It returns properly typed object.
+*
+* @remarks This utility is designed to parse literal string, for generic use, try {@link parseQueryString}.
+*
+* - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+*
+* @param query - The literal query string to parse.
+* @returns An object where keys are strings and values can be string, array, or null/undefined.
+*/
+function parseQueryStringLiteral(query) {
+	const params = new URLSearchParams(query.startsWith("?") ? query.slice(1) : query);
+	const entries = {};
+	for (const [key, value] of params.entries()) if (key in entries) {
+		const current = entries[key];
+		entries[key] = Array.isArray(current) ? [...current, value] : [current, value];
+	} else entries[key] = value;
+	return entries;
+}
+
+//#endregion
+//#region src/dom/storage.ts
+/**
+* * Get item from local storage.
+*
+* @param key - Key to get item from local storage.
+* @param deserialize - Optional deserializer function to convert the stored value back to type `T`. Defaults to `JSON.parse`.
+* @returns Returns saved item from local storage if it exists with that key.
+*/
+function getFromLocalStorage(key, deserialize) {
+	const deserializer = deserialize ?? JSON.parse;
+	try {
+		const item = localStorage.getItem(key);
+		return item ? deserializer(item) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* * Save item in local storage.
+*
+* @param key - Key to save an item.
+* @param value - The item/value to save.
+* @param serialize - Optional serializer function to convert the value of type `T` to a string. Defaults to `JSON.stringify`.
+*/
+function saveToLocalStorage(key, value, serialize) {
+	const serializer = serialize ?? JSON.stringify;
+	try {
+		localStorage.setItem(key, serializer(value));
+	} catch (error) {
+		console.error(`Error saving item with key "${key}" in local storage:`, error);
+	}
+}
+/**
+* * Remove item from local storage.
+*
+* @param key - Key to delete item from local storage.
+*/
+function removeFromLocalStorage(key) {
+	try {
+		localStorage.removeItem(key);
+	} catch (error) {
+		console.error(`Error removing item with key "${key}" from local storage:`, error);
+	}
+}
+/**
+* * Get item from session storage.
+*
+* @param key - Key to get item from session storage.
+* @param deserialize - Optional deserializer function to convert the stored value back to type `T`. Defaults to `JSON.parse`.
+* @returns Returns saved item from session storage if it exists with that key.
+*/
+function getFromSessionStorage(key, deserialize) {
+	const deserializer = deserialize ?? JSON.parse;
+	try {
+		const item = sessionStorage.getItem(key);
+		return item ? deserializer(item) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* * Save item in session storage.
+*
+* @param key - Key to save an item.
+* @param value - The item/value to save.
+* @param serialize - Optional serializer function to convert the value of type `T` to a string. Defaults to `JSON.stringify`.
+*/
+function saveToSessionStorage(key, value, serialize) {
+	const serializer = serialize ?? JSON.stringify;
+	try {
+		sessionStorage.setItem(key, serializer(value));
+	} catch (error) {
+		console.error(`Error saving item with key "${key}" in session storage:`, error);
+	}
+}
+/**
+* * Remove item from session storage.
+*
+* @param key - Key to delete item from session storage.
+*/
+function removeFromSessionStorage(key) {
+	try {
+		sessionStorage.removeItem(key);
+	} catch (error) {
+		console.error(`Error removing item with key "${key}" from session storage:`, error);
+	}
+}
+
+//#endregion
+//#region src/dom/utils.ts
+/**
+* * Scrolls smoothly to the given element with an optional vertical offset.
+* @param element The target element to scroll to.
+* @param offset Additional vertical offset in pixels (positive moves down, negative moves up).
+*/
+function smoothScrollTo(element, offset = 0) {
+	element.scrollIntoView({
+		behavior: "smooth",
+		block: "start"
+	});
+	if (offset !== 0) setTimeout(() => {
+		window.scrollBy({
+			top: offset,
+			behavior: "smooth"
+		});
+	}, 300);
+}
+/**
+* * Toggles full-screen mode for a given element (or the `document` by default).
+* @param element The element to toggle fullscreen mode for (default: document root).
+*/
+function toggleFullScreen(element = document.documentElement) {
+	const doc = document;
+	const elem = element;
+	if (!doc.fullscreenElement && !doc.webkitFullscreenElement) {
+		if (elem.requestFullscreen) elem.requestFullscreen();
+		else if (elem.webkitRequestFullscreen) elem.webkitRequestFullscreen();
+	} else if (doc.exitFullscreen) doc.exitFullscreen();
+	else if (doc.webkitExitFullscreen) doc.webkitExitFullscreen();
+}
+/**
+* * Copies text to the clipboard, falling back to legacy methods if needed.
+* @param text - The text to copy.
+* @returns A promise that resolves when the text is copied.
+*/
+async function copyToClipboard(text) {
+	try {
+		if (navigator?.clipboard?.writeText) await navigator.clipboard.writeText(text);
+		else {
+			const textArea = document.createElement("textarea");
+			textArea.value = text;
+			textArea.style.position = "fixed";
+			textArea.style.opacity = "0";
+			document.body.appendChild(textArea);
+			textArea.select();
+			textArea.setSelectionRange(0, textArea.value?.length);
+			const success = document.execCommand("copy");
+			document.body.removeChild(textArea);
+			if (!success) throw new Error("Cannot execute command in this environment!");
+		}
+	} catch (error) {
+		console.error("Failed to copy text:", error);
+		throw error;
+	} finally {
+		const textArea = document.querySelector("textarea[style*=\"fixed\"]");
+		if (textArea) document.body.removeChild(textArea);
+	}
+}
+
+//#endregion
+//#region src/form/convert.ts
+/**
+* * Utility to convert object into FormData in a controlled way.
+* - **N.B.** Be cautious when using this in SSR (Server-Side Rendering) environments (such as `Next.js` Server Components), as it may not work as expected.
+*
+* @param data - The source object to control and convert to FormData.
+* @param configs - Configuration options to control the formData.
+* @returns `FormData` instance containing the sanitized and transformed data.
+*/
+const createControlledFormData = (data, configs) => {
+	const formData = new FormData();
+	const { stringifyNested = "*" } = configs || {};
+	/** - Helper to check if a key should be lowercase */
+	const _shouldLowercaseKeys = (key) => {
+		return Array.isArray(configs?.lowerCaseKeys) ? configs?.lowerCaseKeys?.some((path) => key === path || key.startsWith(`${path}.`)) : configs?.lowerCaseKeys === "*";
+	};
+	/** - Helper to check if a key should be lowercase */
+	const _shouldLowercaseValue = (key) => {
+		return Array.isArray(configs?.lowerCaseValues) ? configs.lowerCaseValues?.some((path) => key === path || key?.startsWith(`${path}.`)) : configs?.lowerCaseValues === "*";
+	};
+	/** - Transforms key to lowercase if needed */
+	const _transformKey = (key) => {
+		return _shouldLowercaseKeys(key) ? key.toLowerCase() : key;
+	};
+	/** - Helper function to check if a key matches a breakArray key. */
+	const _isRequiredKey = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(configs?.requiredKeys) ? configs?.requiredKeys?.some((path) => transformedKey === path || transformedKey?.startsWith(`${path}.`)) : configs?.requiredKeys === "*";
+	};
+	/** - Helper function to check if a key matches a dotNotation path to preserve. */
+	const _shouldDotNotate = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(configs?.dotNotateNested) ? configs.dotNotateNested.includes(transformedKey) : configs?.dotNotateNested === "*";
+	};
+	/** - Helper function to check if a key matches a stringifyNested key. */
+	const _shouldStringify = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(stringifyNested) ? stringifyNested.includes(transformedKey) : stringifyNested === "*";
+	};
+	/** - Helper function to check if a key matches a breakArray key. */
+	const _shouldBreakArray = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(configs?.breakArray) ? configs.breakArray.includes(transformedKey) : configs?.breakArray === "*";
+	};
+	/** - Helper to clean object by removing null/undefined/empty values while respecting required keys */
+	const _cleanObject = (obj, parentKey = "") => {
+		return Object.entries(obj).reduce((acc, [key, value]) => {
+			const transformedKey = _transformKey(key);
+			const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
+			if (configs?.ignoreKeys?.includes(fullKey)) return acc;
+			if (value != null && value !== "" || _isRequiredKey(fullKey) || isNonEmptyString(value) || isValidArray(value) || isNotEmptyObject(value)) if (isNotEmptyObject(value)) if (isDateLike(value)) acc[transformedKey] = value;
+			else {
+				const cleaned = _cleanObject(value, fullKey);
+				if (_isRequiredKey(fullKey) || isNotEmptyObject(cleaned)) acc[transformedKey] = cleaned;
+			}
+			else if (isString(value)) if (isNonEmptyString(value)) {
+				let cleanString = value;
+				if (configs?.trimStrings) cleanString = cleanString?.trim();
+				if (_shouldLowercaseValue(fullKey)) cleanString = cleanString?.toLowerCase();
+				acc[transformedKey] = cleanString;
+			} else acc[transformedKey] = value;
+			else if (Array.isArray(value)) {
+				if (_isRequiredKey(fullKey) || isValidArray(value)) acc[transformedKey] = value;
+			} else if (isEmptyObject(value)) {
+				if (_isRequiredKey(fullKey)) acc[transformedKey] = value;
+			} else acc[transformedKey] = value;
+			return acc;
+		}, {});
+	};
+	/** * Helper function to add values to formData */
+	const _addToFormData = (key, value) => {
+		const transformedKey = _transformKey(key);
+		if (isCustomFileArray(value)) value?.forEach((file) => formData.append(transformedKey, file?.originFileObj));
+		else if (isFileUpload(value)) {
+			if (value?.fileList) value?.fileList.forEach((file) => formData.append(transformedKey, file?.originFileObj));
+			else if (value?.file) if (isCustomFile(value?.file)) formData.append(transformedKey, value?.file?.originFileObj);
+			else formData.append(transformedKey, value?.file);
+		} else if (isFileOrBlob(value)) formData.append(transformedKey, value);
+		else if (isFileList(value)) for (let i = 0; i < value?.length; i++) formData.append(transformedKey, value.item(i));
+		else if (Array.isArray(value)) {
+			if (isFileArray(value)) if (_shouldBreakArray(key)) value?.forEach((item, index) => {
+				_addToFormData(`${transformedKey}[${index}]`, item);
+			});
+			else value?.forEach((item) => {
+				formData.append(transformedKey, item);
+			});
+			else if (isValidArray(value)) if (_shouldBreakArray(key)) value?.forEach((item, index) => {
+				_addToFormData(`${transformedKey}[${index}]`, item);
+			});
+			else formData.append(transformedKey, JSON.stringify(value));
+			else if (_isRequiredKey(key)) formData.append(transformedKey, JSON.stringify(value));
+		} else if (isDateLike(value)) formData.append(transformedKey, JSON.parse(JSON.stringify(value)));
+		else if (isNotEmptyObject(value)) if (_shouldStringify(key) && !_shouldDotNotate(key)) {
+			const cleanedValue = _cleanObject(value, key);
+			if (isNotEmptyObject(cleanedValue) || _isRequiredKey(key)) formData.append(transformedKey, JSON.stringify(cleanedValue));
+		} else Object.entries(value).forEach(([nestedKey, nestedValue]) => {
+			_addToFormData(`${key}.${nestedKey}`, nestedValue);
+		});
+		else if (value != null && value !== "" || _isRequiredKey(key)) if (isString(value) && _shouldLowercaseValue(key)) formData.append(transformedKey, value?.toLowerCase());
+		else formData.append(transformedKey, value);
+	};
+	/** - Helper to process object */
+	const _processObject = (obj, parentKey = "") => {
+		Object.entries(obj).forEach(([key, value]) => {
+			const transformedKey = _transformKey(key);
+			const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
+			if (configs?.ignoreKeys?.includes(fullKey)) return;
+			if (configs?.trimStrings && isNonEmptyString(value)) value = value?.trim();
+			if (_shouldDotNotate(fullKey)) _addToFormData(fullKey, value);
+			else if (isNotEmptyObject(value) && !_shouldStringify(fullKey)) if (isDateLike(value)) _addToFormData(key, JSON.parse(JSON.stringify(value)));
+			else _processObject(value, key);
+			else if (isFileOrBlob(value)) _addToFormData(key, value);
+			else if (isDateLike(value)) _addToFormData(key, JSON.parse(JSON.stringify(value)));
+			else if (isEmptyObject(value)) {
+				if (_isRequiredKey(fullKey)) _addToFormData(key, JSON.stringify(value));
+			} else _addToFormData(key, value);
+		});
+	};
+	if (isNotEmptyObject(data)) _processObject(data);
+	return formData;
+};
+
+//#endregion
+//#region src/form/transform.ts
+/**
+* * Serialize form data into an object or a query string.
+* - **N.B.** Be cautious when using this in SSR (Server-Side Rendering) environments (such as `Next.js` Server Components), as it may not work as expected.
+*
+* @param form - The form element to serialize.
+* @param toQueryString - Whether to return the result as a query string. If false, returns an object.
+* @returns The serialized form data as an object or query string.
+*/
+function serializeForm(form, toQueryString = false) {
+	const formData = new FormData(form);
+	const data = {};
+	formData?.forEach((value, key) => {
+		if (data[key]) data[key] = Array.isArray(data[key]) ? [...data[key], value.toString()] : [data[key], value.toString()];
+		else data[key] = value.toString();
+	});
+	if (toQueryString) return generateQueryParams(data);
+	return data;
+}
+/**
+* * Parse form data from a `FormData` object or query string into a structured object format.
+*
+* @param data - The `FormData` object or query string to parse.
+* @param parsePrimitives - Whether to parse string values into primitive types (e.g., boolean, number, array, object). Defaults to `true`.
+* @returns The parsed form data as an object.
+*/
+function parseFormData(data, parsePrimitives = true) {
+	const parsed = {};
+	if (isString(data)) new URLSearchParams(data)?.forEach((value, key) => {
+		const existing = parsed[key];
+		if (isString(existing)) parsed[key] = [existing, value];
+		else if (Array.isArray(existing)) parsed[key] = [...existing, value];
+		else parsed[key] = value;
+	});
+	else data?.forEach((value, key) => {
+		const existing = parsed[key];
+		if (value instanceof File) if (Array.isArray(existing)) parsed[key] = [...existing, value];
+		else if (existing instanceof File) parsed[key] = [existing, value];
+		else parsed[key] = value;
+		else if (isString(existing)) parsed[key] = [existing, value];
+		else if (Array.isArray(existing)) parsed[key] = [...existing, value];
+		else parsed[key] = value;
+	});
+	if (parsePrimitives) return parseObjectValues(parsed);
+	else return parsed;
+}
+
+//#endregion
+export { createControlledFormData as convertIntoFormData, createControlledFormData, createControlledFormData as createFormData, copyToClipboard, generateQueryParams as createQueryParams, generateQueryParams as formatQueryParams, generateQueryParams, getFromLocalStorage, getFromSessionStorage, getQueryParams, parseQueryString as getQueryStringAsObject, parseQueryString, parseQueryString as queryStringToObject, isCustomFile, isCustomFileArray, isFileArray, isFileList, isFileOrBlob, isFileUpload, isOriginFileObj, isValidFormData, parseQueryStringLiteral as literalQueryStringToObject, parseQueryStringLiteral, parseFormData, removeFromLocalStorage, removeFromSessionStorage, saveToLocalStorage, saveToSessionStorage, serializeForm, smoothScrollTo, toggleFullScreen, updateQueryParam };

package/dist/form-BMFVGUrN.d.mts

@@ -0,0 +1,118 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { S as KeyForObject, T as NestedKeyString, u as DotNotationKey, x as KeyForArray } from "./object-B0TV3eHx.mjs";
+import { P as QueryString } from "./string-CBAbxaG1.mjs";
+
+//#region src/types/form.d.ts
+/** - Configuration options to control FormData generation behavior. */
+interface FormDataConfigs<T> {
+  /**
+   * * An array of dot-notation keys to exclude from processing.
+   * * Ignored keys are omitted entirely, even if included in other options.
+   */
+  ignoreKeys?: DotNotationKey<T>[];
+  /**
+   * * Specifies which keys should be included even if their values are falsy.
+   * * Use `*` to preserve all keys.
+   */
+  requiredKeys?: '*' | DotNotationKey<T>[];
+  /**
+   * * Defines which keys should be converted to lowercase.
+   * * Use `*` to apply to all keys.
+   */
+  lowerCaseKeys?: '*' | DotNotationKey<T>[];
+  /**
+   * * Defines which values should be converted to lowercase.
+   * * Use `*` to apply to all keys.
+   */
+  lowerCaseValues?: '*' | NestedKeyString<T>[];
+  /**
+   * * An array of keys (values must be object) to preserve in their original structure.
+   * - Use `*` to preserve all keys with object values in their dot-notation format.
+   * - If a key exists in both `dotNotateNested` and `stringifyNested`, `dotNotateNested` takes precedence.
+   */
+  dotNotateNested?: '*' | KeyForObject<T>[];
+  /**
+   * * Specifies which keys (values must be objects) should be stringified instead of being dot-notated.
+   * - Defaults to `*`, meaning all keys with object values will be stringified. Which is standard in modern form submissions.
+   * - Use `*` to stringify all nested objects.
+   * - If a key exists in both `dotNotateNested` and `stringifyNested`, `dotNotateNested` takes precedence.
+   */
+  stringifyNested?: '*' | KeyForObject<T>[];
+  /**
+   * * Controls how arrays should be serialized in FormData.
+   * - If a key is included, the array will be broken into individual key-value pairs (`key[0]: value, key[1]: value`).
+   * - Use `*` to apply this behavior to all array keys.
+   */
+  breakArray?: '*' | KeyForArray<T>[];
+  /** - Enables automatic trimming of string values before appending them to FormData. */
+  trimStrings?: boolean;
+}
+/** * Represents a file upload operation, commonly used in libraries like `FilePond` or `Ant Design Upload`. */
+interface FileUpload {
+  /** The primary file being uploaded. */
+  file: File | CustomFile;
+  /** The list of files associated with the upload. */
+  fileList: CustomFile[];
+}
+/** * Represents a custom file structure used in file upload components. */
+interface CustomFile {
+  /** Unique identifier for the file. */
+  uid: string;
+  /** The timestamp (milliseconds) when the file was last modified. */
+  lastModified: number;
+  /** A string representation of the last modified date. */
+  lastModifiedDate: Date;
+  /** The name of the file. */
+  name: string;
+  /** The size of the file in bytes. */
+  size: number;
+  /** The MIME type of the file. */
+  type: string;
+  /** Upload progress percentage (0-100). */
+  percent: number;
+  /** The original file object before any transformations. */
+  originFileObj: OriginFileObj;
+  /** The URL for a thumbnail preview of the file. */
+  thumbUrl: string;
+  /** Optional error information if the upload fails. */
+  error?: FileError;
+  /** Optional server response after a successful upload. */
+  response?: string;
+  /** Optional status of the file upload (e.g., "uploading", "done", "error"). */
+  status?: string;
+}
+/** * Represents the original file object before any modifications. */
+interface OriginFileObj extends File {
+  /** Unique identifier for the original file. */
+  uid: string;
+}
+/** * Represents an error that occurs during a file upload. */
+interface FileError extends Error {
+  /** HTTP status code of the error. */
+  status: number;
+  /** The HTTP method used for the request (e.g., "POST", "PUT"). */
+  method: string;
+  /** The URL where the upload was attempted. */
+  url: string;
+}
+/** THe return type of `serializeForm` wither as object or query string. */
+type SerializedForm<T extends boolean> = T extends false ? Record<string, string | string[]> : QueryString;
+/** * Represents the parsed form data. */
+type ParsedFormData<T> = T extends string ? Record<string, string | string[]> : Record<string, string | string[] | File | File[]>;
+//#endregion
+export { OriginFileObj as a, FormDataConfigs as i, FileError as n, ParsedFormData as o, FileUpload as r, SerializedForm as s, CustomFile as t };

package/dist/form-DRFbryvK.d.cts

@@ -0,0 +1,118 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { S as KeyForObject, T as NestedKeyString, u as DotNotationKey, x as KeyForArray } from "./object-Blq0Amdv.cjs";
+import { P as QueryString } from "./string-CsNsm_65.cjs";
+
+//#region src/types/form.d.ts
+/** - Configuration options to control FormData generation behavior. */
+interface FormDataConfigs<T> {
+  /**
+   * * An array of dot-notation keys to exclude from processing.
+   * * Ignored keys are omitted entirely, even if included in other options.
+   */
+  ignoreKeys?: DotNotationKey<T>[];
+  /**
+   * * Specifies which keys should be included even if their values are falsy.
+   * * Use `*` to preserve all keys.
+   */
+  requiredKeys?: '*' | DotNotationKey<T>[];
+  /**
+   * * Defines which keys should be converted to lowercase.
+   * * Use `*` to apply to all keys.
+   */
+  lowerCaseKeys?: '*' | DotNotationKey<T>[];
+  /**
+   * * Defines which values should be converted to lowercase.
+   * * Use `*` to apply to all keys.
+   */
+  lowerCaseValues?: '*' | NestedKeyString<T>[];
+  /**
+   * * An array of keys (values must be object) to preserve in their original structure.
+   * - Use `*` to preserve all keys with object values in their dot-notation format.
+   * - If a key exists in both `dotNotateNested` and `stringifyNested`, `dotNotateNested` takes precedence.
+   */
+  dotNotateNested?: '*' | KeyForObject<T>[];
+  /**
+   * * Specifies which keys (values must be objects) should be stringified instead of being dot-notated.
+   * - Defaults to `*`, meaning all keys with object values will be stringified. Which is standard in modern form submissions.
+   * - Use `*` to stringify all nested objects.
+   * - If a key exists in both `dotNotateNested` and `stringifyNested`, `dotNotateNested` takes precedence.
+   */
+  stringifyNested?: '*' | KeyForObject<T>[];
+  /**
+   * * Controls how arrays should be serialized in FormData.
+   * - If a key is included, the array will be broken into individual key-value pairs (`key[0]: value, key[1]: value`).
+   * - Use `*` to apply this behavior to all array keys.
+   */
+  breakArray?: '*' | KeyForArray<T>[];
+  /** - Enables automatic trimming of string values before appending them to FormData. */
+  trimStrings?: boolean;
+}
+/** * Represents a file upload operation, commonly used in libraries like `FilePond` or `Ant Design Upload`. */
+interface FileUpload {
+  /** The primary file being uploaded. */
+  file: File | CustomFile;
+  /** The list of files associated with the upload. */
+  fileList: CustomFile[];
+}
+/** * Represents a custom file structure used in file upload components. */
+interface CustomFile {
+  /** Unique identifier for the file. */
+  uid: string;
+  /** The timestamp (milliseconds) when the file was last modified. */
+  lastModified: number;
+  /** A string representation of the last modified date. */
+  lastModifiedDate: Date;
+  /** The name of the file. */
+  name: string;
+  /** The size of the file in bytes. */
+  size: number;
+  /** The MIME type of the file. */
+  type: string;
+  /** Upload progress percentage (0-100). */
+  percent: number;
+  /** The original file object before any transformations. */
+  originFileObj: OriginFileObj;
+  /** The URL for a thumbnail preview of the file. */
+  thumbUrl: string;
+  /** Optional error information if the upload fails. */
+  error?: FileError;
+  /** Optional server response after a successful upload. */
+  response?: string;
+  /** Optional status of the file upload (e.g., "uploading", "done", "error"). */
+  status?: string;
+}
+/** * Represents the original file object before any modifications. */
+interface OriginFileObj extends File {
+  /** Unique identifier for the original file. */
+  uid: string;
+}
+/** * Represents an error that occurs during a file upload. */
+interface FileError extends Error {
+  /** HTTP status code of the error. */
+  status: number;
+  /** The HTTP method used for the request (e.g., "POST", "PUT"). */
+  method: string;
+  /** The URL where the upload was attempted. */
+  url: string;
+}
+/** THe return type of `serializeForm` wither as object or query string. */
+type SerializedForm<T extends boolean> = T extends false ? Record<string, string | string[]> : QueryString;
+/** * Represents the parsed form data. */
+type ParsedFormData<T> = T extends string ? Record<string, string | string[]> : Record<string, string | string[] | File | File[]>;
+//#endregion
+export { OriginFileObj as a, FormDataConfigs as i, FileError as n, ParsedFormData as o, FileUpload as r, SerializedForm as s, CustomFile as t };