@h3ravel/support 0.13.0 → 0.14.0

package/dist/index.js

@@ -12,132 +12,27 @@ import relativeTime from "dayjs/plugin/relativeTime.js";
 import timezone from "dayjs/plugin/timezone.js";
 import utc from "dayjs/plugin/utc.js";
 
-//#region src/Helpers/Arr.ts
-var Arr_exports = /* @__PURE__ */ __export({
-	alternate: () => alternate,
-	chunk: () => chunk,
-	collapse: () => collapse,
-	combine: () => combine,
-	find: () => find,
-	first: () => first,
-	flatten: () => flatten,
-	forget: () => forget,
-	isEmpty: () => isEmpty,
-	isNotEmpty: () => isNotEmpty,
-	last: () => last,
-	pop: () => pop,
-	prepend: () => prepend,
-	range: () => range,
-	reverse: () => reverse,
-	shift: () => shift,
-	take: () => take,
-	wrap: () => wrap
-});
+//#region src/Exceptions/InvalidArgumentException.ts
 /**
-* Splits an array into chunks of a specified size.
-*
-* @template T - Type of elements in the array
-* @param arr - The input array
-* @param size - Size of each chunk (default: 2)
-* @returns An array of chunks (arrays)
+* Custom error for invalid type coercion
 */
-const chunk = (arr, size = 2) => {
-	if (size <= 0) throw new Error("Chunk size must be greater than 0");
-	const chunks = [];
-	for (let i = 0; i < arr.length; i += size) chunks.push(arr.slice(i, i + size));
-	return chunks;
-};
-/**
-* Collapse an array of arrays into a single array.
-*/
-const collapse = (arr) => {
-	const result = [];
-	for (const item of arr) if (Array.isArray(item)) result.push(...item);
-	else result.push(item);
-	return result;
-};
-/**
-* Alternates between two arrays, creating a zipped result.
-*/
-const alternate = (a, b) => {
-	const result = [];
-	const max = Math.max(a.length, b.length);
-	for (let i = 0; i < max; i++) {
-		if (i < a.length) result.push(a[i]);
-		if (i < b.length) result.push(b[i]);
+var InvalidArgumentException = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidArgumentException";
 	}
-	return result;
-};
-/**
-* Combine arrays and sum their values element by element.
-*/
-const combine = (...arr) => {
-	const maxLength = Math.max(...arr.map((a) => a.length));
-	const result = new Array(maxLength).fill(0);
-	for (let i = 0; i < maxLength; i++) for (const array of arr) result[i] += array[i] || 0;
-	return result;
-};
-/** Find the value associated with a given key. */
-const find = (key, arr) => arr.find((item) => item === key) || null;
-/** Returns a new array without the given indices. */
-const forget = (arr, keys) => arr.filter((_, i) => !keys.includes(i));
-/** Remove the first element and return tuple [el, rest]. */
-const first = (arr) => {
-	if (!arr.length) throw new Error("Cannot shift from empty array");
-	return [arr[0], arr.slice(1)];
-};
-/** Remove the last element and return tuple [el, rest]. */
-const last = (arr) => {
-	if (!arr.length) throw new Error("Cannot pop from empty array");
-	return [arr[arr.length - 1], arr.slice(0, -1)];
-};
-/** Check if array is empty. */
-const isEmpty = (arr) => {
-	if (arr.length === 0) return true;
-	else return false;
-};
-/** Check if array is empty. */
-const isNotEmpty = (arr) => arr.length > 0;
-/** Pop the element off the end of array. */
-const pop = (arr) => arr.slice(0, -1);
-/** Add elements to the beginning of array. */
-const prepend = (arr, ...elements) => [...elements, ...arr];
-/** Take first n elements of array. */
-const take = (amount, arr) => arr.slice(0, Math.max(0, amount));
-/** Create a new array in reverse order. */
-const reverse = (arr) => [...arr].reverse();
-/** Alias for first element removal. */
-const shift = first;
-/**
-* Generates an array of sequential numbers.
-*
-* @param size - Number of elements in the range
-* @param startAt - Starting number (default: 0)
-* @returns An array of numbers from startAt to startAt + size - 1
-*/
-const range = (size, startAt = 0) => {
-	if (size <= 0 || !Number.isFinite(size)) return [];
-	return Array.from({ length: size }, (_, i) => startAt + i);
-};
-/** Flatten multi-dimensional arrays into single level. */
-const flatten = (arr) => {
-	const result = [];
-	const recurse = (input) => {
-		for (const item of input) if (Array.isArray(item)) recurse(item);
-		else result.push(item);
-	};
-	recurse(arr);
-	return result;
 };
+
+//#endregion
+//#region src/Exceptions/RuntimeException.ts
 /**
-* If the given value is not an array and not null, wrap it in one.
-*
-* @param  {Array}  value
-* @return array
+* Custom error for invalid type coercion
 */
-const wrap = (value) => {
-	if (value === null) return [];
-	return Array.isArray(value) ? value : [value];
+var RuntimeException = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RuntimeException";
+	}
 };
 
 //#endregion
