@ocavue/utils 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -18,10 +18,10 @@ declare function isSet(value: unknown): value is Set<unknown>;
  *
  * Similar to Python's [defaultdict](https://docs.python.org/3.13/library/collections.html#collections.defaultdict).
  */
-declare class DefaultMap<K, V> extends Map<K, V> {
+declare class DefaultMap<K$1, V> extends Map<K$1, V> {
   private readonly defaultFactory;
-  constructor(defaultFactory: () => V, iterable?: Iterable<readonly [K, V]>);
-  get(key: K): V;
+  constructor(defaultFactory: () => V, iterable?: Iterable<readonly [K$1, V]>);
+  get(key: K$1): V;
 }
 //#endregion
 //#region src/dom.d.ts
@@ -98,6 +98,119 @@ declare function formatBytes(bytes: number): string;
  */
 declare function getId(): number;
 //#endregion
+//#region src/is-deep-equal.d.ts
+/**
+ * Whether two values are deeply equal.
+ */
+declare function isDeepEqual(a: unknown, b: unknown): boolean;
+//#endregion
+//#region src/map-group-by.d.ts
+/**
+ * A polyfill for the `Map.groupBy` static method.
+ *
+ * @public
+ */
+declare const mapGroupBy: <K$1, T>(items: Iterable<T>, keySelector: (item: T, index: number) => K$1) => Map<K$1, T[]>;
+//#endregion
+//#region src/map-values.d.ts
+/**
+ * Creates a new object with the same keys as the input object, but with values
+ * transformed by the provided callback function. Similar to `Array.prototype.map()`
+ * but for object values.
+
+ * @param object - The object whose values will be transformed.
+ * @param callback - A function that transforms each value. Receives the value and
+ *   its corresponding key as arguments.
+ * @returns A new object with the same keys but transformed values.
+ *
+ * @example
+ * ```typescript
+ * const prices = { apple: 1, banana: 2, orange: 3 }
+ * const doubled = mapValues(prices, (price) => price * 2)
+ * // Result: { apple: 2, banana: 4, orange: 6 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const users = { john: 25, jane: 30, bob: 35 }
+ * const greetings = mapValues(users, (age, name) => `${name} is ${age} years old`)
+ * // Result: { john: 'john is 25 years old', jane: 'jane is 30 years old', bob: 'bob is 35 years old' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const data = { a: '1', b: '2', c: '3' }
+ * const numbers = mapValues(data, (str) => parseInt(str, 10))
+ * // Result: { a: 1, b: 2, c: 3 }
+ * ```
+ *
+ * @public
+ */
+declare function mapValues<ValueIn, ValueOut>(object: Record<string, ValueIn>, callback: (value: ValueIn, key: string) => ValueOut): Record<string, ValueOut>;
+//#endregion
+//#region src/object-entries.d.ts
+/**
+ * A TypeScript utility type that represents the entries of an object as a union of tuple types.
+ * Each tuple contains a key-value pair where the key and value types are precisely typed
+ * according to the input object type.
+ *
+ * @example
+ * ```typescript
+ * type MyObject = { a: 1; b: 'B' }
+ * type MyEntries = ObjectEntries<MyObject>
+ * //   ^ ["a", 1] | ["b", "B"]
+ * ```
+ *
+ * @public
+ */
+type ObjectEntries<T extends Record<string, any>> = { [K in keyof T]: [K, T[K]] }[keyof T];
+/**
+ * A type-safe wrapper around `Object.entries()` that preserves the exact types of object keys
+ * and values. Unlike the standard `Object.entries()` which returns `[string, any][]`, this
+ * function returns an array of tuples where each tuple is precisely typed according to the
+ * input object's structure.
+ *
+ * This is particularly useful when working with objects that have known, fixed property types
+ * and you want to maintain type safety when iterating over entries.
+ *
+ * @example
+ * ```typescript
+ * const myObject = { a: 1, b: 'hello', c: true } as const
+ * const entries = objectEntries(myObject)
+ * // Type: (["a", 1] | ["b", "hello"] | ["c", true])[]
+ *
+ * for (const [key, value] of entries) {
+ *   // key is typed as "a" | "b" | "c"
+ *   // value is typed as 1 | "hello" | true
+ *   console.log(`${key}: ${value}`)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string
+ *   age: number
+ *   active: boolean
+ * }
+ *
+ * const user: User = { name: 'Alice', age: 30, active: true }
+ * const entries = objectEntries(user)
+ * // Type: (["name", string] | ["age", number] | ["active", boolean])[]
+ * ```
+ *
+ * @public
+ */
+declare const objectEntries: <T extends Record<string, any>>(obj: T) => ObjectEntries<T>[];
+//#endregion
+//#region src/object-group-by.d.ts
+/**
+ * A polyfill for the `Object.groupBy` static method.
+ *
+ * @public
+ */
+declare const objectGroupBy: <K$1 extends PropertyKey, T>(items: Iterable<T>, keySelector: (item: T, index: number) => K$1) => Partial<Record<K$1, T[]>>;
+//#endregion
 //#region src/once.d.ts
 /**
  * Creates a function that will only execute the provided function once.
@@ -120,11 +233,5 @@ declare function once<T>(fn: () => T): () => T;
  */
 declare function sleep(ms: number): Promise<void>;
 //#endregion
-//#region src/is-deep-equal.d.ts
-/**
- * Whether two values are deeply equal.
- */
-declare function isDeepEqual(a: unknown, b: unknown): boolean;
-//#endregion
-export { DefaultMap, formatBytes, getDocument, getDocumentElement, getId, getWindow, isDeepEqual, isDocument, isDocumentFragment, isElement, isElementLike, isHTMLElement, isMap, isMathMLElement, isNodeLike, isObject, isSVGElement, isSet, isShadowRoot, isTextNode, isWindowLike, once, sleep };
+export { DefaultMap, type ObjectEntries, formatBytes, getDocument, getDocumentElement, getId, getWindow, isDeepEqual, isDocument, isDocumentFragment, isElement, isElementLike, isHTMLElement, isMap, isMathMLElement, isNodeLike, isObject, isSVGElement, isSet, isShadowRoot, isTextNode, isWindowLike, mapGroupBy, mapValues, objectEntries, objectGroupBy, once, sleep };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/checker.ts","../src/default-map.ts","../src/dom.ts","../src/format-bytes.ts","../src/get-id.ts","../src/once.ts","../src/sleep.ts","../src/is-deep-equal.ts"],"sourcesContent":[],"mappings":";;AAGA;AASA;AAOgB,iBAhBA,QAAA,CAgBmC,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IAdvC,MAcuC,CAAA,MAAA,GAAA,MAAA,GAAA,MAAA,EAAA,OAAA,CAAA;;;;ACdtC,iBDOG,KAAA,CCPO,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IDOyB,GCPzB,CAAA,OAAA,EAAA,OAAA,CAAA;;;;AAG8C,iBDWrD,KAAA,CCXqD,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IDWrB,GCXqB,CAAA,OAAA,CAAA;;;;ADLrE;AASA;AAOA;;cCda,yBAAyB,IAAI,GAAG;;EAAhC,WAAA,CAAA,cAAU,EAAA,GAAA,GAGa,CAHb,EAAA,QAAA,CAAA,EAG2B,QAH3B,CAAA,SAAA,CAG8C,CAH9C,EAGiD,CAHjD,CAAA,CAAA;EAAmB,GAAA,CAAA,GAAA,EAQtB,CARsB,CAAA,EAQlB,CARkB;;;;;ADF1C;AASA;AAOgB,iBEbA,SAAA,CFamC,IAAA,EEbnB,IFamB,CAAA,EAAA,IAAA,IEbJ,OFaI;;;;ACdtC,iBCQG,UAAA,CDRO,IAAA,ECQU,IDRV,CAAA,EAAA,IAAA,ICQyB,IDRzB;;;;AAG8C,iBCYrD,aAAA,CDZqD,IAAA,ECYjC,IDZiC,CAAA,EAAA,IAAA,ICYlB,WDZkB;;;;AAK7C,iBCcR,YAAA,CDdQ,IAAA,ECcW,IDdX,CAAA,EAAA,IAAA,ICc0B,UDd1B;;;;iBCqBR,eAAA,OAAsB,eAAe;;AA5BrD;AAOA;AAOgB,iBAwBA,UAAA,CAxBoB,IAAe,EAwBlB,IAxBkB,CAAA,EAAA,IAAW,IAwBd,QAxBc;AAO9D;AAOA;AAUA;AAOgB,iBAAA,kBAAA,CAAwC,IAAA,EAAf,IAAe,CAAA,EAAA,IAAgB,IAAhB,gBAAgB;AAOxE;AAOA;AAOA;AAWgB,iBAzBA,YAAA,CAyBuC,IAAM,EAzB1B,IAyB0B,CAAA,EAAA,IAAA,IAzBX,UAyBW;AAQ7D;;;AAC+B,iBA3Bf,UAAA,CA2Be,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IA3BsB,IA2BtB;;;;AAoBf,iBAxCA,aAAA,CAwCW,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IAxC6B,OAwC7B;;;;AACU,iBA9BrB,YAAA,CA8BqB,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IA9BkB,MA8BlB;;;AAiBrC;;AACqB,iBAxCL,SAAA,CAwCK,MAAA,CAAA,EAvCV,IAuCU,GAvCH,UAuCG,GAvCU,QAuCV,GAAA,IAAA,CAAA,EAtClB,MAsCkB,GAAA,OAtCF,UAsCE;;;;;iBAnBL,WAAA,UACL,UAAU,SAAS,OAAO,kBAClC;;;AC7GH;iBD6HgB,kBAAA,UACL,UAAU,OAAO,SAAS,kBAClC;;;;AFjIH;AASA;AAOA;;iBGdgB,WAAA;;;;AHFhB;AASA;AAOgB,iBIdA,KAAA,CAAA,CJcmC,EAAA,MAAA;;;;AAhBnD;AASA;AAOA;;;;ACdA;;;;;;AAGkD,iBIKlC,IJLkC,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,GAAA,GIKhB,CJLgB,CAAA,EAAA,GAAA,GIKN,CJLM;;;;ADLlD;AASA;AAOgB,iBMhBA,KAAA,CNgBmC,EAAA,EAAA,MAAA,CAAA,EMhBhB,ONgBgB,CAAA,IAAA,CAAA;;;;AAhBnD;AASA;AAOgB,iBOdA,WAAA,CPcmC,CAAA,EAAA,OAAA,EAAA,CAAA,EAAA,OAAA,CAAA,EAAA,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/checker.ts","../src/default-map.ts","../src/dom.ts","../src/format-bytes.ts","../src/get-id.ts","../src/is-deep-equal.ts","../src/map-group-by.ts","../src/map-values.ts","../src/object-entries.ts","../src/object-group-by.ts","../src/once.ts","../src/sleep.ts"],"sourcesContent":[],"mappings":";;AAGA;AASA;AAOgB,iBAhBA,QAAA,CAgBmC,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IAdvC,MAcuC,CAAA,MAAA,GAAA,MAAA,GAAA,MAAA,EAAA,OAAA,CAAA;;;;ACdtC,iBDOG,KAAA,CCPO,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IDOyB,GCPzB,CAAA,OAAA,EAAA,OAAA,CAAA;;;;AAG8C,iBDWrD,KAAA,CCXqD,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IDWrB,GCXqB,CAAA,OAAA,CAAA;;;;ADLrE;AASA;AAOA;;cCda,2BAAyB,IAAI,KAAG;;EAAhC,WAAA,CAAA,cAAU,EAAA,GAAA,GAGa,CAHb,EAAA,QAAA,CAAA,EAG2B,QAH3B,CAAA,SAAA,CAG8C,GAH9C,EAGiD,CAHjD,CAAA,CAAA;EAAmB,GAAA,CAAA,GAAA,EAQtB,GARsB,CAAA,EAQlB,CARkB;;;;;ADF1C;AASA;AAOgB,iBEbA,SAAA,CFamC,IAAA,EEbnB,IFamB,CAAA,EAAA,IAAA,IEbJ,OFaI;;;;ACdtC,iBCQG,UAAA,CDRO,IAAA,ECQU,IDRV,CAAA,EAAA,IAAA,ICQyB,IDRzB;;;;AAG8C,iBCYrD,aAAA,CDZqD,IAAA,ECYjC,IDZiC,CAAA,EAAA,IAAA,ICYlB,WDZkB;;;;AAK7C,iBCcR,YAAA,CDdQ,IAAA,ECcW,IDdX,CAAA,EAAA,IAAA,ICc0B,UDd1B;;;;iBCqBR,eAAA,OAAsB,eAAe;;AA5BrD;AAOA;AAOgB,iBAwBA,UAAA,CAxBoB,IAAe,EAwBlB,IAxBkB,CAAA,EAAA,IAAW,IAwBd,QAxBc;AAO9D;AAOA;AAUA;AAOgB,iBAAA,kBAAA,CAAwC,IAAA,EAAf,IAAe,CAAA,EAAA,IAAgB,IAAhB,gBAAgB;AAOxE;AAOA;AAOA;AAWgB,iBAzBA,YAAA,CAyBuC,IAAM,EAzB1B,IAyB0B,CAAA,EAAA,IAAA,IAzBX,UAyBW;AAQ7D;;;AAC+B,iBA3Bf,UAAA,CA2Be,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IA3BsB,IA2BtB;;;;AAoBf,iBAxCA,aAAA,CAwCW,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IAxC6B,OAwC7B;;;;AACU,iBA9BrB,YAAA,CA8BqB,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IA9BkB,MA8BlB;;;AAiBrC;;AACqB,iBAxCL,SAAA,CAwCK,MAAA,CAAA,EAvCV,IAuCU,GAvCH,UAuCG,GAvCU,QAuCV,GAAA,IAAA,CAAA,EAtClB,MAsCkB,GAAA,OAtCF,UAsCE;;;;;iBAnBL,WAAA,UACL,UAAU,SAAS,OAAO,kBAClC;;;AC7GH;iBD6HgB,kBAAA,UACL,UAAU,OAAO,SAAS,kBAClC;;;;AFjIH;AASA;AAOA;;iBGdgB,WAAA;;;;AHFhB;AASA;AAOgB,iBIdA,KAAA,CAAA,CJcmC,EAAA,MAAA;;;;AAhBnD;AASA;AAOgB,iBKdA,WAAA,CLcmC,CAAA,EAAA,OAAA,EAAA,CAAA,EAAA,OAAA,CAAA,EAAA,OAAA;;;;;;;;ACXD,cK6BrC,UL7BqC,EAAA,CAAA,GAAA,EAAA,CAAA,CAAA,CAAA,KAAA,EK8BzC,QL9ByC,CK8BhC,CL9BgC,CAAA,EAAA,WAAA,EAAA,CAAA,IAAA,EK+B5B,CL/B4B,EAAA,KAAA,EAAA,MAAA,EAAA,GK+BP,GL/BO,EAAA,GKgC7C,GLhC6C,CKgCzC,GLhCyC,EKgCtC,CLhCsC,EAAA,CAAA;;;;ADLlD;AASA;AAOA;;;;ACdA;;;;;;;;;;;;;;ACCA;AAOA;AAOA;AAOA;AAOA;AAUA;AAOA;AAOA;AAOA;AAOA;AAWA;AAQA;AACW,iBK3DK,SL2DL,CAAA,OAAA,EAAA,QAAA,CAAA,CAAA,MAAA,EK1DD,ML0DC,CAAA,MAAA,EK1Dc,OL0Dd,CAAA,EAAA,QAAA,EAAA,CAAA,KAAA,EKzDS,OLyDT,EAAA,GAAA,EAAA,MAAA,EAAA,GKzDkC,QLyDlC,CAAA,EKxDR,MLwDQ,CAAA,MAAA,EKxDO,QLwDP,CAAA;;;;AFzFX;AASA;AAOA;;;;ACdA;;;;;;;AAQoB,KOCR,aPDQ,CAAA,UOCgB,MPDhB,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,GAAA,QAAI,MOEV,CPFU,GAAA,COEL,CPFK,EOEF,CPFE,COEA,CPFA,CAAA,CAAA,EARc,CAAA,MOW9B,CPX8B,CAAA;;;;;ACCtC;AAOA;AAOA;AAOA;AAOA;AAUA;AAOA;AAOA;AAOA;AAOA;AAWA;AAQA;;;;;;;AAqBA;;;;;;;AAkBA;;;;;;;;cM3Ea,0BAA0B,0BAChC,MACF,cAAc;;;;;;;;APjD+B,cQ6BrC,aR7BqC,EAAA,CAAA,YQ6BX,WR7BW,EAAA,CAAA,CAAA,CAAA,KAAA,EQ8BzC,QR9ByC,CQ8BhC,CR9BgC,CAAA,EAAA,WAAA,EAAA,CAAA,IAAA,EQ+B5B,CR/B4B,EAAA,KAAA,EAAA,MAAA,EAAA,GQ+BP,GR/BO,EAAA,GQgC7C,ORhC6C,CQgCrC,MRhCqC,CQgC9B,GRhC8B,EQgC3B,CRhC2B,EAAA,CAAA,CAAA;;;;ADLlD;AASA;AAOA;;;;ACdA;;;;;;AAGkD,iBSKlC,ITLkC,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,GAAA,GSKhB,CTLgB,CAAA,EAAA,GAAA,GSKN,CTLM;;;;ADLlD;AASA;AAOgB,iBWhBA,KAAA,CXgBmC,EAAA,EAAA,MAAA,CAAA,EWhBhB,OXgBgB,CAAA,IAAA,CAAA"}

package/dist/index.js

@@ -179,43 +179,6 @@ function getId() {
 	return id;
 }
 
-//#endregion
-//#region src/once.ts
-/**
-* Creates a function that will only execute the provided function once.
-* Subsequent calls will return the cached result from the first execution.
-*
-* @param fn The function to execute once
-* @returns A function that will only execute the provided function once
-* @example
-* ```ts
-* const getValue = once(() => expensiveOperation())
-* getValue() // executes expensiveOperation
-* getValue() // returns cached result
-* ```
-*/
-function once(fn) {
-	let called = false;
-	let result;
-	return () => {
-		if (!called) {
-			result = fn();
-			called = true;
-			fn = void 0;
-		}
-		return result;
-	};
-}
-
-//#endregion
-//#region src/sleep.ts
-/**
-* Sleep for a given number of milliseconds.
-*/
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 //#endregion
 //#region src/is-deep-equal.ts
 /**
@@ -260,5 +223,184 @@ function isDeepEqual(a, b) {
 }
 
 //#endregion
-export { DefaultMap, formatBytes, getDocument, getDocumentElement, getId, getWindow, isDeepEqual, isDocument, isDocumentFragment, isElement, isElementLike, isHTMLElement, isMap, isMathMLElement, isNodeLike, isObject, isSVGElement, isSet, isShadowRoot, isTextNode, isWindowLike, once, sleep };
+//#region src/map-group-by.ts
+/**
+* @internal
+*/
+function mapGroupByPolyfill(items, keySelector) {
+	const map = /* @__PURE__ */ new Map();
+	let index = 0;
+	for (const item of items) {
+		const key = keySelector(item, index);
+		const group = map.get(key);
+		if (group) group.push(item);
+		else map.set(key, [item]);
+		index++;
+	}
+	return map;
+}
+/**
+* @internal
+*/
+function mapGroupByNative(items, keySelector) {
+	return Map.groupBy(items, keySelector);
+}
+/**
+* A polyfill for the `Map.groupBy` static method.
+*
+* @public
+*/
+const mapGroupBy = !!Map.groupBy ? mapGroupByNative : mapGroupByPolyfill;
+
+//#endregion
+//#region src/map-values.ts
+/**
+* Creates a new object with the same keys as the input object, but with values
+* transformed by the provided callback function. Similar to `Array.prototype.map()`
+* but for object values.
+
+* @param object - The object whose values will be transformed.
+* @param callback - A function that transforms each value. Receives the value and
+*   its corresponding key as arguments.
+* @returns A new object with the same keys but transformed values.
+*
+* @example
+* ```typescript
+* const prices = { apple: 1, banana: 2, orange: 3 }
+* const doubled = mapValues(prices, (price) => price * 2)
+* // Result: { apple: 2, banana: 4, orange: 6 }
+* ```
+*
+* @example
+* ```typescript
+* const users = { john: 25, jane: 30, bob: 35 }
+* const greetings = mapValues(users, (age, name) => `${name} is ${age} years old`)
+* // Result: { john: 'john is 25 years old', jane: 'jane is 30 years old', bob: 'bob is 35 years old' }
+* ```
+*
+* @example
+* ```typescript
+* const data = { a: '1', b: '2', c: '3' }
+* const numbers = mapValues(data, (str) => parseInt(str, 10))
+* // Result: { a: 1, b: 2, c: 3 }
+* ```
+*
+* @public
+*/
+function mapValues(object, callback) {
+	let result = {};
+	for (const [key, value] of Object.entries(object)) result[key] = callback(value, key);
+	return result;
+}
+
+//#endregion
+//#region src/object-entries.ts
+/**
+* A type-safe wrapper around `Object.entries()` that preserves the exact types of object keys
+* and values. Unlike the standard `Object.entries()` which returns `[string, any][]`, this
+* function returns an array of tuples where each tuple is precisely typed according to the
+* input object's structure.
+*
+* This is particularly useful when working with objects that have known, fixed property types
+* and you want to maintain type safety when iterating over entries.
+*
+* @example
+* ```typescript
+* const myObject = { a: 1, b: 'hello', c: true } as const
+* const entries = objectEntries(myObject)
+* // Type: (["a", 1] | ["b", "hello"] | ["c", true])[]
+*
+* for (const [key, value] of entries) {
+*   // key is typed as "a" | "b" | "c"
+*   // value is typed as 1 | "hello" | true
+*   console.log(`${key}: ${value}`)
+* }
+* ```
+*
+* @example
+* ```typescript
+* interface User {
+*   name: string
+*   age: number
+*   active: boolean
+* }
+*
+* const user: User = { name: 'Alice', age: 30, active: true }
+* const entries = objectEntries(user)
+* // Type: (["name", string] | ["age", number] | ["active", boolean])[]
+* ```
+*
+* @public
+*/
+const objectEntries = Object.entries;
+
+//#endregion
+//#region src/object-group-by.ts
+/**
+* @internal
+*/
+function objectGroupByPolyfill(items, keySelector) {
+	const result = {};
+	let index = 0;
+	for (const item of items) {
+		const key = keySelector(item, index);
+		const group = result[key];
+		if (group) group.push(item);
+		else result[key] = [item];
+		index++;
+	}
+	return result;
+}
+/**
+* @internal
+*/
+function objectGroupByNative(items, keySelector) {
+	return Object.groupBy(items, keySelector);
+}
+/**
+* A polyfill for the `Object.groupBy` static method.
+*
+* @public
+*/
+const objectGroupBy = !!Object.groupBy ? objectGroupByNative : objectGroupByPolyfill;
+
+//#endregion
+//#region src/once.ts
+/**
+* Creates a function that will only execute the provided function once.
+* Subsequent calls will return the cached result from the first execution.
+*
+* @param fn The function to execute once
+* @returns A function that will only execute the provided function once
+* @example
+* ```ts
+* const getValue = once(() => expensiveOperation())
+* getValue() // executes expensiveOperation
+* getValue() // returns cached result
+* ```
+*/
+function once(fn) {
+	let called = false;
+	let result;
+	return () => {
+		if (!called) {
+			result = fn();
+			called = true;
+			fn = void 0;
+		}
+		return result;
+	};
+}
+
+//#endregion
+//#region src/sleep.ts
+/**
+* Sleep for a given number of milliseconds.
+*/
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+export { DefaultMap, formatBytes, getDocument, getDocumentElement, getId, getWindow, isDeepEqual, isDocument, isDocumentFragment, isElement, isElementLike, isHTMLElement, isMap, isMathMLElement, isNodeLike, isObject, isSVGElement, isSet, isShadowRoot, isTextNode, isWindowLike, mapGroupBy, mapValues, objectEntries, objectGroupBy, once, sleep };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["NodeType.ELEMENT_NODE","NodeType.TEXT_NODE","NodeType.DOCUMENT_NODE","NodeType.DOCUMENT_FRAGMENT_NODE","result: T"],"sources":["../src/checker.ts","../src/default-map.ts","../src/dom-node-type.ts","../src/dom.ts","../src/format-bytes.ts","../src/get-id.ts","../src/once.ts","../src/sleep.ts","../src/is-deep-equal.ts"],"sourcesContent":["/**\n * Checks if the given value is an object.\n */\nexport function isObject(\n  value: unknown,\n): value is Record<string | symbol | number, unknown> {\n  return value != null && typeof value === 'object'\n}\n\n/**\n * Checks if the given value is a Map.\n */\nexport function isMap(value: unknown): value is Map<unknown, unknown> {\n  return value instanceof Map\n}\n\n/**\n * Checks if the given value is a Set.\n */\nexport function isSet(value: unknown): value is Set<unknown> {\n  return value instanceof Set\n}\n","/**\n * A map that automatically creates values for missing keys using a factory function.\n *\n * Similar to Python's [defaultdict](https://docs.python.org/3.13/library/collections.html#collections.defaultdict).\n */\nexport class DefaultMap<K, V> extends Map<K, V> {\n  private readonly defaultFactory: () => V\n\n  constructor(defaultFactory: () => V, iterable?: Iterable<readonly [K, V]>) {\n    super(iterable)\n    this.defaultFactory = defaultFactory\n  }\n\n  override get(key: K): V {\n    if (this.has(key)) {\n      return super.get(key)!\n    }\n    const value = this.defaultFactory()\n    this.set(key, value)\n    return value\n  }\n}\n","// prettier-ignore\nexport const ELEMENT_NODE = 1 satisfies typeof Node.ELEMENT_NODE;\n// prettier-ignore\nexport const ATTRIBUTE_NODE = 2 satisfies typeof Node.ATTRIBUTE_NODE;\n// prettier-ignore\nexport const TEXT_NODE = 3 satisfies typeof Node.TEXT_NODE;\n// prettier-ignore\nexport const CDATA_SECTION_NODE = 4 satisfies typeof Node.CDATA_SECTION_NODE;\n// prettier-ignore\nexport const ENTITY_REFERENCE_NODE = 5 satisfies typeof Node.ENTITY_REFERENCE_NODE;\n// prettier-ignore\nexport const ENTITY_NODE = 6 satisfies typeof Node.ENTITY_NODE;\n// prettier-ignore\nexport const PROCESSING_INSTRUCTION_NODE = 7 satisfies typeof Node.PROCESSING_INSTRUCTION_NODE;\n// prettier-ignore\nexport const COMMENT_NODE = 8 satisfies typeof Node.COMMENT_NODE;\n// prettier-ignore\nexport const DOCUMENT_NODE = 9 satisfies typeof Node.DOCUMENT_NODE;\n// prettier-ignore\nexport const DOCUMENT_TYPE_NODE = 10 satisfies typeof Node.DOCUMENT_TYPE_NODE;\n// prettier-ignore\nexport const DOCUMENT_FRAGMENT_NODE = 11 satisfies typeof Node.DOCUMENT_FRAGMENT_NODE;\n// prettier-ignore\nexport const NOTATION_NODE = 12 satisfies typeof Node.NOTATION_NODE;\n","import { isObject } from './checker'\nimport * as NodeType from './dom-node-type'\n\n/**\n * Checks if the given DOM node is an Element.\n */\nexport function isElement(node: Node): node is Element {\n  return node.nodeType === NodeType.ELEMENT_NODE\n}\n\n/**\n * Checks if the given DOM node is a Text node.\n */\nexport function isTextNode(node: Node): node is Text {\n  return node.nodeType === NodeType.TEXT_NODE\n}\n\n/**\n * Checks if the given DOM node is an HTMLElement.\n */\nexport function isHTMLElement(node: Node): node is HTMLElement {\n  return isElement(node) && node.namespaceURI === 'http://www.w3.org/1999/xhtml'\n}\n\n/**\n * Checks if the given DOM node is an SVGElement.\n */\nexport function isSVGElement(node: Node): node is SVGElement {\n  return isElement(node) && node.namespaceURI === 'http://www.w3.org/2000/svg'\n}\n\n/**\n * Checks if the given DOM node is an MathMLElement.\n */\nexport function isMathMLElement(node: Node): node is MathMLElement {\n  return (\n    isElement(node) &&\n    node.namespaceURI === 'http://www.w3.org/1998/Math/MathML'\n  )\n}\n\n/**\n * Checks if the given DOM node is a Document.\n */\nexport function isDocument(node: Node): node is Document {\n  return node.nodeType === NodeType.DOCUMENT_NODE\n}\n\n/**\n * Checks if the given DOM node is a DocumentFragment.\n */\nexport function isDocumentFragment(node: Node): node is DocumentFragment {\n  return node.nodeType === NodeType.DOCUMENT_FRAGMENT_NODE\n}\n\n/**\n * Checks if the given DOM node is a ShadowRoot.\n */\nexport function isShadowRoot(node: Node): node is ShadowRoot {\n  return isDocumentFragment(node) && 'host' in node && isElementLike(node.host)\n}\n\n/**\n * Checks if an unknown value is likely a DOM node.\n */\nexport function isNodeLike(value: unknown): value is Node {\n  return isObject(value) && value.nodeType !== undefined\n}\n\n/**\n * Checks if an unknown value is likely a DOM element.\n */\nexport function isElementLike(value: unknown): value is Element {\n  return (\n    isObject(value) &&\n    value.nodeType === NodeType.ELEMENT_NODE &&\n    typeof value.nodeName === 'string'\n  )\n}\n\n/**\n * Checks if the given value is likely a Window object.\n */\nexport function isWindowLike(value: unknown): value is Window {\n  return isObject(value) && value.window === value\n}\n\n/**\n * Gets the window object for the given target or the global window object if no\n * target is provided.\n */\nexport function getWindow(\n  target?: Node | ShadowRoot | Document | null,\n): Window & typeof globalThis {\n  if (target) {\n    if (isShadowRoot(target)) {\n      return getWindow(target.host)\n    }\n    if (isDocument(target)) {\n      return target.defaultView || window\n    }\n    if (isElement(target)) {\n      return target.ownerDocument?.defaultView || window\n    }\n  }\n  return window\n}\n\n/**\n * Gets the document for the given target or the global document if no target is\n * provided.\n */\nexport function getDocument(\n  target?: Element | Window | Node | Document | null,\n): Document {\n  if (target) {\n    if (isWindowLike(target)) {\n      return target.document\n    }\n    if (isDocument(target)) {\n      return target\n    }\n    return target.ownerDocument || document\n  }\n  return document\n}\n\n/**\n * Gets a reference to the root node of the document based on the given target.\n */\nexport function getDocumentElement(\n  target?: Element | Node | Window | Document | null,\n): HTMLElement {\n  return getDocument(target).documentElement\n}\n","/**\n * Formats a number of bytes into a human-readable string.\n * @param bytes - The number of bytes to format.\n * @returns A string representing the number of bytes in a human-readable format.\n */\nexport function formatBytes(bytes: number): string {\n  const units = ['B', 'KB', 'MB', 'GB']\n  let unitIndex = 0\n  let num = bytes\n  while (Math.abs(num) >= 1024 && unitIndex < units.length - 1) {\n    num /= 1024\n    unitIndex++\n  }\n  const fraction = unitIndex === 0 && num % 1 === 0 ? 0 : 1\n  return `${num.toFixed(fraction)}${units[unitIndex]}`\n}\n","let id = 0\n\n/**\n * Generates a unique positive integer.\n */\nexport function getId(): number {\n  id = (id % Number.MAX_SAFE_INTEGER) + 1\n  return id\n}\n","/**\n * Creates a function that will only execute the provided function once.\n * Subsequent calls will return the cached result from the first execution.\n *\n * @param fn The function to execute once\n * @returns A function that will only execute the provided function once\n * @example\n * ```ts\n * const getValue = once(() => expensiveOperation())\n * getValue() // executes expensiveOperation\n * getValue() // returns cached result\n * ```\n */\nexport function once<T>(fn: () => T): () => T {\n  let called = false\n  let result: T\n  return () => {\n    if (!called) {\n      result = fn()\n      called = true\n      // @ts-expect-error - micro-optimization for memory management\n      fn = undefined\n    }\n    return result\n  }\n}\n","/**\n * Sleep for a given number of milliseconds.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms))\n}\n","import { isMap, isSet } from './checker'\n\n/**\n * Whether two values are deeply equal.\n */\nexport function isDeepEqual(a: unknown, b: unknown): boolean {\n  if (a === b) {\n    return true\n  }\n\n  // Handle null and undefined early\n  if (a == null || b == null) {\n    return false\n  }\n\n  const aType = typeof a\n  const bType = typeof b\n  if (aType !== bType) {\n    return false\n  }\n\n  if (aType === 'number' && Number.isNaN(a) && Number.isNaN(b)) {\n    return true\n  }\n\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b)) {\n      return false\n    }\n    if (a.length !== b.length) {\n      return false\n    }\n    const size = a.length\n    for (let i = 0; i < size; i++) {\n      if (!isDeepEqual(a[i], b[i])) {\n        return false\n      }\n    }\n    return true\n  }\n\n  if (isSet(a)) {\n    if (!isSet(b)) {\n      return false\n    }\n    if (a.size !== b.size) {\n      return false\n    }\n    for (const value of a) {\n      if (!b.has(value)) {\n        return false\n      }\n    }\n    return true\n  }\n\n  if (isMap(a)) {\n    if (!isMap(b)) {\n      return false\n    }\n    if (a.size !== b.size) {\n      return false\n    }\n    for (const key of a.keys()) {\n      if (!b.has(key)) {\n        return false\n      }\n      if (!isDeepEqual(a.get(key), b.get(key))) {\n        return false\n      }\n    }\n    return true\n  }\n\n  if (typeof a === 'object' && typeof b === 'object') {\n    const aKeys = Object.keys(a)\n    const bKeys = Object.keys(b)\n    if (aKeys.length !== bKeys.length) {\n      return false\n    }\n    for (const key of aKeys) {\n      if (\n        !isDeepEqual(\n          (a as Record<string, unknown>)[key],\n          (b as Record<string, unknown>)[key],\n        )\n      ) {\n        return false\n      }\n    }\n    return true\n  }\n\n  return false\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["NodeType.ELEMENT_NODE","NodeType.TEXT_NODE","NodeType.DOCUMENT_NODE","NodeType.DOCUMENT_FRAGMENT_NODE","mapGroupBy: <K, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n) => Map<K, T[]>","objectEntries: <T extends Record<string, any>>(\n  obj: T,\n) => ObjectEntries<T>[]","result: Partial<Record<K, T[]>>","objectGroupBy: <K extends PropertyKey, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n) => Partial<Record<K, T[]>>","result: T"],"sources":["../src/checker.ts","../src/default-map.ts","../src/dom-node-type.ts","../src/dom.ts","../src/format-bytes.ts","../src/get-id.ts","../src/is-deep-equal.ts","../src/map-group-by.ts","../src/map-values.ts","../src/object-entries.ts","../src/object-group-by.ts","../src/once.ts","../src/sleep.ts"],"sourcesContent":["/**\n * Checks if the given value is an object.\n */\nexport function isObject(\n  value: unknown,\n): value is Record<string | symbol | number, unknown> {\n  return value != null && typeof value === 'object'\n}\n\n/**\n * Checks if the given value is a Map.\n */\nexport function isMap(value: unknown): value is Map<unknown, unknown> {\n  return value instanceof Map\n}\n\n/**\n * Checks if the given value is a Set.\n */\nexport function isSet(value: unknown): value is Set<unknown> {\n  return value instanceof Set\n}\n","/**\n * A map that automatically creates values for missing keys using a factory function.\n *\n * Similar to Python's [defaultdict](https://docs.python.org/3.13/library/collections.html#collections.defaultdict).\n */\nexport class DefaultMap<K, V> extends Map<K, V> {\n  private readonly defaultFactory: () => V\n\n  constructor(defaultFactory: () => V, iterable?: Iterable<readonly [K, V]>) {\n    super(iterable)\n    this.defaultFactory = defaultFactory\n  }\n\n  override get(key: K): V {\n    if (this.has(key)) {\n      return super.get(key)!\n    }\n    const value = this.defaultFactory()\n    this.set(key, value)\n    return value\n  }\n}\n","// prettier-ignore\nexport const ELEMENT_NODE = 1 satisfies typeof Node.ELEMENT_NODE;\n// prettier-ignore\nexport const ATTRIBUTE_NODE = 2 satisfies typeof Node.ATTRIBUTE_NODE;\n// prettier-ignore\nexport const TEXT_NODE = 3 satisfies typeof Node.TEXT_NODE;\n// prettier-ignore\nexport const CDATA_SECTION_NODE = 4 satisfies typeof Node.CDATA_SECTION_NODE;\n// prettier-ignore\nexport const ENTITY_REFERENCE_NODE = 5 satisfies typeof Node.ENTITY_REFERENCE_NODE;\n// prettier-ignore\nexport const ENTITY_NODE = 6 satisfies typeof Node.ENTITY_NODE;\n// prettier-ignore\nexport const PROCESSING_INSTRUCTION_NODE = 7 satisfies typeof Node.PROCESSING_INSTRUCTION_NODE;\n// prettier-ignore\nexport const COMMENT_NODE = 8 satisfies typeof Node.COMMENT_NODE;\n// prettier-ignore\nexport const DOCUMENT_NODE = 9 satisfies typeof Node.DOCUMENT_NODE;\n// prettier-ignore\nexport const DOCUMENT_TYPE_NODE = 10 satisfies typeof Node.DOCUMENT_TYPE_NODE;\n// prettier-ignore\nexport const DOCUMENT_FRAGMENT_NODE = 11 satisfies typeof Node.DOCUMENT_FRAGMENT_NODE;\n// prettier-ignore\nexport const NOTATION_NODE = 12 satisfies typeof Node.NOTATION_NODE;\n","import { isObject } from './checker'\nimport * as NodeType from './dom-node-type'\n\n/**\n * Checks if the given DOM node is an Element.\n */\nexport function isElement(node: Node): node is Element {\n  return node.nodeType === NodeType.ELEMENT_NODE\n}\n\n/**\n * Checks if the given DOM node is a Text node.\n */\nexport function isTextNode(node: Node): node is Text {\n  return node.nodeType === NodeType.TEXT_NODE\n}\n\n/**\n * Checks if the given DOM node is an HTMLElement.\n */\nexport function isHTMLElement(node: Node): node is HTMLElement {\n  return isElement(node) && node.namespaceURI === 'http://www.w3.org/1999/xhtml'\n}\n\n/**\n * Checks if the given DOM node is an SVGElement.\n */\nexport function isSVGElement(node: Node): node is SVGElement {\n  return isElement(node) && node.namespaceURI === 'http://www.w3.org/2000/svg'\n}\n\n/**\n * Checks if the given DOM node is an MathMLElement.\n */\nexport function isMathMLElement(node: Node): node is MathMLElement {\n  return (\n    isElement(node) &&\n    node.namespaceURI === 'http://www.w3.org/1998/Math/MathML'\n  )\n}\n\n/**\n * Checks if the given DOM node is a Document.\n */\nexport function isDocument(node: Node): node is Document {\n  return node.nodeType === NodeType.DOCUMENT_NODE\n}\n\n/**\n * Checks if the given DOM node is a DocumentFragment.\n */\nexport function isDocumentFragment(node: Node): node is DocumentFragment {\n  return node.nodeType === NodeType.DOCUMENT_FRAGMENT_NODE\n}\n\n/**\n * Checks if the given DOM node is a ShadowRoot.\n */\nexport function isShadowRoot(node: Node): node is ShadowRoot {\n  return isDocumentFragment(node) && 'host' in node && isElementLike(node.host)\n}\n\n/**\n * Checks if an unknown value is likely a DOM node.\n */\nexport function isNodeLike(value: unknown): value is Node {\n  return isObject(value) && value.nodeType !== undefined\n}\n\n/**\n * Checks if an unknown value is likely a DOM element.\n */\nexport function isElementLike(value: unknown): value is Element {\n  return (\n    isObject(value) &&\n    value.nodeType === NodeType.ELEMENT_NODE &&\n    typeof value.nodeName === 'string'\n  )\n}\n\n/**\n * Checks if the given value is likely a Window object.\n */\nexport function isWindowLike(value: unknown): value is Window {\n  return isObject(value) && value.window === value\n}\n\n/**\n * Gets the window object for the given target or the global window object if no\n * target is provided.\n */\nexport function getWindow(\n  target?: Node | ShadowRoot | Document | null,\n): Window & typeof globalThis {\n  if (target) {\n    if (isShadowRoot(target)) {\n      return getWindow(target.host)\n    }\n    if (isDocument(target)) {\n      return target.defaultView || window\n    }\n    if (isElement(target)) {\n      return target.ownerDocument?.defaultView || window\n    }\n  }\n  return window\n}\n\n/**\n * Gets the document for the given target or the global document if no target is\n * provided.\n */\nexport function getDocument(\n  target?: Element | Window | Node | Document | null,\n): Document {\n  if (target) {\n    if (isWindowLike(target)) {\n      return target.document\n    }\n    if (isDocument(target)) {\n      return target\n    }\n    return target.ownerDocument || document\n  }\n  return document\n}\n\n/**\n * Gets a reference to the root node of the document based on the given target.\n */\nexport function getDocumentElement(\n  target?: Element | Node | Window | Document | null,\n): HTMLElement {\n  return getDocument(target).documentElement\n}\n","/**\n * Formats a number of bytes into a human-readable string.\n * @param bytes - The number of bytes to format.\n * @returns A string representing the number of bytes in a human-readable format.\n */\nexport function formatBytes(bytes: number): string {\n  const units = ['B', 'KB', 'MB', 'GB']\n  let unitIndex = 0\n  let num = bytes\n  while (Math.abs(num) >= 1024 && unitIndex < units.length - 1) {\n    num /= 1024\n    unitIndex++\n  }\n  const fraction = unitIndex === 0 && num % 1 === 0 ? 0 : 1\n  return `${num.toFixed(fraction)}${units[unitIndex]}`\n}\n","let id = 0\n\n/**\n * Generates a unique positive integer.\n */\nexport function getId(): number {\n  id = (id % Number.MAX_SAFE_INTEGER) + 1\n  return id\n}\n","import { isMap, isSet } from './checker'\n\n/**\n * Whether two values are deeply equal.\n */\nexport function isDeepEqual(a: unknown, b: unknown): boolean {\n  if (a === b) {\n    return true\n  }\n\n  // Handle null and undefined early\n  if (a == null || b == null) {\n    return false\n  }\n\n  const aType = typeof a\n  const bType = typeof b\n  if (aType !== bType) {\n    return false\n  }\n\n  if (aType === 'number' && Number.isNaN(a) && Number.isNaN(b)) {\n    return true\n  }\n\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b)) {\n      return false\n    }\n    if (a.length !== b.length) {\n      return false\n    }\n    const size = a.length\n    for (let i = 0; i < size; i++) {\n      if (!isDeepEqual(a[i], b[i])) {\n        return false\n      }\n    }\n    return true\n  }\n\n  if (isSet(a)) {\n    if (!isSet(b)) {\n      return false\n    }\n    if (a.size !== b.size) {\n      return false\n    }\n    for (const value of a) {\n      if (!b.has(value)) {\n        return false\n      }\n    }\n    return true\n  }\n\n  if (isMap(a)) {\n    if (!isMap(b)) {\n      return false\n    }\n    if (a.size !== b.size) {\n      return false\n    }\n    for (const key of a.keys()) {\n      if (!b.has(key)) {\n        return false\n      }\n      if (!isDeepEqual(a.get(key), b.get(key))) {\n        return false\n      }\n    }\n    return true\n  }\n\n  if (typeof a === 'object' && typeof b === 'object') {\n    const aKeys = Object.keys(a)\n    const bKeys = Object.keys(b)\n    if (aKeys.length !== bKeys.length) {\n      return false\n    }\n    for (const key of aKeys) {\n      if (\n        !isDeepEqual(\n          (a as Record<string, unknown>)[key],\n          (b as Record<string, unknown>)[key],\n        )\n      ) {\n        return false\n      }\n    }\n    return true\n  }\n\n  return false\n}\n","/**\n * @internal\n */\nexport function mapGroupByPolyfill<K, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n): Map<K, T[]> {\n  const map = new Map<K, T[]>()\n  let index = 0\n  for (const item of items) {\n    const key = keySelector(item, index)\n    const group = map.get(key)\n    if (group) {\n      group.push(item)\n    } else {\n      map.set(key, [item])\n    }\n    index++\n  }\n  return map\n}\n\n/**\n * @internal\n */\nexport function mapGroupByNative<K, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n): Map<K, T[]> {\n  return Map.groupBy(items, keySelector)\n}\n\n/**\n * A polyfill for the `Map.groupBy` static method.\n *\n * @public\n */\nexport const mapGroupBy: <K, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n) => Map<K, T[]> = !!Map.groupBy ? mapGroupByNative : mapGroupByPolyfill\n","/**\n * Creates a new object with the same keys as the input object, but with values\n * transformed by the provided callback function. Similar to `Array.prototype.map()`\n * but for object values.\n\n * @param object - The object whose values will be transformed.\n * @param callback - A function that transforms each value. Receives the value and\n *   its corresponding key as arguments.\n * @returns A new object with the same keys but transformed values.\n *\n * @example\n * ```typescript\n * const prices = { apple: 1, banana: 2, orange: 3 }\n * const doubled = mapValues(prices, (price) => price * 2)\n * // Result: { apple: 2, banana: 4, orange: 6 }\n * ```\n *\n * @example\n * ```typescript\n * const users = { john: 25, jane: 30, bob: 35 }\n * const greetings = mapValues(users, (age, name) => `${name} is ${age} years old`)\n * // Result: { john: 'john is 25 years old', jane: 'jane is 30 years old', bob: 'bob is 35 years old' }\n * ```\n *\n * @example\n * ```typescript\n * const data = { a: '1', b: '2', c: '3' }\n * const numbers = mapValues(data, (str) => parseInt(str, 10))\n * // Result: { a: 1, b: 2, c: 3 }\n * ```\n *\n * @public\n */\nexport function mapValues<ValueIn, ValueOut>(\n  object: Record<string, ValueIn>,\n  callback: (value: ValueIn, key: string) => ValueOut,\n): Record<string, ValueOut> {\n  let result = {} as Record<string, ValueOut>\n  for (const [key, value] of Object.entries(object)) {\n    result[key] = callback(value, key)\n  }\n  return result\n}\n","/**\n * A TypeScript utility type that represents the entries of an object as a union of tuple types.\n * Each tuple contains a key-value pair where the key and value types are precisely typed\n * according to the input object type.\n *\n * @example\n * ```typescript\n * type MyObject = { a: 1; b: 'B' }\n * type MyEntries = ObjectEntries<MyObject>\n * //   ^ [\"a\", 1] | [\"b\", \"B\"]\n * ```\n *\n * @public\n */\nexport type ObjectEntries<T extends Record<string, any>> = {\n  [K in keyof T]: [K, T[K]]\n}[keyof T]\n\n/**\n * A type-safe wrapper around `Object.entries()` that preserves the exact types of object keys\n * and values. Unlike the standard `Object.entries()` which returns `[string, any][]`, this\n * function returns an array of tuples where each tuple is precisely typed according to the\n * input object's structure.\n *\n * This is particularly useful when working with objects that have known, fixed property types\n * and you want to maintain type safety when iterating over entries.\n *\n * @example\n * ```typescript\n * const myObject = { a: 1, b: 'hello', c: true } as const\n * const entries = objectEntries(myObject)\n * // Type: ([\"a\", 1] | [\"b\", \"hello\"] | [\"c\", true])[]\n *\n * for (const [key, value] of entries) {\n *   // key is typed as \"a\" | \"b\" | \"c\"\n *   // value is typed as 1 | \"hello\" | true\n *   console.log(`${key}: ${value}`)\n * }\n * ```\n *\n * @example\n * ```typescript\n * interface User {\n *   name: string\n *   age: number\n *   active: boolean\n * }\n *\n * const user: User = { name: 'Alice', age: 30, active: true }\n * const entries = objectEntries(user)\n * // Type: ([\"name\", string] | [\"age\", number] | [\"active\", boolean])[]\n * ```\n *\n * @public\n */\nexport const objectEntries: <T extends Record<string, any>>(\n  obj: T,\n) => ObjectEntries<T>[] = Object.entries\n","/**\n * @internal\n */\nexport function objectGroupByPolyfill<K extends PropertyKey, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n): Partial<Record<K, T[]>> {\n  const result: Partial<Record<K, T[]>> = {}\n  let index = 0\n  for (const item of items) {\n    const key = keySelector(item, index)\n    const group = result[key]\n    if (group) {\n      group.push(item)\n    } else {\n      result[key] = [item]\n    }\n    index++\n  }\n  return result\n}\n\n/**\n * @internal\n */\nexport function objectGroupByNative<K extends PropertyKey, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n): Partial<Record<K, T[]>> {\n  return Object.groupBy(items, keySelector)\n}\n\n/**\n * A polyfill for the `Object.groupBy` static method.\n *\n * @public\n */\nexport const objectGroupBy: <K extends PropertyKey, T>(\n  items: Iterable<T>,\n  keySelector: (item: T, index: number) => K,\n) => Partial<Record<K, T[]>> = !!Object.groupBy\n  ? objectGroupByNative\n  : objectGroupByPolyfill\n","/**\n * Creates a function that will only execute the provided function once.\n * Subsequent calls will return the cached result from the first execution.\n *\n * @param fn The function to execute once\n * @returns A function that will only execute the provided function once\n * @example\n * ```ts\n * const getValue = once(() => expensiveOperation())\n * getValue() // executes expensiveOperation\n * getValue() // returns cached result\n * ```\n */\nexport function once<T>(fn: () => T): () => T {\n  let called = false\n  let result: T\n  return () => {\n    if (!called) {\n      result = fn()\n      called = true\n      // @ts-expect-error - micro-optimization for memory management\n      fn = undefined\n    }\n    return result\n  }\n}\n","/**\n * Sleep for a given number of milliseconds.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms))\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ocavue/utils",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A collection of utility functions for the browser and other environments",
   "author": "ocavue <ocavue@gmail.com>",
   "license": "MIT",
