ts-data-forge 6.13.1 → 7.0.1

package/src/collections/imap-mapped.mts

@@ -1,3 +1,5 @@
+/* eslint-disable unicorn/prefer-iterator-to-array-at-end */
+import { type WidenLiteral } from 'ts-type-forge';
 import { Optional, pipe } from '../functional/index.mjs';
 import { asUint32 } from '../number/index.mjs';
 import { tp } from '../others/index.mjs';
@@ -34,25 +36,91 @@ import { type MapSetKeyType, type SizeType } from '../types.mjs';
 type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   // Getting information
 
-  /** The number of elements in the map. */
+  /**
+   * The number of elements in the map.
+   *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.isTrue(map.size === 2);
+   * ```
+   */
   size: SizeType.Arr;
 
   /**
    * Checks if a key exists in the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [[{ x: 1, y: 2 }, 'A']],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.isTrue(map.has({ x: 1, y: 2 }));
+   *
+   * assert.isFalse(map.has({ x: 3, y: 4 }));
+   * ```
+   *
    * @param key The key to check.
    * @returns `true` if the key exists, `false` otherwise.
    */
-  has: (key: K) => boolean;
+  has: (key: K | (WidenLiteral<K> & {})) => boolean;
 
   /**
    * Retrieves the value associated with a key.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [[{ x: 1, y: 2 }, 'A']],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.deepStrictEqual(map.get({ x: 1, y: 2 }), Optional.some('A'));
+   *
+   * assert.deepStrictEqual(map.get({ x: 0, y: 0 }), Optional.none);
+   * ```
+   *
    * @param key The key to retrieve.
    * @returns The value associated with the key wrapped with `Optional.some`, or
    *   `Optional.none` if the key does not exist.
    */
-  get: (key: K) => Optional<V>;
+  get: (key: K | (WidenLiteral<K> & {})) => Optional<V>;
 
   // Reducing a value
 
@@ -61,6 +129,34 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
    * type predicate overload that narrows the type of values in the map if the
    * predicate returns true for all elements.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, number, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 2],
+   *     [{ x: 1, y: 0 }, 4],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const allEven = map.every((value) => value % 2 === 0);
+   *
+   * const isNarrowed = map.every((value): value is 2 | 4 => value % 2 === 0);
+   *
+   * assert.isTrue(allEven);
+   *
+   * assert.isTrue(isNarrowed);
+   * ```
+   *
    * @template W The narrowed type of the values.
    * @param predicate A function to test each key-value pair.
    * @returns `true` if all elements satisfy the predicate, `false` otherwise.
@@ -73,6 +169,30 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Checks if at least one element in the map satisfies a predicate.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, number, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 3],
+   *     [{ x: 1, y: 0 }, 7],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.isTrue(map.some((value) => value > 5));
+   *
+   * assert.isFalse(map.some((value) => value > 10));
+   * ```
+   *
    * @param predicate A function to test each key-value pair.
    * @returns `true` if at least one element satisfies the predicate, `false`
    *   otherwise.
@@ -84,6 +204,39 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Deletes a key-value pair from the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const original = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const withoutRight = original.delete({ x: 1, y: 0 });
+   *
+   * assert.deepStrictEqual(
+   *   original.get({ x: 1, y: 0 }),
+   *   Optional.some('right'),
+   * );
+   *
+   * assert.deepStrictEqual(withoutRight.get({ x: 1, y: 0 }), Optional.none);
+   *
+   * assert.isTrue(original.size === 2);
+   *
+   * assert.isTrue(withoutRight.size === 1);
+   * ```
+   *
    * @param key The key to delete.
    * @returns A new IMapMapped instance without the specified key.
    */
@@ -92,6 +245,36 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Sets a key-value pair in the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const base = IMapMapped.create<Point, string, string>(
+   *   [[{ x: 0, y: 0 }, 'origin']],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const updated = base.set({ x: 0, y: 0 }, 'home');
+   *
+   * const extended = base.set({ x: 1, y: 0 }, 'right');
+   *
+   * assert.deepStrictEqual(base.get({ x: 0, y: 0 }), Optional.some('origin'));
+   *
+   * assert.deepStrictEqual(updated.get({ x: 0, y: 0 }), Optional.some('home'));
+   *
+   * assert.deepStrictEqual(
+   *   extended.get({ x: 1, y: 0 }),
+   *   Optional.some('right'),
+   * );
+   * ```
+   *
    * @param key The key to set.
    * @param value The value to associate with the key.
    * @returns A new IMapMapped instance with the specified key-value pair.
