@monstermann/map 0.1.1 → 0.2.0

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

@@ -1,15 +1,19 @@
 //#region src/Map/clone.d.ts
 /**
+ * # clone
+ *
  * ```ts
- * function Map.clone(target)
+ * function Map.clone<K, V>(target: ReadonlyMap<K, V>): Map<K, V>
  * ```
  *
+ * Creates a shallow copy of the map, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
+ *
  * ## Example
  *
- * ```ts
+ * ```ts [data-first]
  * import { Map } from "@monstermann/map";
  *
- * const original = Map.create([
+ * const original = new Map([
  *     ["a", 1],
  *     ["b", 2],
  * ]);
@@ -17,16 +21,17 @@
  * const copy = Map.clone(original); // Map { 'a' => 1, 'b' => 2 }
  * ```
  *
- * ```ts
+ * ```ts [data-last]
  * import { Map } from "@monstermann/map";
  *
- * const original = Map.create([
+ * const original = new Map([
  *     ["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>;

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

@@ -3,16 +3,20 @@ import { cloneMap } from "@monstermann/remmi";
 
 //#region src/Map/clone.ts
 /**
+* # clone
+*
 * ```ts
-* function Map.clone(target)
+* function Map.clone<K, V>(target: ReadonlyMap<K, V>): Map<K, V>
 * ```
 *
+* Creates a shallow copy of the map, unless marked as mutable with `markAsMutable` inside a mutation context (see [@monstermann/remmi](https://michaelostermann.github.io/remmi/#clonearray-array)).
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
-* const original = Map.create([
+* const original = new Map([
 *     ["a", 1],
 *     ["b", 2],
 * ]);
@@ -20,16 +24,17 @@ import { cloneMap } from "@monstermann/remmi";
 * const copy = Map.clone(original); // Map { 'a' => 1, 'b' => 2 }
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
-* const original = Map.create([
+* const original = new Map([
 *     ["a", 1],
 *     ["b", 2],
 * ]);
 *
 * const copy = pipe(original, Map.clone()); // Map { 'a' => 1, 'b' => 2 }
 * ```
+*
 */
 const clone = dfdlT(cloneMap, 1);
 

package/dist/Map/compact.d.mts

@@ -0,0 +1,48 @@
+//#region src/Map/compact.d.ts
+/**
+ * # compact
+ *
+ * ```ts
+ * function Map.compact<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ * ): ReadonlyMap<K, Exclude<V, null | undefined>>
+ * ```
+ *
+ * Removes all entries with `null` or `undefined` values.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.compact(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", null],
+ *         ["c", undefined],
+ *     ]),
+ * ); // Map(1) { "a" => 1 }
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", null],
+ *         ["c", undefined],
+ *     ]),
+ *     Map.compact(),
+ * ); // Map(1) { "a" => 1 }
+ * ```
+ *
+ */
+declare const compact: {
+  (): <K, V>(target: Map<K, V>) => Map<K, Exclude<V, null | undefined>>;
+  (): <K, V>(target: ReadonlyMap<K, V>) => ReadonlyMap<K, Exclude<V, null | undefined>>;
+  <K, V>(target: Map<K, V>): Map<K, Exclude<V, null | undefined>>;
+  <K, V>(target: ReadonlyMap<K, V>): ReadonlyMap<K, Exclude<V, null | undefined>>;
+};
+//#endregion
+export { compact };

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