@@ -304,10 +199,10 @@ const verifyChecksum = (data, expectedChecksum, algorithm = "sha256") => {
 * @param shift - Number of positions to shift (default: 13)
 * @returns Encrypted/decrypted text
 */
-const caesarCipher = (text, shift$1 = 13) => {
+const caesarCipher = (text, shift = 13) => {
 	return text.replace(/[a-zA-Z]/g, (char) => {
 		const baseCharCode = char === char.toUpperCase() ? "A" : "a";
-		const shiftedCharCode = (char.charCodeAt(0) - baseCharCode.charCodeAt(0) + shift$1) % 26;
+		const shiftedCharCode = (char.charCodeAt(0) - baseCharCode.charCodeAt(0) + shift) % 26;
 		const newCharCode = (shiftedCharCode < 0 ? 26 + shiftedCharCode : shiftedCharCode) + baseCharCode.charCodeAt(0);
 		return String.fromCharCode(newCharCode);
 	});
@@ -519,22 +414,27 @@ const toHumanTime = (seconds = 0, worded = false) => {
 		if (secs || !hours && !minutes) parts.push(`${secs}sec`);
 		return parts.join(" ");
 	}
-	const hh = hours > 0 ? `${hours}:` : "";
-	const mm = (hours > 0 && minutes < 10 ? `0${minutes}` : minutes) + ":";
-	const ss = secs < 10 ? `0${secs}` : secs;
-	return `${hh}${mm}${ss}`;
+	return `${hours > 0 ? `${hours}:` : ""}${(hours > 0 && minutes < 10 ? `0${minutes}` : minutes) + ":"}${secs < 10 ? `0${secs}` : secs}`;
 };
 
 //#endregion
 //#region src/Helpers/Obj.ts
 var Obj_exports = /* @__PURE__ */ __export({
+	Obj: () => Obj,
+	data_fill: () => data_fill,
+	data_forget: () => data_forget,
+	data_get: () => data_get,
+	data_set: () => data_set,
 	dot: () => dot,
 	extractProperties: () => extractProperties,
 	getValue: () => getValue,
 	modObj: () => modObj,
 	safeDot: () => safeDot,
 	setNested: () => setNested,
-	slugifyKeys: () => slugifyKeys
+	slugifyKeys: () => slugifyKeys,
+	toCssClasses: () => toCssClasses,
+	toCssStyles: () => toCssStyles,
+	undot: () => undot
 });
 /**
 * Flattens a nested object into a single-level object
@@ -677,6 +577,893 @@ const slugifyKeys = (obj, only = [], separator = "_") => {
 	if (only.length) entries = entries.filter(([key]) => only.includes(key));
 	return Object.fromEntries(entries.map(([key, value]) => [slugify(key), value]));
 };
+/**
+* toCssClasses
+*
+* Convert array/object/string input into a CSS class string.
+* - Arrays: included if truthy
+* - Objects: keys included if value is truthy
+* - Strings: included as-is
+*/
+function toCssClasses(input) {
+	if (!input) return "";
+	const classes = [];
+	if (typeof input === "string") return input.trim();
+	if (Array.isArray(input)) input.forEach((item) => {
+		if (item) classes.push(String(item).trim());
+	});
+	else if (typeof input === "object") {
+		for (const [key, value] of Object.entries(input)) if (value) classes.push(key);
+	}
+	return classes.join(" ");
+}
+/**
+* toCssStyles
+*
+* Convert object input into CSS style string.
+* - Only includes truthy values (ignores null/undefined/false)
+*/
+function toCssStyles(styles) {
+	const parts = [];
+	for (const [k, v] of Object.entries(styles)) {
+		if (v === null || v === void 0 || v === false) continue;
+		parts.push(`${k}:${v}`);
+	}
+	return parts.join(";");
+}
+/**
+* undot
+*
+* Convert a dot-notated object back into nested structure.
+*
+* Example:
+* undot({ 'a.b': 1, 'c.0': 2 }) -> { a: { b: 1 }, c: [2] }
+*/
+function undot(obj) {
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		const parts = key.split(".");
+		let node = result;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			const isLast = i === parts.length - 1;
+			const nextPart = parts[i + 1];
+			const isArrayIndex = !isNaN(Number(nextPart));
+			if (isLast) node[part] = value;
+			else {
+				if (!(part in node)) node[part] = isArrayIndex ? [] : {};
+				node = node[part];
+			}
+		}
+	}
+	return result;
+}
+/**
+* data_get
+*
+* Get a value from an object using dot notation.
+*/
+function data_get(obj, path, defaultValue) {
+	if (!obj) return defaultValue;
+	const parts = Array.isArray(path) ? path : path.split(".");
+	let current = obj;
+	for (const part of parts) {
+		if (!current || !(part in current)) return defaultValue;
+		current = current[part];
+	}
+	return current;
+}
+/**
+* data_set
+*
+* Set a value in an object using dot notation. Mutates the object.
+*/
+function data_set(obj, path, value) {
+	const parts = Array.isArray(path) ? path : path.split(".");
+	let current = obj;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (i === parts.length - 1) current[part] = value;
+		else {
+			if (!(part in current) || typeof current[part] !== "object" || current[part] === null) current[part] = {};
+			current = current[part];
+		}
+	}
+}
+/**
+* data_fill
+*
+* Like data_set, but only sets the value if the key does NOT exist.
+*/
+function data_fill(obj, path, value) {
+	if (data_get(obj, path) === void 0) data_set(obj, path, value);
+}
+/**
+* data_forget
+*
+* Remove a key from an object using dot notation.
+*/
+function data_forget(obj, path) {
+	const parts = Array.isArray(path) ? path : path.split(".");
+	let current = obj;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (i === parts.length - 1) delete current[part];
+		else {
+			if (!current[part] || typeof current[part] !== "object") break;
+			current = current[part];
+		}
+	}
+}
+var Obj = class Obj {
+	/**
+	* Check if the value is a non-null object (associative/accessible).
+	*/
+	static accessible(value) {
+		return value !== null && typeof value === "object";
+	}
+	/**
+	* Add a key-value pair to an object only if the key does not already exist.
+	*
+	* Returns a new object (does not mutate original).
+	*/
+	static add(obj, key, value) {
+		if (!(key in obj)) return {
+			...obj,
+			[key]: value
+		};
+		return obj;
+	}
+	/**
+	* Split object into [keys, values]
+	*/
+	static divide(obj) {
+		return [Object.keys(obj), Object.values(obj)];
+	}
+	/**
+	* Check if a key exists in the object.
+	*/
+	static exists(obj, key) {
+		return Object.prototype.hasOwnProperty.call(obj, key);
+	}
+	/**
+	* Get a value from an object using dot notation.
+	*
+	* Example:
+	* Obj.get({a:{b:1}}, 'a.b') -> 1
+	*/
+	static get(obj, path, defaultValue) {
+		if (!Obj.accessible(obj)) return defaultValue;
+		const parts = Array.isArray(path) ? path : path.split(".");
+		let current = obj;
+		for (const part of parts) {
+			if (!Obj.accessible(current) || !(part in current)) return defaultValue;
+			current = current[part];
+		}
+		return current;
+	}
+	/**
+	* Check if the object has a given key or keys (dot notation supported).
+	*/
+	static has(obj, keys) {
+		if (!Obj.accessible(obj)) return false;
+		return (Array.isArray(keys) ? keys : [keys]).every((key) => {
+			const parts = key.split(".");
+			let current = obj;
+			for (const part of parts) {
+				if (!Obj.accessible(current) || !(part in current)) return false;
+				current = current[part];
+			}
+			return true;
+		});
+	}
+	/**
+	* Check if an object is associative (has at least one non-numeric key).
+	*/
+	static isAssoc(obj) {
+		if (!Obj.accessible(obj)) return false;
+		return Object.keys(obj).some((k) => isNaN(Number(k)));
+	}
+	/**
+	* Add a prefix to all keys of the object.
+	*/
+	static prependKeysWith(obj, prefix) {
+		if (!Obj.accessible(obj)) return {};
+		const result = {};
+		for (const [k, v] of Object.entries(obj)) result[`${prefix}${k}`] = v;
+		return result;
+	}
+	/**
+	* Convert an object into a URL query string.
+	*
+	* Nested objects/arrays are flattened using bracket notation.
+	*/
+	static query(obj) {
+		const encode = encodeURIComponent;
+		const parts = [];
+		function build(key, value) {
+			if (Array.isArray(value)) value.forEach((v, i) => build(`${key}[${i}]`, v));
+			else if (Obj.accessible(value)) Object.entries(value).forEach(([k, v]) => build(`${key}[${k}]`, v));
+			else parts.push(`${encode(key)}=${encode(value)}`);
+		}
+		Object.entries(obj).forEach(([k, v]) => build(k, v));
+		return parts.join("&");
+	}
+};
+
+//#endregion
+//#region src/Helpers/Arr.ts
+/**
+* Arr — Laravel-like array helpers for JavaScript.
+*
+* - Methods aim for clear, predictable JS behavior.
+* - Inputs are validated where useful; functions try not to mutate arguments.
+*/
+var Arr = class Arr {
+	/**
+	* Helper: is a value an object (but not null).
+	*/
+	static _isObject(value) {
+		return value !== null && typeof value === "object" && !Array.isArray(value);
+	}
+	/**
+	* Helper: deep clone for safety (simple).
+	* Uses JSON methods — good for typical data shapes (no functions, Dates, Maps).
+	*/
+	static _clone(value) {
+		try {
+			return JSON.parse(JSON.stringify(value));
+		} catch {
+			return value;
+		}
+	}
+	/**
+	* Retrieve a value using dot notation
+	* Throws if value is not an array
+	*/
+	static array(obj, path, defaultValue) {
+		const val = data_get(obj, path, defaultValue);
+		if (!Array.isArray(val)) throw new InvalidArgumentException(`Value at "${path}" is not an array.`);
+		return val;
+	}
+	/**
+	* Retrieve a value using dot notation
+	* Throws if value is not a boolean
+	*/
+	static boolean(obj, path, defaultValue) {
+		const val = data_get(obj, path, defaultValue);
+		if (typeof val !== "boolean") throw new InvalidArgumentException(`Value at "${path}" is not a boolean.`);
+		return val;
+	}
+	/**
+	* Flatten an array of arrays by one level.
+	*
+	* Example:
+	* Arr.collapse([[1,2], [3], 4]) -> [1,2,3,4]
+	*/
+	static collapse(array) {
+		if (!Array.isArray(array)) return [];
+		const result = [];
+		for (const item of array) if (Array.isArray(item)) result.push(...item);
+		else result.push(item);
+		return result;
+	}
+	/**
+	* Cartesian product of arrays.
+	*
+	* Example:
+	* Arr.crossJoin([1,2], ['a','b']) -> [[1,'a'], [1,'b'], [2,'a'], [2,'b']]
+	*
+	* Accepts any number of array arguments (or single array-of-arrays).
+	*/
+	static crossJoin(...arrays) {
+		let inputs = arrays;
+		if (arrays.length === 1 && Array.isArray(arrays[0]) && arrays[0].some(Array.isArray)) inputs = arrays[0];
+		inputs = inputs.map((a) => Array.isArray(a) ? a : [a]);
+		let product = [[]];
+		for (const arr of inputs) {
+			const next = [];
+			for (const prefix of product) for (const value of arr) next.push([...prefix, value]);
+			product = next;
+		}
+		return product;
+	}
+	/**
+	* Split an array (or object) into two arrays: [keys, values].
+	*
+	* For arrays, keys are numeric indices. For objects, keys are property names.
+	*
+	* Example:
+	* Arr.divide(['a','b']) -> [[0,1], ['a','b']]
+	* Arr.divide({x:1,y:2}) -> [['x','y'], [1,2]]
+	*/
+	static divide(input) {
+		if (Array.isArray(input)) return [input.map((_, i) => i), input.slice()];
+		if (Arr._isObject(input)) {
+			const keys = Object.keys(input);
+			return [keys, keys.map((k) => input[k])];
+		}
+		return [[], []];
+	}
+	/**
+	* Flatten a nested array/object structure into a single-level object
+	* with dot-notated keys.
+	*
+	* Example:
+	* Arr.dot({ a: { b: 1 }, c: [2,3] }) -> { 'a.b': 1, 'c.0': 2, 'c.1': 3 }
+	*
+	* Works for arrays and plain objects.
+	*/
+	static dot(input, prefix = "") {
+		const result = {};
+		const recurse = (val, path) => {
+			if (Array.isArray(val)) for (let i = 0; i < val.length; i++) recurse(val[i], path ? `${path}.${i}` : String(i));
+			else if (Arr._isObject(val)) for (const [k, v] of Object.entries(val)) recurse(v, path ? `${path}.${k}` : k);
+			else result[path] = val;
+		};
+		if (Array.isArray(input) || Arr._isObject(input)) recurse(input, prefix);
+		return result;
+	}
+	/**
+	* Checks if all elements satisfy the predicate
+	*/
+	static every(array, predicate) {
+		return array.every(predicate);
+	}
+	/**
+	* Remove items by keys/indices from an array or properties from an object.
+	*
+	* For arrays: keys are numeric indices (single number or array of numbers).
+	*
+	* Returns a shallow-copied result (does not mutate input).
+	*
+	* Example:
+	* Arr.except([10,20,30], [1]) -> [10,30]
+	*/
+	static except(input, keys) {
+		const keySet = new Set(Array.isArray(keys) ? keys : [keys]);
+		if (Array.isArray(input)) return input.filter((_, idx) => !keySet.has(idx));
+		if (Arr._isObject(input)) {
+			const out = {};
+			for (const [k, v] of Object.entries(input)) if (!keySet.has(k)) out[k] = v;
+			return out;
+		}
+		return input;
+	}
+	/**
+	* Return the first element of an array that satisfies the predicate,
+	* or the first element if no predicate is provided, otherwise the defaultValue.
+	*
+	* Predicate can be true (boolean), a function or a value to match (strict equality).
+	* 
+	* When predicate is true (boolean), the first element will be removed and a tuple will be returned [el, rest].
+	* 
+	* @param array 
+	* @param predicate 
+	* @param defaultValue 
+	* 
+	* @returns 
+	*/
+	static first(array, predicate, defaultValue) {
+		if (predicate === true) {
+			if (!array.length) throw new Error("Cannot shift from empty array");
+			return [array[0], array.slice(1)];
+		}
+		if (!Array.isArray(array) || array.length === 0) return defaultValue;
+		if (predicate === void 0) return array[0];
+		if (typeof predicate === "function") {
+			for (const item of array) if (predicate(item)) return item;
+			return defaultValue;
+		}
+		for (const item of array) if (typeof predicate !== "boolean" && item === predicate) return item;
+		return defaultValue;
+	}
+	/**
+	* Recursively flatten an array up to `depth` levels (default: Infinity).
+	*
+	* Example:
+	* Arr.flatten([1, [2, [3]]], 1) -> [1,2,[3]]
+	*/
+	static flatten(array, depth = Infinity) {
+		if (!Array.isArray(array)) return [];
+		if (depth < 1) return array.slice();
+		const result = [];
+		for (const item of array) if (Array.isArray(item) && depth > 0) result.push(...Arr.flatten(item, depth - 1));
+		else result.push(item);
+		return result;
+	}
+	/**
+	* Retrieve a value from an array/object using dot notation
+	* Throws if value is not a float
+	*/
+	static float(obj, path, defaultValue) {
+		const val = data_get(obj, path, defaultValue);
+		if (typeof val !== "number" || Number.isNaN(val)) throw new InvalidArgumentException(`Value at "${path}" is not a float.`);
+		return val;
+	}
+	/**
+	* Remove element(s) by index or dot-notated path from an array/object.
+	*
+	* For arrays: accepts numeric index or array of indices. Returns a new array.
+	*
+	* For objects: supports dot notation to remove nested keys.
+	*
+	* Example:
+	* Arr.forget([1,2,3], 1) -> [1,3]
+	* Arr.forget({a:{b:1}}, 'a.b') -> { a: {} }
+	*/
+	static forget(input, keys) {
+		if (Array.isArray(input)) {
+			const removeSet = new Set(Array.isArray(keys) ? keys : [keys]);
+			return input.filter((_, i) => !removeSet.has(i));
+		}
+		if (Arr._isObject(input)) {
+			const out = Arr._clone(input);
+			const keyList = Array.isArray(keys) ? keys : [keys];
+			for (const key of keyList) {
+				const parts = String(key).split(".");
+				let node = out;
+				for (let i = 0; i < parts.length; i++) {
+					const part = parts[i];
+					if (i === parts.length - 1) {
+						if (node && Object.prototype.hasOwnProperty.call(node, part)) delete node[part];
+					} else {
+						if (!Arr._isObject(node[part])) break;
+						node = node[part];
+					}
+				}
+			}
+			return out;
+		}
+		return input;
+	}
+	/**
+	* Converts various input types into a plain array
+	* Supports Arrays, Objects, Iterables, Map, WeakMap, and custom toArray/toJSON/jsonSerialize methods
+	*/
+	static from(value) {
+		if (value == null) return [];
+		if (Array.isArray(value)) return value;
+		if (Symbol.iterator in Object(value)) return [...value];
+		if (value.toArray) return value.toArray();
+		if (value.toJSON) return value.toJSON();
+		if (value.jsonSerialize) return value.jsonSerialize();
+		if (value instanceof Map) return Array.from(value.entries());
+		if (value instanceof WeakMap) return [];
+		if (typeof value === "object") return Object.values(value);
+		return [value];
+	}
+	/**
+	* Checks if an object has all the specified keys
+	*/
+	static hasAll(obj, keys) {
+		return keys.every((k) => k in obj);
+	}
+	/**
+	* For arrays: check if the array contains any of the provided values.
+	*
+	* values can be single value or array of values.
+	*
+	* Example:
+	* Arr.hasAny([1,2,3], [4,2]) -> true
+	*/
+	static hasAny(array, values) {
+		if (!Array.isArray(array)) return false;
+		const vs = Array.isArray(values) ? values : [values];
+		const set = new Set(array);
+		for (const v of vs) if (set.has(v)) return true;
+		return false;
+	}
+	/**
+	* Retrieve a value using dot notation
+	* Throws if value is not an integer
+	*/
+	static integer(obj, path, defaultValue) {
+		const val = data_get(obj, path, defaultValue);
+		if (!Number.isInteger(val)) throw new InvalidArgumentException(`Value at "${path}" is not an integer.`);
+		return val;
+	}
+	/**
+	* Determine if the input is a "list-like" array: an Array with
+	* contiguous numeric indices starting at 0 (no gaps).
+	*
+	* Example:
+	* Arr.isList([1,2,3]) -> true
+	* const a = []; a[2] = 5; Arr.isList(a) -> false
+	*/
+	static isList(value) {
+		if (!Array.isArray(value)) return false;
+		for (let i = 0; i < value.length; i++) if (!(i in value)) return false;
+		return true;
+	}
+	/**
+	* Join array elements into a string using the given separator.
+	*
+	* Example:
+	* Arr.join([1,2,3], '-') -> '1-2-3'
+	*/
+	static join(array, separator = ",") {
+		return Array.isArray(array) ? array.join(separator) : "";
+	}
+	/**
+	* Create an object indexed by a key or callback function.
+	*
+	* Example:
+	* Arr.keyBy([{id:1},{id:2}], 'id') -> { '1': {id:1}, '2': {id:2} }
+	*/
+	static keyBy(array, key) {
+		const result = {};
+		if (!Array.isArray(array)) return result;
+		for (const item of array) {
+			let k;
+			if (typeof key === "function") k = key(item);
+			else k = String(item[key]);
+			result[k] = item;
+		}
+		return result;
+	}
+	/**
+	* Get the last element of an array, optionally matching a predicate,
+	* or the last element if no predicate is provided, otherwise the defaultValue.
+	*
+	* Predicate can be a true (boolean), a function or a value to match (strict equality).
+	* 
+	* When predicate is true (boolean), the last element will be removed and a tuple will be returned [el, rest].
+	* 
+	* @param array 
+	* @param predicate 
+	* @param defaultValue 
+	* 
+	* @returns 
+	*/
+	static last(array, predicate, defaultValue) {
+		if (predicate === true) {
+			if (!array.length) throw new Error("Cannot pop from empty array");
+			return [array[array.length - 1], array.slice(0, -1)];
+		}
+		if (!Array.isArray(array) || array.length === 0) return defaultValue;
+		if (!predicate) return array[array.length - 1];
+		if (typeof predicate === "function") {
+			for (let i = array.length - 1; i >= 0; i--) if (predicate(array[i])) return array[i];
+		} else for (let i = array.length - 1; i >= 0; i--) if (array[i] === predicate) return array[i];
+		return defaultValue;
+	}
+	/**
+	* Transform each element in an array using a callback.
+	*/
+	static map(array, callback) {
+		return Array.isArray(array) ? array.map(callback) : [];
+	}
+	/**
+	* Maps a multi-dimensional array with a spread callback
+	*/
+	static mapSpread(array, callback) {
+		return array.map((item) => callback(...Array.isArray(item) ? item : [item]));
+	}
+	/**
+	* Map each element to a key-value pair.
+	*
+	* Example:
+	* Arr.mapWithKeys([{id:1, name:'A'}], x => [x.id, x.name])
+	* -> { '1': 'A' }
+	*/
+	static mapWithKeys(array, callback) {
+		const result = {};
+		if (!Array.isArray(array)) return result;
+		array.forEach((item, idx) => {
+			const [k, v] = callback(item, idx);
+			result[String(k)] = v;
+		});
+		return result;
+	}
+	/**
+	* Return only elements at the given indices.
+	*
+	* Example:
+	* Arr.only([10,20,30], [0,2]) -> [10,30]
+	*/
+	static only(array, keys) {
+		if (!Array.isArray(array)) return [];
+		const keyArray = Array.isArray(keys) ? keys : [keys];
+		return array.filter((_, idx) => keyArray.includes(idx));
+	}
+	/**
+	* Split an array into two arrays based on a predicate
+	*/
+	static partition(array, predicate) {
+		const truthy = [];
+		const falsy = [];
+		array.forEach((item) => (predicate(item) ? truthy : falsy).push(item));
+		return [truthy, falsy];
+	}
+	/**
+	* Extract a property from each element in an array of objects.
+	*
+	* Example:
+	* Arr.pluck([{name:'A'},{name:'B'}], 'name') -> ['A','B']
+	*/
+	static pluck(array, key) {
+		if (!Array.isArray(array)) return [];
+		return array.map((item) => item[key]);
+	}
+	/**
+	* Add elements to the beginning of an array and return a new array.
+	* 
+	* @param array 
+	* @param value 
+	* @returns 
+	*/
+	static prepend(array, ...value) {
+		return [...value, ...Array.isArray(array) ? array : []];
+	}
+	/**
+	* Remove a value from an array by index and return it.
+	* Returns a tuple: [newArray, removedValue]
+	*/
+	static pull(array, key) {
+		if (!Array.isArray(array) || key < 0 || key >= array.length) return [array, void 0];
+		const copy = array.slice();
+		const [removed] = copy.splice(key, 1);
+		return [copy, removed];
+	}
+	/**
+	* Append values to an array (mutable)
+	*/
+	static push(array, ...values) {
+		array.push(...values);
+		return array;
+	}
+	/**
+	* Pick one or more random elements from an array.
+	*/
+	static random(array, count = 1) {
+		if (!Array.isArray(array) || array.length === 0) return void 0;
+		const shuffled = Arr.shuffle(array);
+		if (count === 1) return shuffled[0];
+		return shuffled.slice(0, count);
+	}
+	/**
+	* Returns array elements that do NOT satisfy the predicate
+	*/
+	static reject(array, predicate) {
+		return array.filter((item) => !predicate(item));
+	}
+	/**
+	* Pick keys from an array of objects or an object
+	*/
+	static select(obj, keys) {
+		const result = {};
+		keys.forEach((k) => {
+			if (k in obj) result[k] = obj[k];
+		});
+		return result;
+	}
+	/**
+	* Returns the only element that passes a callback, throws if none or multiple
+	*/
+	static sole(array, predicate) {
+		const filtered = array.filter(predicate);
+		if (filtered.length === 0) throw new InvalidArgumentException("No element satisfies the condition.");
+		if (filtered.length > 1) throw new InvalidArgumentException("Multiple elements satisfy the condition.");
+		return filtered[0];
+	}
+	/**
+	* Checks if at least one element satisfies the predicate
+	*/
+	static some(array, predicate) {
+		return array.some(predicate);
+	}
+	/**
+	* Randomly shuffle an array and return a new array.
+	*/
+	static shuffle(array) {
+		if (!Array.isArray(array)) return [];
+		const copy = array.slice();
+		for (let i = copy.length - 1; i > 0; i--) {
+			const j = Math.floor(Math.random() * (i + 1));
+			[copy[i], copy[j]] = [copy[j], copy[i]];
+		}
+		return copy;
+	}
+	/**
+	* Sort an array ascending using optional comparator.
+	*/
+	static sort(array, comparator) {
+		if (!Array.isArray(array)) return [];
+		return array.slice().sort(comparator);
+	}
+	/**
+	* Sort an array descending using optional comparator.
+	*/
+	static sortDesc(array, comparator) {
+		return Arr.sort(array, comparator ? (a, b) => comparator(b, a) : void 0);
+	}
+	/**
+	* Recursively sort arrays inside an array.
+	*/
+	static sortRecursive(array) {
+		if (!Array.isArray(array)) return [];
+		return array.map((item) => Array.isArray(item) ? Arr.sortRecursive(item) : item).sort();
+	}
+	/**
+	* Recursively sort arrays inside an array descending.
+	*/
+	static sortRecursiveDesc(array) {
+		if (!Array.isArray(array)) return [];
+		return array.map((item) => Array.isArray(item) ? Arr.sortRecursiveDesc(item) : item).sort().reverse();
+	}
+	/**
+	* Retrieve a value using dot notation
+	* Throws if value is not a string
+	*/
+	static string(obj, path, defaultValue) {
+		const val = data_get(obj, path, defaultValue);
+		if (typeof val !== "string") throw new InvalidArgumentException(`Value at "${path}" is not a string.`);
+		return val;
+	}
+	/**
+	* Return the first N elements of an array.
+	* 
+	* @param array 
+	* @param count 
+	* @returns 
+	*/
+	static take(array, count) {
+		if (!Array.isArray(array)) return [];
+		return array.slice(0, count);
+	}
+	/**
+	* Filter an array based on a predicate function or key-value match.
+	*/
+	static where(array, predicate) {
+		if (!Array.isArray(array)) return [];
+		if (typeof predicate === "function") return array.filter(predicate);
+		return array.filter((item) => Object.entries(predicate).every(([k, v]) => item[k] === v));
+	}
+	/**
+	* Filter an array of objects, keeping elements where the given key is not null/undefined.
+	*/
+	static whereNotNull(array, key) {
+		if (!Array.isArray(array)) return [];
+		return array.filter((item) => item[key] !== null && item[key] !== void 0);
+	}
+	/**
+	* If the given value is not an array and not null, wrap it in one.
+	* 
+	* Non-array values become [value]; null/undefined becomes [].
+	* 
+	* @param value 
+	* @returns 
+	*/
+	static wrap(value) {
+		if (value === null || value === void 0) return [];
+		return Array.isArray(value) ? value : [value];
+	}
+	/**
+	* Return the first element of an array, undefined if empty.
+	*/
+	static head(array) {
+		return Array.isArray(array) && array.length ? array[0] : void 0;
+	}
+	/**
+	* Splits an array into chunks of a specified size.
+	*
+	* @template T - Type of elements in the array
+	* @param arr - The input array
+	* @param size - Size of each chunk (default: 2)
+	* @returns An array of chunks (arrays)
+	*/
+	static chunk = (arr, size = 2) => {
+		if (size <= 0) throw new Error("Chunk size must be greater than 0");
+		const chunks = [];
+		for (let i = 0; i < arr.length; i += size) chunks.push(arr.slice(i, i + size));
+		return chunks;
+	};
+	/**
+	* Alternates between two arrays, creating a zipped result.
+	* 
+	* @param a 
+	* @param b 
+	* @returns 
+	*/
+	static alternate(a, b) {
+		const result = [];
+		const max = Math.max(a.length, b.length);
+		for (let i = 0; i < max; i++) {
+			if (i < a.length) result.push(a[i]);
+			if (i < b.length) result.push(b[i]);
+		}
+		return result;
+	}
+	/**
+	* Combine arrays and sum their values element by element.
+	* 
+	* @param arr 
+	* @returns 
+	*/
+	static combine(...arr) {
+		const maxLength = Math.max(...arr.map((a) => a.length));
+		const result = new Array(maxLength).fill(0);
+		for (let i = 0; i < maxLength; i++) for (const array of arr) result[i] += array[i] || 0;
+		return result;
+	}
+	/** 
+	* Find the value associated with a given key. 
+	* 
+	* @param key 
+	* @param arr 
+	* @returns 
+	*/
+	static find(key, arr) {
+		return arr.find((item) => item === key) || null;
+	}
+	/**
+	* Check if array is empty.
+	* 
+	* @param arr 
+	* @returns 
+	*/
+	static isEmpty(arr) {
+		if (arr.length === 0) return true;
+		else return false;
+	}
+	/**
+	* Check if array is empty. 
+	* 
+	* @param arr 
+	* @returns 
+	*/
+	static isNotEmpty(arr) {
+		return arr.length > 0;
+	}
+	/**
+	* Pop the element off the end of array.
+	* 
+	* @param arr 
+	* @returns 
+	*/
+	static pop(arr) {
+		return arr.slice(0, -1);
+	}
+	/**
+	* Create a new array in reverse order. 
+	* 
+	* @param arr 
+	* @returns 
+	*/
+	static reverse(arr) {
+		return [...arr].reverse();
+	}
+	/**
+	* Return the first element of an array that satisfies the predicate,
+	* or the first element if no predicate is provided, otherwise the defaultValue.
+	*
+	* Predicate can be true (boolean), a function or a value to match (strict equality).
+	* 
+	* When predicate is true (boolean), the first element will be removed and a tuple will be returned [el, rest].
+	* 
+	* @param array 
+	* @param predicate 
+	* @param defaultValue 
+	* 
+	* @alias Arr.first()
+	* @returns 
+	*/
+	static shift(array, predicate, defaultValue) {
+		return Arr.first(array, predicate, defaultValue);
+	}
+	/**
+	* Generates an array of sequential numbers.
+	*
+	* @param size - Number of elements in the range
+	* @param startAt - Starting number (default: 0)
+	* @returns An array of numbers from startAt to startAt + size - 1
+	*/
+	static range(size, startAt = 0) {
+		if (size <= 0 || !Number.isFinite(size)) return [];
+		return Array.from({ length: size }, (_, i) => startAt + i);
+	}
+};
 
 //#endregion
 //#region src/Helpers/Time.ts