@@ -55,16 +55,16 @@
   "publishConfig": {
     "access": "public"
   },
-  "size-limit": [
-    {
-      "path": "dist/index.js"
-    }
-  ],
   "renovate": {
     "extends": [
       "github>ocavue/config-renovate"
     ]
   },
+  "size-limit": [
+    {
+      "path": "dist/index.js"
+    }
+  ],
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",

package/src/default-map.test.ts

@@ -144,10 +144,13 @@ describe('DefaultMap', () => {
   })
 
   it('works with iteration methods', () => {
-    const map = new DefaultMap<string, number>(() => 0, [
-      ['a', 1],
-      ['b', 2],
-    ])
+    const map = new DefaultMap<string, number>(
+      () => 0,
+      [
+        ['a', 1],
+        ['b', 2],
+      ],
+    )
 
     expect([...map.keys()]).toEqual(['a', 'b'])
     expect([...map.values()]).toEqual([1, 2])

package/src/index.ts

@@ -3,6 +3,10 @@ export { DefaultMap } from './default-map'
 export * from './dom'
 export { formatBytes } from './format-bytes'
 export { getId } from './get-id'
+export { isDeepEqual } from './is-deep-equal'
+export { mapGroupBy } from './map-group-by'
+export { mapValues } from './map-values'
+export { objectEntries, type ObjectEntries } from './object-entries'
+export { objectGroupBy } from './object-group-by'
 export { once } from './once'
 export { sleep } from './sleep'
-export { isDeepEqual } from './is-deep-equal'

package/src/is-deep-equal.test.ts

@@ -59,8 +59,30 @@ describe('isDeepEqual', () => {
     })
 
     it('handles nested arrays', () => {
-      expect(isDeepEqual([[1, 2], [3, 4]], [[1, 2], [3, 4]])).toBe(true)
-      expect(isDeepEqual([[1, 2], [3, 4]], [[1, 2], [3, 5]])).toBe(false)
+      expect(
+        isDeepEqual(
+          [
+            [1, 2],
+            [3, 4],
+          ],
+          [
+            [1, 2],
+            [3, 4],
+          ],
+        ),
+      ).toBe(true)
+      expect(
+        isDeepEqual(
+          [
+            [1, 2],
+            [3, 4],
+          ],
+          [
+            [1, 2],
+            [3, 5],
+          ],
+        ),
+      ).toBe(false)
     })
   })
 