@@ -1,19 +1,25 @@
-import { filter } from "./filter.js";
+import { filter } from "./filter.mjs";
 import { dfdlT } from "@monstermann/dfdl";
 
 //#region src/Map/compact.ts
 /**
+* # compact
+*
 * ```ts
-* function Map.compact(map)
+* function Map.compact<K, V>(
+*     target: ReadonlyMap<K, V>,
+* ): ReadonlyMap<K, Exclude<V, null | undefined>>
 * ```
 *
+* Removes all entries with `null` or `undefined` values.
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
 * Map.compact(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *         ["c", undefined],
@@ -21,11 +27,11 @@ import { dfdlT } from "@monstermann/dfdl";
 * ); // Map(1) { "a" => 1 }
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", null],
 *         ["c", undefined],
@@ -33,6 +39,7 @@ import { dfdlT } from "@monstermann/dfdl";
 *     Map.compact(),
 * ); // Map(1) { "a" => 1 }
 * ```
+*
 */
 const compact = dfdlT((target) => {
 	return filter(target, (v) => v != null);

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

@@ -1,9 +1,15 @@
 //#region src/Map/create.d.ts
 /**
+ * # create
+ *
  * ```ts
- * function Map.create(iterable?)
+ * function Map.create<K, V>(
+ *     iterable?: Iterable<readonly [K, V]> | null | undefined,
+ * ): Map<K, V>
  * ```
  *
+ * Creates a new Map from an iterable of key-value pairs.
+ *
  * ## Example
  *
  * ```ts
@@ -13,8 +19,9 @@
  *     ["a", 1],
  *     ["b", 2],
  *     ["c", 3],
- * ]) // Map(2) { "a" => 1, "b" => 2, "c" => 3 }
+ * ]); // Map(2) { "a" => 1, "b" => 2, "c" => 3 }
  * ```
+ *
  */
 declare function create<K, V>(iterable?: Iterable<readonly [K, V]> | null | undefined): Map<K, V>;
 //#endregion

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

@@ -1,9 +1,15 @@
 //#region src/Map/create.ts
 /**
+* # create
+*
 * ```ts
-* function Map.create(iterable?)
+* function Map.create<K, V>(
+*     iterable?: Iterable<readonly [K, V]> | null | undefined,
+* ): Map<K, V>
 * ```
 *
+* Creates a new Map from an iterable of key-value pairs.
+*
 * ## Example
 *
 * ```ts
@@ -13,8 +19,9 @@
 *     ["a", 1],
 *     ["b", 2],
 *     ["c", 3],
-* ]) // Map(2) { "a" => 1, "b" => 2, "c" => 3 }
+* ]); // Map(2) { "a" => 1, "b" => 2, "c" => 3 }
 * ```
+*
 */
 function create(iterable) {
 	return new globalThis.Map(iterable);

package/dist/Map/every.d.mts

@@ -0,0 +1,58 @@
+//#region src/Map/every.d.ts
+/**
+ * # every
+ *
+ * ```ts
+ * function Map.every<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ * ): boolean
+ * ```
+ *
+ * Tests whether all entries in the map pass the test implemented by the `predicate` function. It returns `true` if all entries pass, otherwise `false`.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.every(
+ *     new Map([
+ *         ["a", 2],
+ *         ["b", 4],
+ *         ["c", 6],
+ *     ]),
+ *     (value) => value % 2 === 0,
+ * ); // true
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 2],
+ *         ["b", 4],
+ *         ["c", 6],
+ *     ]),
+ *     Map.every((value) => value % 2 === 0),
+ * ); // true
+ * ```
+ *
+ */
+declare const every: {
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): (target: Map<K, V>) => target is Map<K, U>;
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): (target: ReadonlyMap<K, V>) => target is ReadonlyMap<K, U>;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean): (target: Map<K, V>) => boolean;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean): (target: ReadonlyMap<K, V>) => boolean;
+  <K, V, U extends V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): target is Map<K, U>;
+  <K, V, U extends V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): target is ReadonlyMap<K, U>;
+  <K, V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean): boolean;
+  <K, V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean): boolean;
+};
+//#endregion
+export { every };

package/dist/Map/every.mjs

@@ -0,0 +1,55 @@
+import { dfdlT } from "@monstermann/dfdl";
+
+//#region src/Map/every.ts
+/**
+* # every
+*
+* ```ts
+* function Map.every<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+* ): boolean
+* ```
+*
+* Tests whether all entries in the map pass the test implemented by the `predicate` function. It returns `true` if all entries pass, otherwise `false`.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.every(
+*     new Map([
+*         ["a", 2],
+*         ["b", 4],
+*         ["c", 6],
+*     ]),
+*     (value) => value % 2 === 0,
+* ); // true
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 2],
+*         ["b", 4],
+*         ["c", 6],
+*     ]),
+*     Map.every((value) => value % 2 === 0),
+* ); // true
+* ```
+*
+*/
+const every = dfdlT(((target, predicate) => {
+	for (const [key, value] of target) if (!predicate(value, key, target)) return false;
+	return true;
+}), 2);
+
+//#endregion
+export { every };

package/dist/Map/filter.d.mts

