@helpers4/map 3.0.2-alpha.0

package/meta/api.json

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

package/meta/category.json

@@ -0,0 +1,6 @@
+{
+  "category": "map",
+  "label": "Map",
+  "smallDescription": "Native Map manipulation utilities",
+  "description": "Utilities for working with native Map instances: iteration, filtering, transforming keys/values, and building Maps from arrays"
+}