@@ -105,9 +127,7 @@ describe('isDeepEqual', () => {
 
     it('returns false for sets with different values', () => {
       expect(isDeepEqual(new Set([1, 2, 3]), new Set([1, 2, 4]))).toBe(false)
-      expect(isDeepEqual(new Set(['a', 'b']), new Set(['a', 'c']))).toBe(
-        false,
-      )
+      expect(isDeepEqual(new Set(['a', 'b']), new Set(['a', 'c']))).toBe(false)
     })
 
     it('handles set order independence', () => {
@@ -145,44 +165,28 @@ describe('isDeepEqual', () => {
     })
 
     it('returns false for maps with different keys', () => {
-      expect(
-        isDeepEqual(new Map([['a', 1]]), new Map([['b', 1]])),
-      ).toBe(false)
+      expect(isDeepEqual(new Map([['a', 1]]), new Map([['b', 1]]))).toBe(false)
     })
 
     it('returns false for maps with different values', () => {
-      expect(
-        isDeepEqual(new Map([['a', 1]]), new Map([['a', 2]])),
-      ).toBe(false)
+      expect(isDeepEqual(new Map([['a', 1]]), new Map([['a', 2]]))).toBe(false)
     })
 
     it('handles nested values in maps', () => {
       expect(
-        isDeepEqual(
-          new Map([['a', { b: 1 }]]),
-          new Map([['a', { b: 1 }]]),
-        ),
+        isDeepEqual(new Map([['a', { b: 1 }]]), new Map([['a', { b: 1 }]])),
       ).toBe(true)
       expect(
-        isDeepEqual(
-          new Map([['a', { b: 1 }]]),
-          new Map([['a', { b: 2 }]]),
-        ),
+        isDeepEqual(new Map([['a', { b: 1 }]]), new Map([['a', { b: 2 }]])),
       ).toBe(false)
     })
 
     it('handles arrays as map values', () => {
       expect(
-        isDeepEqual(
-          new Map([['a', [1, 2, 3]]]),
-          new Map([['a', [1, 2, 3]]]),
-        ),
+        isDeepEqual(new Map([['a', [1, 2, 3]]]), new Map([['a', [1, 2, 3]]])),
       ).toBe(true)
       expect(
-        isDeepEqual(
-          new Map([['a', [1, 2, 3]]]),
-          new Map([['a', [1, 2, 4]]]),
-        ),
+        isDeepEqual(new Map([['a', [1, 2, 3]]]), new Map([['a', [1, 2, 4]]])),
       ).toBe(false)
     })
   })

package/src/map-group-by.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  mapGroupBy,
+  mapGroupByPolyfill,
+  mapGroupByNative,
+} from './map-group-by'
+
+const testCases = [
+  { name: 'mapGroupBy', fn: mapGroupBy },
+  { name: 'mapGroupByPolyfill', fn: mapGroupByPolyfill },
+]
+
+if (!!Map.groupBy) {
+  testCases.push({ name: 'mapGroupByNative', fn: mapGroupByNative })
+}
+
+describe.each(testCases)('$name', ({ fn }) => {
+  it('groups items by key', () => {
+    const items = [1, 2, 3, 4, 5, 6]
+    const result = fn(items, (item) => item % 2)
+
+    expect(result.get(0)).toEqual([2, 4, 6])
+    expect(result.get(1)).toEqual([1, 3, 5])
+  })
+
+  it('works with string keys', () => {
+    const items = ['apple', 'banana', 'apricot', 'blueberry']
+    const result = fn(items, (item) => item[0])
+
+    expect(result.get('a')).toEqual(['apple', 'apricot'])
+    expect(result.get('b')).toEqual(['banana', 'blueberry'])
+  })
+
+  it('works with object keys', () => {
+    const keyA = { type: 'A' }
+    const keyB = { type: 'B' }
+    const items = [1, 2, 3, 4]
+    const result = fn(items, (item) => (item % 2 === 0 ? keyA : keyB))
+
+    expect(result.get(keyA)).toEqual([2, 4])
+    expect(result.get(keyB)).toEqual([1, 3])
+  })
+
+  it('passes index to key selector', () => {
+    const items = ['a', 'b', 'c', 'd']
+    const result = fn(items, (_, index) => Math.floor(index / 2))
+
+    expect(result.get(0)).toEqual(['a', 'b'])
+    expect(result.get(1)).toEqual(['c', 'd'])
+  })
+
+  it('handles empty array', () => {
+    const result = fn([], (item) => item)
+    expect(result.size).toBe(0)
+  })
+
+  it('handles single item', () => {
+    const result = fn([42], (item) => item)
+    expect(result.get(42)).toEqual([42])
+  })
+
+  it('handles all items mapping to same key', () => {
+    const items = [1, 2, 3, 4]
+    const result = fn(items, () => 'same')
+
+    expect(result.size).toBe(1)
+    expect(result.get('same')).toEqual([1, 2, 3, 4])
+  })
+
+  it('works with iterables other than arrays', () => {
+    const set = new Set([1, 2, 3, 4, 5])
+    const result = fn(set, (item) => item % 2)
+
+    expect(result.get(0)).toEqual([2, 4])
+    expect(result.get(1)).toEqual([1, 3, 5])
+  })
+})

package/src/map-group-by.ts

@@ -0,0 +1,41 @@
+/**
+ * @internal
+ */
+export function mapGroupByPolyfill<K, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+): Map<K, T[]> {
+  const map = new Map<K, T[]>()
+  let index = 0
+  for (const item of items) {
+    const key = keySelector(item, index)
+    const group = map.get(key)
+    if (group) {
+      group.push(item)
+    } else {
+      map.set(key, [item])
+    }
+    index++
+  }
+  return map
+}
+
+/**
+ * @internal
+ */
+export function mapGroupByNative<K, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+): Map<K, T[]> {
+  return Map.groupBy(items, keySelector)
+}
+
+/**
+ * A polyfill for the `Map.groupBy` static method.
+ *
+ * @public
+ */
+export const mapGroupBy: <K, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+) => Map<K, T[]> = !!Map.groupBy ? mapGroupByNative : mapGroupByPolyfill