@@ -0,0 +1,58 @@
+//#region src/Map/filter.d.ts
+/**
+ * # filter
+ *
+ * ```ts
+ * function Map.filter<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ * ): ReadonlyMap<K, V>
+ * ```
+ *
+ * Returns a new map containing only entries that satisfy the predicate function.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.filter(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 1,
+ * ); // Map(2) { "b" => 2, "c" => 3 }
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["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: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): (target: Map<K, V>) => Map<K, U>;
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): (target: ReadonlyMap<K, V>) => ReadonlyMap<K, U>;
+  <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, U extends V>(target: Map<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): Map<K, U>;
+  <K, V, U extends V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): ReadonlyMap<K, U>;
+  <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 { filter };

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

@@ -3,17 +3,28 @@ import { cloneMap } from "@monstermann/remmi";
 
 //#region src/Map/filter.ts
 /**
+* # filter
+*
 * ```ts
-* function Map.filter(map, predicate)
+* function Map.filter<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+* ): ReadonlyMap<K, V>
 * ```
 *
+* Returns a new map containing only entries that satisfy the predicate function.
+*
 * ## Example
 *
-* ```ts
+* ```ts [data-first]
 * import { Map } from "@monstermann/map";
 *
 * Map.filter(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *         ["c", 3],
@@ -22,11 +33,11 @@ import { cloneMap } from "@monstermann/remmi";
 * ); // Map(2) { "b" => 2, "c" => 3 }
 * ```
 *
-* ```ts
+* ```ts [data-last]
 * import { Map } from "@monstermann/map";
 *
 * pipe(
-*     Map.create([
+*     new Map([
 *         ["a", 1],
 *         ["b", 2],
 *         ["c", 3],
@@ -34,6 +45,7 @@ import { cloneMap } from "@monstermann/remmi";
 *     Map.filter((value) => value > 1),
 * ); // Map(2) { "b" => 2, "c" => 3 }
 * ```
+*
 */
 const filter = dfdlT((target, predicate) => {
 	let result;

package/dist/Map/find.d.mts

@@ -0,0 +1,54 @@
+//#region src/Map/find.d.ts
+/**
+ * # find
+ *
+ * ```ts
+ * function Map.find<K, V>(
+ *     target: ReadonlyMap<K, V>,
+ *     predicate: (
+ *         value: NoInfer<V>,
+ *         key: NoInfer<K>,
+ *         target: ReadonlyMap<K, V>,
+ *     ) => boolean,
+ * ): V | undefined
+ * ```
+ *
+ * Returns the first value in the map that satisfies the provided `predicate` function, or `undefined` if no value is found.
+ *
+ * ## Example
+ *
+ * ```ts [data-first]
+ * import { Map } from "@monstermann/map";
+ *
+ * Map.find(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     (value) => value > 2,
+ * ); // 3
+ * ```
+ *
+ * ```ts [data-last]
+ * import { Map } from "@monstermann/map";
+ *
+ * pipe(
+ *     new Map([
+ *         ["a", 1],
+ *         ["b", 2],
+ *         ["c", 3],
+ *     ]),
+ *     Map.find((value) => value > 2),
+ * ); // 3
+ * ```
+ *
+ */
+declare const find: {
+  <K, V, U extends V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): (target: ReadonlyMap<K, V>) => U | undefined;
+  <K, V>(predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean): (target: ReadonlyMap<K, V>) => V | undefined;
+  <K, V, U extends V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => value is U): U | undefined;
+  <K, V>(target: ReadonlyMap<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>, target: ReadonlyMap<K, V>) => boolean): V | undefined;
+};
+//#endregion
+export { find };

package/dist/Map/find.mjs

@@ -0,0 +1,54 @@
+import { dfdlT } from "@monstermann/dfdl";
+
+//#region src/Map/find.ts
+/**
+* # find
+*
+* ```ts
+* function Map.find<K, V>(
+*     target: ReadonlyMap<K, V>,
+*     predicate: (
+*         value: NoInfer<V>,
+*         key: NoInfer<K>,
+*         target: ReadonlyMap<K, V>,
+*     ) => boolean,
+* ): V | undefined
+* ```
+*
+* Returns the first value in the map that satisfies the provided `predicate` function, or `undefined` if no value is found.
+*
+* ## Example
+*
+* ```ts [data-first]
+* import { Map } from "@monstermann/map";
+*
+* Map.find(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     (value) => value > 2,
+* ); // 3
+* ```
+*
+* ```ts [data-last]
+* import { Map } from "@monstermann/map";
+*
+* pipe(
+*     new Map([
+*         ["a", 1],
+*         ["b", 2],
+*         ["c", 3],
+*     ]),
+*     Map.find((value) => value > 2),
+* ); // 3
+* ```
+*
+*/
+const find = dfdlT((target, predicate) => {
+	for (const [key, value] of target) if (predicate(value, key, target)) return value;
+}, 2);
+
+//#endregion
+export { find };

package/dist/Map/findMap.d.mts

@@ -0,0 +1,67 @@
+//#region src/Map/findMap.d.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 }
+ * ```
+ *
+ */
+declare const findMap: {
+  <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 { findMap };