@hexclave/shared 1.0.0

package/dist/esm/utils/objects.js

@@ -0,0 +1,818 @@
+import { HexclaveAssertionError } from "./errors.js";
+import { stringCompare } from "./strings.js";
+import { identity } from "./functions.js";
+import { typeAssertIs } from "./types.js";
+
+//#region src/utils/objects.tsx
+function isNotNull(value) {
+	return value !== null && value !== void 0;
+}
+(void 0)?.test("isNotNull", ({ expect }) => {
+	expect(isNotNull(null)).toBe(false);
+	expect(isNotNull(void 0)).toBe(false);
+	expect(isNotNull(0)).toBe(true);
+	expect(isNotNull("")).toBe(true);
+	expect(isNotNull(false)).toBe(true);
+	expect(isNotNull({})).toBe(true);
+	expect(isNotNull([])).toBe(true);
+});
+/**
+* Assumes both objects are primitives, arrays, or non-function plain objects, and compares them deeply.
+*
+* Note that since they are assumed to be plain objects, this function does not compare prototypes.
+*/
+function deepPlainEquals(obj1, obj2, options = {}) {
+	if (typeof obj1 !== typeof obj2) return false;
+	if (obj1 === obj2) return true;
+	switch (typeof obj1) {
+		case "object": {
+			if (!obj1 || !obj2) return false;
+			if (Array.isArray(obj1) || Array.isArray(obj2)) {
+				if (!Array.isArray(obj1) || !Array.isArray(obj2)) return false;
+				if (obj1.length !== obj2.length) return false;
+				return obj1.every((v, i) => deepPlainEquals(v, obj2[i], options));
+			}
+			const entries1 = Object.entries(obj1).filter(([k, v]) => !options.ignoreUndefinedValues || v !== void 0);
+			const entries2 = Object.entries(obj2).filter(([k, v]) => !options.ignoreUndefinedValues || v !== void 0);
+			if (entries1.length !== entries2.length) return false;
+			return entries1.every(([k, v1]) => {
+				const e2 = entries2.find(([k2]) => k === k2);
+				if (!e2) return false;
+				return deepPlainEquals(v1, e2[1], options);
+			});
+		}
+		case "undefined":
+		case "string":
+		case "number":
+		case "boolean":
+		case "bigint":
+		case "symbol":
+		case "function": return false;
+		default: throw new Error("Unexpected typeof " + typeof obj1);
+	}
+}
+(void 0)?.test("deepPlainEquals", ({ expect }) => {
+	expect(deepPlainEquals(1, 1)).toBe(true);
+	expect(deepPlainEquals("test", "test")).toBe(true);
+	expect(deepPlainEquals(1, 2)).toBe(false);
+	expect(deepPlainEquals("test", "other")).toBe(false);
+	expect(deepPlainEquals([
+		1,
+		2,
+		3
+	], [
+		1,
+		2,
+		3
+	])).toBe(true);
+	expect(deepPlainEquals([
+		1,
+		2,
+		3
+	], [
+		1,
+		2,
+		4
+	])).toBe(false);
+	expect(deepPlainEquals([
+		1,
+		2,
+		3
+	], [1, 2])).toBe(false);
+	expect(deepPlainEquals({
+		a: 1,
+		b: 2
+	}, {
+		a: 1,
+		b: 2
+	})).toBe(true);
+	expect(deepPlainEquals({
+		a: 1,
+		b: 2
+	}, {
+		a: 1,
+		b: 3
+	})).toBe(false);
+	expect(deepPlainEquals({
+		a: 1,
+		b: 2
+	}, { a: 1 })).toBe(false);
+	expect(deepPlainEquals({
+		a: 1,
+		b: [
+			1,
+			2,
+			{ c: 3 }
+		]
+	}, {
+		a: 1,
+		b: [
+			1,
+			2,
+			{ c: 3 }
+		]
+	})).toBe(true);
+	expect(deepPlainEquals({
+		a: 1,
+		b: [
+			1,
+			2,
+			{ c: 3 }
+		]
+	}, {
+		a: 1,
+		b: [
+			1,
+			2,
+			{ c: 4 }
+		]
+	})).toBe(false);
+	expect(deepPlainEquals({
+		a: 1,
+		b: void 0
+	}, { a: 1 }, { ignoreUndefinedValues: true })).toBe(true);
+	expect(deepPlainEquals({
+		a: 1,
+		b: void 0
+	}, { a: 1 })).toBe(false);
+});
+function isCloneable(obj) {
+	return typeof obj !== "symbol" && typeof obj !== "function";
+}
+function shallowClone(obj) {
+	if (!isCloneable(obj)) throw new HexclaveAssertionError("shallowClone does not support symbols or functions", { obj });
+	if (Array.isArray(obj)) return obj.map(identity);
+	return { ...obj };
+}
+(void 0)?.test("shallowClone", ({ expect }) => {
+	expect(shallowClone({
+		a: 1,
+		b: 2
+	})).toEqual({
+		a: 1,
+		b: 2
+	});
+	expect(shallowClone([
+		1,
+		2,
+		3
+	])).toEqual([
+		1,
+		2,
+		3
+	]);
+	expect(() => shallowClone(() => {})).toThrow();
+});
+function deepPlainClone(obj) {
+	if (typeof obj === "function") throw new HexclaveAssertionError("deepPlainClone does not support functions");
+	if (typeof obj === "symbol") throw new HexclaveAssertionError("deepPlainClone does not support symbols");
+	if (typeof obj !== "object" || !obj) return obj;
+	if (Array.isArray(obj)) return obj.map(deepPlainClone);
+	return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, deepPlainClone(v)]));
+}
+(void 0)?.test("deepPlainClone", ({ expect }) => {
+	expect(deepPlainClone(1)).toBe(1);
+	expect(deepPlainClone("test")).toBe("test");
+	expect(deepPlainClone(null)).toBe(null);
+	expect(deepPlainClone(void 0)).toBe(void 0);
+	const arr = [
+		1,
+		2,
+		3
+	];
+	const clonedArr = deepPlainClone(arr);
+	expect(clonedArr).toEqual(arr);
+	expect(clonedArr).not.toBe(arr);
+	const obj = {
+		a: 1,
+		b: 2
+	};
+	const clonedObj = deepPlainClone(obj);
+	expect(clonedObj).toEqual(obj);
+	expect(clonedObj).not.toBe(obj);
+	const nested = {
+		a: 1,
+		b: [
+			1,
+			2,
+			{ c: 3 }
+		]
+	};
+	const clonedNested = deepPlainClone(nested);
+	expect(clonedNested).toEqual(nested);
+	expect(clonedNested).not.toBe(nested);
+	expect(clonedNested.b).not.toBe(nested.b);
+	expect(clonedNested.b[2]).not.toBe(nested.b[2]);
+	expect(() => deepPlainClone(() => {})).toThrow();
+	expect(() => deepPlainClone(Symbol())).toThrow();
+});
+function deepMerge(baseObj, mergeObj) {
+	if ([
+		baseObj,
+		mergeObj,
+		...Object.values(baseObj),
+		...Object.values(mergeObj)
+	].some((o) => !isCloneable(o))) throw new HexclaveAssertionError("deepMerge does not support functions or symbols", {
+		baseObj,
+		mergeObj
+	});
+	const res = shallowClone(baseObj);
+	for (const [key, mergeValue] of Object.entries(mergeObj)) {
+		if (has(res, key)) {
+			const baseValue = get(res, key);
+			if (isObjectLike(baseValue) && isObjectLike(mergeValue)) {
+				set(res, key, deepMerge(baseValue, mergeValue));
+				continue;
+			}
+		}
+		set(res, key, mergeValue);
+	}
+	return res;
+}
+(void 0)?.test("deepMerge", ({ expect }) => {
+	expect(deepMerge({ a: 1 }, { b: 2 })).toEqual({
+		a: 1,
+		b: 2
+	});
+	expect(deepMerge({ a: 1 }, { a: 2 })).toEqual({ a: 2 });
+	expect(deepMerge({
+		a: 1,
+		b: 2
+	}, {
+		b: 3,
+		c: 4
+	})).toEqual({
+		a: 1,
+		b: 3,
+		c: 4
+	});
+	expect(deepMerge({
+		a: {
+			x: 1,
+			y: 2
+		},
+		b: 3
+	}, {
+		a: {
+			y: 3,
+			z: 4
+		},
+		c: 5
+	})).toEqual({
+		a: {
+			x: 1,
+			y: 3,
+			z: 4
+		},
+		b: 3,
+		c: 5
+	});
+	expect(deepMerge({
+		a: [1, 2],
+		b: 3
+	}, {
+		a: [3, 4],
+		c: 5
+	})).toEqual({
+		a: [3, 4],
+		b: 3,
+		c: 5
+	});
+	expect(deepMerge({
+		a: { x: 1 },
+		b: null
+	}, {
+		a: { y: 2 },
+		b: { z: 3 }
+	})).toEqual({
+		a: {
+			x: 1,
+			y: 2
+		},
+		b: { z: 3 }
+	});
+	expect(deepMerge({
+		a: 1,
+		b: void 0
+	}, {
+		b: 2,
+		c: 3
+	})).toEqual({
+		a: 1,
+		b: 2,
+		c: 3
+	});
+	expect(deepMerge({
+		a: {
+			x: { deep: 1 },
+			y: [1, 2]
+		},
+		b: 2
+	}, {
+		a: {
+			x: { deeper: 3 },
+			y: [3, 4]
+		},
+		c: 3
+	})).toEqual({
+		a: {
+			x: {
+				deep: 1,
+				deeper: 3
+			},
+			y: [3, 4]
+		},
+		b: 2,
+		c: 3
+	});
+	expect(deepMerge({}, { a: 1 })).toEqual({ a: 1 });
+	expect(deepMerge({ a: 1 }, {})).toEqual({ a: 1 });
+	expect(deepMerge({}, {})).toEqual({});
+	const base = {
+		a: { x: 1 },
+		b: 2
+	};
+	const merge = {
+		a: { y: 2 },
+		c: 3
+	};
+	const baseClone = deepPlainClone(base);
+	const mergeClone = deepPlainClone(merge);
+	const result = deepMerge(base, merge);
+	expect(base).toEqual(baseClone);
+	expect(merge).toEqual(mergeClone);
+	expect(result).toEqual({
+		a: {
+			x: 1,
+			y: 2
+		},
+		b: 2,
+		c: 3
+	});
+	expect(() => deepMerge({ a: () => {} }, { b: 2 })).toThrow();
+	expect(() => deepMerge({ a: 1 }, { b: () => {} })).toThrow();
+	expect(() => deepMerge({ a: Symbol() }, { b: 2 })).toThrow();
+	expect(() => deepMerge({ a: 1 }, { b: Symbol() })).toThrow();
+});
+function typedEntries(obj) {
+	return Object.entries(obj);
+}
+(void 0)?.test("typedEntries", ({ expect }) => {
+	expect(typedEntries({})).toEqual([]);
+	expect(typedEntries({
+		a: 1,
+		b: 2
+	})).toEqual([["a", 1], ["b", 2]]);
+	expect(typedEntries({
+		a: "hello",
+		b: true,
+		c: null
+	})).toEqual([
+		["a", "hello"],
+		["b", true],
+		["c", null]
+	]);
+	const entries = typedEntries({
+		a: 1,
+		b: () => "test"
+	});
+	expect(entries.length).toBe(2);
+	expect(entries[0][0]).toBe("a");
+	expect(entries[0][1]).toBe(1);
+	expect(entries[1][0]).toBe("b");
+	expect(typeof entries[1][1]).toBe("function");
+});
+function typedFromEntries(entries) {
+	return Object.fromEntries(entries);
+}
+(void 0)?.test("typedFromEntries", ({ expect }) => {
+	expect(typedFromEntries([])).toEqual({});
+	expect(typedFromEntries([["a", 1], ["b", 2]])).toEqual({
+		a: 1,
+		b: 2
+	});
+	expect(typedFromEntries([
+		["a", "hello"],
+		["b", true],
+		["c", null]
+	])).toEqual({
+		a: "hello",
+		b: true,
+		c: null
+	});
+	const fn = () => "test";
+	const obj = typedFromEntries([["a", 1], ["b", fn]]);
+	expect(obj.a).toBe(1);
+	expect(typeof obj.b).toBe("function");
+	expect(obj.b()).toBe("test");
+});
+function typedKeys(obj) {
+	return Object.keys(obj);
+}
+(void 0)?.test("typedKeys", ({ expect }) => {
+	expect(typedKeys({})).toEqual([]);
+	expect(typedKeys({
+		a: 1,
+		b: 2
+	})).toEqual(["a", "b"]);
+	expect(typedKeys({
+		a: "hello",
+		b: true,
+		c: null
+	})).toEqual([
+		"a",
+		"b",
+		"c"
+	]);
+	expect(typedKeys({
+		a: 1,
+		b: () => "test"
+	})).toEqual(["a", "b"]);
+});
+function typedValues(obj) {
+	return Object.values(obj);
+}
+(void 0)?.test("typedValues", ({ expect }) => {
+	expect(typedValues({})).toEqual([]);
+	expect(typedValues({
+		a: 1,
+		b: 2
+	})).toEqual([1, 2]);
+	expect(typedValues({
+		a: "hello",
+		b: true,
+		c: null
+	})).toEqual([
+		"hello",
+		true,
+		null
+	]);
+	const fn = () => "test";
+	const values = typedValues({
+		a: 1,
+		b: fn
+	});
+	expect(values.length).toBe(2);
+	expect(values[0]).toBe(1);
+	expect(typeof values[1]).toBe("function");
+	const fnValue = values[1];
+	expect(fnValue()).toBe("test");
+});
+function typedAssign(target, source) {
+	return Object.assign(target, source);
+}
+(void 0)?.test("typedAssign", ({ expect }) => {
+	const emptyTarget = {};
+	const emptyResult = typedAssign(emptyTarget, { a: 1 });
+	expect(emptyResult).toEqual({ a: 1 });
+	expect(emptyResult).toBe(emptyTarget);
+	const target = {
+		a: 1,
+		b: 2
+	};
+	const result = typedAssign(target, {
+		c: 3,
+		d: 4
+	});
+	expect(result).toEqual({
+		a: 1,
+		b: 2,
+		c: 3,
+		d: 4
+	});
+	expect(result).toBe(target);
+	const targetWithOverlap = {
+		a: 1,
+		b: 2
+	};
+	const resultWithOverlap = typedAssign(targetWithOverlap, {
+		b: 3,
+		c: 4
+	});
+	expect(resultWithOverlap).toEqual({
+		a: 1,
+		b: 3,
+		c: 4
+	});
+	expect(resultWithOverlap).toBe(targetWithOverlap);
+});
+/**
+* Returns a new object with all undefined values removed. Useful when spreading optional parameters on an object, as
+* TypeScript's `Partial<XYZ>` type allows `undefined` values.
+*/
+function filterUndefined(obj) {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+}
+(void 0)?.test("filterUndefined", ({ expect }) => {
+	expect(filterUndefined({})).toEqual({});
+	expect(filterUndefined({
+		a: 1,
+		b: 2
+	})).toEqual({
+		a: 1,
+		b: 2
+	});
+	expect(filterUndefined({
+		a: 1,
+		b: void 0
+	})).toEqual({ a: 1 });
+	expect(filterUndefined({
+		a: void 0,
+		b: void 0
+	})).toEqual({});
+	expect(filterUndefined({
+		a: null,
+		b: void 0
+	})).toEqual({ a: null });
+	expect(filterUndefined({
+		a: 0,
+		b: "",
+		c: false,
+		d: void 0
+	})).toEqual({
+		a: 0,
+		b: "",
+		c: false
+	});
+});
+/**
+* Returns a new object with all undefined and null values removed. Useful when spreading optional parameters on an object, as
+* TypeScript's `Partial<XYZ>` type allows `undefined` values.
+*/
+function filterUndefinedOrNull(obj) {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0 && v !== null));
+}
+(void 0)?.test("filterUndefinedOrNull", ({ expect }) => {
+	expect(filterUndefinedOrNull({})).toEqual({});
+	expect(filterUndefinedOrNull({
+		a: 1,
+		b: 2
+	})).toEqual({
+		a: 1,
+		b: 2
+	});
+});
+typeAssertIs()();
+function deepFilterUndefined(obj) {
+	return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0).map(([k, v]) => [k, isObjectLike(v) ? deepFilterUndefined(v) : v]));
+}
+(void 0)?.test("deepFilterUndefined", ({ expect }) => {
+	expect(deepFilterUndefined({
+		a: 1,
+		b: void 0
+	})).toEqual({ a: 1 });
+});
+function pick(obj, keys) {
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k)));
+}
+(void 0)?.test("pick", ({ expect }) => {
+	const obj = {
+		a: 1,
+		b: 2,
+		c: 3,
+		d: 4
+	};
+	expect(pick(obj, ["a", "c"])).toEqual({
+		a: 1,
+		c: 3
+	});
+	expect(pick(obj, [])).toEqual({});
+	expect(pick(obj, ["a", "e"])).toEqual({ a: 1 });
+	expect(pick({}, ["a"])).toEqual({});
+});
+function omit(obj, keys) {
+	if (!Array.isArray(keys)) throw new HexclaveAssertionError("omit: keys must be an array", {
+		obj,
+		keys
+	});
+	return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k)));
+}
+(void 0)?.test("omit", ({ expect }) => {
+	const obj = {
+		a: 1,
+		b: 2,
+		c: 3,
+		d: 4
+	};
+	expect(omit(obj, ["a", "c"])).toEqual({
+		b: 2,
+		d: 4
+	});
+	expect(omit(obj, [])).toEqual(obj);
+	expect(omit(obj, ["a", "e"])).toEqual({
+		b: 2,
+		c: 3,
+		d: 4
+	});
+	expect(omit({}, ["a"])).toEqual({});
+});
+function split(obj, keys) {
+	return [pick(obj, keys), omit(obj, keys)];
+}
+(void 0)?.test("split", ({ expect }) => {
+	const obj = {
+		a: 1,
+		b: 2,
+		c: 3,
+		d: 4
+	};
+	expect(split(obj, ["a", "c"])).toEqual([{
+		a: 1,
+		c: 3
+	}, {
+		b: 2,
+		d: 4
+	}]);
+	expect(split(obj, [])).toEqual([{}, obj]);
+	expect(split(obj, ["a", "e"])).toEqual([{ a: 1 }, {
+		b: 2,
+		c: 3,
+		d: 4
+	}]);
+	expect(split({}, ["a"])).toEqual([{}, {}]);
+});
+function mapValues(obj, fn) {
+	if (Array.isArray(obj)) return obj.map((v, i) => fn(v, i));
+	return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, fn(v, k)]));
+}
+(void 0)?.test("mapValues", ({ expect }) => {
+	expect(mapValues({
+		a: 1,
+		b: 2
+	}, (v) => v * 2)).toEqual({
+		a: 2,
+		b: 4
+	});
+	expect(mapValues([
+		1,
+		2,
+		3
+	], (v) => v * 2)).toEqual([
+		2,
+		4,
+		6
+	]);
+});
+function sortKeys(obj) {
+	if (Array.isArray(obj)) return [...obj];
+	return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => stringCompare(a, b)));
+}
+(void 0)?.test("sortKeys", ({ expect }) => {
+	expect(Object.entries(sortKeys({
+		"1": 0,
+		"10": 1,
+		b: 2,
+		"2": 3,
+		a: 4,
+		"-3.33": 5,
+		"-4": 6,
+		"-3": 7,
+		abc: 8,
+		"a-b": 9,
+		ab: 10,
+		ac: 11,
+		aa: 12,
+		aab: 13
+	}))).toEqual([
+		["1", 0],
+		["2", 3],
+		["10", 1],
+		["-3", 7],
+		["-3.33", 5],
+		["-4", 6],
+		["a", 4],
+		["a-b", 9],
+		["aa", 12],
+		["aab", 13],
+		["ab", 10],
+		["abc", 8],
+		["ac", 11],
+		["b", 2]
+	]);
+});
+function deepSortKeys(obj) {
+	return sortKeys(mapValues(obj, (v) => isObjectLike(v) ? deepSortKeys(v) : v));
+}
+(void 0)?.test("deepSortKeys", ({ expect }) => {
+	const sorted = deepSortKeys({
+		h: {
+			i: {
+				k: 9,
+				j: 8
+			},
+			l: 10
+		},
+		b: {
+			d: 3,
+			c: 2
+		},
+		a: 1,
+		e: [
+			4,
+			5,
+			{
+				g: 7,
+				f: 6
+			}
+		]
+	});
+	expect(Object.entries(sorted)).toEqual([
+		["a", 1],
+		["b", {
+			c: 2,
+			d: 3
+		}],
+		["e", [
+			4,
+			5,
+			{
+				f: 6,
+				g: 7
+			}
+		]],
+		["h", {
+			i: {
+				j: 8,
+				k: 9
+			},
+			l: 10
+		}]
+	]);
+	expect(Object.entries(sorted.b)).toEqual([["c", 2], ["d", 3]]);
+	expect(Object.entries(sorted.e[2])).toEqual([["f", 6], ["g", 7]]);
+	expect(Object.entries(sorted.h)).toEqual([["i", {
+		j: 8,
+		k: 9
+	}], ["l", 10]]);
+	expect(Object.entries(sorted.h.i)).toEqual([["j", 8], ["k", 9]]);
+});
+function set(obj, key, value) {
+	if (!isObjectLike(obj)) throw new HexclaveAssertionError(`set: obj is not an object (found: ${obj === null ? "null" : typeof obj})`, {
+		obj,
+		key,
+		value
+	});
+	Object.defineProperty(obj, key, {
+		value,
+		writable: true,
+		configurable: true,
+		enumerable: true
+	});
+}
+function get(obj, key) {
+	if (obj == null) throw new HexclaveAssertionError("get: obj is null or undefined", {
+		obj,
+		key
+	});
+	const descriptor = Object.getOwnPropertyDescriptor(obj, key);
+	if (!descriptor) throw new HexclaveAssertionError(`get: key ${String(key)} does not exist`, {
+		obj,
+		key
+	});
+	return descriptor.value;
+}
+function getOrUndefined(obj, key) {
+	if (obj == null) throw new HexclaveAssertionError("getOrUndefined: obj is null or undefined", {
+		obj,
+		key
+	});
+	return has(obj, key) ? get(obj, key) : void 0;
+}
+function has(obj, key) {
+	if (obj == null) throw new HexclaveAssertionError("has: obj is null or undefined", {
+		obj,
+		key
+	});
+	return Object.prototype.hasOwnProperty.call(obj, key);
+}
+(void 0)?.test("has", ({ expect }) => {
+	const obj = {
+		a: 1,
+		b: void 0,
+		c: null
+	};
+	expect(has(obj, "a")).toBe(true);
+	expect(has(obj, "b")).toBe(true);
+	expect(has(obj, "c")).toBe(true);
+	expect(has(obj, "d")).toBe(false);
+});
+function hasAndNotUndefined(obj, key) {
+	return has(obj, key) && get(obj, key) !== void 0;
+}
+function deleteKey(obj, key) {
+	if (has(obj, key)) Reflect.deleteProperty(obj, key);
+	else throw new HexclaveAssertionError(`deleteKey: key ${String(key)} does not exist`, {
+		obj,
+		key
+	});
+}
+/**
+* Returns true iff the value is an object or a function, but not null.
+*/
+function isObjectLike(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null;
+}
+
+//#endregion
+export { deepFilterUndefined, deepMerge, deepPlainClone, deepPlainEquals, deepSortKeys, deleteKey, filterUndefined, filterUndefinedOrNull, get, getOrUndefined, has, hasAndNotUndefined, isCloneable, isNotNull, isObjectLike, mapValues, omit, pick, set, shallowClone, sortKeys, split, typedAssign, typedEntries, typedFromEntries, typedKeys, typedValues };
+//# sourceMappingURL=objects.js.map