@helpers4/map 3.0.2-alpha.0

package/llms.txt

@@ -0,0 +1,449 @@
+# @helpers4/map
+
+> Tree-shakable TypeScript utility functions for the `map` domain.
+> Package: `@helpers4/map` — Version: 3.0.2
+> License: LGPL-3.0-or-later
+
+## Installation
+
+```sh
+npm install @helpers4/map
+# or
+pnpm add @helpers4/map
+```
+
+## Usage
+
+```typescript
+import { countBy, every, filter, ... } from '@helpers4/map';
+```
+
+## Functions
+
+| Function | Description |
+|---|---|
+| `countBy` | Groups the entries of a Map by a derived key and counts how many fall into each group. |
+| `every` | Checks if every entry of a Map satisfies the predicate. Short-circuits on the first mismatch. |
+| `filter` | Creates a new Map containing only the entries for which the predicate returns true. |
+| `findKey` | Returns the first key of a Map whose entry satisfies the predicate, in insertion order. |
+| `findValue` | Returns the first value of a Map whose entry satisfies the predicate, in insertion order. |
+| `hasValue` | Checks whether a value exists anywhere in a Map (`Map.prototype.has` checks keys, not values). Uses  |
+| `mapKeys` | Creates a new Map with the same values but with each key transformed by a function. If two entries d |
+| `mapValues` | Creates a new Map with the same keys but with each value transformed by a function. |
+| `reduce` | Reduces a Map to a single value by applying a function to each entry, in insertion order. |
+| `some` | Checks if at least one entry of a Map satisfies the predicate. Short-circuits on the first match. |
+| `toMapByKey` | Builds a Map from an iterable of items, keyed by a derived key. When two items derive the same key,  |
+
+---
+
+## API Reference
+
+### `countBy`
+
+Groups the entries of a Map by a derived key and counts how many fall into each group.
+
+```typescript
+import { countBy } from '@helpers4/map';
+
+countBy<K, V, R>(map: ReadonlyMap<K, V>, fn: function): Map<R, number>
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to summarize
+- `fn: function` — Function deriving the grouping key from (value, key)
+
+**Returns:** `Map<R, number>` — A Map from derived key to the number of entries in that group
+
+**Examples:**
+
+*Count entries by parity*
+
+Groups values by a derived key and counts how many fall into each group.
+
+```typescript
+countBy(new Map([['a', 1], ['b', 2], ['c', 3], ['d', 4]]), v => v % 2 === 0 ? 'even' : 'odd')
+// => Map(2) { 'odd' => 2, 'even' => 2 }
+```
+
+---
+
+### `every`
+
+Checks if every entry of a Map satisfies the predicate. Short-circuits on the first mismatch.
+
+```typescript
+import { every } from '@helpers4/map';
+
+every<K, V>(map: ReadonlyMap<K, V>, predicate: function): boolean
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to check
+- `predicate: function` — Function invoked with (value, key)
+
+**Returns:** `boolean` — `true` if all entries match (vacuously `true` for an empty map), `false` otherwise
+
+**Examples:**
+
+*Check that all values are positive*
+
+Returns false as soon as one entry fails the predicate.
+
+```typescript
+every(new Map([['a', 1], ['b', 2]]), value => value > 0)
+// => true
+```
+
+*Empty map*
+
+Vacuously true for an empty map.
+
+```typescript
+every(new Map(), () => false)
+// => true
+```
+
+---
+
+### `filter`
+
+Creates a new Map containing only the entries for which the predicate returns true.
+
+```typescript
+import { filter } from '@helpers4/map';
+
+filter<K, V>(map: ReadonlyMap<K, V>, predicate: function): Map<K, V>
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to filter
+- `predicate: function` — Function invoked with (value, key) — return true to keep the entry
+
+**Returns:** `Map<K, V>` — A new Map with only the matching entries
+
+**Examples:**
+
+*Keep only even values*
+
+Creates a new Map with only the entries whose value satisfies the predicate.
+
+```typescript
+filter(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0)
+// => Map(1) { 'b' => 2 }
+```
+
+*No matches*
+
+Returns an empty Map when nothing matches.
+
+```typescript
+filter(new Map([['a', 1]]), () => false)
+// => Map(0) {}
+```
+
+---
+
+### `findKey`
+
+Returns the first key of a Map whose entry satisfies the predicate, in insertion order.
+
+```typescript
+import { findKey } from '@helpers4/map';
+
+findKey<K, V>(map: ReadonlyMap<K, V>, predicate: function): K | undefined
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to search
+- `predicate: function` — Function invoked with (value, key)
+
+**Returns:** `K | undefined` — The matching key, or `undefined` if none matches
+
+**Examples:**
+
+*Find the key of the first matching entry*
+
+Searches in insertion order and returns the key of the first match.
+
+```typescript
+findKey(new Map([['a', 1], ['b', 2]]), value => value > 1)
+// => 'b'
+```
+
+*No match*
+
+Returns undefined when nothing satisfies the predicate.
+
+```typescript
+findKey(new Map([['a', 1]]), value => value > 10)
+// => undefined
+```
+
+---
+
+### `findValue`
+
+Returns the first value of a Map whose entry satisfies the predicate, in insertion order.
+
+```typescript
+import { findValue } from '@helpers4/map';
+
+findValue<K, V>(map: ReadonlyMap<K, V>, predicate: function): V | undefined
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to search
+- `predicate: function` — Function invoked with (value, key)
+
+**Returns:** `V | undefined` — The matching value, or `undefined` if none matches
+
+**Examples:**
+
+*Find the first matching value*
+
+Searches in insertion order and returns the value of the first match.
+
+```typescript
+findValue(new Map([['a', 1], ['b', 2]]), value => value > 1)
+// => 2
+```
+
+*No match*
+
+Returns undefined when nothing satisfies the predicate.
+
+```typescript
+findValue(new Map([['a', 1]]), value => value > 10)
+// => undefined
+```
+
+---
+
+### `hasValue`
+
+Checks whether a value exists anywhere in a Map (`Map.prototype.has` checks keys, not values).
+Uses `Object.is`-style equality (via `===`, with `NaN` matching `NaN`).
+
+```typescript
+import { hasValue } from '@helpers4/map';
+
+hasValue<K, V>(map: ReadonlyMap<K, V>, value: V): boolean
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to search
+- `value: V` — The value to look for
+
+**Returns:** `boolean` — `true` if the value is found in at least one entry
+
+**Examples:**
+
+*Check whether a value exists in a Map*
+
+Unlike Map.prototype.has (which checks keys), this checks values.
+
+```typescript
+hasValue(new Map([['a', 1], ['b', 2]]), 2)
+// => true
+```
+
+*Value absent*
+
+Returns false when no entry has that value.
+
+```typescript
+hasValue(new Map([['a', 1]]), 99)
+// => false
+```
+
+---
+
+### `mapKeys`
+
+Creates a new Map with the same values but with each key transformed by a function.
+If two entries derive the same new key, the later one (in insertion order) wins.
+
+```typescript
+import { mapKeys } from '@helpers4/map';
+
+mapKeys<K, V, R>(map: ReadonlyMap<K, V>, fn: function): Map<R, V>
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to transform
+- `fn: function` — Function invoked with (key, value) that returns the new key
+
+**Returns:** `Map<R, V>` — A new Map with transformed keys
+
+**Examples:**
+
+*Uppercase every key*
+
+Creates a new Map with transformed keys and unchanged values.
+
+```typescript
+mapKeys(new Map([['a', 1], ['b', 2]]), key => key.toUpperCase())
+// => Map(2) { 'A' => 1, 'B' => 2 }
+```
+
+---
+
+### `mapValues`
+
+Creates a new Map with the same keys but with each value transformed by a function.
+
+```typescript
+import { mapValues } from '@helpers4/map';
+
+mapValues<K, V, R>(map: ReadonlyMap<K, V>, fn: function): Map<K, R>
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to transform
+- `fn: function` — Function invoked with (value, key) that returns the new value
+
+**Returns:** `Map<K, R>` — A new Map with transformed values
+
+**Examples:**
+
+*Scale every value*
+
+Creates a new Map with transformed values and unchanged keys.
+
+```typescript
+mapValues(new Map([['a', 1], ['b', 2]]), value => value * 10)
+// => Map(2) { 'a' => 10, 'b' => 20 }
+```
+
+---
+
+### `reduce`
+
+Reduces a Map to a single value by applying a function to each entry, in insertion order.
+
+```typescript
+import { reduce } from '@helpers4/map';
+
+reduce<K, V, R>(map: ReadonlyMap<K, V>, fn: function, initial: R): R
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to reduce
+- `fn: function` — Function invoked with (accumulator, value, key)
+- `initial: R` — Initial accumulator value
+
+**Returns:** `R` — The final accumulator value
+
+**Examples:**
+
+*Sum all values*
+
+Reduces a Map of numbers to their total.
+
+```typescript
+reduce(new Map([['a', 1], ['b', 2], ['c', 3]]), (acc, value) => acc + value, 0)
+// => 6
+```
+
+*Build an array of keys*
+
+Reduce can produce a completely different shape than the map values.
+
+```typescript
+reduce(new Map([['a', 1], ['b', 2]]), (acc: string[], _v, key) => [...acc, key], [])
+// => ['a', 'b']
+```
+
+---
+
+### `some`
+
+Checks if at least one entry of a Map satisfies the predicate. Short-circuits on the first match.
+
+```typescript
+import { some } from '@helpers4/map';
+
+some<K, V>(map: ReadonlyMap<K, V>, predicate: function): boolean
+```
+
+**Parameters:**
+
+- `map: ReadonlyMap<K, V>` — The Map to check
+- `predicate: function` — Function invoked with (value, key)
+
+**Returns:** `boolean` — `true` if at least one entry matches, `false` otherwise (including for an empty map)
+
+**Examples:**
+
+*Check if any value exceeds a threshold*
+
+Returns true as soon as one entry satisfies the predicate.
+
+```typescript
+some(new Map([['a', 1], ['b', 2]]), value => value > 1)
+// => true
+```
+
+*Empty map*
+
+Always returns false for an empty map.
+
+```typescript
+some(new Map(), () => true)
+// => false
+```
+
+---
+
+### `toMapByKey`
+
+Builds a Map from an iterable of items, keyed by a derived key. When two items derive the
+same key, the later item wins (last-write-wins, matching `Map.prototype.set` semantics).
+
+Named `toMapByKey`, not `keyBy` (lodash's name for the same idea) — lodash's `_.keyBy`
+returns a plain object, not a `Map`; the `to<Type>` prefix (matching `toSorted`/`toReversed`)
+makes the actual return type unambiguous.
+
+```typescript
+import { toMapByKey } from '@helpers4/map';
+
+toMapByKey<T, K>(items: Iterable<T>, fn: function): Map<K, T>
+```
+
+**Parameters:**
+
+- `items: Iterable<T>` — The items to index
+- `fn: function` — Function deriving the key for each item
+
+**Returns:** `Map<K, T>` — A Map from derived key to item
+
+**Examples:**
+
+*Index an array of records by id*
+
+Builds a Map keyed by a derived value, for O(1) lookup by that key.
+
+```typescript
+toMapByKey([{ id: 'a', n: 1 }, { id: 'b', n: 2 }], item => item.id)
+// => Map(2) { 'a' => {...}, 'b' => {...} }
+```
+
+*Last item wins on collision*
+
+When two items derive the same key, the later one overwrites the earlier one.
+
+```typescript
+toMapByKey([{ id: 'a', n: 1 }, { id: 'a', n: 2 }], item => item.id).get('a')
+// => { id: 'a', n: 2 }
+```
+
+---