@helpers4/map 3.0.2-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +160 -0
- package/README.md +91 -0
- package/lib/index.d.ts +196 -0
- package/lib/index.js +249 -0
- package/lib/index.js.map +1 -0
- package/llms.txt +449 -0
- package/meta/api.json +547 -0
- package/meta/category.json +6 -0
- package/meta/examples.json +155 -0
- package/meta/licenses.json +4 -0
- package/meta/native-alternatives.json +51 -0
- package/package.json +55 -0
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
{
|
|
2
|
+
"category": "map",
|
|
3
|
+
"functions": [
|
|
4
|
+
{
|
|
5
|
+
"name": "countBy",
|
|
6
|
+
"examples": [
|
|
7
|
+
{
|
|
8
|
+
"title": "Count entries by parity",
|
|
9
|
+
"description": "Groups values by a derived key and counts how many fall into each group.",
|
|
10
|
+
"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 }"
|
|
11
|
+
}
|
|
12
|
+
]
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
"name": "every",
|
|
16
|
+
"examples": [
|
|
17
|
+
{
|
|
18
|
+
"title": "Check that all values are positive",
|
|
19
|
+
"description": "Returns false as soon as one entry fails the predicate.",
|
|
20
|
+
"code": "every(new Map([['a', 1], ['b', 2]]), value => value > 0)\n// => true"
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"title": "Empty map",
|
|
24
|
+
"description": "Vacuously true for an empty map.",
|
|
25
|
+
"code": "every(new Map(), () => false)\n// => true"
|
|
26
|
+
}
|
|
27
|
+
]
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
"name": "filter",
|
|
31
|
+
"examples": [
|
|
32
|
+
{
|
|
33
|
+
"title": "Keep only even values",
|
|
34
|
+
"description": "Creates a new Map with only the entries whose value satisfies the predicate.",
|
|
35
|
+
"code": "filter(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0)\n// => Map(1) { 'b' => 2 }"
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"title": "No matches",
|
|
39
|
+
"description": "Returns an empty Map when nothing matches.",
|
|
40
|
+
"code": "filter(new Map([['a', 1]]), () => false)\n// => Map(0) {}"
|
|
41
|
+
}
|
|
42
|
+
]
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"name": "findKey",
|
|
46
|
+
"examples": [
|
|
47
|
+
{
|
|
48
|
+
"title": "Find the key of the first matching entry",
|
|
49
|
+
"description": "Searches in insertion order and returns the key of the first match.",
|
|
50
|
+
"code": "findKey(new Map([['a', 1], ['b', 2]]), value => value > 1)\n// => 'b'"
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"title": "No match",
|
|
54
|
+
"description": "Returns undefined when nothing satisfies the predicate.",
|
|
55
|
+
"code": "findKey(new Map([['a', 1]]), value => value > 10)\n// => undefined"
|
|
56
|
+
}
|
|
57
|
+
]
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"name": "findValue",
|
|
61
|
+
"examples": [
|
|
62
|
+
{
|
|
63
|
+
"title": "Find the first matching value",
|
|
64
|
+
"description": "Searches in insertion order and returns the value of the first match.",
|
|
65
|
+
"code": "findValue(new Map([['a', 1], ['b', 2]]), value => value > 1)\n// => 2"
|
|
66
|
+
},
|
|
67
|
+
{
|
|
68
|
+
"title": "No match",
|
|
69
|
+
"description": "Returns undefined when nothing satisfies the predicate.",
|
|
70
|
+
"code": "findValue(new Map([['a', 1]]), value => value > 10)\n// => undefined"
|
|
71
|
+
}
|
|
72
|
+
]
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
"name": "hasValue",
|
|
76
|
+
"examples": [
|
|
77
|
+
{
|
|
78
|
+
"title": "Check whether a value exists in a Map",
|
|
79
|
+
"description": "Unlike Map.prototype.has (which checks keys), this checks values.",
|
|
80
|
+
"code": "hasValue(new Map([['a', 1], ['b', 2]]), 2)\n// => true"
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
"title": "Value absent",
|
|
84
|
+
"description": "Returns false when no entry has that value.",
|
|
85
|
+
"code": "hasValue(new Map([['a', 1]]), 99)\n// => false"
|
|
86
|
+
}
|
|
87
|
+
]
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
"name": "mapKeys",
|
|
91
|
+
"examples": [
|
|
92
|
+
{
|
|
93
|
+
"title": "Uppercase every key",
|
|
94
|
+
"description": "Creates a new Map with transformed keys and unchanged values.",
|
|
95
|
+
"code": "mapKeys(new Map([['a', 1], ['b', 2]]), key => key.toUpperCase())\n// => Map(2) { 'A' => 1, 'B' => 2 }"
|
|
96
|
+
}
|
|
97
|
+
]
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
"name": "mapValues",
|
|
101
|
+
"examples": [
|
|
102
|
+
{
|
|
103
|
+
"title": "Scale every value",
|
|
104
|
+
"description": "Creates a new Map with transformed values and unchanged keys.",
|
|
105
|
+
"code": "mapValues(new Map([['a', 1], ['b', 2]]), value => value * 10)\n// => Map(2) { 'a' => 10, 'b' => 20 }"
|
|
106
|
+
}
|
|
107
|
+
]
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
"name": "reduce",
|
|
111
|
+
"examples": [
|
|
112
|
+
{
|
|
113
|
+
"title": "Sum all values",
|
|
114
|
+
"description": "Reduces a Map of numbers to their total.",
|
|
115
|
+
"code": "reduce(new Map([['a', 1], ['b', 2], ['c', 3]]), (acc, value) => acc + value, 0)\n// => 6"
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
"title": "Build an array of keys",
|
|
119
|
+
"description": "Reduce can produce a completely different shape than the map values.",
|
|
120
|
+
"code": "reduce(new Map([['a', 1], ['b', 2]]), (acc: string[], _v, key) => [...acc, key], [])\n// => ['a', 'b']"
|
|
121
|
+
}
|
|
122
|
+
]
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
"name": "some",
|
|
126
|
+
"examples": [
|
|
127
|
+
{
|
|
128
|
+
"title": "Check if any value exceeds a threshold",
|
|
129
|
+
"description": "Returns true as soon as one entry satisfies the predicate.",
|
|
130
|
+
"code": "some(new Map([['a', 1], ['b', 2]]), value => value > 1)\n// => true"
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
"title": "Empty map",
|
|
134
|
+
"description": "Always returns false for an empty map.",
|
|
135
|
+
"code": "some(new Map(), () => true)\n// => false"
|
|
136
|
+
}
|
|
137
|
+
]
|
|
138
|
+
},
|
|
139
|
+
{
|
|
140
|
+
"name": "toMapByKey",
|
|
141
|
+
"examples": [
|
|
142
|
+
{
|
|
143
|
+
"title": "Index an array of records by id",
|
|
144
|
+
"description": "Builds a Map keyed by a derived value, for O(1) lookup by that key.",
|
|
145
|
+
"code": "toMapByKey([{ id: 'a', n: 1 }, { id: 'b', n: 2 }], item => item.id)\n// => Map(2) { 'a' => {...}, 'b' => {...} }"
|
|
146
|
+
},
|
|
147
|
+
{
|
|
148
|
+
"title": "Last item wins on collision",
|
|
149
|
+
"description": "When two items derive the same key, the later one overwrites the earlier one.",
|
|
150
|
+
"code": "toMapByKey([{ id: 'a', n: 1 }, { id: 'a', n: 2 }], item => item.id).get('a')\n// => { id: 'a', n: 2 }"
|
|
151
|
+
}
|
|
152
|
+
]
|
|
153
|
+
}
|
|
154
|
+
]
|
|
155
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"category": "map",
|
|
3
|
+
"functions": [
|
|
4
|
+
{
|
|
5
|
+
"name": "forEach",
|
|
6
|
+
"libraries": [
|
|
7
|
+
"es-toolkit"
|
|
8
|
+
],
|
|
9
|
+
"native": "Map.prototype.forEach((value, key, map) => ...)",
|
|
10
|
+
"since": "ES2015",
|
|
11
|
+
"example": "map.forEach((value, key) => console.log(key, value))",
|
|
12
|
+
"notes": "Not implemented — native Map.prototype.forEach already has this exact (value, key, map) signature, nothing to add."
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
"name": "reduce / some / every",
|
|
16
|
+
"libraries": [
|
|
17
|
+
"es-toolkit"
|
|
18
|
+
],
|
|
19
|
+
"native": "map.entries().reduce(fn, init) / .some(fn) / .every(fn)",
|
|
20
|
+
"since": "ES2025 (Iterator Helpers)",
|
|
21
|
+
"example": "map.entries().reduce((acc, [k, v]) => acc + v, 0)\nmap.entries().some(([k, v]) => v > 10)",
|
|
22
|
+
"notes": "Iterator Helpers make these one-liners on map.entries()/.values() — but the callback receives a [key, value] tuple to destructure every time. helpers4/map's versions take (value, key) directly, matching Map.prototype.forEach's own argument order, so they're still provided."
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"name": "findKey / findValue",
|
|
26
|
+
"libraries": [],
|
|
27
|
+
"native": "map.entries().find(([k, v]) => pred(v, k))?.[0 or 1]",
|
|
28
|
+
"since": "ES2025 (Iterator Helpers)",
|
|
29
|
+
"example": "map.entries().find(([k, v]) => v > 10)?.[0] // key\nmap.entries().find(([k, v]) => v > 10)?.[1] // value",
|
|
30
|
+
"notes": "Composable via Iterator Helpers' .find(), but needs a tuple destructure plus an optional-chained index every call site — helpers4/map's versions are still provided for that reason."
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"name": "hasValue",
|
|
34
|
+
"libraries": [],
|
|
35
|
+
"native": "map.values().some(v => Object.is(v, value))",
|
|
36
|
+
"since": "ES2025 (Iterator Helpers)",
|
|
37
|
+
"example": "map.values().some(v => Object.is(v, target))",
|
|
38
|
+
"notes": "Thin wrapper for readability — Map.prototype.has() checks keys, not values, which is the actual reason this needs its own name."
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"name": "countBy / keyBy",
|
|
42
|
+
"libraries": [
|
|
43
|
+
"es-toolkit"
|
|
44
|
+
],
|
|
45
|
+
"native": "Map.groupBy(map.entries(), ([k, v]) => groupFn(v, k))",
|
|
46
|
+
"since": "ES2024",
|
|
47
|
+
"example": "Map.groupBy(map.entries(), ([k, v]) => v % 2 === 0 ? 'even' : 'odd')",
|
|
48
|
+
"notes": "Map.groupBy groups into arrays of matching entries (multiple items per key) — not the same as countBy (counts per group) or the classic keyBy idea (single last-write-wins item per key, implemented here as toMapByKey — see that function's own docs for why it's not named keyBy). Deriving either from Map.groupBy's output is a real extra step, so both remain genuinely useful."
|
|
49
|
+
}
|
|
50
|
+
]
|
|
51
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@helpers4/map",
|
|
3
|
+
"version": "3.0.2-alpha.0",
|
|
4
|
+
"description": "A set of helpers in TS/JS, compatible with tree-shaking, for map.",
|
|
5
|
+
"author": "baxyz <baxy@etik.com>",
|
|
6
|
+
"license": "LGPL-3.0",
|
|
7
|
+
"homepage": "https://helpers4.dev/typescript/categories/map/",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/helpers4/typescript.git"
|
|
11
|
+
},
|
|
12
|
+
"type": "module",
|
|
13
|
+
"sideEffects": false,
|
|
14
|
+
"main": "lib/index.js",
|
|
15
|
+
"types": "lib/index.d.ts",
|
|
16
|
+
"exports": {
|
|
17
|
+
".": {
|
|
18
|
+
"types": "./lib/index.d.ts",
|
|
19
|
+
"import": "./lib/index.js"
|
|
20
|
+
},
|
|
21
|
+
"./meta/api.json": "./meta/api.json",
|
|
22
|
+
"./meta/examples.json": "./meta/examples.json",
|
|
23
|
+
"./meta/licenses.json": "./meta/licenses.json",
|
|
24
|
+
"./llms.txt": "./llms.txt",
|
|
25
|
+
"./package.json": "./package.json"
|
|
26
|
+
},
|
|
27
|
+
"keywords": [
|
|
28
|
+
"helpers",
|
|
29
|
+
"map",
|
|
30
|
+
"countBy",
|
|
31
|
+
"every",
|
|
32
|
+
"filter",
|
|
33
|
+
"findKey",
|
|
34
|
+
"findValue",
|
|
35
|
+
"hasValue",
|
|
36
|
+
"mapKeys",
|
|
37
|
+
"mapValues",
|
|
38
|
+
"reduce",
|
|
39
|
+
"some",
|
|
40
|
+
"toMapByKey"
|
|
41
|
+
],
|
|
42
|
+
"files": [
|
|
43
|
+
"lib/index.js",
|
|
44
|
+
"lib/index.d.ts",
|
|
45
|
+
"lib/index.js.map",
|
|
46
|
+
"meta/",
|
|
47
|
+
"llms.txt",
|
|
48
|
+
"LICENSE.md",
|
|
49
|
+
"package.json",
|
|
50
|
+
"README.md"
|
|
51
|
+
],
|
|
52
|
+
"engines": {
|
|
53
|
+
"node": ">=26.0.0"
|
|
54
|
+
}
|
|
55
|
+
}
|