@ocavue/utils 1.2.0 → 1.3.1

package/src/default-map.test.ts

@@ -2,7 +2,7 @@
 
 import { describe, it, expect } from 'vitest'
 
-import { DefaultMap } from './default-map'
+import { DefaultMap, DefaultWeakMap } from './default-map'
 
 describe('DefaultMap', () => {
   it('creates default values for missing keys', () => {
@@ -184,3 +184,100 @@ describe('DefaultMap', () => {
     expect(map.get('group2').get('item1')).toBe(0)
   })
 })
+
+describe('DefaultWeakMap', () => {
+  it('creates default values for missing keys', () => {
+    const map = new DefaultWeakMap<object, number>(() => 0)
+    const key1 = {}
+    const key2 = {}
+
+    expect(map.get(key1)).toBe(0)
+    expect(map.get(key2)).toBe(0)
+  })
+
+  it('returns existing values for set keys', () => {
+    const map = new DefaultWeakMap<object, number>(() => 0)
+    const key = {}
+
+    map.set(key, 42)
+    expect(map.get(key)).toBe(42)
+  })
+
+  it('stores the default value when accessing missing key', () => {
+    const map = new DefaultWeakMap<object, number>(() => 5)
+    const key = {}
+
+    const value = map.get(key)
+    expect(value).toBe(5)
+    expect(map.has(key)).toBe(true)
+    expect(map.get(key)).toBe(5)
+  })
+
+  it('works with array factory', () => {
+    const map = new DefaultWeakMap<object, string[]>(() => [])
+    const key1 = {}
+    const key2 = {}
+
+    map.get(key1).push('item1')
+    map.get(key1).push('item2')
+    map.get(key2).push('item3')
+
+    expect(map.get(key1)).toEqual(['item1', 'item2'])
+    expect(map.get(key2)).toEqual(['item3'])
+  })
+
+  it('accepts initial entries', () => {
+    const key1 = {}
+    const key2 = {}
+    const key3 = {}
+    const initialEntries: [object, number][] = [
+      [key1, 1],
+      [key2, 2],
+      [key3, 3],
+    ]
+    const map = new DefaultWeakMap<object, number>(() => 0, initialEntries)
+
+    expect(map.get(key1)).toBe(1)
+    expect(map.get(key2)).toBe(2)
+    expect(map.get(key3)).toBe(3)
+
+    const key4 = {}
+    expect(map.get(key4)).toBe(0)
+  })
+
+  it('calls factory function only when key is missing', () => {
+    let callCount = 0
+    const map = new DefaultWeakMap<object, number>(() => {
+      callCount++
+      return 42
+    })
+    const existing = {}
+    const newKey = {}
+
+    map.set(existing, 100)
+
+    map.get(existing)
+    expect(callCount).toBe(0)
+
+    map.get(newKey)
+    expect(callCount).toBe(1)
+
+    map.get(newKey)
+    expect(callCount).toBe(1)
+  })
+
+  it('works with delete method', () => {
+    const map = new DefaultWeakMap<object, number>(() => 10)
+    const key = {}
+
+    map.get(key)
+    expect(map.has(key)).toBe(true)
+
+    map.delete(key)
+    expect(map.has(key)).toBe(false)
+
+    const value = map.get(key)
+    expect(value).toBe(10)
+    expect(map.has(key)).toBe(true)
+  })
+})

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
@@ -20,3 +82,115 @@ export class DefaultMap<K, V> extends Map<K, V> {
     return value
   }
 }
+
+/**
+ * A weak map that automatically creates values for missing keys using a factory function.
+ *
+ * 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
+
+  constructor(
+    defaultFactory: () => V,
+    entries?: readonly (readonly [K, V])[] | null,
+  ) {
+    super(entries)
+    this.defaultFactory = defaultFactory
+  }
+
+  override get(key: K): V {
+    if (this.has(key)) {
+      return super.get(key)!
+    }
+    const value = this.defaultFactory()
+    this.set(key, value)
+    return value
+  }
+}

package/src/e2e.test.ts

@@ -0,0 +1,36 @@
+// @vitest-environment node
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { x } from 'tinyexec'
+import { glob } from 'tinyglobby'
+import { describe, it, expect, beforeAll } from 'vitest'
+
+const ROOT_DIR = path.join(import.meta.dirname, '..')
+const E2E_OUT_DIR = path.join(ROOT_DIR, 'e2e', 'dist')
+
+describe('e2e', () => {
+  beforeAll(async () => {
+    await x('pnpm', ['-w', 'build'], {
+      nodeOptions: { cwd: ROOT_DIR, stdio: 'inherit' },
+      throwOnError: true,
+    })
+    await x('pnpm', ['--filter', 'e2e', 'run', 'build'], {
+      nodeOptions: { cwd: ROOT_DIR, stdio: 'inherit' },
+      throwOnError: true,
+    })
+  })
+
+  it('bundler outputs match snapshot', async () => {
+    const files = await glob('**/*', { cwd: E2E_OUT_DIR, onlyFiles: true })
+    const output = ['']
+
+    for (const file of files.sort()) {
+      const content = fs.readFileSync(path.join(E2E_OUT_DIR, file), 'utf-8')
+      output.push('#'.repeat(80), file, '-'.repeat(80), content, '')
+    }
+
+    expect(output.join('\n')).toMatchSnapshot()
+  })
+})

