@monstermann/map 0.1.2 → 0.2.0

package/dist/Map/findMap.mjs

@@ -0,0 +1,71 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findMap.ts
+/**
+* # findMap
+*
+* ```ts
+* function Map.findMap<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     mapper: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => V,
+* ): ReadonlyMap<K, V>
+* ```
+*
+* Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.findMap(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 1,
+*     (value) => value * 10,
+* ); // Map(3) { "a" => 1, "b" => 20, "c" => 3 }
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.findMap(
+*         (value) => value > 1,
+*         (value) => value * 10,
+*     ),
+* ); // Map(3) { "a" => 1, "b" => 20, "c" => 3 }
+* ```
+*
+*/
+const findMap = dfdlT((target, predicate, mapper) => {
+	for (const [key, prev] of target) if (predicate(prev, key, target)) {
+		const next = mapper(prev, key, target);
+		if (prev === next) return target;
+		const result = cloneMap(target);
+		result.set(key, next);
+		return result;
+	}
+	return target;
+}, 3);
+
+//#endregion
+export { findMap };

package/dist/Map/findMapAll.d.mts

@@ -0,0 +1,67 @@
+//#region src/Map/findMapAll.d.ts
+/**
+ * # findMapAll
+ *
+ * ```ts
+ * function Map.findMapAll<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     mapper: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => V,
+ * ): ReadonlyMap<K, V>
+ * ```
+ *
+ * Finds all entries in the map that satisfy the provided `predicate` function and applies the `mapper` function to each of them, returning a new map with the mapped values.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.findMapAll(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 1,
+ *     (value) => value * 10,
+ * ); // Map(3) { "a" => 1, "b" => 20, "c" => 30 }
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findMapAll(
+ *         (value) => value > 1,
+ *         (value) => value * 10,
+ *     ),
+ * ); // Map(3) { "a" => 1, "b" => 20, "c" => 30 }
+ * ```
+ *
+ */
+declare const findMapAll: {
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: Map<K, V>) => Map<K, V>;
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: Map<K, V>) => Map<K, V>;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V, U extends V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): Map<K, V>;
+  <K, V, U extends V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): ReadonlyMap<K, V>;
+  <K, V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): Map<K, V>;
+  <K, V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): ReadonlyMap<K, V>;
+};
+//#endregion
+export { findMapAll };

package/dist/Map/findMapAll.mjs

@@ -0,0 +1,72 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findMapAll.ts
+/**
+* # findMapAll
+*
+* ```ts
+* function Map.findMapAll<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     mapper: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => V,
+* ): ReadonlyMap<K, V>
+* ```
+*
+* Finds all entries in the map that satisfy the provided `predicate` function and applies the `mapper` function to each of them, returning a new map with the mapped values.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.findMapAll(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 1,
+*     (value) => value * 10,
+* ); // Map(3) { "a" => 1, "b" => 20, "c" => 30 }
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.findMapAll(
+*         (value) => value > 1,
+*         (value) => value * 10,
+*     ),
+* ); // Map(3) { "a" => 1, "b" => 20, "c" => 30 }
+* ```
+*
+*/
+const findMapAll = dfdlT((target, predicate, mapper) => {
+	let result;
+	for (const [key, prev] of target) {
+		if (!predicate(prev, key, target)) continue;
+		const next = mapper(prev, key, target);
+		if (prev === next) continue;
+		result ??= cloneMap(target);
+		result.set(key, next);
+	}
+	return result ?? target;
+}, 3);
+
+//#endregion
+export { findMapAll };

package/dist/Map/findMapOr.d.mts

@@ -0,0 +1,70 @@
+//#region src/Map/findMapOr.d.ts
+/**
+ * # findMapOr
+ *
+ * ```ts
+ * function Map.findMapOr<K, V, O>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     mapper: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => V,
+ *     or: O,
+ * ): ReadonlyMap<K, V> | O
+ * ```
+ *
+ * Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value, or `or` if no entry is found.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.findMapOr(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 10,
+ *     (value) => value * 10,
+ *     new Map(),
+ * ); // Map(0) {}
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findMapOr(
+ *         (value) => value > 10,
+ *         (value) => value * 10,
+ *         new Map(),
+ *     ),
+ * ); // Map(0) {}
+ * ```
+ *
+ */
+declare const findMapOr: {
+  <K, V, U extends V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): (target: Map<K, V>) => Map<K, V> | O;
+  <K, V, U extends V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V> | O;
+  <K, V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): (target: Map<K, V>) => Map<K, V> | O;
+  <K, V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V> | O;
+  <K, V, U extends V, O>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): Map<K, V> | O;
+  <K, V, U extends V, O>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): ReadonlyMap<K, V> | O;
+  <K, V, O>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): Map<K, V> | O;
+  <K, V, O>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, or: O): ReadonlyMap<K, V> | O;
+};
+//#endregion
+export { findMapOr };

package/dist/Map/findMapOr.mjs

@@ -0,0 +1,74 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findMapOr.ts
+/**
+* # findMapOr
+*
+* ```ts
+* function Map.findMapOr<K, V, O>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     mapper: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => V,
+*     or: O,
+* ): ReadonlyMap<K, V> | O
+* ```
+*
+* Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value, or `or` if no entry is found.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.findMapOr(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 10,
+*     (value) => value * 10,
+*     new Map(),
+* ); // Map(0) {}
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.findMapOr(
+*         (value) => value > 10,
+*         (value) => value * 10,
+*         new Map(),
+*     ),
+* ); // Map(0) {}
+* ```
+*
+*/
+const findMapOr = dfdlT((target, predicate, mapper, or) => {
+	for (const [key, prev] of target) if (predicate(prev, key, target)) {
+		const next = mapper(prev, key, target);
+		if (prev === next) return target;
+		const result = cloneMap(target);
+		result.set(key, next);
+		return result;
+	}
+	return or;
+}, 4);
+
+//#endregion
+export { findMapOr };

