toolbox-x 1.0.0

package/dist/objectify-DIJ-OBmo.cjs

@@ -0,0 +1,524 @@
+/**
+ * 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.
+ */
+
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_specials = require('./specials-DzLr1ZgU.cjs');
+const require_guards = require('./guards-Efhp1mNy.cjs');
+const require_utils = require('./utils-DLFRgXUC.cjs');
+const require_basics = require('./basics-D_eSv0cu.cjs');
+
+//#region src/form/guards.ts
+/**
+* * Checks if a given value is a valid `FormData` & it's not empty.
+* - **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 value - The value to check.
+* @returns `true` if the value is a valid `FormData` and not empty, otherwise `false`.
+*/
+function isValidFormData(value) {
+	if (!(value instanceof FormData)) return false;
+	if ("entries" in value) {
+		if (typeof value.entries !== "function") {
+			console.warn("`FormData.entries()` is not supported!");
+			return false;
+		}
+		return Array.from(value.entries())?.length > 0;
+	}
+	return false;
+}
+/**
+* * Checks if a given value is an `OriginFileObj`.
+* - **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 value - The value to check.
+* @returns `true` if the value is a valid `OriginFileObj`, otherwise `false`.
+*/
+function isOriginFileObj(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return require_primitives.isString(value.uid);
+}
+/**
+* * Checks if a given value is a `CustomFile`.
+* - **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 value - The value to check.
+* @returns `true` if the value is a valid `CustomFile`, otherwise `false`.
+*/
+function isCustomFile(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const obj = value;
+	return "originFileObj" in obj && isOriginFileObj(obj.originFileObj);
+}
+/**
+* * Checks if a given value is an array of `CustomFile` objects.
+* - **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 value - The value to check.
+* @returns `true` if the value is a valid `CustomFile[]`, otherwise `false`.
+*/
+function isCustomFileArray(value) {
+	return Array.isArray(value) && value?.length > 0 && value?.every(isCustomFile);
+}
+/**
+* * Checks if a given value is an array of `File/Blob` objects.
+* - **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 value - The value to check.
+* @returns `true` if the value is a valid `File[]` or `Blob[]`, otherwise `false`.
+*/
+function isFileArray(value) {
+	return Array.isArray(value) && value?.length > 0 && value?.every(isFileOrBlob);
+}
+/**
+* * Checks if a given value is an instance of `FileList`.
+* @param value - The value to check.
+* @returns `true` if the value is a valid `FileList`, otherwise `false`.
+*/
+function isFileList(value) {
+	return typeof FileList !== "undefined" && value instanceof FileList;
+}
+/**
+* * Checks if a given value is an instance of `File` or `Blob`.
+* @param value - The value to check.
+* @returns `true` if the value is an instance of `File` or `Blob`, otherwise `false`.
+*/
+function isFileOrBlob(value) {
+	return typeof File !== "undefined" && value instanceof File || typeof Blob !== "undefined" && value instanceof Blob;
+}
+/**
+* * Checks if a given value is a `FileUpload` object.
+* @param value - The value to check.
+* @returns `true` if the value is a valid `FileUpload`, otherwise `false`.
+*/
+function isFileUpload(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const obj = value;
+	return "file" in obj && isCustomFile(obj.file) || "fileList" in obj && isCustomFileArray(obj.fileList);
+}
+
+//#endregion
+//#region src/object/sanitize.ts
+/**
+* * Sanitizes a string, array of strings, an object or array of objects by ignoring specified keys and trimming string values.
+* * Also excludes nullish values (null, undefined) if specified. Always ignores empty nested object(s).
+*
+* @param input - The string, object or array of strings or objects to sanitize.
+* @param options - Options for processing data.
+* @param _return - By default return type is as it is, passing this parameter `partial` makes the return type `$DeepPartial<T>`.
+* @returns A new string, object or array of strings or objects with the specified modifications.
+*/
+function sanitizeData(input, options, _return) {
+	const { keysToIgnore = [], requiredKeys = [], trimStrings = true, ignoreNullish = false, ignoreFalsy = false, ignoreEmpty = false } = options || {};
+	const ignoreKeySet = new Set(keysToIgnore);
+	/**
+	* * Determines if a key is required
+	* @param key The key to check.
+	* @returns `true` if the key is required, otherwise `false`.
+	*/
+	const _isRequiredKey = (key) => {
+		return Array.isArray(requiredKeys) ? requiredKeys?.some((path) => key === path || key.startsWith(`${path}.`)) : requiredKeys === "*";
+	};
+	/**
+	* * Check if a value is an object and determines whether it should skip based on `ignoreEmpty` flag.
+	* @param obj Object value to check.
+	* @returns `true` if the object is skippable, otherwise `false`.
+	*/
+	const _skipObject = (obj) => {
+		return ignoreEmpty && require_specials.isObject(obj) && !require_specials.isNotEmptyObject(obj);
+	};
+	/** Determines if a value is file-like or date-like object */
+	const _shouldNotProcess = (value) => {
+		return isCustomFile(value) || isFileList(value) || isFileOrBlob(value) || isFileUpload(value) || require_guards.isDateLike(value);
+	};
+	/**
+	* * Recursively process an array and its nested content(s).
+	* @param arr Array to process.
+	* @param path Full path as dot notation if needed.
+	* @returns Processed array.
+	*/
+	const _processArray = (arr, path) => {
+		return arr?.map((item) => {
+			if (require_primitives.isString(item) && trimStrings) return require_basics.trimString(item);
+			if (Array.isArray(item)) return _processArray(item, path);
+			if (require_specials.isObject(item)) return _processObject(item, path);
+			return item;
+		})?.filter((v) => {
+			if (ignoreNullish && v == null) return false;
+			if (ignoreFalsy && !v) return false;
+			if (_skipObject(v) && !_isRequiredKey(path)) return false;
+			return true;
+		});
+	};
+	/**
+	* * Helper function to process a single object.
+	*
+	* @param object The object to process.
+	* @param parentPath The parent path of a key.
+	*  */
+	const _processObject = (object, parentPath = "") => Object.entries(object).reduce((acc, [key, value]) => {
+		const fullKeyPath = parentPath ? `${parentPath}.${key}` : key;
+		if (ignoreKeySet.has(fullKeyPath)) return acc;
+		if (ignoreNullish && !_isRequiredKey(fullKeyPath) && value == null) return acc;
+		if (ignoreFalsy && !value && !_isRequiredKey(fullKeyPath)) return acc;
+		if (require_primitives.isString(value) && trimStrings) acc[key] = require_basics.trimString(value);
+		else if (_shouldNotProcess(value)) acc[key] = value;
+		else if (value && require_specials.isObject(value)) if (_shouldNotProcess(value)) acc[key] = value;
+		else {
+			const processedValue = _processObject(value, fullKeyPath);
+			if (!ignoreEmpty || _isRequiredKey(fullKeyPath) || require_specials.isNotEmptyObject(processedValue)) acc[key] = processedValue;
+		}
+		else if (value && Array.isArray(value)) {
+			const processedArray = _processArray(value, fullKeyPath);
+			if (!ignoreEmpty || _isRequiredKey(fullKeyPath) || processedArray?.length > 0) acc[key] = processedArray;
+		} else acc[key] = value;
+		return acc;
+	}, {});
+	if (require_primitives.isString(input)) return require_basics.trimString(input);
+	if (Array.isArray(input)) {
+		if (require_specials.isArrayOfType(input, require_primitives.isString)) return require_basics.trimString(input);
+		return input?.map((item) => sanitizeData(item, options, _return))?.filter((val) => {
+			if (ignoreNullish && val == null) return false;
+			if (ignoreFalsy && !val) return false;
+			if (_skipObject(val)) return false;
+			return true;
+		});
+	}
+	if (require_specials.isObject(input)) return _processObject(input);
+	return input;
+}
+/**
+* * Parse an object of stringified values into their appropriate primitive types.
+*
+* @description
+* - Attempts to convert string values into `boolean`, `number`, or JSON-parsed objects/arrays.
+* - Non-string values except arrays/objects are left unchanged. Nested arrays/objects are parsed recursively.
+*
+* @param object - The object with potentially stringified primitive values.
+* @param parseNested - Whether to convert stringified primitives in nested arrays/objects. (default: `true`).
+* @returns A new object with parsed values converted to their original types.
+*/
+function parseObjectValues(object, parseNested = true) {
+	function _deepParseValues(data) {
+		if (Array.isArray(data)) return data?.map(_deepParseValues);
+		else if (require_specials.isNotEmptyObject(data)) {
+			const result = {};
+			for (const [key, value] of Object.entries(data)) result[key] = parseNested ? _deepParseValues(value) : value;
+			return result;
+		} else if (require_primitives.isString(data)) try {
+			return _deepParseValues(JSON.parse(data));
+		} catch {
+			if (data === "true") return true;
+			else if (data === "false") return false;
+			else if (data === "null") return null;
+			else if (data === "undefined") return;
+			else if (!isNaN(Number(data))) return Number(data);
+			else return data;
+		}
+		return data;
+	}
+	const parsedBody = {};
+	if (require_specials.isNotEmptyObject(object)) Object.entries(object)?.forEach(([key, value]) => {
+		parsedBody[key] = _deepParseValues(value);
+	});
+	return parsedBody;
+}
+
+//#endregion
+//#region src/object/objectify.ts
+/**
+* Deeply merges two or more objects.
+* Objects are merged recursively. Later values override earlier ones unless both are plain objects.
+*
+* @param objects - List of objects to be merged.
+* @returns A new object with deeply merged properties from all input objects.
+*
+* @example
+* const obj1 = { a: 1, b: { x: 10 } };
+* const obj2 = { b: { y: 20 }, c: 3 };
+* const merged = mergeObjects(obj1, obj2);
+* // merged = { a: 1, b: { x: 10, y: 20 }, c: 3 }
+*
+* @example
+* mergeObjects(
+*   { a: 1, b: 2 },
+*   { p: { c: 3 }, d: 4 },
+*   { p: { e: 5 }, f: 6 }
+* );
+* // => { a: 1, b: 2, p: { c: 3, e: 5 }, d: 4, f: 6 }
+*/
+const mergeObjects = (...objects) => {
+	const map = /* @__PURE__ */ new Map();
+	for (const obj of objects) for (const key in obj) {
+		const existingValue = map.get(key);
+		if (require_specials.isNotEmptyObject(obj[key])) if (require_specials.isNotEmptyObject(existingValue)) if (require_guards.isDateLike(obj[key]) || isFileOrBlob(obj[key])) map.set(key, obj[key]);
+		else map.set(key, mergeObjects(existingValue, obj[key]));
+		else map.set(key, obj[key]);
+		else map.set(key, obj[key]);
+	}
+	const result = {};
+	map?.forEach((value, key) => {
+		result[key] = value;
+	});
+	return result;
+};
+/**
+* * Deeply merge objects and flatten nested objects.
+* * Useful for flattening a single object or merging multiple objects with duplicate key(s).
+* * If keys are duplicated, the last object's value will be used.
+*
+* @param objects Objects to merge.
+* @returns Merged object with flattened structure.
+*/
+const mergeAndFlattenObjects = (...objects) => {
+	const map = /* @__PURE__ */ new Map();
+	const _flattenObject = (obj, parentKey = "") => {
+		for (const key in obj) {
+			const newKey = parentKey ? `${String(parentKey)}.${key}` : key;
+			if (require_specials.isNotEmptyObject(obj[key])) if (require_guards.isDateLike(obj[key]) || isFileOrBlob(obj[key])) map.set(newKey, obj[key]);
+			else _flattenObject(obj[key], newKey);
+			else map.set(newKey, obj[key]);
+		}
+	};
+	for (const obj of objects) _flattenObject(obj);
+	const result = {};
+	map?.forEach((value, key) => {
+		result[key] = value;
+	});
+	return result;
+};
+/**
+* * Flattens a nested object into key-value format.
+*
+* @param object - The `object` to flatten.
+* @returns A `flattened object` in key-value format.
+*/
+const flattenObjectKeyValue = (object) => {
+	const flattened = {};
+	for (const [key, value] of Object.entries(object)) if (require_specials.isNotEmptyObject(value)) {
+		const nestedFlattened = flattenObjectKeyValue(value);
+		if (require_guards.isDateLike(value) || isFileOrBlob(value)) flattened[key] = value;
+		else Object.assign(flattened, nestedFlattened);
+	} else flattened[key] = value;
+	return flattened;
+};
+/**
+* * Flattens a nested object into a dot notation format.
+*
+* @param object - The `object` to flatten.
+* @returns A `flattened object` with dot notation keys.
+*/
+const flattenObjectDotNotation = (object) => {
+	/**
+	* * Recursively flattens an object, transforming nested structures into dot-notation keys.
+	*
+	* @param source - The `object` to be flattened.
+	* @param prefix - The prefix to prepend to each key. Used for nested objects.
+	* @returns A flattened version of the input object.
+	*/
+	const _flattenObject = (source, prefix = "") => {
+		const flattened = {};
+		for (const [key, value] of Object.entries(source)) {
+			const newKey = prefix ? `${String(prefix)}.${key}` : key;
+			if (require_specials.isNotEmptyObject(value) || isFileOrBlob(value)) if (require_guards.isDateLike(value)) flattened[newKey] = value;
+			else Object.assign(flattened, _flattenObject(value, newKey));
+			else flattened[newKey] = value;
+		}
+		return flattened;
+	};
+	return _flattenObject(object);
+};
+/**
+* * Extracts only the fields that have changed between the original and updated object.
+*
+* @param baseObject The original object to compare against.
+* @param updatedObject The modified object containing potential updates.
+* @returns A new object containing only the changed fields.
+*/
+const extractUpdatedFields = (baseObject, updatedObject) => {
+	const updatedFields = {};
+	for (const key in updatedObject) if (key in baseObject && !require_utils.isDeepEqual(updatedObject[key], baseObject[key])) if (updatedObject[key] && require_specials.isNotEmptyObject(updatedObject[key])) {
+		updatedFields[key] = extractUpdatedFields(baseObject[key], updatedObject[key]);
+		if (updatedFields[key] && require_specials.isEmptyObject(updatedFields[key])) delete updatedFields[key];
+	} else updatedFields[key] = updatedObject[key];
+	return updatedFields;
+};
+/**
+* * Extracts only new fields that exist in updatedObject but not in baseObject.
+*
+* @param baseObject The original object to compare against.
+* @param updatedObject The modified object containing potential new fields.
+* @returns A new object containing only the new fields.
+*/
+const extractNewFields = (baseObject, updatedObject) => {
+	const newFields = {};
+	for (const key in updatedObject) if (!(key in baseObject)) newFields[key] = updatedObject[key];
+	else if (require_specials.isNotEmptyObject(updatedObject[key]) && require_specials.isNotEmptyObject(baseObject[key])) {
+		const nestedNewFields = extractNewFields(baseObject[key], updatedObject[key]);
+		if (require_specials.isNotEmptyObject(nestedNewFields)) newFields[key] = nestedNewFields;
+	}
+	return newFields;
+};
+/**
+* * Extracts changed fields from the updated object while also identifying newly added keys.
+*
+* @param baseObject The original object to compare against.
+* @param updatedObject The modified object containing potential updates.
+* @returns An object containing modified fields and new fields separately.
+*/
+const extractUpdatedAndNewFields = (baseObject, updatedObject) => {
+	const updatedFields = {};
+	const newFields = {};
+	for (const key in updatedObject) if (!(key in baseObject)) newFields[key] = updatedObject[key];
+	else if (!require_utils.isDeepEqual(updatedObject[key], baseObject[key])) if (updatedObject[key] && require_specials.isNotEmptyObject(updatedObject[key])) {
+		updatedFields[key] = extractUpdatedAndNewFields(baseObject[key], updatedObject[key]);
+		if (updatedFields[key] && require_specials.isEmptyObject(updatedFields[key])) delete updatedFields[key];
+	} else updatedFields[key] = updatedObject[key];
+	return {
+		...updatedFields,
+		...newFields
+	};
+};
+/**
+* * Safely parses a JSON string into an object.
+* * Optionally converts stringified primitive values inside the object (e.g., `"0"` → `0`, `"true"` → `true`, `"null"` → `null`).
+*
+* @param value - The JSON string to parse.
+* @param parsePrimitives - Whether to convert stringified primitives into real values (default: `true`).
+* @returns A parsed object with primitive conversions, or an empty object on failure or if the root is not a valid object.
+* - Returns `{}` if parsing fails, such as when the input is malformed or invalid JSON or passing single quoted string.
+*
+* - **N.B.** This function will return an empty object if the JSON string is invalid or if the root element is not an object.
+*
+* - *Unlike `parseJSON`, which returns any valid JSON structure (including arrays, strings, numbers, etc.),
+* this function strictly ensures that the result is an object and optionally transforms stringified primitives.*
+*
+* @see parseJSON - For parsing generic JSON values (arrays, numbers, etc.) with optional primitive transformation.
+*
+*/
+const parseJsonToObject = (value, parsePrimitives = true) => {
+	try {
+		const data = JSON.parse(value);
+		if (!require_specials.isObject(data)) return {};
+		return parsePrimitives ? parseObjectValues(data) : data;
+	} catch {
+		return {};
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'extractNewFields', {
+  enumerable: true,
+  get: function () {
+    return extractNewFields;
+  }
+});
+Object.defineProperty(exports, 'extractUpdatedAndNewFields', {
+  enumerable: true,
+  get: function () {
+    return extractUpdatedAndNewFields;
+  }
+});
+Object.defineProperty(exports, 'extractUpdatedFields', {
+  enumerable: true,
+  get: function () {
+    return extractUpdatedFields;
+  }
+});
+Object.defineProperty(exports, 'flattenObjectDotNotation', {
+  enumerable: true,
+  get: function () {
+    return flattenObjectDotNotation;
+  }
+});
+Object.defineProperty(exports, 'flattenObjectKeyValue', {
+  enumerable: true,
+  get: function () {
+    return flattenObjectKeyValue;
+  }
+});
+Object.defineProperty(exports, 'isCustomFile', {
+  enumerable: true,
+  get: function () {
+    return isCustomFile;
+  }
+});
+Object.defineProperty(exports, 'isCustomFileArray', {
+  enumerable: true,
+  get: function () {
+    return isCustomFileArray;
+  }
+});
+Object.defineProperty(exports, 'isFileArray', {
+  enumerable: true,
+  get: function () {
+    return isFileArray;
+  }
+});
+Object.defineProperty(exports, 'isFileList', {
+  enumerable: true,
+  get: function () {
+    return isFileList;
+  }
+});
+Object.defineProperty(exports, 'isFileOrBlob', {
+  enumerable: true,
+  get: function () {
+    return isFileOrBlob;
+  }
+});
+Object.defineProperty(exports, 'isFileUpload', {
+  enumerable: true,
+  get: function () {
+    return isFileUpload;
+  }
+});
+Object.defineProperty(exports, 'isOriginFileObj', {
+  enumerable: true,
+  get: function () {
+    return isOriginFileObj;
+  }
+});
+Object.defineProperty(exports, 'isValidFormData', {
+  enumerable: true,
+  get: function () {
+    return isValidFormData;
+  }
+});
+Object.defineProperty(exports, 'mergeAndFlattenObjects', {
+  enumerable: true,
+  get: function () {
+    return mergeAndFlattenObjects;
+  }
+});
+Object.defineProperty(exports, 'mergeObjects', {
+  enumerable: true,
+  get: function () {
+    return mergeObjects;
+  }
+});
+Object.defineProperty(exports, 'parseJsonToObject', {
+  enumerable: true,
+  get: function () {
+    return parseJsonToObject;
+  }
+});
+Object.defineProperty(exports, 'parseObjectValues', {
+  enumerable: true,
+  get: function () {
+    return parseObjectValues;
+  }
+});
+Object.defineProperty(exports, 'sanitizeData', {
+  enumerable: true,
+  get: function () {
+    return sanitizeData;
+  }
+});