package/src/map-values.test.ts

@@ -0,0 +1,41 @@
+// @vitest-environment node
+
+import { describe, expect, it } from 'vitest'
+
+import { mapValues } from './map-values'
+
+describe('mapValues', () => {
+  it('transforms values with callback function', () => {
+    const prices = { apple: 1, banana: 2, orange: 3 }
+    const doubled = mapValues(prices, (price) => price * 2)
+
+    expect(doubled).toEqual({ apple: 2, banana: 4, orange: 6 })
+  })
+
+  it('provides key to callback function', () => {
+    const users = { john: 25, jane: 30 }
+    const greetings = mapValues(
+      users,
+      (age, name) => `${name} is ${age} years old`,
+    )
+
+    expect(greetings).toEqual({
+      john: 'john is 25 years old',
+      jane: 'jane is 30 years old',
+    })
+  })
+
+  it('handles empty objects', () => {
+    const empty = {}
+    const result = mapValues(empty, (value) => value)
+
+    expect(result).toEqual({})
+  })
+
+  it('transforms value types', () => {
+    const data = { a: '1', b: '2', c: '3' }
+    const numbers = mapValues(data, (str) => Number.parseInt(str, 10))
+
+    expect(numbers).toEqual({ a: 1, b: 2, c: 3 })
+  })
+})