package/dist/Map/findMapOrElse.d.mts

@@ -0,0 +1,70 @@
+//#region src/Map/findMapOrElse.d.ts
+/**
+ * # findMapOrElse
+ *
+ * ```ts
+ * function Map.findMapOrElse<K, V, O>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     mapper: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => V,
+ *     orElse: (target: ReadonlyMap<K, V>) => O,
+ * ): ReadonlyMap<K, V> | O
+ * ```
+ *
+ * Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value, or the result of calling `orElse` with the map if no entry is found.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.findMapOrElse(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 10,
+ *     (value) => value * 10,
+ *     (map) => map.size,
+ * ); // 3
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findMapOrElse(
+ *         (value) => value > 10,
+ *         (value) => value * 10,
+ *         (map) => map.size,
+ *     ),
+ * ); // 3
+ * ```
+ *
+ */
+declare const findMapOrElse: {
+  <K, V, U extends V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): (target: Map<K, V>) => Map<K, V> | O;
+  <K, V, U extends V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V> | O;
+  <K, V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): (target: Map<K, V>) => Map<K, V> | O;
+  <K, V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V> | O;
+  <K, V, U extends V, O>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): Map<K, V> | O;
+  <K, V, U extends V, O>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): ReadonlyMap<K, V> | O;
+  <K, V, O>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): Map<K, V> | O;
+  <K, V, O>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V, orElse: (target: ReadonlyMap<K, V>) => O): ReadonlyMap<K, V> | O;
+};
+//#endregion
+export { findMapOrElse };

package/dist/Map/findMapOrElse.mjs

@@ -0,0 +1,74 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findMapOrElse.ts
+/**
+* # findMapOrElse
+*
+* ```ts
+* function Map.findMapOrElse<K, V, O>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     mapper: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => V,
+*     orElse: (target: ReadonlyMap<K, V>) => O,
+* ): ReadonlyMap<K, V> | O
+* ```
+*
+* Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value, or the result of calling `orElse` with the map if no entry is found.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.findMapOrElse(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 10,
+*     (value) => value * 10,
+*     (map) => map.size,
+* ); // 3
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.findMapOrElse(
+*         (value) => value > 10,
+*         (value) => value * 10,
+*         (map) => map.size,
+*     ),
+* ); // 3
+* ```
+*
+*/
+const findMapOrElse = dfdlT((target, predicate, mapper, orElse) => {
+	for (const [key, prev] of target) if (predicate(prev, key, target)) {
+		const next = mapper(prev, key, target);
+		if (prev === next) return target;
+		const result = cloneMap(target);
+		result.set(key, next);
+		return result;
+	}
+	return orElse(target);
+}, 4);
+
+//#endregion
+export { findMapOrElse };

package/dist/Map/findMapOrThrow.d.mts

@@ -0,0 +1,67 @@
+//#region src/Map/findMapOrThrow.d.ts
+/**
+ * # findMapOrThrow
+ *
+ * ```ts
+ * function Map.findMapOrThrow<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     mapper: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => V,
+ * ): ReadonlyMap<K, V>
+ * ```
+ *
+ * Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value, or throws an error if no entry is found.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.findMapOrThrow(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 1,
+ *     (value) => value * 10,
+ * ); // Map(3) { "a" => 1, "b" => 20, "c" => 3 }
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findMapOrThrow(
+ *         (value) => value > 1,
+ *         (value) => value * 10,
+ *     ),
+ * ); // Map(3) { "a" => 1, "b" => 20, "c" => 3 }
+ * ```
+ *
+ */
+declare const findMapOrThrow: {
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: Map<K, V>) => Map<K, V>;
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: Map<K, V>) => Map<K, V>;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V, U extends V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): Map<K, V>;
+  <K, V, U extends V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U, mapper: (value: U, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): ReadonlyMap<K, V>;
+  <K, V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): Map<K, V>;
+  <K, V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, mapper: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => V): ReadonlyMap<K, V>;
+};
+//#endregion
+export { findMapOrThrow };

package/dist/Map/findMapOrThrow.mjs

@@ -0,0 +1,71 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findMapOrThrow.ts
+/**
+* # findMapOrThrow
+*
+* ```ts
+* function Map.findMapOrThrow<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     mapper: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => V,
+* ): ReadonlyMap<K, V>
+* ```
+*
+* Finds the first entry in the map that satisfies the provided `predicate` function and applies the `mapper` function to it, returning a new map with the mapped value, or throws an error if no entry is found.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.findMapOrThrow(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 1,
+*     (value) => value * 10,
+* ); // Map(3) { "a" => 1, "b" => 20, "c" => 3 }
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.findMapOrThrow(
+*         (value) => value > 1,
+*         (value) => value * 10,
+*     ),
+* ); // Map(3) { "a" => 1, "b" => 20, "c" => 3 }
+* ```
+*
+*/
+const findMapOrThrow = dfdlT((target, predicate, mapper) => {
+	for (const [key, prev] of target) if (predicate(prev, key, target)) {
+		const next = mapper(prev, key, target);
+		if (prev === next) return target;
+		const result = cloneMap(target);
+		result.set(key, next);
+		return result;
+	}
+	throw new Error("Map.findMapOrThrow: Value not found.");
+}, 3);
+
+//#endregion
+export { findMapOrThrow };