@helpers4/map 3.0.2-alpha.0

package/lib/index.js

@@ -0,0 +1,249 @@
+//#region helpers/map/countBy.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Groups the entries of a Map by a derived key and counts how many fall into each group.
+* @param map - The Map to summarize
+* @param fn - Function deriving the grouping key from (value, key)
+* @returns A Map from derived key to the number of entries in that group
+* @example
+* countBy(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0 ? 'even' : 'odd')
+* // => Map(2) { 'odd' => 2, 'even' => 1 }
+* @since next
+*/
+function countBy(map, fn) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const [key, value] of map) {
+		const group = fn(value, key);
+		counts.set(group, (counts.get(group) ?? 0) + 1);
+	}
+	return counts;
+}
+//#endregion
+//#region helpers/map/every.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if every entry of a Map satisfies the predicate. Short-circuits on the first mismatch.
+* @param map - The Map to check
+* @param predicate - Function invoked with (value, key)
+* @returns `true` if all entries match (vacuously `true` for an empty map), `false` otherwise
+* @example
+* every(new Map([['a', 1], ['b', 2]]), value => value > 0)
+* // => true
+* @since next
+*/
+function every(map, predicate) {
+	for (const [key, value] of map) if (!predicate(value, key)) return false;
+	return true;
+}
+//#endregion
+//#region helpers/map/filter.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Creates a new Map containing only the entries for which the predicate returns true.
+* @param map - The Map to filter
+* @param predicate - Function invoked with (value, key) — return true to keep the entry
+* @returns A new Map with only the matching entries
+* @example
+* filter(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0)
+* // => Map(1) { 'b' => 2 }
+* @since next
+*/
+function filter(map, predicate) {
+	const result = /* @__PURE__ */ new Map();
+	for (const [key, value] of map) if (predicate(value, key)) result.set(key, value);
+	return result;
+}
+//#endregion
+//#region helpers/map/findKey.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Returns the first key of a Map whose entry satisfies the predicate, in insertion order.
+* @param map - The Map to search
+* @param predicate - Function invoked with (value, key)
+* @returns The matching key, or `undefined` if none matches
+* @example
+* findKey(new Map([['a', 1], ['b', 2]]), value => value > 1)
+* // => 'b'
+* @since next
+*/
+function findKey(map, predicate) {
+	for (const [key, value] of map) if (predicate(value, key)) return key;
+}
+//#endregion
+//#region helpers/map/findValue.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Returns the first value of a Map whose entry satisfies the predicate, in insertion order.
+* @param map - The Map to search
+* @param predicate - Function invoked with (value, key)
+* @returns The matching value, or `undefined` if none matches
+* @example
+* findValue(new Map([['a', 1], ['b', 2]]), value => value > 1)
+* // => 2
+* @since next
+*/
+function findValue(map, predicate) {
+	for (const [key, value] of map) if (predicate(value, key)) return value;
+}
+//#endregion
+//#region helpers/map/hasValue.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* 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`).
+* @param map - The Map to search
+* @param value - The value to look for
+* @returns `true` if the value is found in at least one entry
+* @example
+* hasValue(new Map([['a', 1], ['b', 2]]), 2)
+* // => true
+* @since next
+*/
+function hasValue(map, value) {
+	for (const v of map.values()) if (Object.is(v, value)) return true;
+	return false;
+}
+//#endregion
+//#region helpers/map/mapKeys.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* 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.
+* @param map - The Map to transform
+* @param fn - Function invoked with (key, value) that returns the new key
+* @returns A new Map with transformed keys
+* @example
+* mapKeys(new Map([['a', 1], ['b', 2]]), key => key.toUpperCase())
+* // => Map(2) { 'A' => 1, 'B' => 2 }
+* @since next
+*/
+function mapKeys(map, fn) {
+	const result = /* @__PURE__ */ new Map();
+	for (const [key, value] of map) result.set(fn(key, value), value);
+	return result;
+}
+//#endregion
+//#region helpers/map/mapValues.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Creates a new Map with the same keys but with each value transformed by a function.
+* @param map - The Map to transform
+* @param fn - Function invoked with (value, key) that returns the new value
+* @returns A new Map with transformed values
+* @example
+* mapValues(new Map([['a', 1], ['b', 2]]), value => value * 10)
+* // => Map(2) { 'a' => 10, 'b' => 20 }
+* @since next
+*/
+function mapValues(map, fn) {
+	const result = /* @__PURE__ */ new Map();
+	for (const [key, value] of map) result.set(key, fn(value, key));
+	return result;
+}
+//#endregion
+//#region helpers/map/reduce.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Reduces a Map to a single value by applying a function to each entry, in insertion order.
+* @param map - The Map to reduce
+* @param fn - Function invoked with (accumulator, value, key)
+* @param initial - Initial accumulator value
+* @returns The final accumulator value
+* @example
+* reduce(new Map([['a', 1], ['b', 2]]), (acc, value) => acc + value, 0)
+* // => 3
+* @since next
+*/
+function reduce(map, fn, initial) {
+	let accumulator = initial;
+	for (const [key, value] of map) accumulator = fn(accumulator, value, key);
+	return accumulator;
+}
+//#endregion
+//#region helpers/map/some.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if at least one entry of a Map satisfies the predicate. Short-circuits on the first match.
+* @param map - The Map to check
+* @param predicate - Function invoked with (value, key)
+* @returns `true` if at least one entry matches, `false` otherwise (including for an empty map)
+* @example
+* some(new Map([['a', 1], ['b', 2]]), value => value > 1)
+* // => true
+* @since next
+*/
+function some(map, predicate) {
+	for (const [key, value] of map) if (predicate(value, key)) return true;
+	return false;
+}
+//#endregion
+//#region helpers/map/toMapByKey.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* 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.
+* @param items - The items to index
+* @param fn - Function deriving the key for each item
+* @returns A Map from derived key to item
+* @example
+* toMapByKey([{ id: 'a', n: 1 }, { id: 'b', n: 2 }], item => item.id)
+* // => Map(2) { 'a' => { id: 'a', n: 1 }, 'b' => { id: 'b', n: 2 } }
+* @since next
+*/
+function toMapByKey(items, fn) {
+	const result = /* @__PURE__ */ new Map();
+	for (const item of items) result.set(fn(item), item);
+	return result;
+}
+//#endregion
+export { countBy, every, filter, findKey, findValue, hasValue, mapKeys, mapValues, reduce, some, toMapByKey };
+
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../helpers/map/countBy.ts","../../../helpers/map/every.ts","../../../helpers/map/filter.ts","../../../helpers/map/findKey.ts","../../../helpers/map/findValue.ts","../../../helpers/map/hasValue.ts","../../../helpers/map/mapKeys.ts","../../../helpers/map/mapValues.ts","../../../helpers/map/reduce.ts","../../../helpers/map/some.ts","../../../helpers/map/toMapByKey.ts"],"sourcesContent":["/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Groups the entries of a Map by a derived key and counts how many fall into each group.\n * @param map - The Map to summarize\n * @param fn - Function deriving the grouping key from (value, key)\n * @returns A Map from derived key to the number of entries in that group\n * @example\n * countBy(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0 ? 'even' : 'odd')\n * // => Map(2) { 'odd' => 2, 'even' => 1 }\n * @since next\n */\nexport function countBy<K, V, R>(\n  map: ReadonlyMap<K, V>,\n  fn: (value: V, key: K) => R,\n): Map<R, number> {\n  const counts = new Map<R, number>();\n  for (const [key, value] of map) {\n    const group = fn(value, key);\n    counts.set(group, (counts.get(group) ?? 0) + 1);\n  }\n  return counts;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if every entry of a Map satisfies the predicate. Short-circuits on the first mismatch.\n * @param map - The Map to check\n * @param predicate - Function invoked with (value, key)\n * @returns `true` if all entries match (vacuously `true` for an empty map), `false` otherwise\n * @example\n * every(new Map([['a', 1], ['b', 2]]), value => value > 0)\n * // => true\n * @since next\n */\nexport function every<K, V>(\n  map: ReadonlyMap<K, V>,\n  predicate: (value: V, key: K) => boolean,\n): boolean {\n  for (const [key, value] of map) {\n    if (!predicate(value, key)) return false;\n  }\n  return true;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Creates a new Map containing only the entries for which the predicate returns true.\n * @param map - The Map to filter\n * @param predicate - Function invoked with (value, key) — return true to keep the entry\n * @returns A new Map with only the matching entries\n * @example\n * filter(new Map([['a', 1], ['b', 2], ['c', 3]]), value => value % 2 === 0)\n * // => Map(1) { 'b' => 2 }\n * @since next\n */\nexport function filter<K, V>(\n  map: ReadonlyMap<K, V>,\n  predicate: (value: V, key: K) => boolean,\n): Map<K, V> {\n  const result = new Map<K, V>();\n  for (const [key, value] of map) {\n    if (predicate(value, key)) {\n      result.set(key, value);\n    }\n  }\n  return result;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Returns the first key of a Map whose entry satisfies the predicate, in insertion order.\n * @param map - The Map to search\n * @param predicate - Function invoked with (value, key)\n * @returns The matching key, or `undefined` if none matches\n * @example\n * findKey(new Map([['a', 1], ['b', 2]]), value => value > 1)\n * // => 'b'\n * @since next\n */\nexport function findKey<K, V>(\n  map: ReadonlyMap<K, V>,\n  predicate: (value: V, key: K) => boolean,\n): K | undefined {\n  for (const [key, value] of map) {\n    if (predicate(value, key)) return key;\n  }\n  return undefined;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Returns the first value of a Map whose entry satisfies the predicate, in insertion order.\n * @param map - The Map to search\n * @param predicate - Function invoked with (value, key)\n * @returns The matching value, or `undefined` if none matches\n * @example\n * findValue(new Map([['a', 1], ['b', 2]]), value => value > 1)\n * // => 2\n * @since next\n */\nexport function findValue<K, V>(\n  map: ReadonlyMap<K, V>,\n  predicate: (value: V, key: K) => boolean,\n): V | undefined {\n  for (const [key, value] of map) {\n    if (predicate(value, key)) return value;\n  }\n  return undefined;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks whether a value exists anywhere in a Map (`Map.prototype.has` checks keys, not values).\n * Uses `Object.is`-style equality (via `===`, with `NaN` matching `NaN`).\n * @param map - The Map to search\n * @param value - The value to look for\n * @returns `true` if the value is found in at least one entry\n * @example\n * hasValue(new Map([['a', 1], ['b', 2]]), 2)\n * // => true\n * @since next\n */\nexport function hasValue<K, V>(map: ReadonlyMap<K, V>, value: V): boolean {\n  for (const v of map.values()) {\n    if (Object.is(v, value)) return true;\n  }\n  return false;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Creates a new Map with the same values but with each key transformed by a function.\n * If two entries derive the same new key, the later one (in insertion order) wins.\n * @param map - The Map to transform\n * @param fn - Function invoked with (key, value) that returns the new key\n * @returns A new Map with transformed keys\n * @example\n * mapKeys(new Map([['a', 1], ['b', 2]]), key => key.toUpperCase())\n * // => Map(2) { 'A' => 1, 'B' => 2 }\n * @since next\n */\nexport function mapKeys<K, V, R>(\n  map: ReadonlyMap<K, V>,\n  fn: (key: K, value: V) => R,\n): Map<R, V> {\n  const result = new Map<R, V>();\n  for (const [key, value] of map) {\n    result.set(fn(key, value), value);\n  }\n  return result;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Creates a new Map with the same keys but with each value transformed by a function.\n * @param map - The Map to transform\n * @param fn - Function invoked with (value, key) that returns the new value\n * @returns A new Map with transformed values\n * @example\n * mapValues(new Map([['a', 1], ['b', 2]]), value => value * 10)\n * // => Map(2) { 'a' => 10, 'b' => 20 }\n * @since next\n */\nexport function mapValues<K, V, R>(\n  map: ReadonlyMap<K, V>,\n  fn: (value: V, key: K) => R,\n): Map<K, R> {\n  const result = new Map<K, R>();\n  for (const [key, value] of map) {\n    result.set(key, fn(value, key));\n  }\n  return result;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Reduces a Map to a single value by applying a function to each entry, in insertion order.\n * @param map - The Map to reduce\n * @param fn - Function invoked with (accumulator, value, key)\n * @param initial - Initial accumulator value\n * @returns The final accumulator value\n * @example\n * reduce(new Map([['a', 1], ['b', 2]]), (acc, value) => acc + value, 0)\n * // => 3\n * @since next\n */\nexport function reduce<K, V, R>(\n  map: ReadonlyMap<K, V>,\n  fn: (accumulator: R, value: V, key: K) => R,\n  initial: R,\n): R {\n  let accumulator = initial;\n  for (const [key, value] of map) {\n    accumulator = fn(accumulator, value, key);\n  }\n  return accumulator;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Checks if at least one entry of a Map satisfies the predicate. Short-circuits on the first match.\n * @param map - The Map to check\n * @param predicate - Function invoked with (value, key)\n * @returns `true` if at least one entry matches, `false` otherwise (including for an empty map)\n * @example\n * some(new Map([['a', 1], ['b', 2]]), value => value > 1)\n * // => true\n * @since next\n */\nexport function some<K, V>(\n  map: ReadonlyMap<K, V>,\n  predicate: (value: V, key: K) => boolean,\n): boolean {\n  for (const [key, value] of map) {\n    if (predicate(value, key)) return true;\n  }\n  return false;\n}\n","/**\n * This file is part of helpers4.\n * Copyright (C) 2025 baxyz\n * SPDX-License-Identifier: LGPL-3.0-or-later\n */\n\n/**\n * Builds a Map from an iterable of items, keyed by a derived key. When two items derive the\n * same key, the later item wins (last-write-wins, matching `Map.prototype.set` semantics).\n *\n * Named `toMapByKey`, not `keyBy` (lodash's name for the same idea) — lodash's `_.keyBy`\n * returns a plain object, not a `Map`; the `to<Type>` prefix (matching `toSorted`/`toReversed`)\n * makes the actual return type unambiguous.\n * @param items - The items to index\n * @param fn - Function deriving the key for each item\n * @returns A Map from derived key to item\n * @example\n * toMapByKey([{ id: 'a', n: 1 }, { id: 'b', n: 2 }], item => item.id)\n * // => Map(2) { 'a' => { id: 'a', n: 1 }, 'b' => { id: 'b', n: 2 } }\n * @since next\n */\nexport function toMapByKey<T, K>(items: Iterable<T>, fn: (item: T) => K): Map<K, T> {\n  const result = new Map<K, T>();\n  for (const item of items) {\n    result.set(fn(item), item);\n  }\n  return result;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,SAAgB,QACd,KACA,IACgB;CAChB,MAAM,yBAAS,IAAI,IAAe;CAClC,KAAK,MAAM,CAAC,KAAK,UAAU,KAAK;EAC9B,MAAM,QAAQ,GAAG,OAAO,GAAG;EAC3B,OAAO,IAAI,QAAQ,OAAO,IAAI,KAAK,KAAK,KAAK,CAAC;CAChD;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;ACVA,SAAgB,MACd,KACA,WACS;CACT,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,IAAI,CAAC,UAAU,OAAO,GAAG,GAAG,OAAO;CAErC,OAAO;AACT;;;;;;;;;;;;;;;;;;ACRA,SAAgB,OACd,KACA,WACW;CACX,MAAM,yBAAS,IAAI,IAAU;CAC7B,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,IAAI,UAAU,OAAO,GAAG,GACtB,OAAO,IAAI,KAAK,KAAK;CAGzB,OAAO;AACT;;;;;;;;;;;;;;;;;;ACXA,SAAgB,QACd,KACA,WACe;CACf,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,IAAI,UAAU,OAAO,GAAG,GAAG,OAAO;AAGtC;;;;;;;;;;;;;;;;;;ACRA,SAAgB,UACd,KACA,WACe;CACf,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,IAAI,UAAU,OAAO,GAAG,GAAG,OAAO;AAGtC;;;;;;;;;;;;;;;;;;;ACPA,SAAgB,SAAe,KAAwB,OAAmB;CACxE,KAAK,MAAM,KAAK,IAAI,OAAO,GACzB,IAAI,OAAO,GAAG,GAAG,KAAK,GAAG,OAAO;CAElC,OAAO;AACT;;;;;;;;;;;;;;;;;;;ACLA,SAAgB,QACd,KACA,IACW;CACX,MAAM,yBAAS,IAAI,IAAU;CAC7B,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,OAAO,IAAI,GAAG,KAAK,KAAK,GAAG,KAAK;CAElC,OAAO;AACT;;;;;;;;;;;;;;;;;;ACVA,SAAgB,UACd,KACA,IACW;CACX,MAAM,yBAAS,IAAI,IAAU;CAC7B,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,OAAO,IAAI,KAAK,GAAG,OAAO,GAAG,CAAC;CAEhC,OAAO;AACT;;;;;;;;;;;;;;;;;;;ACRA,SAAgB,OACd,KACA,IACA,SACG;CACH,IAAI,cAAc;CAClB,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,cAAc,GAAG,aAAa,OAAO,GAAG;CAE1C,OAAO;AACT;;;;;;;;;;;;;;;;;;ACXA,SAAgB,KACd,KACA,WACS;CACT,KAAK,MAAM,CAAC,KAAK,UAAU,KACzB,IAAI,UAAU,OAAO,GAAG,GAAG,OAAO;CAEpC,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;ACHA,SAAgB,WAAiB,OAAoB,IAA+B;CAClF,MAAM,yBAAS,IAAI,IAAU;CAC7B,KAAK,MAAM,QAAQ,OACjB,OAAO,IAAI,GAAG,IAAI,GAAG,IAAI;CAE3B,OAAO;AACT"}