package/src/map-values.ts

@@ -0,0 +1,43 @@
+/**
+ * Creates a new object with the same keys as the input object, but with values
+ * transformed by the provided callback function. Similar to `Array.prototype.map()`
+ * but for object values.
+
+ * @param object - The object whose values will be transformed.
+ * @param callback - A function that transforms each value. Receives the value and
+ *   its corresponding key as arguments.
+ * @returns A new object with the same keys but transformed values.
+ *
+ * @example
+ * ```typescript
+ * const prices = { apple: 1, banana: 2, orange: 3 }
+ * const doubled = mapValues(prices, (price) => price * 2)
+ * // Result: { apple: 2, banana: 4, orange: 6 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const users = { john: 25, jane: 30, bob: 35 }
+ * const greetings = mapValues(users, (age, name) => `${name} is ${age} years old`)
+ * // Result: { john: 'john is 25 years old', jane: 'jane is 30 years old', bob: 'bob is 35 years old' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const data = { a: '1', b: '2', c: '3' }
+ * const numbers = mapValues(data, (str) => parseInt(str, 10))
+ * // Result: { a: 1, b: 2, c: 3 }
+ * ```
+ *
+ * @public
+ */
+export function mapValues<ValueIn, ValueOut>(
+  object: Record<string, ValueIn>,
+  callback: (value: ValueIn, key: string) => ValueOut,
+): Record<string, ValueOut> {
+  let result = {} as Record<string, ValueOut>
+  for (const [key, value] of Object.entries(object)) {
+    result[key] = callback(value, key)
+  }
+  return result
+}