@@ -101,6 +284,36 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Updates the value associated with a key using an updater function.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const scores = IMapMapped.create<Point, number, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 10],
+   *     [{ x: 1, y: 0 }, 8],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const boosted = scores.update({ x: 0, y: 0 }, (value) => value + 5);
+   *
+   * const unchanged = scores.update({ x: 9, y: 9 }, (value) => value + 1);
+   *
+   * assert.deepStrictEqual(boosted.get({ x: 0, y: 0 }), Optional.some(15));
+   *
+   * assert.deepStrictEqual(scores.get({ x: 0, y: 0 }), Optional.some(10));
+   *
+   * assert.isTrue(unchanged === scores);
+   * ```
+   *
    * @param key The key whose value to update.
    * @param updater A function that takes the current value and returns the new
    *   value.
@@ -111,6 +324,40 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Applies a series of mutations to the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const base = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const mutated = base.withMutations([
+   *   { type: 'set', key: { x: 2, y: 0 }, value: 'far' },
+   *   { type: 'update', key: { x: 1, y: 0 }, updater: (v) => v.toUpperCase() },
+   *   { type: 'delete', key: { x: 0, y: 0 } },
+   * ]);
+   *
+   * assert.deepStrictEqual(mutated.get({ x: 2, y: 0 }), Optional.some('far'));
+   *
+   * assert.deepStrictEqual(mutated.get({ x: 1, y: 0 }), Optional.some('RIGHT'));
+   *
+   * assert.deepStrictEqual(mutated.get({ x: 0, y: 0 }), Optional.none);
+   *
+   * assert.deepStrictEqual(base.get({ x: 1, y: 0 }), Optional.some('right'));
+   * ```
+   *
    * @param actions An array of mutation actions (delete, set, or update).
    * @returns A new IMapMapped instance with all mutations applied.
    */
@@ -127,6 +374,33 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Maps the values of the map to new values.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, number, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 1],
+   *     [{ x: 1, y: 0 }, 2],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const doubled = map.map((value) => value * 2);
+   *
+   * assert.deepStrictEqual(Array.from(doubled), [
+   *   [{ x: 0, y: 0 }, 2],
+   *   [{ x: 1, y: 0 }, 4],
+   * ]);
+   * ```
+   *
    * @template V2 The type of the new values.
    * @param mapFn A function that maps a value and key to a new value.
    * @returns A new IMapMapped instance with mapped values.
@@ -137,6 +411,33 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
    * Maps the keys of the map to new keys. Note: The key type cannot be changed
    * because `toKey` and `fromKey` would become unusable.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const shifted = map.mapKeys((p) => ({ x: p.x + 10, y: p.y + 10 }));
+   *
+   * assert.deepStrictEqual(Array.from(shifted), [
+   *   [{ x: 10, y: 10 }, 'origin'],
+   *   [{ x: 11, y: 10 }, 'right'],
+   * ]);
+   * ```
+   *
    * @param mapFn A function that maps a key to a new key of the same type.
    * @returns A new IMapMapped instance with mapped keys.
    */
@@ -145,6 +446,33 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Maps the entries (key-value pairs) of the map to new entries.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, number, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 1],
+   *     [{ x: 1, y: 0 }, 2],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const labeled = map.mapEntries(([key, value]) => [key, `value=${value}`]);
+   *
+   * assert.deepStrictEqual(Array.from(labeled), [
+   *   [{ x: 0, y: 0 }, 'value=1'],
+   *   [{ x: 1, y: 0 }, 'value=2'],
+   * ]);
+   * ```
+   *
    * @template V2 The type of the new values in the entries.
    * @param mapFn A function that maps an entry to a new entry (key must remain
    *   the same type).
@@ -159,6 +487,37 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Executes a callback function for each key-value pair in the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const mut_entries: (readonly [Point, string])[] = [];
+   *
+   * map.forEach((value, key) => {
+   *   mut_entries.push([key, value]);
+   * });
+   *
+   * assert.deepStrictEqual(mut_entries, [
+   *   [{ x: 0, y: 0 }, 'origin'],
+   *   [{ x: 1, y: 0 }, 'right'],
+   * ]);
+   * ```
+   *
    * @param callbackfn A function to execute for each element.
    */
   forEach: (callbackfn: (value: V, key: K) => void) => void;
@@ -168,6 +527,33 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Returns an iterator for the keys in the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const keys = Array.from(map.keys());
+   *
+   * assert.deepStrictEqual(keys, [
+   *   { x: 0, y: 0 },
+   *   { x: 1, y: 0 },
+   * ]);
+   * ```
+   *
    * @returns An iterable iterator of keys.
    */
   keys: () => IterableIterator<K>;
@@ -175,6 +561,30 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Returns an iterator for the values in the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const values = Array.from(map.values());
+   *
+   * assert.deepStrictEqual(values, ['origin', 'right']);
+   * ```
+   *
    * @returns An iterable iterator of values.
    */
   values: () => IterableIterator<V>;
