@ocavue/utils 1.1.0 → 1.3.0

package/src/default-map.ts

@@ -20,3 +20,79 @@ 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 DefaultMap but uses WeakMap as the base, allowing garbage collection of keys.
+ */
+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
+  }
+}
+
+/**
+ * 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/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,10 +1,12 @@
 export * from './checker'
-export { DefaultMap } from './default-map'
+export { Counter, DefaultMap, DefaultWeakMap, WeakCounter } 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'

package/src/map-group-by.ts

@@ -30,6 +30,8 @@ export function mapGroupByNative<K, T>(
   return Map.groupBy(items, keySelector)
 }
 
+const hasMapGroupBy: boolean = /* @__PURE__ */ (() => !!Map.groupBy)()
+
 /**
  * A polyfill for the `Map.groupBy` static method.
  *
@@ -38,4 +40,4 @@ export function mapGroupByNative<K, T>(
 export const mapGroupBy: <K, T>(
   items: Iterable<T>,
   keySelector: (item: T, index: number) => K,
-) => Map<K, T[]> = !!Map.groupBy ? mapGroupByNative : mapGroupByPolyfill
+) => Map<K, T[]> = hasMapGroupBy ? 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.ts

@@ -30,6 +30,8 @@ export function objectGroupByNative<K extends PropertyKey, T>(
   return Object.groupBy(items, keySelector)
 }
 
+const hasObjectGroupBy: boolean = /* @__PURE__ */ (() => !!Object.groupBy)()
+
 /**
  * A polyfill for the `Object.groupBy` static method.
  *
@@ -38,6 +40,6 @@ export function objectGroupByNative<K extends PropertyKey, T>(
 export const objectGroupBy: <K extends PropertyKey, T>(
   items: Iterable<T>,
   keySelector: (item: T, index: number) => K,
-) => Partial<Record<K, T[]>> = !!Object.groupBy
+) => Partial<Record<K, T[]>> = hasObjectGroupBy
   ? objectGroupByNative
   : objectGroupByPolyfill

package/src/once-stub-1.ts

@@ -0,0 +1,13 @@
+import { once } from './once'
+
+function fn1() {
+  console.log('fn1')
+}
+
+const once1 = once(fn1)
+
+function fn2() {
+  console.log('fn2')
+}
+
+export { once1, fn2 }

package/src/once-stub-2.ts

@@ -0,0 +1,3 @@
+import { fn2 } from './once-stub-1'
+
+fn2()

package/src/once.test.ts

@@ -1,5 +1,7 @@
 // @vitest-environment node
 
+import path from 'node:path'
+
 import { describe, it, expect, vi } from 'vitest'
 
 import { once } from './once'
@@ -23,4 +25,31 @@ 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();
+      ",
+      ]
+    `)
+  })
 })