Bump 0.30.7

package.json

@@ -1,46 +1,46 @@
-{
-	"name": "@ztimson/utils",
-	"version": "0.30.0",
-	"description": "Utility library",
-	"author": "Zak Timson",
-	"license": "MIT",
-	"private": false,
-	"repository": {
-		"type": "git",
-		"url": "https://git.zakscode.com/ztimson/js-utilities"
-	},
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.mjs",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.mjs",
-			"require": "./dist/index.cjs"
-		}
-	},
-	"scripts": {
-		"build": "npx tsc && npx vite build",
-		"docs": "typedoc --cleanOutputDir false --out ./docs --entryPoints src/**/*.ts --readme none",
-		"test": "npx jest",
-		"test:coverage": "npx jest --coverage",
-		"watch": "npx vite build --watch"
-	},
-	"dependencies": {
-		"var-persist": "^1.0.1"
-	},
-	"devDependencies": {
-		"@types/jest": "^30.0.0",
-		"fake-indexeddb": "^6.2.5",
-		"jest": "^30.2.0",
-		"jest-junit": "^16.0.0",
-		"ts-jest": "^29.4.5",
-		"typedoc": "^0.28.15",
-		"typescript": "^5.9.3",
-		"vite": "^7.2.4",
-		"vite-plugin-dts": "^4.5.4"
-	},
-	"files": [
-		"dist"
-	]
-}
+{
+	"name": "@ztimson/utils",
+	"version": "0.30.7",
+	"description": "Utility library",
+	"author": "Zak Timson",
+	"license": "MIT",
+	"private": false,
+	"repository": {
+		"type": "git",
+		"url": "https://git.zakscode.com/ztimson/js-utilities"
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"scripts": {
+		"build": "npx tsc && npx vite build",
+		"docs": "typedoc --cleanOutputDir false --out ./docs --entryPoints src/**/*.ts --readme none",
+		"test": "npx jest",
+		"test:coverage": "npx jest --coverage",
+		"watch": "npx vite build --watch"
+	},
+	"dependencies": {
+		"var-persist": "^1.0.1"
+	},
+	"devDependencies": {
+		"@types/jest": "^30.0.0",
+		"fake-indexeddb": "^6.2.5",
+		"jest": "^30.2.0",
+		"jest-junit": "^16.0.0",
+		"ts-jest": "^29.4.5",
+		"typedoc": "^0.28.15",
+		"typescript": "^5.9.3",
+		"vite": "^7.2.4",
+		"vite-plugin-dts": "^4.5.4"
+	},
+	"files": [
+		"dist"
+	]
+}

src/cache.ts

@@ -31,6 +31,8 @@ export class Cache<K extends string | number | symbol, T> {
 	/** Await initial loading */
 	loading = new Promise<void>(r => this._loading = r);
 
+	get size() { return this.store.keys().toArray().length }
+
 	/**
 	 * Create new cache
 	 * @param {keyof T} key Default property to use as primary key

src/html.ts

@@ -0,0 +1,65 @@
+/**
+ * Decode HTML escaped characters
+ * @param html HTML to clean up
+ * @returns {any}
+ */
+export function decodeHtml(html: string) {
+	return html
+		.replace(/ /g, '\u00A0')
+		.replace(/"/g, '"')
+		.replace(/'/g, "'")
+		.replace(/&lt;/g, '<')
+		.replace(/&gt;/g, '>')
+		.replace(/&cent;/g, '¢')
+		.replace(/&pound;/g, '£')
+		.replace(/&yen;/g, '¥')
+		.replace(/&euro;/g, '€')
+		.replace(/&copy;/g, '©')
+		.replace(/&reg;/g, '®')
+		.replace(/&trade;/g, '™')
+		.replace(/&times;/g, '×')
+		.replace(/&divide;/g, '÷')
+		.replace(/&#(\d+);/g, (match, dec) => String.fromCharCode(dec))
+		.replace(/&#x([0-9a-fA-F]+);/g, (match, hex) => String.fromCharCode(parseInt(hex, 16)))
+		.replace(/&amp;/g, '&'); // Always last!
+}
+
+/**
+ * Parse markdown headers
+ *
+ * **NOTE: frontmatter parsing only works 2 layers deep**
+ *
+ * @param {string} content
+ * @returns {{meta: any, content: string} | {meta: {}, content: string}}
+ */
+export function parseMarkdown(content: string) {
+	const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+	if (!match) return {meta: {}, content};
+
+	const meta: any = {};
+	let currentParent: string | null = null;
+
+	for (const rawLine of match[1].split('\n')) {
+		if (!rawLine.trim()) continue;
+		const indented = /^\s+/.test(rawLine);
+		const line = rawLine.trim();
+		const colonIdx = line.indexOf(':');
+		if (colonIdx === -1) continue;
+
+		const key = line.slice(0, colonIdx).trim();
+		const value = line.slice(colonIdx + 1).trim();
+
+		let parsed: any = value;
+		try { parsed = JSON.parse(value); } catch {}
+
+		if (!indented) {
+			currentParent = value === '' ? key : null;
+			if (value === '') meta[key] = {};
+			else meta[key] = parsed;
+		} else if (currentParent) {
+			meta[currentParent][key] = parsed;
+		}
+	}
+
+	return {meta, content: match[2].trim()};
+}

src/index.ts

@@ -7,10 +7,12 @@ export * from './cache';
 export * from './color';
 export * from './csv';
 export * from './database';
-export * from './files';
 export * from './emitter';
 export * from './errors';
+export * from './files';
+export * from './html';
 export * from './http';
+export * from './ip';
 export * from './json';
 export * from './jwt';
 export * from './logger';

src/ip.ts

@@ -0,0 +1,77 @@
+/**
+ * Check if IP address falls within any of the given CIDR ranges
+ * @param {string} ip IPV4 to check (192.168.0.12)
+ * @param {...string} cidrs IP ranges to check against (example: 192.168.0.0/24)
+ * @returns {boolean} Whether IP address is within any range
+ */
+export function matchesCidr(ip: string, ...cidrs: string[]): boolean {
+	if (!ip) return false;
+	if (!cidrs.length) return true;
+	const ipToInt = (str: string) => str.split('.')
+		.reduce((int, octet) => (int << 8) + parseInt(octet), 0) >>> 0;
+	return cidrs.some(cidr => {
+		if (!cidr) return true;
+		if (!cidr.includes('/')) return ip === cidr; // Single IP
+		const [range, bits] = cidr.split('/');
+		const mask = ~(2 ** (32 - parseInt(bits)) - 1);
+		return (ipToInt(ip) & mask) === (ipToInt(range) & mask);
+	});
+}
+
+/**
+ * Convert IPv6 to v4 because who uses that, NAT4Life
+ * @param {string} ip IPv6 address, e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334
+ * @returns {string | null} IPv4 address, e.g. 172.16.58.3
+ */
+export function ipV6ToV4(ip: string) {
+	if(!ip) return null;
+	const ipv4 = ip.split(':').splice(-1)[0];
+	if(ipv4 == '1') return '127.0.0.1';
+	return ipv4;
+}
+
+/**
+ * @deprecated Use isReserved
+ *
+ * Check if IP is reserved, e.g. localhost, private IPs, etc.
+ * @param {string} ip
+ * @returns {boolean}
+ */
+export function reservedIp(ip: string): boolean {
+	if(ip == 'localhost' || ip == '127.0.0.1') return true;
+	return /\b(10\.(?:[0-9]{1,3}\.){2}[0-9]{1,3})\b|\b(172\.(?:1[6-9]|2[0-9]|3[0-1])\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b|\b(192\.168\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b/.test(ip);
+}
+
+/**
+ * Check if IP is within a reserved range
+ * @param {string} ip
+ * @returns {null | 'Invalid' | 'Host' | 'Loopback' | 'Private (Class A)' | 'Private (Class B)' | 'Link-Local' | 'IETF Protocol Assignments' | 'Documentation (TEST-NET-1)' | 'Benchmarking' | 'Documentation (TEST-NET-2)' | 'Documentation (TEST-NET-3)' | 'Multicast' | 'Reserved (Class E)'} null if public, class name if reserved
+ */
+export function isReserved(ip: string): null | 'Invalid' | 'Host' | 'Loopback' | 'Private (Class A)' | 'Private (Class B)' | 'Link-Local' | 'IETF Protocol Assignments' | 'Documentation (TEST-NET-1)' | 'Benchmarking' | 'Documentation (TEST-NET-2)' | 'Documentation (TEST-NET-3)' | 'Multicast' | 'Reserved (Class E)' {
+	const ipToNumber = (ip: string) => {
+		return ip.split('.').reduce((acc: number, octet: string) => (acc << 8) + parseInt(octet, 10), 0) >>> 0;
+	};
+
+	const ipNum = ipToNumber(ip);
+	if (ipNum === null) return 'Invalid';
+
+	const reserved = [
+		{ name: "Host", start: ipToNumber("0.0.0.0"), end: ipToNumber("0.255.255.255") },
+		{ name: "Loopback", start: ipToNumber("127.0.0.0"), end: ipToNumber("127.255.255.255") },
+		{ name: "Private (Class A)", start: ipToNumber("10.0.0.0"), end: ipToNumber("10.255.255.255") },
+		{ name: "CGNAT", start: ipToNumber("100.64.0.0"), end: ipToNumber("100.127.255.255") },
+		{ name: "Private (Class B)", start: ipToNumber("172.16.0.0"), end: ipToNumber("172.31.255.255") },
+		{ name: "Private (Class C)", start: ipToNumber("192.168.0.0"), end: ipToNumber("192.168.255.255") },
+		{ name: "Link-Local", start: ipToNumber("169.254.0.0"), end: ipToNumber("169.254.255.255") },
+		{ name: "IETF Protocol Assignments", start: ipToNumber("192.0.0.0"), end: ipToNumber("192.0.0.255") },
+		{ name: "Documentation (TEST-NET-1)", start: ipToNumber("192.0.2.0"), end: ipToNumber("192.0.2.255") },
+		{ name: "Benchmarking", start: ipToNumber("198.18.0.0"), end: ipToNumber("198.19.255.255") },
+		{ name: "Documentation (TEST-NET-2)", start: ipToNumber("198.51.100.0"), end: ipToNumber("198.51.100.255") },
+		{ name: "Documentation (TEST-NET-3)", start: ipToNumber("203.0.113.0"), end: ipToNumber("203.0.113.255") },
+		{ name: "Multicast", start: ipToNumber("224.0.0.0"), end: ipToNumber("239.255.255.255") },
+		{ name: "Reserved (Class E)", start: ipToNumber("240.0.0.0"), end: ipToNumber("255.255.255.255") }
+	];
+
+	const match = reserved.find(r => ipNum >= r.start && ipNum <= r.end);
+	return match ? <any>match.name : null;
+}

src/misc.ts

@@ -76,46 +76,6 @@ export function gravatar(email: string, def='mp') {
 	return `https://www.gravatar.com/avatar/${md5(email)}?d=${def}`;
 }
 
-/**
- * Check if IP address falls within CIDR range
- * @param {string} ip IPV4 to check (192.168.0.12)
- * @param {string} cidr IP range to check against (example: 192.168.0.0/24)
- * @returns {boolean} Whether IP address is within range
- */
-export function matchesCidr(ip: string, cidr: string): boolean {
-	if(!cidr) return true;
-	if(!ip) return false;
-	if(!cidr?.includes('/')) return ip === cidr; // Single IP
-	const [range, bits] = cidr.split('/');
-	const mask = ~(2 ** (32 - parseInt(bits)) - 1);
-	const ipToInt = (str: string) => str.split('.')
-		.reduce((int, octet) => (int << 8) + parseInt(octet), 0) >>> 0;
-	return (ipToInt(ip) & mask) === (ipToInt(range) & mask);
-}
-
-/**
- * Convert IPv6 to v4 because who uses that, NAT4Life
- * @param {string} ip IPv6 address, e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334
- * @returns {string | null} IPv4 address, e.g. 172.16.58.3
- */
-export function ipV6ToV4(ip: string) {
-	if(!ip) return null;
-	const ipv4 = ip.split(':').splice(-1)[0];
-	if(ipv4 == '1') return '127.0.0.1';
-	return ipv4;
-}
-
-/**
- * Check if IP is reserved, e.g. localhost, private IPs, etc.
- * @param {string} ip
- * @returns {boolean}
- */
-export function reservedIp(ip: string): boolean {
-	if(ip == 'localhost' || ip == '127.0.0.1') return true;
-	return /\b(10\.(?:[0-9]{1,3}\.){2}[0-9]{1,3})\b|\b(172\.(?:1[6-9]|2[0-9]|3[0-1])\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b|\b(192\.168\.(?:[0-9]{1,3}\.)[0-9]{1,3})\b/.test(ip);
-}
-
-
 /**
  * Represents a function that listens for events and handles them accordingly.
  *

src/objects.ts

@@ -1,309 +1,311 @@
-import {JSONSanitize} from './json.ts';
-
-export type Delta = { [key: string]: any | Delta | null };
-
-/**
- * Applies deltas to `target`.
- * @param base starting point
- * @param deltas List of deltas to apply
- * @returns Mutated target
- */
-export function applyDeltas(base: any, ...deltas: any[]): any {
-	function applyDelta(base: any, delta: any): any {
-		if(delta === null) return null;
-		if(typeof base !== 'object' || base === null) return delta === undefined ? base : delta;
-		const result = Array.isArray(base) ? [...base] : { ...base };
-		for(const key in delta) {
-			const val = delta[key];
-			if(val === undefined) delete result[key];
-			else if(typeof val === 'object' && val !== null && !Array.isArray(val)) result[key] = applyDelta(result[key], val);
-			else result[key] = val;
-		}
-		return result;
-	}
-
-	for(const d of deltas.flat()) base = applyDelta(base, d?.delta ?? d);
-	return base;
-}
-
-/**
- * Creates a nested delta that reverts `target` back to `old`.
- * @param old - Original object
- * @param updated - Modified object
- * @returns New changes
- */
-export function calcDelta(old: any, updated: any): any {
-	if(updated == null) return null; // full delete
-	const delta: any = {};
-	const isObj = (v: any) => v && typeof v === 'object' && !Array.isArray(v);
-	for (const key of new Set([...(old ? Object.keys(old) : []), ...(updated ? Object.keys(updated) : [])])) {
-		const oldVal = old?.[key];
-		const newVal = updated?.[key];
-		if(isObj(oldVal) && isObj(newVal)) {
-			const nested = calcDelta(oldVal, newVal);
-			if(nested !== null && Object.keys(nested).length > 0) delta[key] = nested;
-		} else if(JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
-			delta[key] = newVal;
-		}
-	}
-	return Object.keys(delta).length === 0 ? {} : delta;
-}
-
-/**
- * Removes any null values from an object in-place
- *
- * @example
- * ```ts
- * let test = {a: 0, b: false, c: null, d: 'abc'}
- * console.log(clean(test)); // Output: {a: 0, b: false, d: 'abc'}
- * ```
- *
- * @param {T} obj Object reference that will be cleaned
- * @param undefinedOnly Ignore null values
- * @returns {Partial<T>} Cleaned object
- */
-export function clean<T>(obj: T, undefinedOnly = false): Partial<T> {
-	if(obj == null) throw new Error("Cannot clean a NULL value");
-	if(Array.isArray(obj)) {
-		obj = <any>obj.filter(o => undefinedOnly ? o !== undefined : o != null);
-	} else {
-		Object.entries(obj).forEach(([key, value]) => {
-			if((undefinedOnly && value === undefined) || (!undefinedOnly && value == null)) delete (<any>obj)[key];
-		});
-	}
-	return <any>obj;
-}
-
-/**
- * Create a deep copy of an object (vs. a shallow copy of references)
- *
- * Should be replaced by `structuredClone` once released.
- * @param {T} value Object to copy
- * @returns {T} Type
- */
-export function deepCopy<T>(value: T): T {
-	if(value == null) return value;
-	const t = typeof value;
-	if(t === 'string' || t === 'number' || t === 'boolean' || t === 'function') return value;
-	try {return structuredClone(value); }
-	catch { return JSON.parse(JSONSanitize(value)); }
-}
-
-/**
- * Merge any number of objects into the target
- *
- * @param target Destination of all properties
- * @param sources Objects that will copied into target
- * @return {any} The des
- */
-export function deepMerge<T>(target: any, ...sources: any[]): T {
-	sources.forEach(s => {
-		for(const key in s) {
-			if(s[key] && typeof s[key] == 'object' && !Array.isArray(s[key])) {
-				if(!target[key]) target[key] = {};
-				deepMerge(target[key], s[key]);
-			} else {
-				target[key] = s[key];
-			}
-		}
-	});
-	return target;
-}
-
-/**
- * Get/set a property of an object using dot notation
- *
- * @example
- * ```ts
- * // Get a value
- * const name = dotNotation<string>(person, 'firstName');
- * const familyCarMake = dotNotation(family, 'cars[0].make');
- * // Set a value
- * dotNotation(family, 'cars[0].make', 'toyota');
- * ```
- *
- * @type T Return type
- * @param {Object} obj source object to search
- * @param {string} prop property name (Dot notation & indexing allowed)
- * @param {any} set  Set object property to value, omit to fetch value instead
- * @return {T} property value
- */
-export function dotNotation<T>(obj: any, prop: string, set: T): T;
-export function dotNotation<T>(obj: any, prop: string): T | undefined;
-export function dotNotation<T>(obj: any, prop: string, set?: T): T | undefined {
-	if(obj == null || !prop) return undefined;
-	// Split property string by '.' or [index]
-	return <T>prop.split(/[.[\]]/g).filter(prop => prop.length).reduce((obj, prop,  i, arr) => {
-		if(prop[0] == '"' || prop[0] == "'") prop = prop.slice(1, -1); // Take quotes out
-		if(!obj?.hasOwnProperty(prop)) {
-			if(set == undefined) return undefined;
-			obj[prop] = {};
-		}
-		if(set !== undefined && i == arr.length - 1)
-			return obj[prop] = set;
-		return obj[prop];
-	}, obj);
-}
-
-/**
- * Convert object into URL encoded query string
- *
- * @example
- * ```js
- * const query = encodeQuery({page: 1, size: 20});
- * console.log(query); // Output: "page=1&size=20"
- * ```
- *
- * @param {any} data - data to convert
- * @returns {string} - Encoded form data
- */
-export function encodeQuery(data: any): string {
-	return Object.entries(data).map(([key, value]) =>
-		encodeURIComponent(key) + '=' + encodeURIComponent(<any>value)
-	).join('&');
-}
-
-/**
- * Recursively flatten a nested object, while maintaining key structure
- *
- * @example
- * ```ts
- * const car = {honda: {model: "Civic"}};
- * console.log(flattenObj(car)); //Output {honda.model: "Civic"}
- * ```
- *
- * @param obj - Object to flatten
- * @param parent - Recursively check if key is a parent key or not
- * @param result - Result
- * @returns {object} - Flattened object
- */
-export function flattenObj(obj: any, parent?: any, result: any = {}) {
-	if(typeof obj === "object" && !Array.isArray(obj)) {
-		for(const key of Object.keys(obj)) {
-			const propName = parent ? `${parent}.${key}` : key;
-			if(typeof obj[key] === 'object' && obj[key] != null && !Array.isArray(obj[key])) {
-				flattenObj(obj[key], propName, result);
-			} else {
-				result[propName] = obj[key];
-			}
-		}
-		return result;
-	}
-}
-
-/**
- * Convert object to FormData
- *
- * @param target - Object to convert
- * @return {FormData} - Form object
- */
-export function formData(target: any): FormData {
-	const data = new FormData();
-	Object.entries(target).forEach(([key, value]) => data.append(key, <any>value));
-	return data;
-}
-
-/**
- * Check that an object has the following values
- *
- * @example
- * ```ts
- * const test = {a: 2, b: 2};
- * includes(test, {a: 1}); // true
- * includes(test, {b: 1, c: 3}); // false
- * ```
- *
- * @param target Object to search
- * @param values Criteria to check against
- * @param allowMissing Only check the keys that are available on the target
- * @returns {boolean} Does target include all the values
- */
-export function includes(target: any, values: any, allowMissing = false): boolean {
-	if(target == undefined) return allowMissing;
-	if(Array.isArray(values)) return values.findIndex((e: any, i: number) => !includes(target[i], values[i], allowMissing)) == -1;
-	const type = typeof values;
-	if(type != typeof target) return false;
-	if(type == 'object') {
-		return Object.keys(values).find(key => !includes(target[key], values[key], allowMissing)) == null;
-	}
-	if(type == 'function') return target.toString() == values.toString();
-	return target == values;
-}
-
-/**
- * Deep check if two items are equal.
- * Handles primitives, objects, arrays, functions, Date, RegExp, and circular references.
- *
- * @param {any} a - first item to compare
- * @param {any} b - second item to compare
- * @param {WeakMap<object, object>} [seen] - Internal parameter to track circular references
- * @returns {boolean} True if they match
- */
-export function isEqual(a: any, b: any, seen = new WeakMap<object, object>()): boolean {
-	// Simple cases
-	if(a === b) return true;
-	if(a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
-	if(a instanceof RegExp && b instanceof RegExp) return a.source === b.source && a.flags === b.flags;
-
-	// Null checks
-	if(typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
-		if(Number.isNaN(a) && Number.isNaN(b)) return true;
-		if(typeof a === 'function' && typeof b === 'function') return a.toString() === b.toString()
-		return false;
-	}
-
-	// Circular references
-	if(seen.has(a)) return seen.get(a) === b;
-	seen.set(a, b);
-	const isArrayA = Array.isArray(a);
-	const isArrayB = Array.isArray(b);
-
-	// Array checks
-	if(isArrayA && isArrayB) {
-		if(a.length !== b.length) return false;
-		for(let i = 0; i < a.length; i++) {
-			if(!isEqual(a[i], b[i], seen)) return false;
-		}
-		return true;
-	}
-	if(isArrayA !== isArrayB) return false;
-
-	// Key & value deep comparison
-	const keysA = Object.keys(a);
-	const keysB = Object.keys(b);
-	if(keysA.length !== keysB.length) return false;
-	for(const key of keysA) {
-		if(!Object.prototype.hasOwnProperty.call(b, key) || !isEqual(a[key], b[key], seen)) return false;
-	}
-	return true;
-}
-
-/**
- * Experimental: Combine multiple object prototypes into one
- *
- * @param target Object that will have prototypes added
- * @param {any[]} constructors Additionally prototypes that should be merged into target
- */
-export function mixin(target: any, constructors: any[]) {
-	constructors.forEach(c => {
-		Object.getOwnPropertyNames(c.prototype).forEach((name) => {
-			Object.defineProperty(
-				target.prototype,
-				name,
-				Object.getOwnPropertyDescriptor(c.prototype, name) ||
-				Object.create(null)
-			);
-		});
-	});
-}
-
-/**
- * Run a map function on each property
- * @param obj Object that will be iterated
- * @param {(key: string, value: any) => any} fn Transformer function - receives key & value
- * @returns {{}}
- */
-export function objectMap<T>(obj: any, fn: (key: string, value: any) => any): T {
-	return <any>Object.entries(obj).map(([key, value]: [string, any]) => [key, fn(key, value)])
-		.reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {});
-}
+import {JSONSanitize} from './json.ts';
+
+export type Delta = { [key: string]: any | Delta | null };
+
+/**
+ * Applies deltas to `target`.
+ * @param base starting point
+ * @param deltas List of deltas to apply
+ * @returns Mutated target
+ */
+export function applyDeltas(base: any, ...deltas: any[]): any {
+	function applyDelta(base: any, delta: any): any {
+		if(delta === null) return null;
+		if(typeof base !== 'object' || base === null) return delta === undefined ? base : delta;
+		const result = Array.isArray(base) ? [...base] : { ...base };
+		for(const key in delta) {
+			const val = delta[key];
+			if(val === undefined) delete result[key];
+			else if(typeof val === 'object' && val !== null && !Array.isArray(val)) result[key] = applyDelta(result[key], val);
+			else result[key] = val;
+		}
+		return result;
+	}
+
+	for(const d of deltas.flat()) base = applyDelta(base, d?.delta ?? d);
+	return base;
+}
+
+/**
+ * Creates a nested delta that reverts `target` back to `old`.
+ * @param old - Original object
+ * @param updated - Modified object
+ * @returns New changes
+ */
+export function calcDelta(old: any, updated: any): any {
+	if(updated == null) return null; // full delete
+	const delta: any = {};
+	const isObj = (v: any) => v && typeof v === 'object' && !Array.isArray(v);
+	for (const key of new Set([...(old ? Object.keys(old) : []), ...(updated ? Object.keys(updated) : [])])) {
+		const oldVal = old?.[key];
+		const newVal = updated?.[key];
+		if(isObj(oldVal) && isObj(newVal)) {
+			const nested = calcDelta(oldVal, newVal);
+			if(nested !== null && Object.keys(nested).length > 0) delta[key] = nested;
+		} else if(JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+			delta[key] = newVal;
+		}
+	}
+	return Object.keys(delta).length === 0 ? {} : delta;
+}
+
+/**
+ * Removes any null values from an object in-place
+ *
+ * @example
+ * ```ts
+ * let test = {a: 0, b: false, c: null, d: 'abc'}
+ * console.log(clean(test)); // Output: {a: 0, b: false, d: 'abc'}
+ * ```
+ *
+ * @param {T} obj Object reference that will be cleaned
+ * @param undefinedOnly Ignore null values
+ * @returns {Partial<T>} Cleaned object
+ */
+export function clean<T>(obj: T, undefinedOnly = false): Partial<T> {
+	if(obj == null) throw new Error("Cannot clean a NULL value");
+	if(Array.isArray(obj)) {
+		obj = <any>obj.filter(o => undefinedOnly ? o !== undefined : o != null);
+	} else {
+		Object.entries(obj).forEach(([key, value]) => {
+			if((undefinedOnly && value === undefined) || (!undefinedOnly && value == null)) delete (<any>obj)[key];
+		});
+	}
+	return <any>obj;
+}
+
+/**
+ * Create a deep copy of an object (vs. a shallow copy of references)
+ *
+ * Should be replaced by `structuredClone` once released.
+ * @param {T} value Object to copy
+ * @returns {T} Type
+ */
+export function deepCopy<T>(value: T): T {
+	if(value == null) return value;
+	const t = typeof value;
+	if(t === 'string' || t === 'number' || t === 'boolean' || t === 'function') return value;
+	try {return structuredClone(value); }
+	catch { return JSON.parse(JSONSanitize(value)); }
+}
+
+/**
+ * Merge any number of objects into the target
+ *
+ * @param target Destination of all properties
+ * @param sources Objects that will copied into target
+ * @return {any} The des
+ */
+export function deepMerge<T>(target: any, ...sources: any[]): T {
+	const BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);
+	sources.forEach(s => {
+		for(const key in s) {
+			if(BLOCKED.has(key) || !Object.prototype.hasOwnProperty.call(s, key)) continue;
+			if(s[key] && typeof s[key] == 'object' && !Array.isArray(s[key])) {
+				if(!target[key]) target[key] = {};
+				deepMerge(target[key], s[key]);
+			} else {
+				target[key] = s[key];
+			}
+		}
+	});
+	return target;
+}
+
+/**
+ * Get/set a property of an object using dot notation
+ *
+ * @example
+ * ```ts
+ * // Get a value
+ * const name = dotNotation<string>(person, 'firstName');
+ * const familyCarMake = dotNotation(family, 'cars[0].make');
+ * // Set a value
+ * dotNotation(family, 'cars[0].make', 'toyota');
+ * ```
+ *
+ * @type T Return type
+ * @param {Object} obj source object to search
+ * @param {string} prop property name (Dot notation & indexing allowed)
+ * @param {any} set  Set object property to value, omit to fetch value instead
+ * @return {T} property value
+ */
+export function dotNotation<T>(obj: any, prop: string, set: T): T;
+export function dotNotation<T>(obj: any, prop: string): T | undefined;
+export function dotNotation<T>(obj: any, prop: string, set?: T): T | undefined {
+	if(obj == null || !prop) return undefined;
+	// Split property string by '.' or [index]
+	return <T>prop.split(/[.[\]]/g).filter(prop => prop.length).reduce((obj, prop,  i, arr) => {
+		if(prop[0] == '"' || prop[0] == "'") prop = prop.slice(1, -1); // Take quotes out
+		if(!obj?.hasOwnProperty(prop)) {
+			if(set == undefined) return undefined;
+			obj[prop] = {};
+		}
+		if(set !== undefined && i == arr.length - 1)
+			return obj[prop] = set;
+		return obj[prop];
+	}, obj);
+}
+
+/**
+ * Convert object into URL encoded query string
+ *
+ * @example
+ * ```js
+ * const query = encodeQuery({page: 1, size: 20});
+ * console.log(query); // Output: "page=1&size=20"
+ * ```
+ *
+ * @param {any} data - data to convert
+ * @returns {string} - Encoded form data
+ */
+export function encodeQuery(data: any): string {
+	return Object.entries(data).map(([key, value]) =>
+		encodeURIComponent(key) + '=' + encodeURIComponent(<any>value)
+	).join('&');
+}
+
+/**
+ * Recursively flatten a nested object, while maintaining key structure
+ *
+ * @example
+ * ```ts
+ * const car = {honda: {model: "Civic"}};
+ * console.log(flattenObj(car)); //Output {honda.model: "Civic"}
+ * ```
+ *
+ * @param obj - Object to flatten
+ * @param parent - Recursively check if key is a parent key or not
+ * @param result - Result
+ * @returns {object} - Flattened object
+ */
+export function flattenObj(obj: any, parent?: any, result: any = {}) {
+	if(typeof obj === "object" && !Array.isArray(obj)) {
+		for(const key of Object.keys(obj)) {
+			const propName = parent ? `${parent}.${key}` : key;
+			if(typeof obj[key] === 'object' && obj[key] != null && !Array.isArray(obj[key])) {
+				flattenObj(obj[key], propName, result);
+			} else {
+				result[propName] = obj[key];
+			}
+		}
+		return result;
+	}
+}
+
+/**
+ * Convert object to FormData
+ *
+ * @param target - Object to convert
+ * @return {FormData} - Form object
+ */
+export function formData(target: any): FormData {
+	const data = new FormData();
+	Object.entries(target).forEach(([key, value]) => data.append(key, <any>value));
+	return data;
+}
+
+/**
+ * Check that an object has the following values
+ *
+ * @example
+ * ```ts
+ * const test = {a: 2, b: 2};
+ * includes(test, {a: 1}); // true
+ * includes(test, {b: 1, c: 3}); // false
+ * ```
+ *
+ * @param target Object to search
+ * @param values Criteria to check against
+ * @param allowMissing Only check the keys that are available on the target
+ * @returns {boolean} Does target include all the values
+ */
+export function includes(target: any, values: any, allowMissing = false): boolean {
+	if(target == undefined) return allowMissing;
+	if(Array.isArray(values)) return values.findIndex((e: any, i: number) => !includes(target[i], values[i], allowMissing)) == -1;
+	const type = typeof values;
+	if(type != typeof target) return false;
+	if(type == 'object') {
+		return Object.keys(values).find(key => !includes(target[key], values[key], allowMissing)) == null;
+	}
+	if(type == 'function') return target.toString() == values.toString();
+	return target == values;
+}
+
+/**
+ * Deep check if two items are equal.
+ * Handles primitives, objects, arrays, functions, Date, RegExp, and circular references.
+ *
+ * @param {any} a - first item to compare
+ * @param {any} b - second item to compare
+ * @param {WeakMap<object, object>} [seen] - Internal parameter to track circular references
+ * @returns {boolean} True if they match
+ */
+export function isEqual(a: any, b: any, seen = new WeakMap<object, object>()): boolean {
+	// Simple cases
+	if(a === b) return true;
+	if(a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if(a instanceof RegExp && b instanceof RegExp) return a.source === b.source && a.flags === b.flags;
+
+	// Null checks
+	if(typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+		if(Number.isNaN(a) && Number.isNaN(b)) return true;
+		if(typeof a === 'function' && typeof b === 'function') return a.toString() === b.toString()
+		return false;
+	}
+
+	// Circular references
+	if(seen.has(a)) return seen.get(a) === b;
+	seen.set(a, b);
+	const isArrayA = Array.isArray(a);
+	const isArrayB = Array.isArray(b);
+
+	// Array checks
+	if(isArrayA && isArrayB) {
+		if(a.length !== b.length) return false;
+		for(let i = 0; i < a.length; i++) {
+			if(!isEqual(a[i], b[i], seen)) return false;
+		}
+		return true;
+	}
+	if(isArrayA !== isArrayB) return false;
+
+	// Key & value deep comparison
+	const keysA = Object.keys(a);
+	const keysB = Object.keys(b);
+	if(keysA.length !== keysB.length) return false;
+	for(const key of keysA) {
+		if(!Object.prototype.hasOwnProperty.call(b, key) || !isEqual(a[key], b[key], seen)) return false;
+	}
+	return true;
+}
+
+/**
+ * Experimental: Combine multiple object prototypes into one
+ *
+ * @param target Object that will have prototypes added
+ * @param {any[]} constructors Additionally prototypes that should be merged into target
+ */
+export function mixin(target: any, constructors: any[]) {
+	constructors.forEach(c => {
+		Object.getOwnPropertyNames(c.prototype).forEach((name) => {
+			Object.defineProperty(
+				target.prototype,
+				name,
+				Object.getOwnPropertyDescriptor(c.prototype, name) ||
+				Object.create(null)
+			);
+		});
+	});
+}
+
+/**
+ * Run a map function on each property
+ * @param obj Object that will be iterated
+ * @param {(key: string, value: any) => any} fn Transformer function - receives key & value
+ * @returns {{}}
+ */
+export function objectMap<T>(obj: any, fn: (key: string, value: any) => any): T {
+	return <any>Object.entries(obj).map(([key, value]: [string, any]) => [key, fn(key, value)])
+		.reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {});
+}

src/string.ts

@@ -27,32 +27,6 @@ export function camelCase(str?: string): string {
 	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
 }
 
-/**
- * Decode HTML escaped characters
- * @param html HTML to clean up
- * @returns {any}
- */
-export function decodeHtml(html: string) {
-	return html
-		.replace(/ /g, '\u00A0')
-		.replace(/"/g, '"')
-		.replace(/'/g, "'")
-		.replace(/&lt;/g, '<')
-		.replace(/&gt;/g, '>')
-		.replace(/&cent;/g, '¢')
-		.replace(/&pound;/g, '£')
-		.replace(/&yen;/g, '¥')
-		.replace(/&euro;/g, '€')
-		.replace(/&copy;/g, '©')
-		.replace(/&reg;/g, '®')
-		.replace(/&trade;/g, '™')
-		.replace(/&times;/g, '×')
-		.replace(/&divide;/g, '÷')
-		.replace(/&#(\d+);/g, (match, dec) => String.fromCharCode(dec))
-		.replace(/&#x([0-9a-fA-F]+);/g, (match, hex) => String.fromCharCode(parseInt(hex, 16)))
-		.replace(/&amp;/g, '&'); // Always last!
-}
-
 /**
  * Convert number of bytes into a human-readable size
  *
@@ -125,7 +99,6 @@ export function kebabCase(str?: string): string {
 	return wordSegments(str).map(w => w.toLowerCase()).join("-");
 }
 
-
 /**
  * Add padding to string
  *
@@ -256,18 +229,14 @@ export function strSplice(str: string, start: number, deleteCount: number, inser
 	return before + insert + after;
 }
 
-function titleCase(str: string) {
-	// Normalize separators: replace underscores and hyphens with spaces
-	let normalizedStr = str.replace(/(_|-)/g, ' ');
-	// Handle CamelCase/PascalCase boundaries: insert a space before capital letters
-	normalizedStr = normalizedStr.replace(/([a-z])([A-Z])/g, '$1 $2');
-	// Lowercase the whole string, split by any whitespace, and capitalize each word
-	let words = normalizedStr.toLowerCase().split(/\s+/).filter(Boolean);
-	const titledWords = words.map(word => {
-		if (word.length === 0) return '';
-		return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
-	});
-	return titledWords.join(' ');
+/**
+ * Converts text to Title Case
+ */
+export function titleCase(str?: string): string {
+	if(!str) return '';
+	return wordSegments(str)
+		.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+		.join(' ');
 }
 
 /**
@@ -280,19 +249,16 @@ function titleCase(str: string) {
  * @return {RegExpExecArray[]} Found matches.
  */
 export function matchAll(value: string, regex: RegExp | string): RegExpExecArray[] {
-	if(typeof regex === 'string') {
-		regex = new RegExp(regex, 'g');
-	}
-
-	// https://stackoverflow.com/a/60290199
-	if(!regex.global) {
-		throw new TypeError('Regular expression must be global.');
-	}
+	if(typeof regex === 'string') regex = new RegExp(regex, 'g');
+	if(!regex.global) throw new TypeError('Regular expression must be global.');
 
 	let ret: RegExpExecArray[] = [];
 	let match: RegExpExecArray | null;
 	while((match = regex.exec(value)) !== null) {
 		ret.push(match);
+		if(match[0].length === 0) {
+			regex.lastIndex++;
+		}
 	}
 
 	return ret;