@monstermann/map 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Michael Ostermann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+<div align="center">
+
+<h1>map</h1>
+
+**Functional utilities for maps.**
+
+[Documentation](https://MichaelOstermann.github.io/map)
+
+</div>

package/dist/Map/clone.d.ts

@@ -0,0 +1,32 @@
+//#region src/Map/clone.d.ts
+/**
+ * `Map.clone(target)`
+ *
+ * Creates a shallow copy of a `Map`, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
+ *
+ * ## Example
+ *
+ * ```ts
+ * const original = Map.create([
+ *     ["a", 1],
+ *     ["b", 2],
+ * ]);
+ *
+ * const copy = Map.clone(original); // Map { 'a' => 1, 'b' => 2 }
+ * ```
+ *
+ * ```ts
+ * const original = Map.create([
+ *     ["a", 1],
+ *     ["b", 2],
+ * ]);
+ *
+ * const copy = pipe(original, Map.clone()); // Map { 'a' => 1, 'b' => 2 }
+ * ```
+ */
+declare const clone: {
+  (): <K, V>(target: ReadonlyMap<K, V>) => Map<K, V>;
+  <K, V>(target: ReadonlyMap<K, V>): Map<K, V>;
+};
+//#endregion
+export { clone };

package/dist/Map/clone.js

@@ -0,0 +1,33 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/clone.ts
+/**
+* `Map.clone(target)`
+*
+* Creates a shallow copy of a `Map`, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
+*
+* ## Example
+*
+* ```ts
+* const original = Map.create([
+*     ["a", 1],
+*     ["b", 2],
+* ]);
+*
+* const copy = Map.clone(original); // Map { 'a' => 1, 'b' => 2 }
+* ```
+*
+* ```ts
+* const original = Map.create([
+*     ["a", 1],
+*     ["b", 2],
+* ]);
+*
+* const copy = pipe(original, Map.clone()); // Map { 'a' => 1, 'b' => 2 }
+* ```
+*/
+const clone = dfdlT(cloneMap, 1);
+
+//#endregion
+export { clone };

package/dist/Map/compact.d.ts

@@ -0,0 +1,40 @@
+import { NonNil } from "./internals/types.js";
+
+//#region src/Map/compact.d.ts
+
+/**
+ * `Map.compact(map)`
+ *
+ * Removes all nullable values from `map`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * Map.compact(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *         ["c", undefined],
+ *     ]),
+ * ); // Map(1) { "a" => 1 }
+ * ```
+ *
+ * ```ts
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *         ["c", undefined],
+ *     ]),
+ *     Map.compact(),
+ * ); // Map(1) { "a" => 1 }
+ * ```
+ */
+declare const compact: {
+  (): <K, V>(target: Map<K, V>) => Map<K, NonNil<V>>;
+  (): <K, V>(target: ReadonlyMap<K, V>) => ReadonlyMap<K, NonNil<V>>;
+  <K, V>(target: Map<K, V>): Map<K, NonNil<V>>;
+  <K, V>(target: ReadonlyMap<K, V>): ReadonlyMap<K, NonNil<V>>;
+};
+//#endregion
+export { compact };

package/dist/Map/compact.js

@@ -0,0 +1,38 @@
+import { filter } from "./filter.js";
+import { dfdlT } from "@monstermann/dfdl";
+
+//#region src/Map/compact.ts
+/**
+* `Map.compact(map)`
+*
+* Removes all nullable values from `map`.
+*
+* ## Example
+*
+* ```ts
+* Map.compact(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*         ["c", undefined],
+*     ]),
+* ); // Map(1) { "a" => 1 }
+* ```
+*
+* ```ts
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*         ["c", undefined],
+*     ]),
+*     Map.compact(),
+* ); // Map(1) { "a" => 1 }
+* ```
+*/
+const compact = dfdlT((target) => {
+	return filter(target, (v) => v != null);
+}, 1);
+
+//#endregion
+export { compact };

package/dist/Map/filter.d.ts

@@ -0,0 +1,45 @@
+import { MapGuard, MapPredicate } from "./internals/types.js";
+
+//#region src/Map/filter.d.ts
+
+/**
+ * `Map.filter(map, predicate)`
+ *
+ * Filters `map` by keeping only the entries where `predicate` returns true for the value.
+ *
+ * ## Example
+ *
+ * ```ts
+ * Map.filter(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 1,
+ * ); // Map(2) { "b" => 2, "c" => 3 }
+ * ```
+ *
+ * ```ts
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.filter((value) => value > 1),
+ * ); // Map(2) { "b" => 2, "c" => 3 }
+ * ```
+ */
+declare const filter: {
+  <K, V, U extends V>(predicate: MapGuard<K, V, U>): (target: Map<K, V>) => Map<K, U>;
+  <K, V, U extends V>(predicate: MapGuard<K, V, U>): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, U>;
+  <K, V>(predicate: MapPredicate<K, V>): (target: Map<K, V>) => Map<K, V>;
+  <K, V>(predicate: MapPredicate<K, V>): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V, U extends V>(target: Map<K, V>, predicate: MapGuard<K, V, U>): Map<K, U>;
+  <K, V, U extends V>(target: ReadonlyMap<K, V>, predicate: MapGuard<K, V, U>): ReadonlyMap<K, U>;
+  <K, V>(target: Map<K, V>, predicate: MapPredicate<K, V>): Map<K, V>;
+  <K, V>(target: ReadonlyMap<K, V>, predicate: MapPredicate<K, V>): ReadonlyMap<K, V>;
+};
+//#endregion
+export { filter };

package/dist/Map/filter.js

@@ -0,0 +1,44 @@
+import { dfdlT } from "@monstermann/dfdl";
+import { cloneMap } from "@monstermann/remmi";
+
+//#region src/Map/filter.ts
+/**
+* `Map.filter(map, predicate)`
+*
+* Filters `map` by keeping only the entries where `predicate` returns true for the value.
+*
+* ## Example
+*
+* ```ts
+* Map.filter(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 1,
+* ); // Map(2) { "b" => 2, "c" => 3 }
+* ```
+*
+* ```ts
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.filter((value) => value > 1),
+* ); // Map(2) { "b" => 2, "c" => 3 }
+* ```
+*/
+const filter = dfdlT((target, predicate) => {
+	let result;
+	for (const [key, value] of target) if (!predicate(value, key, target)) {
+		result ??= cloneMap(target);
+		result.delete(key);
+	}
+	return result ?? target;
+}, 2);
+
+//#endregion
+export { filter };

package/dist/Map/forEach.d.ts

@@ -0,0 +1,39 @@
+import { MapMap } from "./internals/types.js";
+
+//#region src/Map/forEach.d.ts
+
+/**
+ * `Map.forEach(map, fn)`
+ *
+ * Executes `fn` for each entry in `map` and returns the original map.
+ *
+ * ## Example
+ *
+ * ```ts
+ * Map.forEach(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *     ]),
+ *     (value, key) => console.log(key, value),
+ * ); // Map(2) { "a" => 1, "b" => 2 }
+ * ```
+ *
+ * ```ts
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *     ]),
+ *     Map.forEach((value, key) => console.log(key, value)),
+ * ); // Map(2) { "a" => 1, "b" => 2 }
+ * ```
+ */
+declare const forEach: {
+  <K, V>(fn: MapMap<K, V, any>): (target: Map<K, V>) => Map<K, V>;
+  <K, V>(fn: MapMap<K, V, any>): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+  <K, V>(target: Map<K, V>, fn: MapMap<K, V, any>): Map<K, V>;
+  <K, V>(target: ReadonlyMap<K, V>, fn: MapMap<K, V, any>): ReadonlyMap<K, V>;
+};
+//#endregion
+export { forEach };

package/dist/Map/forEach.js

@@ -0,0 +1,37 @@
+import { dfdlT } from "@monstermann/dfdl";
+
+//#region src/Map/forEach.ts
+/**
+* `Map.forEach(map, fn)`
+*
+* Executes `fn` for each entry in `map` and returns the original map.
+*
+* ## Example
+*
+* ```ts
+* Map.forEach(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*     ]),
+*     (value, key) => console.log(key, value),
+* ); // Map(2) { "a" => 1, "b" => 2 }
+* ```
+*
+* ```ts
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*     ]),
+*     Map.forEach((value, key) => console.log(key, value)),
+* ); // Map(2) { "a" => 1, "b" => 2 }
+* ```
+*/
+const forEach = dfdlT((target, fn) => {
+	target.forEach(fn);
+	return target;
+}, 2);
+
+//#endregion
+export { forEach };

package/dist/Map/get.d.ts

@@ -0,0 +1,50 @@
+//#region src/Map/get.d.ts
+/**
+ * `Map.get(map, key)`
+ *
+ * Gets the value associated with `key` from `map`, returning `undefined` if the key doesn't exist.
+ *
+ * ## Example
+ *
+ * ```ts
+ * Map.get(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *     ]),
+ *     "a",
+ * ); // 1
+ *
+ * Map.get(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *     ]),
+ *     "c",
+ * ); // undefined
+ * ```
+ *
+ * ```ts
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *     ]),
+ *     Map.get("a"),
+ * ); // 1
+ *
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", 2],
+ *     ]),
+ *     Map.get("c"),
+ * ); // undefined
+ * ```
+ */
+declare const get: {
+  <K, V>(key: NoInfer<K>): (target: ReadonlyMap<K, V>) => V | undefined;
+  <K, V>(target: ReadonlyMap<K, V>, key: NoInfer<K>): V | undefined;
+};
+//#endregion
+export { get };

package/dist/Map/get.js

@@ -0,0 +1,52 @@
+import { dfdlT } from "@monstermann/dfdl";
+
+//#region src/Map/get.ts
+/**
+* `Map.get(map, key)`
+*
+* Gets the value associated with `key` from `map`, returning `undefined` if the key doesn't exist.
+*
+* ## Example
+*
+* ```ts
+* Map.get(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*     ]),
+*     "a",
+* ); // 1
+*
+* Map.get(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*     ]),
+*     "c",
+* ); // undefined
+* ```
+*
+* ```ts
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*     ]),
+*     Map.get("a"),
+* ); // 1
+*
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", 2],
+*     ]),
+*     Map.get("c"),
+* ); // undefined
+* ```
+*/
+const get = dfdlT((target, key) => {
+	return target.get(key);
+}, 2);
+
+//#endregion
+export { get };

package/dist/Map/getOr.d.ts

@@ -0,0 +1,72 @@
+import { NonNil } from "./internals/types.js";
+
+//#region src/Map/getOr.d.ts
+
+/**
+ * `Map.getOr(map, key, or)`
+ *
+ * Gets the value associated with `key` from `map`, returning `or` if the key doesn't exist or the value is nullable.
+ *
+ * ## Example
+ *
+ * ```ts
+ * Map.getOr(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     "a",
+ *     0,
+ * ); // 1
+ *
+ * Map.getOr(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     "b",
+ *     0,
+ * ); // 0
+ *
+ * Map.getOr(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     "c",
+ *     0,
+ * ); // 0
+ * ```
+ *
+ * ```ts
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     Map.getOr("a", 0),
+ * ); // 1
+ *
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     Map.getOr("b", 0),
+ * ); // 0
+ *
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     Map.getOr("c", 0),
+ * ); // 0
+ * ```
+ */
+declare const getOr: {
+  <K, V, U>(key: NoInfer<K>, or: U): (target: ReadonlyMap<K, V>) => NonNil<V> | U;
+  <K, V, U>(target: ReadonlyMap<K, V>, key: NoInfer<K>, or: U): NonNil<V> | U;
+};
+//#endregion
+export { getOr };

package/dist/Map/getOr.js

@@ -0,0 +1,71 @@
+import { dfdlT } from "@monstermann/dfdl";
+
+//#region src/Map/getOr.ts
+/**
+* `Map.getOr(map, key, or)`
+*
+* Gets the value associated with `key` from `map`, returning `or` if the key doesn't exist or the value is nullable.
+*
+* ## Example
+*
+* ```ts
+* Map.getOr(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*     ]),
+*     "a",
+*     0,
+* ); // 1
+*
+* Map.getOr(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*     ]),
+*     "b",
+*     0,
+* ); // 0
+*
+* Map.getOr(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*     ]),
+*     "c",
+*     0,
+* ); // 0
+* ```
+*
+* ```ts
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*     ]),
+*     Map.getOr("a", 0),
+* ); // 1
+*
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*     ]),
+*     Map.getOr("b", 0),
+* ); // 0
+*
+* pipe(
+*     Map.create([
+*         ["a", 1],
+*         ["b", null],
+*     ]),
+*     Map.getOr("c", 0),
+* ); // 0
+* ```
+*/
+const getOr = dfdlT((target, key, or) => {
+	return target.get(key) ?? or;
+}, 3);
+
+//#endregion
+export { getOr };

package/dist/Map/getOrElse.d.ts

@@ -0,0 +1,72 @@
+import { NonNil, OrElse } from "./internals/types.js";
+
+//#region src/Map/getOrElse.d.ts
+
+/**
+ * `Map.getOrElse(map, key, orElse)`
+ *
+ * Gets the value associated with `key` from `map`, calling `orElse` with the map if the key doesn't exist or the value is nullable.
+ *
+ * ## Example
+ *
+ * ```ts
+ * Map.getOrElse(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     "a",
+ *     () => 0,
+ * ); // 1
+ *
+ * Map.getOrElse(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     "b",
+ *     () => 0,
+ * ); // 0
+ *
+ * Map.getOrElse(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     "c",
+ *     (map) => map.size,
+ * ); // 2
+ * ```
+ *
+ * ```ts
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     Map.getOrElse("a", () => 0),
+ * ); // 1
+ *
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     Map.getOrElse("b", () => 0),
+ * ); // 0
+ *
+ * pipe(
+ *     Map.create([
+ *         ["a", 1],
+ *         ["b", null],
+ *     ]),
+ *     Map.getOrElse("c", (map) => map.size),
+ * ); // 2
+ * ```
+ */
+declare const getOrElse: {
+  <K, V, U>(key: NoInfer<K>, orElse: OrElse<K, V, U>): (target: ReadonlyMap<K, V>) => NonNil<V> | U;
+  <K, V, U>(target: ReadonlyMap<K, V>, key: NoInfer<K>, orElse: OrElse<K, V, U>): NonNil<V> | U;
+};
+//#endregion
+export { getOrElse };