@monstermann/map 0.1.1 → 0.2.0

package/dist/Map/findRemoveOrElse.mjs

@@ -0,0 +1,65 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findRemoveOrElse.ts
+/**
+* # findRemoveOrElse
+*
+* ```ts
+* function Map.findRemoveOrElse<K, V, O>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     orElse: (target: ReadonlyMap<K, V>) => O,
+* ): ReadonlyMap<K, V> | O
+* ```
+*
+* Finds the first entry in the map that satisfies the provided `predicate` function and removes it, returning a new map without the removed entry, or the result of calling `orElse` with the map if no entry is found.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.findRemoveOrElse(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (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.findRemoveOrElse(
+*         (value) => value > 10,
+*         (map) => map.size,
+*     ),
+* ); // 3
+* ```
+*
+*/
+const findRemoveOrElse = dfdlT((target, predicate, orElse) => {
+	for (const [key, value] of target) if (predicate(value, key, target)) {
+		const result = cloneMap(target);
+		result.delete(key);
+		return result;
+	}
+	return orElse(target);
+}, 3);
+
+//#endregion
+export { findRemoveOrElse };

package/dist/Map/findRemoveOrThrow.d.mts

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

package/dist/Map/findRemoveOrThrow.mjs

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

package/dist/Map/findReplace.d.mts

@@ -0,0 +1,56 @@
+//#region src/Map/findReplace.d.ts
+/**
+ * # findReplace
+ *
+ * ```ts
+ * function Map.findReplace<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     replacement: NoInfer<V>,
+ * ): ReadonlyMap<K, V>
+ * ```
+ *
+ * Finds the first entry in the map that satisfies the provided `predicate` function and replaces its value with `replacement`, returning a new map with the replaced value.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.findReplace(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 1,
+ *     10,
+ * ); // Map(3) { "a" => 1, "b" => 10, "c" => 3 }
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findReplace((value) => value > 1, 10),
+ * ); // Map(3) { "a" => 1, "b" => 10, "c" => 3 }
+ * ```
+ *
+ */
+declare const findReplace: {
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<V>): (target: Map<K, V>) => Map<K, V>;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<V>): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<V>): Map<K, V>;
+  <K, V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<V>): ReadonlyMap<K, V>;
+};
+//#endregion
+export { findReplace };

package/dist/Map/findReplace.mjs

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

package/dist/Map/findReplaceOr.d.mts

@@ -0,0 +1,58 @@
+//#region src/Map/findReplaceOr.d.ts
+/**
+ * # findReplaceOr
+ *
+ * ```ts
+ * function Map.findReplaceOr<K, V, O>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     replacement: NoInfer<V>,
+ *     or: O,
+ * ): ReadonlyMap<K, V> | O
+ * ```
+ *
+ * Finds the first entry in the map that satisfies the provided `predicate` function and replaces its value with `replacement`, returning a new map with the replaced value, or `or` if no entry is found.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.findReplaceOr(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 10,
+ *     99,
+ *     new Map(),
+ * ); // Map(0) {}
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findReplaceOr((value) => value > 10, 99, new Map()),
+ * ); // Map(0) {}
+ * ```
+ *
+ */
+declare const findReplaceOr: {
+  <K, V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<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, replacement: NoInfer<V>, or: O): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V> | O;
+  <K, V, O>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<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, replacement: NoInfer<V>, or: O): ReadonlyMap<K, V> | O;
+};
+//#endregion
+export { findReplaceOr };

package/dist/Map/findReplaceOr.mjs

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

package/dist/Map/findReplaceOrElse.d.mts

@@ -0,0 +1,62 @@
+//#region src/Map/findReplaceOrElse.d.ts
+/**
+ * # findReplaceOrElse
+ *
+ * ```ts
+ * function Map.findReplaceOrElse<K, V, O>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ *     replacement: NoInfer<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 replaces its value with `replacement`, returning a new map with the replaced 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.findReplaceOrElse(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 10,
+ *     99,
+ *     (map) => map.size,
+ * ); // 3
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.findReplaceOrElse(
+ *         (value) => value > 10,
+ *         99,
+ *         (map) => map.size,
+ *     ),
+ * ); // 3
+ * ```
+ *
+ */
+declare const findReplaceOrElse: {
+  <K, V, O>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<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, replacement: NoInfer<V>, orElse: (target: ReadonlyMap<K, V>) => O): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V> | O;
+  <K, V, O>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean, replacement: NoInfer<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, replacement: NoInfer<V>, orElse: (target: ReadonlyMap<K, V>) => O): ReadonlyMap<K, V> | O;
+};
+//#endregion
+export { findReplaceOrElse };

package/dist/Map/findReplaceOrElse.mjs

@@ -0,0 +1,69 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/findReplaceOrElse.ts
+/**
+* # findReplaceOrElse
+*
+* ```ts
+* function Map.findReplaceOrElse<K, V, O>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+*     replacement: NoInfer<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 replaces its value with `replacement`, returning a new map with the replaced 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.findReplaceOrElse(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 10,
+*     99,
+*     (map) => map.size,
+* ); // 3
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.findReplaceOrElse(
+*         (value) => value > 10,
+*         99,
+*         (map) => map.size,
+*     ),
+* ); // 3
+* ```
+*
+*/
+const findReplaceOrElse = dfdlT((target, predicate, replacement, orElse) => {
+	for (const [key, prev] of target) if (predicate(prev, key, target)) {
+		if (prev === replacement) return target;
+		const result = cloneMap(target);
+		result.set(key, replacement);
+		return result;
+	}
+	return orElse(target);
+}, 4);
+
+//#endregion
+export { findReplaceOrElse };

package/dist/Map/findReplaceOrThrow.d.mts

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

package/dist/Map/findReplaceOrThrow.mjs

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