package/src/get-id.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 
-import { getId } from './get-id'
+import { getId, setMaxSafeInteger } from './get-id'
 
 describe('getId', () => {
   it('returns a positive number', () => {
@@ -11,4 +11,23 @@ describe('getId', () => {
   it('returns different values on consecutive calls', () => {
     expect(getId()).not.toBe(getId())
   })
+
+  it('never exceeds the configured maximum', () => {
+    const max = 5
+    setMaxSafeInteger(max)
+    let prevId = -1
+
+    try {
+      for (let i = 0; i < max * 3; i += 1) {
+        const id = getId()
+        expect(id).toBeLessThan(max)
+        expect(id).toBeGreaterThanOrEqual(1)
+        expect(id).not.toBe(prevId)
+
+        prevId = id
+      }
+    } finally {
+      setMaxSafeInteger(Number.MAX_SAFE_INTEGER)
+    }
+  })
 })

package/src/get-id.ts

@@ -1,9 +1,23 @@
 let id = 0
 
+let maxSafeInteger = Number.MAX_SAFE_INTEGER
+
+/**
+ * Sets the maximum safe integer for the id generator. Only for testing purposes.
+ *
+ * @internal
+ */
+export function setMaxSafeInteger(max: number) {
+  maxSafeInteger = max
+}
+
 /**
  * Generates a unique positive integer.
  */
 export function getId(): number {
-  id = (id % Number.MAX_SAFE_INTEGER) + 1
+  id++
+  if (id >= maxSafeInteger) {
+    id = 1
+  }
   return id
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './checker'
-export { DefaultMap } 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,21 +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)
-}
-
-/**
- * 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[]> = !!Map.groupBy ? mapGroupByNative : mapGroupByPolyfill
+): Map<K, T[]> {
+  return Map.groupBy
+    ? Map.groupBy(items, keySelector)
+    : mapGroupByPolyfill(items, keySelector)
+}

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,23 +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)
-}
-
-/**
- * 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[]>> = !!Object.groupBy
-  ? objectGroupByNative
-  : objectGroupByPolyfill
+): Partial<Record<K, T[]>> {
+  return Object.groupBy
+    ? Object.groupBy(items, keySelector)
+    : objectGroupByPolyfill(items, keySelector)
+}

package/src/once.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment node
 
-import { describe, it, expect, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 
 import { once } from './once'
 

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))