@ocavue/utils 1.2.0 → 1.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ocavue/utils",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "A collection of utility functions for the browser and other environments",
   "author": "ocavue <ocavue@gmail.com>",
   "license": "MIT",
@@ -37,20 +37,22 @@
     "dist"
   ],
   "devDependencies": {
-    "@ocavue/eslint-config": "^3.6.2",
-    "@ocavue/tsconfig": "^0.6.1",
-    "@size-limit/preset-small-lib": "^11.2.0",
+    "@ocavue/eslint-config": "^3.8.3",
+    "@ocavue/tsconfig": "^0.6.2",
+    "@size-limit/preset-small-lib": "^12.0.0",
     "@types/node": "^24.9.2",
-    "@vitest/coverage-v8": "4.0.13",
-    "eslint": "^9.38.0",
-    "jsdom": "^27.2.0",
-    "pkg-pr-new": "^0.0.60",
-    "prettier": "^3.6.2",
-    "size-limit": "^11.2.0",
-    "tsdown": "^0.16.6",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
+    "jsdom": "^27.4.0",
+    "knip": "^5.79.0",
+    "pkg-pr-new": "^0.0.62",
+    "prettier": "^3.7.4",
+    "size-limit": "^12.0.0",
+    "tinyexec": "^1.0.2",
+    "tinyglobby": "^0.2.15",
+    "tsdown": "^0.18.4",
     "typescript": "^5.9.3",
-    "vite": "^7.2.4",
-    "vitest": "^4.0.13"
+    "vitest": "^4.0.16"
   },
   "publishConfig": {
     "access": "public"
@@ -68,8 +70,13 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "lint": "eslint .",
-    "fix": "eslint --fix . && prettier --write .",
+    "lint": "pnpm run lint:eslint && pnpm run lint:prettier && pnpm run lint:knip",
+    "lint:eslint": "eslint .",
+    "lint:prettier": "prettier --check .",
+    "lint:knip": "knip",
+    "fix": "pnpm run fix:eslint && pnpm run fix:prettier",
+    "fix:eslint": "eslint --fix .",
+    "fix:prettier": "prettier --write .",
     "ci:publish:snapshot": "pkg-pr-new publish --pnpm",
     "test": "vitest",
     "typecheck": "tsc -b"

package/src/__snapshots__/e2e.test.ts.snap

@@ -0,0 +1,247 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`e2e > bundler outputs match snapshot 1`] = `
+"
+################################################################################
+esbuild/fn1.js
+--------------------------------------------------------------------------------
+var s = 2 ** 53 - 1
+function e(t) {
+  let n = !1,
+    r
+  return () => (n || ((r = t()), (n = !0), (t = void 0)), r)
+}
+function o() {
+  console.log('function_1')
+}
+function u() {
+  console.log('function_2')
+}
+var l = e(u)
+function i() {
+  console.log('function_3')
+}
+var p = e(i)
+export { o as fn1 }
+
+
+################################################################################
+esbuild/fn2.js
+--------------------------------------------------------------------------------
+var i = 2 ** 53 - 1
+function e(t) {
+  let n = !1,
+    r
+  return () => (n || ((r = t()), (n = !0), (t = void 0)), r)
+}
+function o() {
+  console.log('function_2')
+}
+var c = e(o)
+function u() {
+  console.log('function_3')
+}
+var l = e(u)
+export { o as fn2 }
+
+
+################################################################################
+esbuild/fn3.js
+--------------------------------------------------------------------------------
+var i = 2 ** 53 - 1
+function e(t) {
+  let n = !1,
+    r
+  return () => (n || ((r = t()), (n = !0), (t = void 0)), r)
+}
+function u() {
+  console.log('function_2')
+}
+var c = e(u)
+function o() {
+  console.log('function_3')
+}
+var l = e(o)
+export { o as fn3 }
+
+
+################################################################################
+esbuild/fn4.js
+--------------------------------------------------------------------------------
+var s = 2 ** 53 - 1
+function e(t) {
+  let n = !1,
+    r
+  return () => (n || ((r = t()), (n = !0), (t = void 0)), r)
+}
+function o() {
+  console.log('function_2')
+}
+var l = e(o)
+function u() {
+  console.log('function_3')
+}
+var p = e(u)
+function i() {
+  console.log('function_4')
+}
+export { i as fn4 }
+
+
+################################################################################
+rolldown/fn1.js
+--------------------------------------------------------------------------------
+function e() {
+  console.log(\`function_1\`)
+}
+export { e as fn1 }
+
+
+################################################################################
+rolldown/fn2.js
+--------------------------------------------------------------------------------
+function e() {
+  console.log(\`function_2\`)
+}
+export { e as fn2 }
+
+
+################################################################################
+rolldown/fn3.js
+--------------------------------------------------------------------------------
+function e() {
+  console.log(\`function_3\`)
+}
+export { e as fn3 }
+
+
+################################################################################
+rolldown/fn4.js
+--------------------------------------------------------------------------------
+function e() {
+  console.log(\`function_4\`)
+}
+export { e as fn4 }
+
+
+################################################################################
+rollup/fn1.js
+--------------------------------------------------------------------------------
+// A function that is not wrapped by \`once()\`
+function fn1() {
+  console.log('function_1')
+}
+
+export { fn1 }
+
+
+################################################################################
+rollup/fn2.js
+--------------------------------------------------------------------------------
+// A function that is wrapped by \`once()\`, but the wrapper is not exported
+function fn2() {
+  console.log('function_2')
+}
+
+export { fn2 }
+
+
+################################################################################
+rollup/fn3.js
+--------------------------------------------------------------------------------
+// A function that is wrapped by \`once()\`, and the wrapper is exported
+function fn3() {
+  console.log('function_3')
+}
+
+export { fn3 }
+
+
+################################################################################
+rollup/fn4.js
+--------------------------------------------------------------------------------
+// A function that is wrapped by \`once()\`, but the wrapper is marked as \`__PURE__\`
+function fn4() {
+  console.log('function_4')
+}
+
+export { fn4 }
+
+
+################################################################################
+rslib/fn1.js
+--------------------------------------------------------------------------------
+function n(n) {
+  let o = !1,
+    c
+  return () => (o || ((c = n()), (o = !0), (n = void 0)), c)
+}
+function o() {
+  console.log('function_1')
+}
+;(n(function () {
+  console.log('function_2')
+}),
+  n(function () {
+    console.log('function_3')
+  }))
+export { o as fn1 }
+
+
+################################################################################
+rslib/fn2.js
+--------------------------------------------------------------------------------
+function n(n) {
+  let o = !1,
+    t
+  return () => (o || ((t = n()), (o = !0), (n = void 0)), t)
+}
+function o() {
+  console.log('function_2')
+}
+;(n(o),
+  n(function () {
+    console.log('function_3')
+  }))
+export { o as fn2 }
+
+
+################################################################################
+rslib/fn3.js
+--------------------------------------------------------------------------------
+function n(n) {
+  let o = !1,
+    t
+  return () => (o || ((t = n()), (o = !0), (n = void 0)), t)
+}
+function o() {
+  console.log('function_3')
+}
+;(n(function () {
+  console.log('function_2')
+}),
+  n(o))
+export { o as fn3 }
+
+
+################################################################################
+rslib/fn4.js
+--------------------------------------------------------------------------------
+function n(n) {
+  let o = !1,
+    c
+  return () => (o || ((c = n()), (o = !0), (n = void 0)), c)
+}
+function o() {
+  console.log('function_4')
+}
+;(n(function () {
+  console.log('function_2')
+}),
+  n(function () {
+    console.log('function_3')
+  }))
+export { o as fn4 }
+
+"
+`;

