@monstermann/map 0.1.1 → 0.2.0

package/dist/Map/forEach.d.mts

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

package/dist/Map/{forEach.js → forEach.mjs}

@@ -2,17 +2,28 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Map/forEach.ts
 /**
+* # forEach
+*
 * ```ts
-* function Map.forEach(map, fn)
+* function Map.forEach<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     fn: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => any,
+* ): ReadonlyMap<K, V>
 * ```
 *
+* Executes a function for each entry in the map and returns the original map.
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
 * Map.forEach(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *     ]),
@@ -20,17 +31,18 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // Map(2) { "a" => 1, "b" => 2 }
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["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);

package/dist/Map/{get.d.ts → get.d.mts}

@@ -1,16 +1,23 @@
 //#region src/Map/get.d.ts
 /**
+ * # get
+ *
  * ```ts
- * function Map.get(map, key)
+ * function Map.get<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     key: NoInfer<K>,
+ * ): V | undefined
  * ```
  *
+ * Gets the value associated with the specified key, or `undefined` if the key doesn't exist.
+ *
  * ## Example
  *
- * ```ts
+ * ```ts [data-first]
  * import { Map } from "@monstermann/map";
  *
  * Map.get(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
@@ -18,7 +25,7 @@
  * ); // 1
  *
  * Map.get(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
@@ -26,11 +33,11 @@
  * ); // undefined
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Map } from "@monstermann/map";
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
@@ -38,13 +45,14 @@
  * ); // 1
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
  *     Map.get("c"),
  * ); // undefined
  * ```
+ *
  */
 declare const get: {
   <K, V>(key: NoInfer<K>): (target: ReadonlyMap<K, V>) => V | undefined;

package/dist/Map/{get.js → get.mjs}

@@ -2,17 +2,24 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Map/get.ts
 /**
+* # get
+*
 * ```ts
-* function Map.get(map, key)
+* function Map.get<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     key: NoInfer<K>,
+* ): V | undefined
 * ```
 *
+* Gets the value associated with the specified key, or `undefined` if the key doesn't exist.
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
 * Map.get(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *     ]),
@@ -20,7 +27,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 1
 *
 * Map.get(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *     ]),
@@ -28,11 +35,11 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // undefined
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *     ]),
@@ -40,13 +47,14 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 1
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *     ]),
 *     Map.get("c"),
 * ); // undefined
 * ```
+*
 */
 const get = dfdlT((target, key) => {
 	return target.get(key);

package/dist/Map/{getOr.d.ts → getOr.d.mts}

@@ -1,19 +1,24 @@
-import { NonNil } from "./internals/types.js";
-
 //#region src/Map/getOr.d.ts
-
 /**
+ * # getOr
+ *
  * ```ts
- * function Map.getOr(map, key, or)
+ * function Map.getOr<K, V, U>(
+ *     target: ReadonlyMap<K, V>,
+ *     key: NoInfer<K>,
+ *     or: U,
+ * ): Exclude<V, null | undefined> | U
  * ```
  *
+ * Gets the value associated with the specified key, or returns the fallback value if the value is `null` or `undefined`.
+ *
  * ## Example
  *
- * ```ts
+ * ```ts [data-first]
  * import { Map } from "@monstermann/map";
  *
  * Map.getOr(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -22,7 +27,7 @@ import { NonNil } from "./internals/types.js";
  * ); // 1
  *
  * Map.getOr(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -31,7 +36,7 @@ import { NonNil } from "./internals/types.js";
  * ); // 0
  *
  * Map.getOr(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -40,11 +45,11 @@ import { NonNil } from "./internals/types.js";
  * ); // 0
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Map } from "@monstermann/map";
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -52,7 +57,7 @@ import { NonNil } from "./internals/types.js";
  * ); // 1
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -60,17 +65,18 @@ import { NonNil } from "./internals/types.js";
  * ); // 0
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["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;
+  <K, V, U>(key: NoInfer<K>, or: U): (target: ReadonlyMap<K, V>) => Exclude<V, null | undefined> | U;
+  <K, V, U>(target: ReadonlyMap<K, V>, key: NoInfer<K>, or: U): Exclude<V, null | undefined> | U;
 };
 //#endregion
 export { getOr };

package/dist/Map/{getOr.js → getOr.mjs}

@@ -2,17 +2,25 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Map/getOr.ts
 /**
+* # getOr
+*
 * ```ts
-* function Map.getOr(map, key, or)
+* function Map.getOr<K, V, U>(
+*     target: ReadonlyMap<K, V>,
+*     key: NoInfer<K>,
+*     or: U,
+* ): Exclude<V, null | undefined> | U
 * ```
 *
+* Gets the value associated with the specified key, or returns the fallback value if the value is `null` or `undefined`.
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
 * Map.getOr(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -21,7 +29,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 1
 *
 * Map.getOr(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -30,7 +38,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 0
 *
 * Map.getOr(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -39,11 +47,11 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 0
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -51,7 +59,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 1
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -59,13 +67,14 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 0
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
 *     Map.getOr("c", 0),
 * ); // 0
 * ```
+*
 */
 const getOr = dfdlT((target, key, or) => {
 	return target.get(key) ?? or;

package/dist/Map/{getOrElse.d.ts → getOrElse.d.mts}

@@ -1,19 +1,24 @@
-import { NonNil, OrElse } from "./internals/types.js";
-
 //#region src/Map/getOrElse.d.ts
-
 /**
+ * # getOrElse
+ *
  * ```ts
- * function Map.getOrElse(map, key, orElse)
+ * function Map.getOrElse<K, V, U>(
+ *     target: ReadonlyMap<K, V>,
+ *     key: NoInfer<K>,
+ *     orElse: (target: ReadonlyMap<K, V>) => U,
+ * ): Exclude<V, null | undefined> | U
  * ```
  *
+ * Gets the value associated with the specified key, or calls the provided function to compute a fallback value if the value is `null` or `undefined`.
+ *
  * ## Example
  *
- * ```ts
+ * ```ts [data-first]
  * import { Map } from "@monstermann/map";
  *
  * Map.getOrElse(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -22,7 +27,7 @@ import { NonNil, OrElse } from "./internals/types.js";
  * ); // 1
  *
  * Map.getOrElse(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -31,7 +36,7 @@ import { NonNil, OrElse } from "./internals/types.js";
  * ); // 0
  *
  * Map.getOrElse(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -40,11 +45,11 @@ import { NonNil, OrElse } from "./internals/types.js";
  * ); // 2
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Map } from "@monstermann/map";
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -52,7 +57,7 @@ import { NonNil, OrElse } from "./internals/types.js";
  * ); // 1
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -60,17 +65,18 @@ import { NonNil, OrElse } from "./internals/types.js";
  * ); // 0
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["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;
+  <K, V, U>(key: NoInfer<K>, orElse: (target: ReadonlyMap<K, V>) => U): (target: ReadonlyMap<K, V>) => Exclude<V, null | undefined> | U;
+  <K, V, U>(target: ReadonlyMap<K, V>, key: NoInfer<K>, orElse: (target: ReadonlyMap<K, V>) => U): Exclude<V, null | undefined> | U;
 };
 //#endregion
 export { getOrElse };

package/dist/Map/{getOrElse.js → getOrElse.mjs}

@@ -2,17 +2,25 @@ import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Map/getOrElse.ts
 /**
+* # getOrElse
+*
 * ```ts
-* function Map.getOrElse(map, key, orElse)
+* function Map.getOrElse<K, V, U>(
+*     target: ReadonlyMap<K, V>,
+*     key: NoInfer<K>,
+*     orElse: (target: ReadonlyMap<K, V>) => U,
+* ): Exclude<V, null | undefined> | U
 * ```
 *
+* Gets the value associated with the specified key, or calls the provided function to compute a fallback value if the value is `null` or `undefined`.
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
 * Map.getOrElse(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -21,7 +29,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 1
 *
 * Map.getOrElse(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -30,7 +38,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 0
 *
 * Map.getOrElse(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -39,11 +47,11 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 2
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -51,7 +59,7 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 1
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
@@ -59,13 +67,14 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // 0
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *     ]),
 *     Map.getOrElse("c", (map) => map.size),
 * ); // 2
 * ```
+*
 */
 const getOrElse = dfdlT((target, key, orElse) => {
 	return target.get(key) ?? orElse(target);

package/dist/Map/{getOrThrow.d.ts → getOrThrow.d.mts}

@@ -1,19 +1,23 @@
-import { NonNil } from "./internals/types.js";
-
 //#region src/Map/getOrThrow.d.ts
-
 /**
+ * # getOrThrow
+ *
  * ```ts
- * function Map.getOrThrow(map, key)
+ * function Map.getOrThrow<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     key: NoInfer<K>,
+ * ): Exclude<V, null | undefined>
  * ```
  *
+ * Gets the value associated with the specified key, or throws an error if the value is `null` or `undefined`.
+ *
  * ## Example
  *
- * ```ts
+ * ```ts [data-first]
  * import { Map } from "@monstermann/map";
  *
  * Map.getOrThrow(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
@@ -21,7 +25,7 @@ import { NonNil } from "./internals/types.js";
  * ); // 1
  *
  * Map.getOrThrow(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -29,7 +33,7 @@ import { NonNil } from "./internals/types.js";
  * ); // throws FnError
  *
  * Map.getOrThrow(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
@@ -37,11 +41,11 @@ import { NonNil } from "./internals/types.js";
  * ); // throws FnError
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Map } from "@monstermann/map";
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
@@ -49,7 +53,7 @@ import { NonNil } from "./internals/types.js";
  * ); // 1
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", null],
  *     ]),
@@ -57,17 +61,18 @@ import { NonNil } from "./internals/types.js";
  * ); // throws FnError
  *
  * pipe(
- *     Map.create([
+ *     new Map([
  *         ["a", 1],
  *         ["b", 2],
  *     ]),
  *     Map.getOrThrow("c"),
  * ); // throws FnError
  * ```
+ *
  */
 declare const getOrThrow: {
-  <K, V>(key: NoInfer<K>): (target: ReadonlyMap<K, V>) => NonNil<V>;
-  <K, V>(target: ReadonlyMap<K, V>, key: NoInfer<K>): NonNil<V>;
+  <K, V>(key: NoInfer<K>): (target: ReadonlyMap<K, V>) => Exclude<V, null | undefined>;
+  <K, V>(target: ReadonlyMap<K, V>, key: NoInfer<K>): Exclude<V, null | undefined>;
 };
 //#endregion
 export { getOrThrow };