@@ -182,6 +592,33 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Returns an iterator for the entries (key-value pairs) in the map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const entries = Array.from(map.entries());
+   *
+   * assert.deepStrictEqual(entries, [
+   *   [{ x: 0, y: 0 }, 'origin'],
+   *   [{ x: 1, y: 0 }, 'right'],
+   * ]);
+   * ```
+   *
    * @returns An iterable iterator of entries.
    */
   entries: () => IterableIterator<readonly [K, V]>;
@@ -191,6 +628,31 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Converts the keys of the map to an array.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.deepStrictEqual(map.toKeysArray(), [
+   *   { x: 0, y: 0 },
+   *   { x: 1, y: 0 },
+   * ]);
+   * ```
+   *
    * @returns A readonly array of keys.
    */
   toKeysArray: () => readonly K[];
@@ -198,6 +660,28 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Converts the values of the map to an array.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.deepStrictEqual(map.toValuesArray(), ['origin', 'right']);
+   * ```
+   *
    * @returns A readonly array of values.
    */
   toValuesArray: () => readonly V[];
@@ -205,6 +689,31 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Converts the entries (key-value pairs) of the map to an array.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.deepStrictEqual(map.toEntriesArray(), [
+   *   [{ x: 0, y: 0 }, 'origin'],
+   *   [{ x: 1, y: 0 }, 'right'],
+   * ]);
+   * ```
+   *
    * @returns A readonly array of entries.
    */
   toEntriesArray: () => readonly (readonly [K, V])[];
@@ -213,6 +722,31 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
    * Converts the map to an array of entries (key-value pairs). Alias for
    * `toEntriesArray`.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.deepStrictEqual(map.toArray(), [
+   *   [{ x: 0, y: 0 }, 'origin'],
+   *   [{ x: 1, y: 0 }, 'right'],
+   * ]);
+   * ```
+   *
    * @returns A readonly array of entries.
    */
   toArray: () => readonly (readonly [K, V])[];
@@ -220,6 +754,29 @@ type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
   /**
    * Returns the underlying readonly JavaScript Map.
    *
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [[{ x: 1, y: 2 }, 'A']],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const raw = map.toRawMap();
+   *
+   * assert.isTrue(isMap(raw));
+   *
+   * assert.isTrue(raw.get(toKey({ x: 1, y: 2 })) === 'A');
+   * ```
+   *
    * @returns The raw ReadonlyMap instance.
    */
   toRawMap: () => ReadonlyMap<KM, V>;
@@ -276,6 +833,30 @@ export namespace IMapMapped {
    * @template K The type of the custom keys.
    * @template V The type of the values.
    * @template KM The type of the mapped primitive keys.
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.isTrue(map.size === 2);
+   *
+   * assert.deepStrictEqual(map.get({ x: 0, y: 0 }), Optional.some('origin'));
+   * ```
+   *
    * @param iterable An iterable of key-value pairs using the custom key type.
    * @param toKey A function that converts a custom key `K` to a primitive key
    *   `KM`. This function must be deterministic and produce unique values for
@@ -306,6 +887,45 @@ export namespace IMapMapped {
    * @template K The type of the custom keys.
    * @template V The type of the values.
    * @template KM The type of the mapped primitive keys.
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const first = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const second = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 1, y: 0 }, 'right'],
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const third = IMapMapped.create<Point, string, string>(
+   *   [[{ x: 0, y: 0 }, 'different']],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * assert.isTrue(IMapMapped.equal(first, second));
+   *
+   * assert.isFalse(IMapMapped.equal(first, third));
+   * ```
+   *
    * @param a The first IMapMapped instance to compare.
    * @param b The second IMapMapped instance to compare.
    * @returns `true` if the maps contain exactly the same key-value pairs,
@@ -314,7 +934,12 @@ export namespace IMapMapped {
   export const equal = <K, V, KM extends MapSetKeyType>(
     a: IMapMapped<K, V, KM>,
     b: IMapMapped<K, V, KM>,
-  ): boolean => a.size === b.size && a.every((v, k) => b.get(k) === v);
+  ): boolean =>
+    a.size === b.size &&
+    a.every(
+      (v, k) =>
+        pipe(b.get(k)).map((bv) => Optional.isSome(bv) && bv.value === v).value,
+    );
 }
 
 /**
@@ -382,16 +1007,17 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
   }
 
   /** @inheritdoc */
