@ocavue/utils 1.3.0 → 1.4.0

package/src/default-map.test.ts

@@ -2,7 +2,7 @@
 
 import { describe, it, expect } from 'vitest'
 
-import { Counter, DefaultMap, DefaultWeakMap, WeakCounter } from './default-map'
+import { DefaultMap, DefaultWeakMap } from './default-map'
 
 describe('DefaultMap', () => {
   it('creates default values for missing keys', () => {
@@ -281,195 +281,3 @@ describe('DefaultWeakMap', () => {
     expect(map.has(key)).toBe(true)
   })
 })
-
-describe('Counter', () => {
-  it('initializes counts to 0', () => {
-    const counter = new Counter<string>()
-
-    expect(counter.get('key1')).toBe(0)
-    expect(counter.get('key2')).toBe(0)
-  })
-
-  it('increments counts', () => {
-    const counter = new Counter<string>()
-
-    counter.increment('key1')
-    expect(counter.get('key1')).toBe(1)
-
-    counter.increment('key1')
-    expect(counter.get('key1')).toBe(2)
-
-    counter.increment('key2')
-    expect(counter.get('key2')).toBe(1)
-  })
-
-  it('increments by custom amounts', () => {
-    const counter = new Counter<string>()
-
-    counter.increment('key1', 5)
-    expect(counter.get('key1')).toBe(5)
-
-    counter.increment('key1', 3)
-    expect(counter.get('key1')).toBe(8)
-  })
-
-  it('decrements counts', () => {
-    const counter = new Counter<string>()
-
-    counter.set('key1', 10)
-    counter.decrement('key1')
-    expect(counter.get('key1')).toBe(9)
-
-    counter.decrement('key1')
-    expect(counter.get('key1')).toBe(8)
-  })
-
-  it('decrements by custom amounts', () => {
-    const counter = new Counter<string>()
-
-    counter.set('key1', 10)
-    counter.decrement('key1', 3)
-    expect(counter.get('key1')).toBe(7)
-
-    counter.decrement('key1', 2)
-    expect(counter.get('key1')).toBe(5)
-  })
-
-  it('allows negative counts', () => {
-    const counter = new Counter<string>()
-
-    counter.decrement('key1')
-    expect(counter.get('key1')).toBe(-1)
-
-    counter.decrement('key1', 5)
-    expect(counter.get('key1')).toBe(-6)
-  })
-
-  it('accepts initial entries', () => {
-    const initialEntries: [string, number][] = [
-      ['a', 5],
-      ['b', 10],
-      ['c', 15],
-    ]
-    const counter = new Counter<string>(initialEntries)
-
-    expect(counter.get('a')).toBe(5)
-    expect(counter.get('b')).toBe(10)
-    expect(counter.get('c')).toBe(15)
-    expect(counter.get('d')).toBe(0)
-  })
-
-  it('works with all Map methods', () => {
-    const counter = new Counter<string>()
-
-    counter.increment('key1')
-    counter.increment('key2', 2)
-
-    expect(counter.size).toBe(2)
-    expect(counter.has('key1')).toBe(true)
-    expect([...counter.keys()]).toEqual(['key1', 'key2'])
-    expect([...counter.values()]).toEqual([1, 2])
-  })
-})
-
-describe('WeakCounter', () => {
-  it('initializes counts to 0', () => {
-    const counter = new WeakCounter<object>()
-    const key1 = {}
-    const key2 = {}
-
-    expect(counter.get(key1)).toBe(0)
-    expect(counter.get(key2)).toBe(0)
-  })
-
-  it('increments counts', () => {
-    const counter = new WeakCounter<object>()
-    const key = {}
-
-    counter.increment(key)
-    expect(counter.get(key)).toBe(1)
-
-    counter.increment(key)
-    expect(counter.get(key)).toBe(2)
-  })
-
-  it('increments by custom amounts', () => {
-    const counter = new WeakCounter<object>()
-    const key = {}
-
-    counter.increment(key, 5)
-    expect(counter.get(key)).toBe(5)
-
-    counter.increment(key, 3)
-    expect(counter.get(key)).toBe(8)
-  })
-
-  it('decrements counts', () => {
-    const counter = new WeakCounter<object>()
-    const key = {}
-
-    counter.set(key, 10)
-    counter.decrement(key)
-    expect(counter.get(key)).toBe(9)
-
-    counter.decrement(key)
-    expect(counter.get(key)).toBe(8)
-  })
-
-  it('decrements by custom amounts', () => {
-    const counter = new WeakCounter<object>()
-    const key = {}
-
-    counter.set(key, 10)
-    counter.decrement(key, 3)
-    expect(counter.get(key)).toBe(7)
-
-    counter.decrement(key, 2)
-    expect(counter.get(key)).toBe(5)
-  })
-
-  it('allows negative counts', () => {
-    const counter = new WeakCounter<object>()
-    const key = {}
-
-    counter.decrement(key)
-    expect(counter.get(key)).toBe(-1)
-
-    counter.decrement(key, 5)
-    expect(counter.get(key)).toBe(-6)
-  })
-
-  it('accepts initial entries', () => {
-    const key1 = {}
-    const key2 = {}
-    const key3 = {}
-    const initialEntries: [object, number][] = [
-      [key1, 5],
-      [key2, 10],
-      [key3, 15],
-    ]
-    const counter = new WeakCounter<object>(initialEntries)
-
-    expect(counter.get(key1)).toBe(5)
-    expect(counter.get(key2)).toBe(10)
-    expect(counter.get(key3)).toBe(15)
-
-    const key4 = {}
-    expect(counter.get(key4)).toBe(0)
-  })
-
-  it('works with WeakMap methods', () => {
-    const counter = new WeakCounter<object>()
-    const key1 = {}
-    const key2 = {}
-
-    counter.increment(key1)
-    counter.increment(key2, 2)
-
-    expect(counter.has(key1)).toBe(true)
-    expect(counter.has(key2)).toBe(true)
-
-    counter.delete(key1)
-    expect(counter.has(key1)).toBe(false)
-  })
-})

package/src/default-map.ts

@@ -2,6 +2,68 @@
  * A map that automatically creates values for missing keys using a factory function.
  *
  * Similar to Python's [defaultdict](https://docs.python.org/3.13/library/collections.html#collections.defaultdict).
+ *
+ * @example
+ * ```typescript
+ * // Group items by category using arrays
+ * const groupByCategory = new DefaultMap<string, string[]>(() => [])
+ *
+ * groupByCategory.get('fruits').push('apple', 'banana')
+ * groupByCategory.get('vegetables').push('carrot')
+ * groupByCategory.get('fruits').push('orange')
+ *
+ * console.log(groupByCategory.get('fruits'))      // ['apple', 'banana', 'orange']
+ * console.log(groupByCategory.get('vegetables'))  // ['carrot']
+ * console.log(groupByCategory.get('dairy'))       // [] (auto-created)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Build a graph with adjacency lists
+ * const graph = new DefaultMap<string, Set<string>>(() => new Set())
+ *
+ * graph.get('A').add('B').add('C')
+ * graph.get('B').add('C').add('D')
+ * graph.get('C').add('D')
+ *
+ * console.log([...graph.get('A')])  // ['B', 'C']
+ * console.log([...graph.get('B')])  // ['C', 'D']
+ * console.log([...graph.get('E')])  // [] (auto-created empty set)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Initialize with existing entries
+ * const scores = new DefaultMap<string, number>(
+ *   () => 0,
+ *   [
+ *     ['Alice', 100],
+ *     ['Bob', 85]
+ *   ]
+ * )
+ *
+ * scores.set('Alice', scores.get('Alice') + 10)  // 100 -> 110
+ * console.log(scores.get('Alice'))   // 110
+ * console.log(scores.get('Bob'))     // 85
+ * console.log(scores.get('Charlie')) // 0 (auto-created)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nested DefaultMaps for 2D data structures
+ * const matrix = new DefaultMap<number, DefaultMap<number, number>>(
+ *   () => new DefaultMap<number, number>(() => 0)
+ * )
+ *
+ * matrix.get(0).set(0, 1)
+ * matrix.get(0).set(1, 2)
+ * matrix.get(1).set(1, 3)
+ *
+ * console.log(matrix.get(0).get(0))  // 1
+ * console.log(matrix.get(0).get(1))  // 2
+ * console.log(matrix.get(1).get(0))  // 0 (auto-created)
+ * console.log(matrix.get(2).get(3))  // 0 (both auto-created)
+ * ```
  */
 export class DefaultMap<K, V> extends Map<K, V> {
   private readonly defaultFactory: () => V
@@ -24,7 +86,93 @@ export class DefaultMap<K, V> extends Map<K, V> {
 /**
  * A weak map that automatically creates values for missing keys using a factory function.
  *
- * Similar to DefaultMap but uses WeakMap as the base, allowing garbage collection of keys.
+ * Similar to {@link DefaultMap} but uses WeakMap as the base, allowing garbage collection of keys.
+ *
+ * @example
+ * ```typescript
+ * // Store metadata for DOM elements without preventing garbage collection
+ * const elementMetadata = new DefaultWeakMap<HTMLElement, { clicks: number; hovers: number }>(
+ *   () => ({ clicks: 0, hovers: 0 })
+ * )
+ *
+ * const button = document.querySelector('button')!
+ * const div = document.querySelector('div')!
+ *
+ * elementMetadata.get(button).clicks++
+ * elementMetadata.get(button).clicks++
+ * elementMetadata.get(div).hovers++
+ *
+ * console.log(elementMetadata.get(button)) // { clicks: 2, hovers: 0 }
+ * console.log(elementMetadata.get(div))    // { clicks: 0, hovers: 1 }
+ * // When elements are removed from DOM and not referenced,
+ * // their metadata can be garbage collected
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Cache computed properties for objects
+ * const computedCache = new DefaultWeakMap<object, Map<string, any>>(
+ *   () => new Map()
+ * )
+ *
+ * function getOrCompute(obj: object, key: string, compute: () => any) {
+ *   const cache = computedCache.get(obj)
+ *   if (!cache.has(key)) {
+ *     cache.set(key, compute())
+ *   }
+ *   return cache.get(key)
+ * }
+ *
+ * const user = { name: 'Alice', age: 30 }
+ * const displayName = getOrCompute(user, 'displayName', () => user.name.toUpperCase())
+ * const birthYear = getOrCompute(user, 'birthYear', () => new Date().getFullYear() - user.age)
+ *
+ * console.log(displayName) // 'ALICE'
+ * console.log(birthYear)   // 1994 (or current year - 30)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Initialize with existing entries
+ * const obj1 = {}
+ * const obj2 = {}
+ *
+ * const objectData = new DefaultWeakMap<object, string[]>(
+ *   () => [],
+ *   [
+ *     [obj1, ['tag1', 'tag2']],
+ *     [obj2, ['tag3']]
+ *   ]
+ * )
+ *
+ * objectData.get(obj1).push('tag4')
+ * console.log(objectData.get(obj1))  // ['tag1', 'tag2', 'tag4']
+ * console.log(objectData.get(obj2))  // ['tag3']
+ *
+ * const obj3 = {}
+ * console.log(objectData.get(obj3))  // [] (auto-created)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Track event listeners per element using both DefaultWeakMap and DefaultMap
+ * const eventListeners = new DefaultWeakMap<EventTarget, DefaultMap<string, Function[]>>(
+ *   () => new DefaultMap<string, Function[]>(() => [])
+ * )
+ *
+ * function addListener(target: EventTarget, event: string, handler: Function) {
+ *   eventListeners.get(target).get(event).push(handler)
+ * }
+ *
+ * const element = document.createElement('button')
+ * addListener(element, 'click', () => console.log('clicked'))
+ * addListener(element, 'click', () => console.log('also clicked'))
+ * addListener(element, 'hover', () => console.log('hovered'))
+ *
+ * console.log(eventListeners.get(element).get('click').length)  // 2
+ * console.log(eventListeners.get(element).get('hover').length)  // 1
+ * // No need for has() checks or null assertions - everything auto-initializes!
+ * ```
  */
 export class DefaultWeakMap<K extends WeakKey, V> extends WeakMap<K, V> {
   private readonly defaultFactory: () => V
@@ -46,53 +194,3 @@ export class DefaultWeakMap<K extends WeakKey, V> extends WeakMap<K, V> {
     return value
   }
 }
-
-/**
- * A map that counts occurrences of keys.
- *
- * Similar to Python's [Counter](https://docs.python.org/3.13/library/collections.html#collections.Counter).
- */
-export class Counter<K> extends DefaultMap<K, number> {
-  constructor(iterable?: Iterable<readonly [K, number]>) {
-    super(() => 0, iterable)
-  }
-
-  /**
-   * Increments the count for a key by a given amount (default 1).
-   */
-  increment(key: K, amount = 1): void {
-    this.set(key, this.get(key) + amount)
-  }
-
-  /**
-   * Decrements the count for a key by a given amount (default 1).
-   */
-  decrement(key: K, amount = 1): void {
-    this.set(key, this.get(key) - amount)
-  }
-}
-
-/**
- * A weak map that counts occurrences of object keys.
- *
- * Similar to Counter but uses WeakMap as the base, allowing garbage collection of keys.
- */
-export class WeakCounter<K extends WeakKey> extends DefaultWeakMap<K, number> {
-  constructor(entries?: readonly (readonly [K, number])[] | null) {
-    super(() => 0, entries)
-  }
-
-  /**
-   * Increments the count for a key by a given amount (default 1).
-   */
-  increment(key: K, amount = 1): void {
-    this.set(key, this.get(key) + amount)
-  }
-
-  /**
-   * Decrements the count for a key by a given amount (default 1).
-   */
-  decrement(key: K, amount = 1): void {
-    this.set(key, this.get(key) - amount)
-  }
-}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './checker'
-export { Counter, DefaultMap, DefaultWeakMap, WeakCounter } from './default-map'
+export { Counter, WeakCounter } from './counter'
+export { DefaultMap, DefaultWeakMap } from './default-map'
 export * from './dom'
 export { formatBytes } from './format-bytes'
 export { getId } from './get-id'

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

@@ -1,20 +1,12 @@
-import { describe, it, expect } from 'vitest'
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 
-import {
-  mapGroupBy,
-  mapGroupByPolyfill,
-  mapGroupByNative,
-} from './map-group-by'
+import { mapGroupBy, mapGroupByPolyfill } 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]
@@ -76,3 +68,24 @@ describe.each(testCases)('$name', ({ fn }) => {
     expect(result.get(1)).toEqual([1, 3, 5])
   })
 })
+
+describe('mapGroupBy', () => {
+  beforeEach(() => {
+    if ('groupBy' in Map) {
+      // @ts-expect-error - spy
+      vi.spyOn(Map, 'groupBy', 'get').mockReturnValueOnce(undefined)
+    }
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('falls back to polyfill when Map.groupBy is not available', () => {
+    const items = [1, 2, 3, 4, 5, 6]
+    const result = mapGroupBy(items, (item) => item % 2)
+
+    expect(result.get(0)).toEqual([2, 4, 6])
+    expect(result.get(1)).toEqual([1, 3, 5])
+  })
+})

package/src/map-group-by.ts

@@ -21,23 +21,15 @@ export function mapGroupByPolyfill<K, T>(
 }
 
 /**
- * @internal
- */
-export function mapGroupByNative<K, T>(
-  items: Iterable<T>,
-  keySelector: (item: T, index: number) => K,
-): Map<K, T[]> {
-  return Map.groupBy(items, keySelector)
-}
-
-const hasMapGroupBy: boolean = /* @__PURE__ */ (() => !!Map.groupBy)()
-
-/**
- * A polyfill for the `Map.groupBy` static method.
+ * A polyfill for the [`Map.groupBy()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/groupBy) static method.
  *
  * @public
  */
-export const mapGroupBy: <K, T>(
+export function mapGroupBy<K, T>(
   items: Iterable<T>,
   keySelector: (item: T, index: number) => K,
-) => Map<K, T[]> = hasMapGroupBy ? mapGroupByNative : mapGroupByPolyfill
+): Map<K, T[]> {
+  return Map.groupBy
+    ? Map.groupBy(items, keySelector)
+    : mapGroupByPolyfill(items, keySelector)
+}

package/src/map-values.ts

@@ -35,7 +35,7 @@ export function mapValues<ValueIn, ValueOut>(
   object: Record<string, ValueIn>,
   callback: (value: ValueIn, key: string) => ValueOut,
 ): Record<string, ValueOut> {
-  let result = {} as Record<string, ValueOut>
+  const result = {} as Record<string, ValueOut>
   for (const [key, value] of Object.entries(object)) {
     result[key] = callback(value, key)
   }

package/src/object-entries.ts

@@ -17,13 +17,16 @@ export type ObjectEntries<T extends Record<string, any>> = {
 }[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.
+ * A type-safe wrapper around
+ * [`Object.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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.
+ * 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
@@ -53,6 +56,8 @@ export type ObjectEntries<T extends Record<string, any>> = {
  *
  * @public
  */
-export const objectEntries: <T extends Record<string, any>>(
+export function objectEntries<T extends Record<string, any>>(
   obj: T,
-) => ObjectEntries<T>[] = Object.entries
+): ObjectEntries<T>[] {
+  return Object.entries(obj)
+}

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

@@ -1,20 +1,12 @@
-import { describe, it, expect } from 'vitest'
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest'
 
-import {
-  objectGroupBy,
-  objectGroupByPolyfill,
-  objectGroupByNative,
-} from './object-group-by'
+import { objectGroupBy, objectGroupByPolyfill } 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]
@@ -84,3 +76,26 @@ describe.each(testCases)('$name', ({ fn }) => {
     expect(result.odd).toEqual([1, 3, 5])
   })
 })
+
+describe('objectGroupBy', () => {
+  beforeEach(() => {
+    if ('groupBy' in Object) {
+      // @ts-expect-error - spy
+      vi.spyOn(Object, 'groupBy', 'get').mockReturnValueOnce(undefined)
+    }
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('falls back to polyfill when Object.groupBy is not available', () => {
+    const items = [1, 2, 3, 4, 5, 6]
+    const result = objectGroupBy(items, (item) =>
+      item % 2 === 0 ? 'even' : 'odd',
+    )
+
+    expect(result.even).toEqual([2, 4, 6])
+    expect(result.odd).toEqual([1, 3, 5])
+  })
+})

package/src/object-group-by.ts

@@ -21,25 +21,15 @@ export function objectGroupByPolyfill<K extends PropertyKey, T>(
 }
 
 /**
- * @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)
-}
-
-const hasObjectGroupBy: boolean = /* @__PURE__ */ (() => !!Object.groupBy)()
-
-/**
- * A polyfill for the `Object.groupBy` static method.
+ * A polyfill for the [`Object.groupBy()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy) static method.
  *
  * @public
  */
-export const objectGroupBy: <K extends PropertyKey, T>(
+export function objectGroupBy<K extends PropertyKey, T>(
   items: Iterable<T>,
   keySelector: (item: T, index: number) => K,
-) => Partial<Record<K, T[]>> = hasObjectGroupBy
-  ? objectGroupByNative
-  : objectGroupByPolyfill
+): Partial<Record<K, T[]>> {
+  return Object.groupBy
+    ? Object.groupBy(items, keySelector)
+    : objectGroupByPolyfill(items, keySelector)
+}

package/src/once.test.ts

@@ -1,8 +1,6 @@
 // @vitest-environment node
 
-import path from 'node:path'
-
-import { describe, it, expect, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 import { once } from './once'
 
@@ -25,31 +23,4 @@ describe('once', () => {
     const getValue = once(() => value)
     expect(getValue()).toBe(value)
   })
-
-  it('can tree-shake', async () => {
-    const esbuild = await import('esbuild')
-    const cwd = import.meta.dirname
-    const input = path.join(cwd, 'once-stub-2.ts')
-
-    const result = await esbuild.build({
-      entryPoints: [input],
-      format: 'esm',
-      platform: 'neutral',
-      minify: true,
-      bundle: true,
-      write: false,
-      absWorkingDir: cwd,
-    })
-
-    const files = result.outputFiles.map((file) => {
-      return file.text
-    })
-
-    expect(files).toMatchInlineSnapshot(`
-      [
-        "function t(n){let o=!1,e;return()=>(o||(e=n(),o=!0,n=void 0),e)}function r(){console.log("fn1")}var u=t(r);function f(){console.log("fn2")}f();
-      ",
-      ]
-    `)
-  })
 })

package/src/sleep.ts

@@ -1,5 +1,12 @@
 /**
- * Sleep for a given number of milliseconds.
+ * Returns a Promise that resolves after a specified number of milliseconds.
+ *
+ * @param ms - The number of milliseconds to wait.
+ *
+ * @example
+ * ```js
+ * await sleep(1000)  // Wait 1 second
+ * ```
  */
 export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))