@@ -5201,10 +5988,10 @@ function matchCase(value, comparison) {
 */
 function loadHelpers(target = globalThis) {
 	const globalHelpers = {
-		Arr: Arr_exports,
+		Arr,
 		Crypto: Crypto_exports,
 		Number: Number_exports,
-		Obj: Obj_exports,
+		Obj,
 		Str,
 		DateTime,
 		DumpDie: DumpDie_exports,
@@ -5220,24 +6007,26 @@ function loadHelpers(target = globalThis) {
 		plural: Str.plural,
 		singular: Str.singular,
 		capitalize: Str.capitalize,
-		collapse,
-		alternate,
-		combine,
-		forget,
-		first,
-		last,
-		isEmpty,
-		isNotEmpty,
-		prepend,
-		range,
-		flatten,
+		collapse: Arr.collapse,
+		forget: Arr.forget,
+		first: Arr.first,
+		last: Arr.last,
+		prepend: Arr.prepend,
+		flatten: Arr.flatten,
 		dot,
+		undot,
 		extractProperties,
 		getValue,
 		modObj,
 		safeDot,
 		setNested,
+		toCssClasses,
 		slugifyKeys,
+		toCssStyles,
+		data_get,
+		data_set,
+		data_fill,
+		data_forget,
 		uuid,
 		random,
 		randomSecure,
@@ -5319,6 +6108,13 @@ function cleanHelpers(target = globalThis) {
 		"safeDot",
 		"setNested",
 		"slugifyKeys",
+		"toCssClasses",
+		"undot",
+		"toCssStyles",
+		"data_get",
+		"data_set",
+		"data_fill",
+		"data_forget",
 		"Crypto",
 		"uuid",
 		"random",
@@ -5356,5 +6152,5 @@ function cleanHelpers(target = globalThis) {
 }
 
 //#endregion
-export { Arr_exports as Arr, Crypto_exports as Crypto, DateTime, DumpDie_exports as DumpDie, HtmlString, Mode, Number_exports as Number, Obj_exports as Obj, Str, Stringable, abbreviate, alternate, base64Decode, base64Encode, caesarCipher, checksum, chunk, cleanHelpers, collapse, combine, dd, dot, dump, extractProperties, find, first, flatten, forget, format, getValue, hash, hmac, humanize, isEmpty, isNotEmpty, last, loadHelpers, modObj, pop, prepend, random, randomColor, randomPassword, randomSecure, range, reverse, safeDot, secureToken, setNested, shift, slugifyKeys, str, take, toBytes, toHumanTime, uuid, verifyChecksum, wrap, xor };
+export { Arr, Crypto_exports as Crypto, DateTime, DumpDie_exports as DumpDie, HtmlString, InvalidArgumentException, Mode, Number_exports as Number, Obj_exports as Obj, RuntimeException, Str, Stringable, abbreviate, base64Decode, base64Encode, caesarCipher, checksum, cleanHelpers, data_fill, data_forget, data_get, data_set, dd, dot, dump, extractProperties, format, getValue, hash, hmac, humanize, loadHelpers, modObj, random, randomColor, randomPassword, randomSecure, safeDot, secureToken, setNested, slugifyKeys, str, toBytes, toCssClasses, toCssStyles, toHumanTime, undot, uuid, verifyChecksum, xor };
 //# sourceMappingURL=index.js.map