ts-data-forge 7.0.0 → 7.0.1

package/dist/collections/imap-mapped.d.mts

@@ -1,3 +1,4 @@
+import { type WidenLiteral } from 'ts-type-forge';
 import { Optional } from '../functional/index.mjs';
 import { type MapSetKeyType, type SizeType } from '../types.mjs';
 /**
@@ -29,28 +30,122 @@ import { type MapSetKeyType, type SizeType } from '../types.mjs';
  * @template KM The type of the mapped primitive keys (string, number, etc.).
  */
 type IMapMappedInterface<K, V, KM extends MapSetKeyType> = Readonly<{
-    /** 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>;
     /**
      * Checks if all elements in the map satisfy a predicate. Also supports a
      * 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.
@@ -59,6 +154,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.
@@ -67,6 +186,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.
      */
@@ -74,6 +226,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.
@@ -82,6 +264,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.
@@ -91,6 +303,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.
      */
@@ -109,6 +355,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.
@@ -118,6 +391,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.
      */
@@ -125,6 +425,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).
@@ -134,42 +461,223 @@ 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;
     /**
      * 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>;
     /**
      * 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>;
     /**
      * 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]>;
     /**
      * 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[];
     /**
      * 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[];
     /**
      * 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])[];
@@ -177,12 +685,60 @@ 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])[];
     /**
      * 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>;
@@ -234,6 +790,30 @@ export declare 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
@@ -258,6 +838,45 @@ export declare 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,