package/src/object-entries.test.ts

@@ -0,0 +1,33 @@
+// @vitest-environment node
+
+import { describe, expect, it } from 'vitest'
+
+import { objectEntries } from './object-entries'
+
+describe('objectEntries', () => {
+  it('returns entries for an empty object', () => {
+    const obj = {}
+    const entries = objectEntries(obj)
+    expect(entries).toEqual([])
+  })
+
+  it('returns entries for objects with mixed types', () => {
+    const obj = { name: 'Alice', age: 30, active: true }
+    const entries = objectEntries(obj)
+    expect(entries).toEqual([
+      ['name', 'Alice'],
+      ['age', 30],
+      ['active', true],
+    ])
+  })
+
+  it('preserves type safety with const objects', () => {
+    const obj = { a: 1, b: 'hello', c: true } as const
+    const entries = objectEntries(obj)
+
+    expect(entries).toHaveLength(3)
+    expect(entries).toContainEqual(['a', 1])
+    expect(entries).toContainEqual(['b', 'hello'])
+    expect(entries).toContainEqual(['c', true])
+  })
+})

package/src/object-entries.ts

@@ -0,0 +1,58 @@
+/**
+ * A TypeScript utility type that represents the entries of an object as a union of tuple types.
+ * Each tuple contains a key-value pair where the key and value types are precisely typed
+ * according to the input object type.
+ *
+ * @example
+ * ```typescript
+ * type MyObject = { a: 1; b: 'B' }
+ * type MyEntries = ObjectEntries<MyObject>
+ * //   ^ ["a", 1] | ["b", "B"]
+ * ```
+ *
+ * @public
+ */
+export type ObjectEntries<T extends Record<string, any>> = {
+  [K in keyof T]: [K, T[K]]
+}[keyof T]
+
+/**
+ * A type-safe wrapper around `Object.entries()` that preserves the exact types of object keys
+ * and values. Unlike the standard `Object.entries()` which returns `[string, any][]`, this
+ * function returns an array of tuples where each tuple is precisely typed according to the
+ * input object's structure.
+ *
+ * This is particularly useful when working with objects that have known, fixed property types
+ * and you want to maintain type safety when iterating over entries.
+ *
+ * @example
+ * ```typescript
+ * const myObject = { a: 1, b: 'hello', c: true } as const
+ * const entries = objectEntries(myObject)
+ * // Type: (["a", 1] | ["b", "hello"] | ["c", true])[]
+ *
+ * for (const [key, value] of entries) {
+ *   // key is typed as "a" | "b" | "c"
+ *   // value is typed as 1 | "hello" | true
+ *   console.log(`${key}: ${value}`)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   name: string
+ *   age: number
+ *   active: boolean
+ * }
+ *
+ * const user: User = { name: 'Alice', age: 30, active: true }
+ * const entries = objectEntries(user)
+ * // Type: (["name", string] | ["age", number] | ["active", boolean])[]
+ * ```
+ *
+ * @public
+ */
+export const objectEntries: <T extends Record<string, any>>(
+  obj: T,
+) => ObjectEntries<T>[] = Object.entries