package/src/counter.test.ts

@@ -0,0 +1,197 @@
+// @vitest-environment node
+
+import { describe, it, expect } from 'vitest'
+
+import { Counter, WeakCounter } from './counter'
+
+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/counter.ts

@@ -0,0 +1,166 @@
+/**
+ * A map that counts occurrences of keys.
+ *
+ * @example
+ * ```typescript
+ * // Count word occurrences
+ * const wordCounter = new Counter<string>()
+ * const words = ['apple', 'banana', 'apple', 'cherry', 'banana', 'apple']
+ *
+ * for (const word of words) {
+ *   wordCounter.increment(word)
+ * }
+ *
+ * console.log(wordCounter.get('apple'))   // 3
+ * console.log(wordCounter.get('banana'))  // 2
+ * console.log(wordCounter.get('cherry'))  // 1
+ * console.log(wordCounter.get('orange'))  // 0 (defaults to 0)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Initialize with existing counts
+ * const counter = new Counter<string>([
+ *   ['red', 5],
+ *   ['blue', 3],
+ *   ['green', 7]
+ * ])
+ *
+ * counter.increment('red', 2)      // red: 5 -> 7
+ * counter.decrement('blue')        // blue: 3 -> 2
+ * counter.increment('yellow')      // yellow: 0 -> 1
+ *
+ * console.log(counter.get('red'))    // 7
+ * console.log(counter.get('blue'))   // 2
+ * console.log(counter.get('yellow')) // 1
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Track event frequencies
+ * const eventCounter = new Counter<string>()
+ *
+ * eventCounter.increment('click', 5)
+ * eventCounter.increment('hover', 3)
+ * eventCounter.increment('click', 2)
+ *
+ * // Get most common events
+ * const events = [...eventCounter.entries()]
+ *   .sort((a, b) => b[1] - a[1])
+ *
+ * console.log(events) // [['click', 7], ['hover', 3]]
+ * ```
+ */
+export class Counter<K> extends Map<K, number> {
+  constructor(iterable?: Iterable<readonly [K, number]>) {
+    super(iterable)
+  }
+
+  override get(key: K): number {
+    return super.get(key) ?? 0
+  }
+
+  /**
+   * 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 {@link Counter} but uses WeakMap as the base, allowing garbage collection of keys.
+ *
+ * @example
+ * ```typescript
+ * // Track reference counts for DOM elements
+ * const elementRefs = new WeakCounter<HTMLElement>()
+ *
+ * function addReference(element: HTMLElement) {
+ *   elementRefs.increment(element)
+ *   console.log(`References: ${elementRefs.get(element)}`)
+ * }
+ *
+ * function removeReference(element: HTMLElement) {
+ *   elementRefs.decrement(element)
+ *   console.log(`References: ${elementRefs.get(element)}`)
+ * }
+ *
+ * const div = document.createElement('div')
+ * addReference(div)     // References: 1
+ * addReference(div)     // References: 2
+ * removeReference(div)  // References: 1
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Count object interactions without preventing garbage collection
+ * const objectInteractions = new WeakCounter<object>()
+ *
+ * function handleInteraction(obj: object, count = 1) {
+ *   objectInteractions.increment(obj, count)
+ * }
+ *
+ * const user = { id: 1, name: 'Alice' }
+ * const session = { sessionId: 'abc123' }
+ *
+ * handleInteraction(user, 3)
+ * handleInteraction(session, 1)
+ * handleInteraction(user, 2)
+ *
+ * console.log(objectInteractions.get(user))     // 5
+ * console.log(objectInteractions.get(session))  // 1
+ * // When user and session are no longer referenced elsewhere,
+ * // they can be garbage collected along with their counts
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Initialize with existing counts
+ * const cache1 = {}
+ * const cache2 = {}
+ * const cache3 = {}
+ *
+ * const hitCounter = new WeakCounter<object>([
+ *   [cache1, 10],
+ *   [cache2, 5],
+ *   [cache3, 15]
+ * ])
+ *
+ * hitCounter.increment(cache1, 3)  // 10 -> 13
+ * console.log(hitCounter.get(cache1))  // 13
+ * console.log(hitCounter.get(cache2))  // 5
+ * ```
+ */
+export class WeakCounter<K extends WeakKey> extends WeakMap<K, number> {
+  constructor(entries?: readonly (readonly [K, number])[] | null) {
+    super(entries)
+  }
+
+  override get(key: K): number {
+    return super.get(key) ?? 0
+  }
+
+  /**
+   * 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)
+  }
+}