-  has(key: K): boolean {
-    return this.#map.has(this.#toKey(key));
+  has(key: K | (WidenLiteral<K> & {})): boolean {
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    return this.#map.has(this.#toKey(key as K));
   }
 
   /** @inheritdoc */
-  get(key: K): Optional<V> {
+  get(key: K | (WidenLiteral<K> & {})): Optional<V> {
     if (!this.has(key)) return Optional.none;
 
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    return Optional.some(this.#map.get(this.#toKey(key))!);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion, total-functions/no-unsafe-type-assertion
+    return Optional.some(this.#map.get(this.#toKey(key as K))!);
   }
 
   /** @inheritdoc */
@@ -445,7 +1071,9 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
 
   /** @inheritdoc */
   set(key: K, value: V): IMapMapped<K, V, KM> {
-    if (value === this.get(key)) return this; // has no changes
+    const curr = this.get(key);
+
+    if (Optional.isSome(curr) && value === curr.value) return this;
 
     const keyMapped = this.#toKey(key);
 
@@ -457,15 +1085,15 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
         this.#toKey,
         this.#fromKey,
       );
-    } else {
-      return IMapMapped.create(
-        Array.from(this.#map, ([km, v]) =>
-          tp(this.#fromKey(km), Object.is(km, keyMapped) ? value : v),
-        ),
-        this.#toKey,
-        this.#fromKey,
-      );
     }
+
+    return IMapMapped.create(
+      Array.from(this.#map, ([km, v]) =>
+        tp(this.#fromKey(km), Object.is(km, keyMapped) ? value : v),
+      ),
+      this.#toKey,
+      this.#fromKey,
+    );
   }
 
   /** @inheritdoc */
@@ -485,14 +1113,11 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
     const keyMapped = this.#toKey(key);
 
     return IMapMapped.create(
-      Array.from(
-        this.#map.entries(),
-        (keyValue) =>
-          pipe(keyValue)
-            .map(([km, v]) =>
-              tp(km, Object.is(km, keyMapped) ? updater(curr.value) : v),
-            )
-            .map(([km, v]) => tp(this.#fromKey(km), v)).value,
+      Array.from(this.#map, ([km, v]) =>
+        tp(
+          this.#fromKey(km),
+          Object.is(km, keyMapped) ? updater(curr.value) : v,
+        ),
       ),
       this.#toKey,
       this.#fromKey,
@@ -509,7 +1134,13 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
   ): IMapMapped<K, V, KM> {
     const mut_result = new Map<KM, V>(this.#map);
 
-    for (const action of actions) {
+    const updateFn = (
+      action: Readonly<
+        | { type: 'delete'; key: K }
+        | { type: 'set'; key: K; value: V }
+        | { type: 'update'; key: K; updater: (value: V) => V }
+      >,
+    ): void => {
       const key = this.#toKey(action.key);
 
       switch (action.type) {
@@ -541,6 +1172,10 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
           break;
         }
       }
+    };
+
+    for (const action of actions) {
+      updateFn(action);
     }
 
     return IMapMapped.create<K, V, KM>(
@@ -581,12 +1216,41 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
 
   /** @inheritdoc */
   forEach(callbackfn: (value: V, key: K) => void): void {
-    for (const [km, value] of this.#map.entries()) {
+    for (const [km, value] of this.#map) {
       callbackfn(value, this.#fromKey(km));
     }
   }
 
-  /** @inheritdoc */
+  /**
+   * @example
+   *
+   * ```ts
+   * type Point = Readonly<{ x: number; y: number }>;
+   *
+   * const toKey = (p: Point) => JSON.stringify(p);
+   *
+   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+   * const fromKey = (key: string) => JSON.parse(key) as Point;
+   *
+   * const map = IMapMapped.create<Point, string, string>(
+   *   [
+   *     [{ x: 0, y: 0 }, 'origin'],
+   *     [{ x: 1, y: 0 }, 'right'],
+   *   ],
+   *   toKey,
+   *   fromKey,
+   * );
+   *
+   * const collected = Array.from(map);
+   *
+   * assert.deepStrictEqual(collected, [
+   *   [{ x: 0, y: 0 }, 'origin'],
+   *   [{ x: 1, y: 0 }, 'right'],
+   * ]);
+   * ```
+   *
+   * @inheritdoc
+   */
   *[Symbol.iterator](): Iterator<readonly [K, V]> {
     for (const e of this.entries()) {
       yield e;
@@ -601,15 +1265,13 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
   }
 
   /** @inheritdoc */
-  *values(): IterableIterator<V> {
-    for (const v of this.#map.values()) {
-      yield v;
-    }
+  values(): IterableIterator<V> {
+    return this.#map.values();
   }
 
   /** @inheritdoc */
   *entries(): IterableIterator<readonly [K, V]> {
-    for (const [km, v] of this.#map.entries()) {
+    for (const [km, v] of this.#map) {
       yield [this.#fromKey(km), v];
     }
   }