@ts-utilities/core 1.0.4 → 1.0.5

package/dist/index.cjs

@@ -1 +1,784 @@
-const e=e=>!e,t=e=>e==null,n=e=>{if(e==null)return!0;switch(typeof e){case`string`:case`number`:case`bigint`:case`boolean`:case`symbol`:return!0;default:return!1}};function r(e){if(typeof e!=`object`||!e||Object.prototype.toString.call(e)!==`[object Object]`)return!1;let t=Object.getPrototypeOf(e);return t===null||t===Object.prototype}function i(e,...t){let n,i={},a=t[t.length-1];a&&typeof a==`object`&&!Array.isArray(a)&&(a.arrayMerge!==void 0||a.clone!==void 0||a.customMerge!==void 0||a.functionMerge!==void 0||a.maxDepth!==void 0)?(i={...i,...a},n=t.slice(0,-1)):n=t;let{arrayMerge:o=`replace`,clone:s=!0,functionMerge:c=`replace`,maxDepth:l=100,customMerge:u}=i,d=new WeakMap;return f(e,n,0);function f(e,t,n){if(n>=l)return console.warn(`[deepmerge] Maximum depth ${l} exceeded. Returning target as-is.`),e;if(!r(e)&&!Array.isArray(e)){for(let n of t)if(n!==void 0){if(u){let t=u(``,e,n);if(t!==void 0)return t}return typeof e==`function`&&typeof n==`function`&&c===`compose`?(...t)=>{e(...t),n(...t)}:n}return e}let i=s?Array.isArray(e)?[...e]:{...e}:e;for(let e of t)if(e!=null&&!d.has(e))if(d.set(e,i),Array.isArray(i)&&Array.isArray(e))i=p(i,e,o);else if(r(i)&&r(e)){let t=new Set([...Object.keys(i),...Object.keys(e),...Object.getOwnPropertySymbols(i),...Object.getOwnPropertySymbols(e)]);for(let a of t){let t=i[a],s=e[a];u&&u(a,t,s)!==void 0?i[a]=u(a,t,s):typeof t==`function`&&typeof s==`function`?c===`compose`?i[a]=(...e)=>{t(...e),s(...e)}:i[a]=s:r(t)&&r(s)?i[a]=f(t,[s],n+1):Array.isArray(t)&&Array.isArray(s)?i[a]=p(t,s,o):s!==void 0&&(i[a]=s)}}else i=e;return i}function p(e,t,n){if(typeof n==`function`)return n(e,t);switch(n){case`concat`:return[...e,...t];case`merge`:let n=Math.max(e.length,t.length),i=[];for(let a=0;a<n;a++)a<e.length&&a<t.length?r(e[a])&&r(t[a])?i[a]=f(e[a],[t[a]],0):i[a]=t[a]:a<e.length?i[a]=e[a]:i[a]=t[a];return i;case`replace`:default:return[...t]}}}function a(e){return o(e)}function o(e){if(e!==null){if(typeof e!=`object`||!e)return e;if(Array.isArray(e))return e.map(o);if(r(e)){let t={};for(let n in e)t[n]=o(e[n]);return t}return e}}function s(e,t,n){if(typeof t!=`string`&&!Array.isArray(t))return n;let r=(()=>Array.isArray(t)?t:t===``?[]:String(t).split(`.`).filter(e=>e!==``))();if(!Array.isArray(r))return n;let i=e;for(let e of r){if(i==null)return n;let t=typeof e==`string`&&Array.isArray(i)&&/^\d+$/.test(e)?Number.parseInt(e,10):e;i=i[t]}return i===void 0?n:i}function c(e,t){return e==null?e:Object.assign(e,t)}function l(e){return(e.split(`.`).pop()||e).replace(/([a-z])([A-Z])/g,`$1 $2`).split(/[-_|�\s]+/).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(` `)}const u=`àáãäâèéëêìíïîòóöôùúüûñç·/_,:;`,d=`aaaaaeeeeiiiioooouuuunc------`,f=e=>{if(typeof e!=`string`)throw TypeError(`Input must be a string`);let t=e.trim().toLowerCase(),n={};for(let e=0;e<29;e++)n[u.charAt(e)]=`aaaaaeeeeiiiioooouuuunc------`.charAt(e);return t=t.replace(RegExp(`[${u}]`,`g`),e=>n[e]||e),t.replace(/[^a-z0-9 -]/g,``).replace(/\s+/g,`-`).replace(/-+/g,`-`).replace(/^-+/,``).replace(/-+$/,``)||``},p=(e=1e3,t)=>new Promise(n=>{if(t?.aborted)return n();let r=setTimeout(()=>{a(),n()},e);function i(){clearTimeout(r),a(),n()}function a(){t?.removeEventListener(`abort`,i)}t&&t.addEventListener(`abort`,i,{once:!0})});function m(e,t=100,n){if(typeof e!=`function`)throw TypeError(`Expected the first parameter to be a function, got \`${typeof e}\`.`);if(t<0)throw RangeError("`wait` must not be negative.");let r=n?.immediate??!1,i,a,o,s;function c(){return s=e.apply(o,a),a=void 0,o=void 0,s}let l=function(...e){return a=e,o=this,i===void 0&&r&&(s=c.call(this)),i!==void 0&&clearTimeout(i),i=setTimeout(c.bind(this),t),s};return Object.defineProperty(l,`isPending`,{get(){return i!==void 0}}),l}function h(e,t=100,n){if(typeof e!=`function`)throw TypeError(`Expected the first parameter to be a function, got \`${typeof e}\`.`);if(t<0)throw RangeError("`wait` must not be negative.");let r=n?.leading??!0,i=n?.trailing??!0,a,o,s,c,l;function u(){c=Date.now(),l=e.apply(s,o),o=void 0,s=void 0}function d(){a=void 0,i&&o&&u()}let f=function(...e){let n=c?Date.now()-c:1/0;return o=e,s=this,n>=t?r?u():a=setTimeout(d,t):!a&&i&&(a=setTimeout(d,t-n)),l};return Object.defineProperty(f,`isPending`,{get(){return a!==void 0}}),f}function g(e,...t){let n=t.length===1&&Array.isArray(t[0])?t[0]:t,r=0;return e.replace(/%s/g,()=>{let e=n[r++];return e===void 0?``:String(e)})}function _(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function v(e,t={}){if(!e)return``;let{lowercase:n=!0,removeAccents:r=!0,removeNonAlphanumeric:i=!0}=t,a=e.normalize(`NFC`);return r&&(a=a.normalize(`NFD`).replace(/\p{M}/gu,``)),i&&(a=a.replace(/^[^\p{L}\p{N}]*|[^\p{L}\p{N}]*$/gu,``)),n&&(a=a.toLocaleLowerCase()),a}async function y(e,{interval:t=5e3,timeout:n=300*1e3,jitter:r=!0,signal:i}={}){let a=Date.now(),o=i?.aborted??!1,s=()=>{o=!0};i?.addEventListener(`abort`,s,{once:!0});try{for(let s=0;;s++){if(o)throw Error(`Polling aborted`);let s=await e();if(s)return s;if(Date.now()-a>=n)throw Error(`Polling timed out`,{cause:`Polling timed out after ${n}ms`});await p(r?t+(Math.random()-.5)*t*.2:t,i)}}catch(e){throw e}finally{i?.removeEventListener(`abort`,s)}}function b(e,t={}){let{retry:n=0,delay:r=0}=t,i=Date.now(),a=async t=>{try{await e();let t=Date.now()-i;console.log(`⚡[schedule.ts] Completed in ${t}ms`)}catch(e){if(console.log(`⚡[schedule.ts] err:`,e),t>0)console.log(`⚡[schedule.ts] Retrying in ${r}ms...`),setTimeout(()=>a(t-1),r);else{let e=Date.now()-i;console.log(`⚡[schedule.ts] Failed after ${e}ms`)}}};setTimeout(()=>a(n),0)}function x(e){if(e instanceof Promise)return e.then(e=>[null,e]).catch(e=>[e,null]);try{return[null,e()]}catch(t){return console.log(`\x1b[31m🛡 [shield]\x1b[0m ${e.name} failed →`,t),[t,null]}}exports.convertToNormalCase=l,exports.convertToSlug=f,exports.debounce=m,exports.deepmerge=i,exports.escapeRegExp=_,exports.extendProps=c,exports.getObjectValue=s,exports.hydrate=a,exports.isFalsy=e,exports.isNullish=t,exports.isPlainObject=r,exports.isPrimitive=n,exports.normalizeText=v,exports.poll=y,exports.printf=g,exports.schedule=b,exports.shield=x,exports.sleep=p,exports.throttle=h;
+
+//#region src/types/guards.ts
+/**
+* Type guard that checks if a value is falsy.
+*
+* @param val - The value to check
+* @returns True if the value is falsy, false otherwise
+*
+* @example
+* if (isFalsy(value)) {
+*   console.log('Value is falsy');
+* }
+*/
+const isFalsy = (val) => !val;
+/**
+* Type guard that checks if a value is null or undefined.
+*
+* @param val - The value to check
+* @returns True if the value is null or undefined, false otherwise
+*
+* @example
+* if (isNullish(value)) {
+*   console.log('Value is null or undefined');
+* }
+*/
+const isNullish = (val) => val == null;
+/**
+* Type guard that checks if a value is a primitive type.
+*
+* @param val - The value to check
+* @returns True if the value is a primitive, false otherwise
+*
+* @example
+* if (isPrimitive(value)) {
+*   console.log('Value is a primitive type');
+* }
+*/
+const isPrimitive = (val) => {
+	if (val === null || val === void 0) return true;
+	switch (typeof val) {
+		case "string":
+		case "number":
+		case "bigint":
+		case "boolean":
+		case "symbol": return true;
+		default: return false;
+	}
+};
+/**
+* Type guard that checks if a value is a plain object (not an array, function, etc.).
+*
+* @param value - The value to check
+* @returns True if the value is a plain object, false otherwise
+*
+* @example
+* if (isPlainObject(value)) {
+*   console.log('Value is a plain object');
+* }
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (Object.prototype.toString.call(value) !== "[object Object]") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === null || proto === Object.prototype;
+}
+
+//#endregion
+//#region src/functions/deepmerge.ts
+function deepmerge(target, ...args) {
+	let sources;
+	let options = {};
+	const lastArg = args[args.length - 1];
+	if (lastArg && typeof lastArg === "object" && !Array.isArray(lastArg) && (lastArg.arrayMerge !== void 0 || lastArg.clone !== void 0 || lastArg.customMerge !== void 0 || lastArg.functionMerge !== void 0 || lastArg.maxDepth !== void 0)) {
+		options = {
+			...options,
+			...lastArg
+		};
+		sources = args.slice(0, -1);
+	} else sources = args;
+	const { arrayMerge = "replace", clone = true, functionMerge = "replace", maxDepth = 100, customMerge } = options;
+	const visited = /* @__PURE__ */ new WeakMap();
+	return mergeObjects(target, sources, 0);
+	function mergeObjects(target$1, sources$1, depth) {
+		if (depth >= maxDepth) {
+			console.warn(`[deepmerge] Maximum depth ${maxDepth} exceeded. Returning target as-is.`);
+			return target$1;
+		}
+		if (!isPlainObject(target$1) && !Array.isArray(target$1)) {
+			for (const source of sources$1) if (source !== void 0) {
+				if (customMerge) {
+					const merged = customMerge("", target$1, source);
+					if (merged !== void 0) return merged;
+				}
+				if (typeof target$1 === "function" && typeof source === "function") if (functionMerge === "compose") return (...args$1) => {
+					target$1(...args$1);
+					source(...args$1);
+				};
+				else return source;
+				return source;
+			}
+			return target$1;
+		}
+		let result = clone ? Array.isArray(target$1) ? [...target$1] : { ...target$1 } : target$1;
+		for (const source of sources$1) {
+			if (source == null) continue;
+			if (visited.has(source)) continue;
+			visited.set(source, result);
+			if (Array.isArray(result) && Array.isArray(source)) result = mergeArrays(result, source, arrayMerge);
+			else if (isPlainObject(result) && isPlainObject(source)) {
+				const keys = new Set([
+					...Object.keys(result),
+					...Object.keys(source),
+					...Object.getOwnPropertySymbols(result),
+					...Object.getOwnPropertySymbols(source)
+				]);
+				for (const key of keys) {
+					const targetValue = result[key];
+					const sourceValue = source[key];
+					if (customMerge && customMerge(key, targetValue, sourceValue) !== void 0) result[key] = customMerge(key, targetValue, sourceValue);
+					else if (typeof targetValue === "function" && typeof sourceValue === "function") if (functionMerge === "compose") result[key] = (...args$1) => {
+						targetValue(...args$1);
+						sourceValue(...args$1);
+					};
+					else result[key] = sourceValue;
+					else if (isPlainObject(targetValue) && isPlainObject(sourceValue)) result[key] = mergeObjects(targetValue, [sourceValue], depth + 1);
+					else if (Array.isArray(targetValue) && Array.isArray(sourceValue)) result[key] = mergeArrays(targetValue, sourceValue, arrayMerge);
+					else if (sourceValue !== void 0) result[key] = sourceValue;
+				}
+			} else result = source;
+		}
+		return result;
+	}
+	function mergeArrays(target$1, source, strategy) {
+		if (typeof strategy === "function") return strategy(target$1, source);
+		switch (strategy) {
+			case "concat": return [...target$1, ...source];
+			case "merge":
+				const maxLength = Math.max(target$1.length, source.length);
+				const merged = [];
+				for (let i = 0; i < maxLength; i++) if (i < target$1.length && i < source.length) if (isPlainObject(target$1[i]) && isPlainObject(source[i])) merged[i] = mergeObjects(target$1[i], [source[i]], 0);
+				else merged[i] = source[i];
+				else if (i < target$1.length) merged[i] = target$1[i];
+				else merged[i] = source[i];
+				return merged;
+			case "replace":
+			default: return [...source];
+		}
+	}
+}
+
+//#endregion
+//#region src/functions/hydrate.ts
+/**
+* Converts all `null` values to `undefined` in the data structure recursively.
+*
+* @param data - Any input data (object, array, primitive)
+* @returns Same type as input, but with all nulls replaced by undefined
+*
+* @example
+* ```ts
+* // Basic object hydration
+* hydrate({ name: null, age: 25 }) // { name: undefined, age: 25 }
+*
+* // Nested object hydration
+* hydrate({
+*   user: { email: null, profile: { avatar: null } },
+*   settings: { theme: 'dark' }
+* })
+* // { user: { email: undefined, profile: { avatar: undefined } }, settings: { theme: 'dark' } }
+*
+* // Array hydration
+* hydrate([null, 'hello', null, 42]) // [undefined, 'hello', undefined, 42]
+*
+* // Mixed data structures
+* hydrate({
+*   posts: [null, { title: 'Hello', content: null }],
+*   metadata: { published: null, tags: ['react', null] }
+* })
+* ```
+*
+* @example
+* ```ts
+* // API response normalization
+* const apiResponse = await fetch('/api/user');
+* const rawData = await apiResponse.json(); // May contain null values
+* const normalizedData = hydrate(rawData); // Convert nulls to undefined
+*
+* // Database result processing
+* const dbResult = query('SELECT * FROM users'); // Some fields may be NULL
+* const cleanData = hydrate(dbResult); // Normalize for consistent handling
+*
+* // Form data sanitization
+* const formData = getFormValues(); // May have null values from empty fields
+* const sanitizedData = hydrate(formData); // Prepare for validation/state
+* ```
+*/
+function hydrate(data) {
+	return convertNulls(data);
+}
+function convertNulls(value) {
+	if (value === null) return void 0;
+	if (typeof value !== "object" || value === null) return value;
+	if (Array.isArray(value)) return value.map(convertNulls);
+	if (isPlainObject(value)) {
+		const result = {};
+		for (const key in value) result[key] = convertNulls(value[key]);
+		return result;
+	}
+	return value;
+}
+
+//#endregion
+//#region src/functions/object.ts
+/**
+* Core implementation of getObjectValue with runtime type checking.
+*
+* Handles both dot-notation strings and array paths, with support for nested objects and arrays.
+* Performs validation and safe navigation to prevent runtime errors.
+*
+* @param obj - The source object to traverse
+* @param path - Path as string (dot-separated) or array of keys/indices
+* @param defaultValue - Value to return if path doesn't exist
+* @returns The value at the specified path, or defaultValue if not found
+*
+* @example
+* ```ts
+* getObjectValue({ a: { b: 1 } }, 'a.b') // 1
+* getObjectValue({ a: [1, 2] }, ['a', 0]) // 1
+* getObjectValue({}, 'missing.path', 'default') // 'default'
+* ```
+*/
+function getObjectValue(obj, path, defaultValue) {
+	if (typeof path !== "string" && !Array.isArray(path)) return defaultValue;
+	const pathArray = (() => {
+		if (Array.isArray(path)) return path;
+		if (path === "") return [];
+		return String(path).split(".").filter((segment) => segment !== "");
+	})();
+	if (!Array.isArray(pathArray)) return defaultValue;
+	let current = obj;
+	for (const key of pathArray) {
+		if (current === null || current === void 0) return defaultValue;
+		const actualKey = typeof key === "string" && Array.isArray(current) && /^\d+$/.test(key) ? Number.parseInt(key, 10) : key;
+		current = current[actualKey];
+	}
+	return current !== void 0 ? current : defaultValue;
+}
+/**
+* Extend an object or function with additional properties while
+* preserving the original type information.
+*
+* Works with both plain objects and callable functions since
+* functions in JavaScript are objects too. Also handles nullable types.
+*
+* @template T The base object or function type (can be null/undefined)
+* @template P The additional properties type
+*
+* @param base - The object or function to extend (can be null/undefined)
+* @param props - An object containing properties to attach
+*
+* @returns The same object/function, augmented with the given properties, or the original value if null/undefined
+*
+* @example
+* ```ts
+* // Extend a plain object
+* const config = extendProps({ apiUrl: '/api' }, { timeout: 5000 });
+* // config has both apiUrl and timeout properties
+*
+* // Extend a function with metadata
+* const fetchData = (url: string) => fetch(url).then(r => r.json());
+* const enhancedFetch = extendProps(fetchData, {
+*   description: 'Data fetching utility',
+*   version: '1.0'
+* });
+* // enhancedFetch is callable and has description/version properties
+*
+* // Create plugin system
+* const basePlugin = { name: 'base', enabled: true };
+* const authPlugin = extendProps(basePlugin, {
+*   authenticate: (token: string) => validateToken(token)
+* });
+*
+* // Build configuration objects
+* const defaultSettings = { theme: 'light', lang: 'en' };
+* const userSettings = extendProps(defaultSettings, {
+*   theme: 'dark',
+*   notifications: true
+* });
+*
+* // Handle nullable types (e.g., Supabase Session | null)
+* const session: Session | null = getSession();
+* const extendedSession = extendProps(session, { customProp: 'value' });
+* // extendedSession is (Session & { customProp: string }) | null
+* ```
+*/
+function extendProps(base, props) {
+	if (base == null) return base;
+	return Object.assign(base, props);
+}
+
+//#endregion
+//#region src/functions/utils-core.ts
+/**
+* Converts various case styles (camelCase, PascalCase, kebab-case, snake_case) into readable normal case.
+*
+* Transforms technical naming conventions into human-readable titles by:
+* - Adding spaces between words
+* - Capitalizing the first letter of each word
+* - Handling common separators (-, _, camelCase boundaries)
+*
+* @param inputString - The string to convert (supports camelCase, PascalCase, kebab-case, snake_case).
+* @returns The converted string in normal case (title case).
+*
+* @example
+* ```ts
+* convertToNormalCase('camelCase') // 'Camel Case'
+* convertToNormalCase('kebab-case') // 'Kebab Case'
+* convertToNormalCase('snake_case') // 'Snake Case'
+* convertToNormalCase('PascalCase') // 'Pascal Case'
+* ```
+*/
+function convertToNormalCase(inputString) {
+	return (inputString.split(".").pop() || inputString).replace(/([a-z])([A-Z])/g, "$1 $2").split(/[-_|�\s]+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+const from = "àáãäâèéëêìíïîòóöôùúüûñç·/_,:;";
+const to = "aaaaaeeeeiiiioooouuuunc------";
+/**
+* Converts a string to a URL-friendly slug by trimming, converting to lowercase,
+* replacing diacritics, removing invalid characters, and replacing spaces with hyphens.
+* @param {string} [str] - The input string to convert.
+* @returns {string} The generated slug.
+* @example
+* convertToSlug("Hello World!"); // "hello-world"
+* convertToSlug("Déjà Vu"); // "deja-vu"
+*/
+const convertToSlug = (str) => {
+	if (typeof str !== "string") throw new TypeError("Input must be a string");
+	let slug = str.trim().toLowerCase();
+	const charMap = {};
+	for (let i = 0; i < 29; i++) charMap[from.charAt(i)] = to.charAt(i);
+	slug = slug.replace(new RegExp(`[${from}]`, "g"), (match) => charMap[match] || match);
+	return slug.replace(/[^a-z0-9 -]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-+/, "").replace(/-+$/, "") || "";
+};
+/**
+* Pauses execution for the specified time.
+*
+* `signal` allows cancelling the sleep via AbortSignal.
+*
+* @param time - Time in milliseconds to sleep (default is 1000ms)
+* @param signal - Optional AbortSignal to cancel the sleep early
+* @returns - A Promise that resolves after the specified time or when aborted
+*/
+const sleep = (time = 1e3, signal) => new Promise((resolve) => {
+	if (signal?.aborted) return resolve();
+	const id = setTimeout(() => {
+		cleanup();
+		resolve();
+	}, time);
+	function onAbort() {
+		clearTimeout(id);
+		cleanup();
+		resolve();
+	}
+	function cleanup() {
+		signal?.removeEventListener("abort", onAbort);
+	}
+	if (signal) signal.addEventListener("abort", onAbort, { once: true });
+});
+/**
+* Creates a debounced function that delays invoking the provided function until
+* after the specified `wait` time has elapsed since the last invocation.
+*
+* If the `immediate` option is set to `true`, the function will be invoked immediately
+* on the leading edge of the wait interval. Subsequent calls during the wait interval
+* will reset the timer but not invoke the function until the interval elapses again.
+*
+* The returned function includes the `isPending` property to check if the debounce
+* timer is currently active.
+*
+* @typeParam F - The type of the function to debounce.
+*
+* @param function_ - The function to debounce.
+* @param wait - The number of milliseconds to delay (default is 100ms).
+* @param options - An optional object with the following properties:
+*   - `immediate` (boolean): If `true`, invokes the function on the leading edge
+*     of the wait interval instead of the trailing edge.
+*
+* @returns A debounced version of the provided function, enhanced with the `isPending` property.
+*
+* @throws {TypeError} If the first parameter is not a function.
+* @throws {RangeError} If the `wait` parameter is negative.
+*
+* @example
+* ```ts
+* // Basic debouncing
+* const log = debounce((message: string) => console.log(message), 200);
+* log('Hello'); // Logs "Hello" after 200ms if no other call is made.
+* console.log(log.isPending); // true if the timer is active.
+*
+* // Immediate execution
+* const save = debounce(() => saveToServer(), 500, { immediate: true });
+* save(); // Executes immediately, then waits 500ms for subsequent calls
+*
+* // Check pending state
+* const debouncedSearch = debounce(searchAPI, 300);
+* debouncedSearch('query');
+* if (debouncedSearch.isPending) {
+*   showLoadingIndicator();
+* }
+* ```
+*/
+function debounce(function_, wait = 100, options) {
+	if (typeof function_ !== "function") throw new TypeError(`Expected the first parameter to be a function, got \`${typeof function_}\`.`);
+	if (wait < 0) throw new RangeError("`wait` must not be negative.");
+	const immediate = options?.immediate ?? false;
+	let timeoutId;
+	let lastArgs;
+	let lastContext;
+	let result;
+	function run() {
+		result = function_.apply(lastContext, lastArgs);
+		lastArgs = void 0;
+		lastContext = void 0;
+		return result;
+	}
+	const debounced = function(...args) {
+		lastArgs = args;
+		lastContext = this;
+		if (timeoutId === void 0 && immediate) result = run.call(this);
+		if (timeoutId !== void 0) clearTimeout(timeoutId);
+		timeoutId = setTimeout(run.bind(this), wait);
+		return result;
+	};
+	Object.defineProperty(debounced, "isPending", { get() {
+		return timeoutId !== void 0;
+	} });
+	return debounced;
+}
+/**
+* Creates a throttled function that invokes the provided function at most once
+* every `wait` milliseconds.
+*
+* If the `leading` option is set to `true`, the function will be invoked immediately
+* on the leading edge of the throttle interval. If the `trailing` option is set to `true`,
+* the function will also be invoked at the end of the throttle interval if additional
+* calls were made during the interval.
+*
+* The returned function includes the `isPending` property to check if the throttle
+* timer is currently active.
+*
+* @typeParam F - The type of the function to throttle.
+*
+* @param function_ - The function to throttle.
+* @param wait - The number of milliseconds to wait between invocations (default is 100ms).
+* @param options - An optional object with the following properties:
+*   - `leading` (boolean): If `true`, invokes the function on the leading edge of the interval.
+*   - `trailing` (boolean): If `true`, invokes the function on the trailing edge of the interval.
+*
+* @returns A throttled version of the provided function, enhanced with the `isPending` property.
+*
+* @throws {TypeError} If the first parameter is not a function.
+* @throws {RangeError} If the `wait` parameter is negative.
+*
+* @example
+* ```ts
+* // Basic throttling (leading edge by default)
+* const log = throttle((message: string) => console.log(message), 200);
+* log('Hello'); // Logs "Hello" immediately
+* log('World'); // Ignored for 200ms
+* console.log(log.isPending); // true if within throttle window
+*
+* // Trailing edge only
+* const trailingLog = throttle(() => console.log('trailing'), 200, {
+*   leading: false,
+*   trailing: true
+* });
+* trailingLog(); // No immediate execution
+* // After 200ms: logs "trailing"
+*
+* // Both edges
+* const bothLog = throttle(() => console.log('both'), 200, {
+*   leading: true,
+*   trailing: true
+* });
+* bothLog(); // Immediate execution
+* // After 200ms: executes again if called during window
+* ```
+*/
+function throttle(function_, wait = 100, options) {
+	if (typeof function_ !== "function") throw new TypeError(`Expected the first parameter to be a function, got \`${typeof function_}\`.`);
+	if (wait < 0) throw new RangeError("`wait` must not be negative.");
+	const leading = options?.leading ?? true;
+	const trailing = options?.trailing ?? true;
+	let timeoutId;
+	let lastArgs;
+	let lastContext;
+	let lastCallTime;
+	let result;
+	function invoke() {
+		lastCallTime = Date.now();
+		result = function_.apply(lastContext, lastArgs);
+		lastArgs = void 0;
+		lastContext = void 0;
+	}
+	function later() {
+		timeoutId = void 0;
+		if (trailing && lastArgs) invoke();
+	}
+	const throttled = function(...args) {
+		const timeSinceLastCall = lastCallTime ? Date.now() - lastCallTime : Number.POSITIVE_INFINITY;
+		lastArgs = args;
+		lastContext = this;
+		if (timeSinceLastCall >= wait) if (leading) invoke();
+		else timeoutId = setTimeout(later, wait);
+		else if (!timeoutId && trailing) timeoutId = setTimeout(later, wait - timeSinceLastCall);
+		return result;
+	};
+	Object.defineProperty(throttled, "isPending", { get() {
+		return timeoutId !== void 0;
+	} });
+	return throttled;
+}
+/**
+* Formats a string by replacing each '%s' placeholder with the corresponding argument.
+*
+* Mimics the basic behavior of C's printf for %s substitution. Supports both
+* variadic arguments and array-based argument passing. Extra placeholders
+* are left as-is, missing arguments result in empty strings.
+*
+* @param format - The format string containing '%s' placeholders.
+* @param args - The values to substitute, either as separate arguments or a single array.
+* @returns The formatted string with placeholders replaced by arguments.
+*
+* @example
+* ```ts
+* // Basic usage with separate arguments
+* printf("%s love %s", "I", "Bangladesh") // "I love Bangladesh"
+*
+* // Using array of arguments
+* printf("%s love %s", ["I", "Bangladesh"]) // "I love Bangladesh"
+*
+* // Extra placeholders remain unchanged
+* printf("%s %s %s", "Hello", "World") // "Hello World %s"
+*
+* // Missing arguments become empty strings
+* printf("%s and %s", "this") // "this and "
+*
+* // Multiple occurrences
+* printf("%s %s %s", "repeat", "repeat", "repeat") // "repeat repeat repeat"
+* ```
+*/
+function printf(format, ...args) {
+	const replacements = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
+	let idx = 0;
+	return format.replace(/%s/g, () => {
+		const arg = replacements[idx++];
+		return arg === void 0 ? "" : String(arg);
+	});
+}
+/**
+* Escapes a string for use in a regular expression.
+*
+* @param str - The string to escape
+* @returns - The escaped string safe for use in RegExp constructor
+*
+* @example
+* ```ts
+* const escapedString = escapeRegExp('Hello, world!');
+* // escapedString === 'Hello\\, world!'
+*
+* const regex = new RegExp(escapeRegExp(userInput));
+* ```
+*/
+function escapeRegExp(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Normalizes a string by:
+* - Applying Unicode normalization (NFC)
+* - Optionally removing diacritic marks (accents)
+* - Optionally trimming leading/trailing non-alphanumeric characters
+* - Optionally converting to lowercase
+*
+* @param str - The string to normalize
+* @param options - Normalization options
+* @param options.lowercase - Whether to convert the result to lowercase (default: true)
+* @param options.removeAccents - Whether to remove diacritic marks like accents (default: true)
+* @param options.removeNonAlphanumeric - Whether to trim non-alphanumeric characters from the edges (default: true)
+* @returns The normalized string
+*
+* @example
+* ```ts
+* normalizeText('Café') // 'cafe'
+* normalizeText('  Hello!  ') // 'hello'
+* normalizeText('José', { removeAccents: false }) // 'josé'
+* ```
+*/
+function normalizeText(str, options = {}) {
+	if (!str) return "";
+	const { lowercase = true, removeAccents = true, removeNonAlphanumeric = true } = options;
+	let result = str.normalize("NFC");
+	if (removeAccents) result = result.normalize("NFD").replace(/\p{M}/gu, "");
+	if (removeNonAlphanumeric) result = result.replace(/^[^\p{L}\p{N}]*|[^\p{L}\p{N}]*$/gu, "");
+	if (lowercase) result = result.toLocaleLowerCase();
+	return result;
+}
+
+//#endregion
+//#region src/functions/poll.ts
+/**
+* Repeatedly polls an async `cond` function UNTIL it returns a TRUTHY value,
+* or until the operation times out or is aborted.
+*
+* Designed for waiting on async jobs, external state, or delayed availability.
+*
+* @template T The type of the successful result.
+*
+* @param cond
+* A function returning a Promise that resolves to:
+*   - a truthy value `T` → stop polling and return it
+*   - falsy/null/undefined → continue polling
+*
+* @param options
+* Configuration options:
+* - `interval` (number) — Time between polls in ms (default: 5000 ms)
+* - `timeout` (number) — Max total duration before failing (default: 5 min)
+* - `jitter` (boolean) — Add small random offset (±10%) to intervals to avoid sync bursts (default: true)
+* - `signal` (AbortSignal) — Optional abort signal to cancel polling
+*
+* @returns
+* Resolves with the truthy value `T` when successful.
+* Throws `AbortError` if aborted
+*
+* @example
+* ```ts
+* // Poll for job completion
+* const job = await poll(async () => {
+*   const status = await getJobStatus();
+*   return status === 'done' ? status : null;
+* }, { interval: 3000, timeout: 60000 });
+* ```
+*
+* @example
+* ```ts
+* // Wait for API endpoint to be ready
+* const apiReady = await poll(async () => {
+*   try {
+*     await fetch('/api/health');
+*     return true;
+*   } catch {
+*     return null;
+*   }
+* }, { interval: 1000, timeout: 30000 });
+* ```
+*
+* @example
+* ```ts
+* // Poll with abort signal for cancellation
+* const controller = new AbortController();
+* setTimeout(() => controller.abort(), 10000); // Cancel after 10s
+*
+* try {
+*   const result = await poll(
+*     () => checkExternalService(),
+*     { interval: 2000, signal: controller.signal }
+*   );
+* } catch (err) {
+*   if (err.name === 'AbortError') {
+*     console.log('Polling was cancelled');
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* // Poll for user action completion
+* const userConfirmed = await poll(async () => {
+*   const confirmations = await getPendingConfirmations();
+*   return confirmations.length > 0 ? confirmations[0] : null;
+* }, { interval: 5000, timeout: 300000 }); // 5 min timeout
+* ```
+*/
+async function poll(cond, { interval = 5e3, timeout = 300 * 1e3, jitter = true, signal } = {}) {
+	const start = Date.now();
+	let aborted = signal?.aborted ?? false;
+	const abortListener = () => {
+		aborted = true;
+	};
+	signal?.addEventListener("abort", abortListener, { once: true });
+	try {
+		for (let attempt = 0;; attempt++) {
+			if (aborted) throw new Error("Polling aborted");
+			const result = await cond();
+			if (result) return result;
+			if (Date.now() - start >= timeout) throw new Error("Polling timed out", { cause: `Polling timed out after ${timeout}ms` });
+			await sleep(jitter ? interval + (Math.random() - .5) * interval * .2 : interval, signal);
+		}
+	} catch (err) {
+		throw err;
+	} finally {
+		signal?.removeEventListener("abort", abortListener);
+	}
+}
+
+//#endregion
+//#region src/functions/schedule.ts
+/**
+* Runs a function asynchronously in the background without blocking the main thread.
+*
+* Executes the task immediately using setTimeout, with optional retry logic on failure.
+* Useful for non-critical operations like analytics, logging, or background processing.
+* Logs execution time and retry attempts to the console.
+*
+* @param task - The function to execute asynchronously
+* @param options - Configuration options for retries and timing
+*
+* @example
+* ```ts
+* // Simple background task
+* schedule(() => {
+*   console.log('Background work done');
+* });
+*
+* // Task with retry on failure
+* schedule(
+*   () => sendAnalytics(),
+*   { retry: 3, delay: 1000 }
+* );
+* ```
+*/
+function schedule(task, options = {}) {
+	const { retry = 0, delay = 0 } = options;
+	const start = Date.now();
+	const attempt = async (triesLeft) => {
+		try {
+			await task();
+			const total = Date.now() - start;
+			console.log(`⚡[schedule.ts] Completed in ${total}ms`);
+		} catch (err) {
+			console.log("⚡[schedule.ts] err:", err);
+			if (triesLeft > 0) {
+				console.log(`⚡[schedule.ts] Retrying in ${delay}ms...`);
+				setTimeout(() => attempt(triesLeft - 1), delay);
+			} else {
+				const total = Date.now() - start;
+				console.log(`⚡[schedule.ts] Failed after ${total}ms`);
+			}
+		}
+	};
+	setTimeout(() => attempt(retry), 0);
+}
+
+//#endregion
+//#region src/functions/shield.ts
+function shield(operation) {
+	if (operation instanceof Promise) return operation.then((value) => [null, value]).catch((error) => [error, null]);
+	try {
+		return [null, operation()];
+	} catch (error) {
+		console.log(`\x1b[31m🛡 [shield]\x1b[0m ${operation.name} failed →`, error);
+		return [error, null];
+	}
+}
+
+//#endregion
+exports.convertToNormalCase = convertToNormalCase;
+exports.convertToSlug = convertToSlug;
+exports.debounce = debounce;
+exports.deepmerge = deepmerge;
+exports.escapeRegExp = escapeRegExp;
+exports.extendProps = extendProps;
+exports.getObjectValue = getObjectValue;
+exports.hydrate = hydrate;
+exports.isFalsy = isFalsy;
+exports.isNullish = isNullish;
+exports.isPlainObject = isPlainObject;
+exports.isPrimitive = isPrimitive;
+exports.normalizeText = normalizeText;
+exports.poll = poll;
+exports.printf = printf;
+exports.schedule = schedule;
+exports.shield = shield;
+exports.sleep = sleep;
+exports.throttle = throttle;