package/src/object-group-by.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  objectGroupBy,
+  objectGroupByPolyfill,
+  objectGroupByNative,
+} from './object-group-by'
+
+const testCases = [
+  { name: 'objectGroupBy', fn: objectGroupBy },
+  { name: 'objectGroupByPolyfill', fn: objectGroupByPolyfill },
+]
+
+if (!!Object.groupBy) {
+  testCases.push({ name: 'objectGroupByNative', fn: objectGroupByNative })
+}
+
+describe.each(testCases)('$name', ({ fn }) => {
+  it('groups items by key', () => {
+    const items = [1, 2, 3, 4, 5, 6]
+    const result = fn(items, (item) => (item % 2 === 0 ? 'even' : 'odd'))
+
+    expect(result.even).toEqual([2, 4, 6])
+    expect(result.odd).toEqual([1, 3, 5])
+  })
+
+  it('works with string keys', () => {
+    const items = ['apple', 'banana', 'apricot', 'blueberry']
+    const result = fn(items, (item) => item[0])
+
+    expect(result.a).toEqual(['apple', 'apricot'])
+    expect(result.b).toEqual(['banana', 'blueberry'])
+  })
+
+  it('works with number keys', () => {
+    const items = ['a', 'b', 'c', 'd']
+    const result = fn(items, (_, index) => Math.floor(index / 2))
+
+    expect(result[0]).toEqual(['a', 'b'])
+    expect(result[1]).toEqual(['c', 'd'])
+  })
+
+  it('works with symbol keys', () => {
+    const symA = Symbol('A')
+    const symB = Symbol('B')
+    const items = [1, 2, 3, 4]
+    const result = fn(items, (item) => (item % 2 === 0 ? symA : symB))
+
+    expect(result[symA]).toEqual([2, 4])
+    expect(result[symB]).toEqual([1, 3])
+  })
+
+  it('passes index to key selector', () => {
+    const items = ['a', 'b', 'c', 'd']
+    const result = fn(items, (_, index) => (index < 2 ? 'first' : 'second'))
+
+    expect(result.first).toEqual(['a', 'b'])
+    expect(result.second).toEqual(['c', 'd'])
+  })
+
+  it('handles empty array', () => {
+    const result = fn([], (item) => String(item))
+    expect(Object.keys(result)).toHaveLength(0)
+  })
+
+  it('handles single item', () => {
+    const result = fn([42], (item) => String(item))
+    expect(result['42']).toEqual([42])
+  })
+
+  it('handles all items mapping to same key', () => {
+    const items = [1, 2, 3, 4]
+    const result = fn(items, () => 'same')
+
+    expect(Object.keys(result)).toHaveLength(1)
+    expect(result.same).toEqual([1, 2, 3, 4])
+  })
+
+  it('works with iterables other than arrays', () => {
+    const set = new Set([1, 2, 3, 4, 5])
+    const result = fn(set, (item) => (item % 2 === 0 ? 'even' : 'odd'))
+
+    expect(result.even).toEqual([2, 4])
+    expect(result.odd).toEqual([1, 3, 5])
+  })
+})

package/src/object-group-by.ts

@@ -0,0 +1,43 @@
+/**
+ * @internal
+ */
+export function objectGroupByPolyfill<K extends PropertyKey, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+): Partial<Record<K, T[]>> {
+  const result: Partial<Record<K, T[]>> = {}
+  let index = 0
+  for (const item of items) {
+    const key = keySelector(item, index)
+    const group = result[key]
+    if (group) {
+      group.push(item)
+    } else {
+      result[key] = [item]
+    }
+    index++
+  }
+  return result
+}
+
+/**
+ * @internal
+ */
+export function objectGroupByNative<K extends PropertyKey, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+): Partial<Record<K, T[]>> {
+  return Object.groupBy(items, keySelector)
+}
+
+/**
+ * A polyfill for the `Object.groupBy` static method.
+ *
+ * @public
+ */
+export const objectGroupBy: <K extends PropertyKey, T>(
+  items: Iterable<T>,
+  keySelector: (item: T, index: number) => K,
+) => Partial<Record<K, T[]>> = !!Object.groupBy
+  ? objectGroupByNative
+  : objectGroupByPolyfill