ts-data-forge 14.5.0 → 14.6.1

package/dist/collections/iset-mapped.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"iset-mapped.mjs","sources":["../../src/collections/iset-mapped.mts"],"sourcesContent":["/* eslint-disable unicorn/prefer-iterator-to-array-at-end */\nimport {\n  type FixedLengthTuple,\n  type ReadonlyRecord,\n  type WidenLiteral,\n} from 'ts-type-forge';\nimport { asUint32 } from '../number/index.mjs';\nimport { type MapSetKeyType, type SizeType } from '../types.mjs';\n\n/**\n * Interface for an immutable set with custom element mapping and membership\n * testing.\n *\n * ISetMapped allows you to use complex objects as set elements by providing\n * transformation functions that convert between your custom element type `K`\n * and a primitive `MapSetKeyType` `KM` that can be efficiently stored in\n * JavaScript's native Set. This enables set operations on complex elements\n * while maintaining type safety and immutability.\n *\n * **Key Features:**\n *\n * - **Custom Element Types**: Use any type as set elements by providing\n *   `toKey`/`fromKey` functions\n * - **Immutable**: All operations return new instances, preserving immutability\n * - **Set Operations**: Full support for union, intersection, difference,\n *   subset/superset checks\n * - **Type Safe**: Full TypeScript support with generic element types\n *\n * **Performance Characteristics:**\n *\n * - has: O(1) average case (plus element transformation overhead)\n * - add/delete: O(n) due to copying for immutability (plus element\n *   transformation overhead)\n * - set operations (union, intersection, difference): O(n)\n * - map/filter operations: O(n)\n * - iteration: O(n) (plus element transformation overhead)\n *\n * @template K The type of the custom elements in the set.\n * @template KM The type of the mapped primitive keys (string, number, etc.).\n */\ntype ISetMappedInterface<K, KM extends MapSetKeyType> = Readonly<{\n  /**\n   * Creates a new ISetMapped instance.\n   *\n   * @param iterable An iterable of elements.\n   * @param toKey A function that converts an element of type `K` to `KM`.\n   * @param fromKey A function that converts a mapped key of type `KM` back to\n   *   `K`.\n   */\n  new (iterable: Iterable<K>, toKey: (a: K) => KM, fromKey: (k: KM) => K): void;\n\n  // Getting information\n\n  /**\n   * The number of elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const points: readonly Point[] = [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ] as const;\n   *\n   * const set = ISetMapped.create<Point, string>(points, toKey, fromKey);\n   *\n   * assert.isTrue(set.size === 2);\n   * ```\n   */\n  size: SizeType.Arr;\n\n  /**\n   * Checks if the set is empty.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const empty = ISetMapped.create<Point, string>([], toKey, fromKey);\n   *\n   * const points = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(empty.isEmpty);\n   *\n   * assert.isFalse(points.isEmpty);\n   * ```\n   */\n  isEmpty: boolean;\n\n  /**\n   * Checks if an element exists in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(set.has({ x: 1, tag: 'a' }));\n   *\n   * assert.isFalse(set.has({ x: 2, tag: 'b' }));\n   * ```\n   *\n   * @param key The element to check.\n   * @returns `true` if the element exists, `false` otherwise.\n   */\n  has: (key: K | (WidenLiteral<K> & {})) => boolean;\n\n  // Reducing a value\n\n  /**\n   * Checks if all elements in the set satisfy a type predicate. Narrows the\n   * type of elements in the set if the predicate returns true for all\n   * elements.\n   *\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 2, tag: 'even' },\n   *     { x: 4, tag: 'even' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const allEven = set.every((point) => point.x % 2 === 0);\n   *\n   * const narrowed = set.every(\n   *   (point): point is Readonly<{ x: 2 | 4; tag: 'even' }> =>\n   *     point.x % 2 === 0,\n   * );\n   *\n   * assert.isTrue(allEven);\n   *\n   * assert.isTrue(narrowed);\n   * ```\n   *\n   * @template L The narrowed type of the elements.\n   * @param predicate A function to test each element.\n   * @returns `true` if all elements satisfy the predicate, `false` otherwise.\n   */\n  every: ((predicate: (key: K) => boolean) => boolean) &\n    (<L extends K>(\n      predicate: (key: K) => key is L,\n    ) => this is ISetMapped<L, KM>);\n\n  /**\n   * Checks if at least one element in the set satisfies a predicate.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 5, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(set.some((point) => point.x > 4));\n   *\n   * assert.isFalse(set.some((point) => point.x > 10));\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns `true` if at least one element satisfies the predicate, `false`\n   *   otherwise.\n   */\n  some: (predicate: (key: K) => boolean) => boolean;\n\n  // Mutation\n\n  /**\n   * Adds an element to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const base = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const withNew = base.add({ x: 2, tag: 'b' });\n   *\n   * const unchanged = base.add({ x: 1, tag: 'a' });\n   *\n   * assert.deepStrictEqual(Array.from(withNew), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to add.\n   * @returns A new ISetMapped instance with the element added.\n   */\n  add: (key: K) => ISetMapped<K, KM>;\n\n  /**\n   * Deletes an element from the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const base = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const withoutSecond = base.delete({ x: 2, tag: 'b' });\n   *\n   * const unchanged = base.delete({ x: 3, tag: 'c' });\n   *\n   * assert.deepStrictEqual(Array.from(withoutSecond), [{ x: 1, tag: 'a' }]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to delete.\n   * @returns A new ISetMapped instance without the specified element.\n   */\n  delete: (key: K) => ISetMapped<K, KM>;\n\n  /**\n   * Applies a series of mutations to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const base = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const actions: readonly Readonly<\n   *   { type: 'add'; key: Point } | { type: 'delete'; key: Point }\n   * >[] = [\n   *   { type: 'add', key: { x: 3, tag: 'c' } },\n   *   { type: 'delete', key: { x: 1, tag: 'a' } },\n   * ] as const;\n   *\n   * const mutated = base.withMutations(actions);\n   *\n   * assert.deepStrictEqual(Array.from(mutated), [\n   *   { x: 2, tag: 'b' },\n   *   { x: 3, tag: 'c' },\n   * ]);\n   *\n   * assert.deepStrictEqual(Array.from(base), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @param actions An array of mutation actions (add or delete).\n   * @returns A new ISetMapped instance with all mutations applied.\n   */\n  withMutations: (\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ) => ISetMapped<K, KM>;\n\n  // Sequence algorithms\n\n  /**\n   * Maps the elements of the set to new elements. Note: The element type `K`\n   * cannot be changed because `toKey` and `fromKey` would become unusable if\n   * the mapped type `KM` changes.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const shifted = set.map((point) => ({\n   *   x: point.x + 10,\n   *   tag: point.tag.toUpperCase(),\n   * }));\n   *\n   * assert.deepStrictEqual(Array.from(shifted), [\n   *   { x: 11, tag: 'A' },\n   *   { x: 12, tag: 'B' },\n   * ]);\n   * ```\n   *\n   * @param mapFn A function that maps an element to a new element of the same\n   *   type `K`.\n   * @returns A new ISetMapped instance with mapped elements.\n   */\n  map: (mapFn: (key: K) => K) => ISetMapped<K, KM>;\n\n  /**\n   * Filters the elements of the set based on a predicate.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *     { x: 3, tag: 'c' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const evenPoints = set.filter((point) => point.x % 2 === 0);\n   *\n   * assert.deepStrictEqual(Array.from(evenPoints), [{ x: 2, tag: 'b' }]);\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns A new ISetMapped instance with elements that satisfy the\n   *   predicate.\n   */\n  filter: (predicate: (value: K) => boolean) => ISetMapped<K, KM>;\n\n  /**\n   * Filters the elements of the set by excluding elements for which the\n   * predicate returns true.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const withoutEven = set.filterNot((point) => point.x % 2 === 0);\n   *\n   * assert.deepStrictEqual(Array.from(withoutEven), [{ x: 1, tag: 'a' }]);\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns A new ISetMapped instance with elements for which the predicate\n   *   returned `false`.\n   */\n  filterNot: (predicate: (key: K) => boolean) => ISetMapped<K, KM>;\n\n  // Side effects\n\n  /**\n   * Executes a callback function for each element in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const mut_collected: Point[] = [];\n   *\n   * set.forEach((point) => {\n   *   mut_collected.push(point);\n   * });\n   *\n   * assert.deepStrictEqual(mut_collected, [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @param callbackfn A function to execute for each element.\n   */\n  forEach: (callbackfn: (key: K) => void) => void;\n\n  // Comparison\n\n  /**\n   * Checks if this set is a subset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const subset = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const superset = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(subset.isSubsetOf(superset));\n   *\n   * assert.isFalse(superset.isSubsetOf(subset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a subset of the other set, `false`\n   *   otherwise.\n   */\n  isSubsetOf: (set: ISetMapped<K, KM>) => boolean;\n\n  /**\n   * Checks if this set is a superset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const superset = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const subset = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(superset.isSupersetOf(subset));\n   *\n   * assert.isFalse(subset.isSupersetOf(superset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a superset of the other set, `false`\n   *   otherwise.\n   */\n  isSupersetOf: (set: ISetMapped<K, KM>) => boolean;\n\n  /**\n   * Returns a new set with elements that are in this set but not in another\n   * set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *     { x: 3, tag: 'c' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const difference = left.subtract(right);\n   *\n   * assert.deepStrictEqual(Array.from(difference), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 3, tag: 'c' },\n   * ]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISetMapped instance representing the set difference.\n   */\n  subtract: (set: ISetMapped<K, KM>) => ISetMapped<K, KM>;\n\n  /**\n   * Returns a new set with elements that are common to both this set and\n   * another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const intersection = left.intersect(right);\n   *\n   * assert.deepStrictEqual(Array.from(intersection), [{ x: 2, tag: 'b' }]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISetMapped instance representing the set intersection.\n   */\n  intersect: (set: ISetMapped<K, KM>) => ISetMapped<K, KM>;\n\n  /**\n   * Returns a new set with all elements from both this set and another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const combined = left.union(right);\n   *\n   * assert.deepStrictEqual(Array.from(combined), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISetMapped instance representing the set union.\n   */\n  union: (set: ISetMapped<K, KM>) => ISetMapped<K, KM>;\n\n  // Iterators\n\n  /**\n   * Returns an iterator for the elements in the set (alias for values).\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set.keys()), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  keys: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set.values()), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  values: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the entries (element-element pairs) in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set.entries()), [\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 1, tag: 'a' },\n   *   ],\n   *   [\n   *     { x: 2, tag: 'b' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of entries.\n   */\n  entries: () => IterableIterator<FixedLengthTuple<2, K>>;\n\n  // Conversion\n\n  /**\n   * Converts the elements of the set to an array.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(set.toArray(), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @returns A readonly array of elements.\n   */\n  toArray: () => readonly K[];\n\n  /**\n   * Returns the underlying readonly JavaScript Set of mapped keys.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const raw = set.toRawSet();\n   *\n   * assert.isTrue(isSet(raw));\n   *\n   * assert.isTrue(raw.has(toKey({ x: 1, tag: 'a' })));\n   * ```\n   *\n   * @returns The raw ReadonlySet instance.\n   */\n  toRawSet: () => ReadonlySet<KM>;\n}>;\n\n/**\n * Represents an immutable set with custom element transformation and\n * high-performance operations.\n *\n * ISetMapped is a specialized persistent data structure that enables using\n * complex objects as set elements while maintaining the performance benefits of\n * JavaScript's native Set. It achieves this by requiring bidirectional\n * transformation functions that convert between your custom element type and a\n * primitive type that can be efficiently stored and compared for uniqueness.\n *\n * **Key Features:**\n *\n * - **Complex Elements**: Use objects, arrays, or any custom type as set elements\n * - **Immutable**: All mutation operations return new instances\n * - **Type Safe**: Full TypeScript support with compile-time element type\n *   checking\n * - **Bidirectional**: Maintains ability to reconstruct original elements from\n *   mapped keys\n * - **Set Algebra**: Complete support for mathematical set operations\n *\n * **Use Cases:**\n *\n * - Sets of entities with complex identifiers\n * - Deduplication of objects based on specific properties\n * - Performance-critical sets with non-primitive elements\n * - Mathematical set operations on complex data structures\n *\n * @template K The type of the custom elements in the set.\n * @template KM The type of the mapped primitive keys (string, number, etc.).\n */\nexport type ISetMapped<K, KM extends MapSetKeyType> = Iterable<K> &\n  Readonly<ISetMappedInterface<K, KM>>;\n\n/** Provides utility functions for ISetMapped. */\nexport namespace ISetMapped {\n  /**\n   * Creates a new ISetMapped instance with custom element transformation\n   * functions.\n   *\n   * This factory function creates an immutable set that can use complex objects\n   * as elements by providing bidirectional transformation functions. The\n   * `toKey` function converts your custom element type to a primitive type that\n   * can be efficiently stored, while `fromKey` reconstructs the original\n   * element type for iteration and access.\n   *\n   * **Performance:** O(n) where n is the number of elements in the iterable.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @template K The type of the custom elements.\n   * @template KM The type of the mapped primitive keys.\n   * @param iterable An iterable of elements using the custom element type.\n   * @param toKey A function that converts a custom element `K` to a primitive\n   *   key `KM`. This function must be deterministic and produce unique values\n   *   for unique elements.\n   * @param fromKey A function that converts a primitive key `KM` back to the\n   *   custom element `K`. This should be the inverse of `toKey`.\n   * @returns A new ISetMapped instance containing all unique elements from the\n   *   iterable.\n   */\n  export const create = <K, KM extends MapSetKeyType>(\n    iterable: Iterable<K>,\n    toKey: (a: K) => KM,\n    fromKey: (k: KM) => K,\n  ): ISetMapped<K, KM> => new ISetMappedClass<K, KM>(iterable, toKey, fromKey);\n\n  /**\n   * Checks if two ISetMapped instances are structurally equal.\n   *\n   * Two ISetMapped instances are considered equal if they have the same size\n   * and contain exactly the same elements. The comparison is performed on the\n   * underlying mapped keys, so the transformation functions themselves don't\n   * need to be identical. Elements are compared based on their mapped key\n   * representations.\n   *\n   * **Performance:** O(n) where n is the size of the smaller set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const first = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const second = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 2, tag: 'b' },\n   *     { x: 1, tag: 'a' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const third = ISetMapped.create<Point, string>(\n   *   [{ x: 3, tag: 'c' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(ISetMapped.equal(first, second));\n   *\n   * assert.isFalse(ISetMapped.equal(first, third));\n   * ```\n   *\n   * @template K The type of the custom elements.\n   * @template KM The type of the mapped primitive keys.\n   * @param a The first ISetMapped instance to compare.\n   * @param b The second ISetMapped instance to compare.\n   * @returns `true` if the sets contain exactly the same elements, `false`\n   *   otherwise.\n   */\n  export const equal = <K, KM extends MapSetKeyType>(\n    a: ISetMapped<K, KM>,\n    b: ISetMapped<K, KM>,\n  ): boolean => a.size === b.size && a.every((e) => b.has(e));\n\n  /**\n   * Computes the difference between two ISetMapped instances.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const previous = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const current = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 2, tag: 'b' },\n   *     { x: 3, tag: 'c' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const { added, deleted } = ISetMapped.diff(previous, current);\n   *\n   * assert.deepStrictEqual(Array.from(added), [{ x: 3, tag: 'c' }]);\n   *\n   * assert.deepStrictEqual(Array.from(deleted), [{ x: 1, tag: 'a' }]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @template KM The type of the mapped keys.\n   * @param oldSet The original set.\n   * @param newSet The new set.\n   * @returns An object containing sets of added and deleted elements.\n   */\n  export const diff = <K, KM extends MapSetKeyType>(\n    oldSet: ISetMapped<K, KM>,\n    newSet: ISetMapped<K, KM>,\n  ): ReadonlyRecord<'added' | 'deleted', ISetMapped<K, KM>> =>\n    ({\n      deleted: oldSet.subtract(newSet),\n      added: newSet.subtract(oldSet),\n    }) as const;\n\n  /**\n   * Computes the intersection of two ISetMapped instances.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const overlap = ISetMapped.intersection(left, right);\n   *\n   * assert.deepStrictEqual(Array.from(overlap), [{ x: 2, tag: 'b' }]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @template KM The type of the mapped keys.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISetMapped instance representing the intersection.\n   */\n  export const intersection = <K, KM extends MapSetKeyType>(\n    a: ISetMapped<K, KM>,\n    b: ISetMapped<K, KM>,\n  ): ISetMapped<K, KM> => a.intersect(b);\n\n  /**\n   * Computes the union of two ISetMapped instances.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const combined = ISetMapped.union(left, right);\n   *\n   * assert.deepStrictEqual(Array.from(combined), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @template KM The type of the mapped keys.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISetMapped instance representing the union.\n   */\n  export const union = <K, KM extends MapSetKeyType>(\n    a: ISetMapped<K, KM>,\n    b: ISetMapped<K, KM>,\n  ): ISetMapped<K, KM> => a.union(b);\n}\n\n/**\n * Internal class implementation for ISetMapped providing immutable set\n * operations with element transformation.\n *\n * This class implements the ISetMapped interface by maintaining a JavaScript\n * Set with primitive keys internally while exposing an API that works with\n * custom element types. The transformation between custom and primitive\n * elements is handled transparently through the provided `toKey` and `fromKey`\n * functions.\n *\n * **Implementation Details:**\n *\n * - Uses ReadonlySet<KM> internally where KM is the primitive key type\n * - Stores transformation functions for bidirectional element conversion\n * - Implements copy-on-write semantics for efficiency\n * - Provides optional debug messaging for development\n *\n * @template K The type of the custom elements.\n * @template KM The type of the mapped primitive keys.\n * @implements ISetMapped\n * @implements Iterable\n * @internal This class should not be used directly. Use ISetMapped.create() instead.\n */\nclass ISetMappedClass<K, KM extends MapSetKeyType>\n  implements ISetMapped<K, KM>, Iterable<K>\n{\n  readonly #set: ReadonlySet<KM>;\n  readonly #toKey: (a: K) => KM;\n  readonly #fromKey: (k: KM) => K;\n  readonly #showNotFoundMessage: boolean;\n\n  /**\n   * Constructs an ISetMappedClass instance with custom element transformation.\n   *\n   * @param iterable An iterable of elements using the custom element type K.\n   * @param toKey A function that converts a custom element K to a primitive key\n   *   KM. Must be deterministic and produce unique values for unique elements.\n   * @param fromKey A function that converts a primitive key KM back to the\n   *   custom element K. Should be the inverse of the toKey function.\n   * @param showNotFoundMessage Whether to log warning messages when operations\n   *   are performed on non-existent elements. Useful for debugging. Defaults to\n   *   false for production use.\n   * @internal Use ISetMapped.create() instead of calling this constructor directly.\n   */\n  constructor(\n    iterable: Iterable<K>,\n    toKey: (a: K) => KM,\n    fromKey: (k: KM) => K,\n    showNotFoundMessage: boolean = false,\n  ) {\n    this.#set = new Set(Array.from(iterable, toKey));\n\n    this.#toKey = toKey;\n\n    this.#fromKey = fromKey;\n\n    this.#showNotFoundMessage = showNotFoundMessage;\n  }\n\n  /** @inheritdoc */\n  get size(): SizeType.Arr {\n    return asUint32(this.#set.size);\n  }\n\n  /** @inheritdoc */\n  get isEmpty(): boolean {\n    return this.size === 0;\n  }\n\n  /** @inheritdoc */\n  has(key: K | (WidenLiteral<K> & {})): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return this.#set.has(this.#toKey(key as K));\n  }\n\n  /** @inheritdoc */\n  every<L extends K>(\n    predicate: (key: K) => key is L,\n  ): this is ISetMapped<L, KM>;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (!predicate(key)) return false;\n    }\n\n    return true;\n  }\n\n  /** @inheritdoc */\n  some(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (predicate(key)) return true;\n    }\n\n    return false;\n  }\n\n  /** @inheritdoc */\n  add(key: K): ISetMapped<K, KM> {\n    if (this.has(key)) return this;\n\n    return ISetMapped.create(\n      [...this.#set, this.#toKey(key)].map(this.#fromKey),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  delete(key: K): ISetMapped<K, KM> {\n    if (!this.has(key)) {\n      if (this.#showNotFoundMessage) {\n        console.warn(\n          `ISetMapped.delete: key not found: ${String(this.#toKey(key))}`,\n        );\n      }\n\n      return this;\n    }\n\n    const keyMapped = this.#toKey(key);\n\n    return ISetMapped.create(\n      Array.from(this.#set)\n        .filter((k) => !Object.is(k, keyMapped))\n        .map(this.#fromKey),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  withMutations(\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ): ISetMapped<K, KM> {\n    const mut_result = new Set<KM>(this.#set);\n\n    const updateFn = (\n      action: Readonly<{ type: 'add'; key: K } | { type: 'delete'; key: K }>,\n    ): void => {\n      const key = this.#toKey(action.key);\n\n      switch (action.type) {\n        case 'delete':\n          mut_result.delete(key);\n\n          break;\n\n        case 'add':\n          mut_result.add(key);\n\n          break;\n      }\n    };\n\n    for (const action of actions) {\n      updateFn(action);\n    }\n\n    return ISetMapped.create<K, KM>(\n      Array.from(mut_result, this.#fromKey),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  map(mapFn: (key: K) => K): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().map(mapFn),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  filter(predicate: (key: K) => boolean): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter(predicate),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  filterNot(predicate: (key: K) => boolean): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter((k) => !predicate(k)),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  forEach(callbackfn: (key: K) => void): void {\n    for (const km of this.#set) {\n      callbackfn(this.#fromKey(km));\n    }\n  }\n\n  /** @inheritdoc */\n  isSubsetOf(set: ISetMapped<K, KM>): boolean {\n    return this.every((k) => set.has(k));\n  }\n\n  /** @inheritdoc */\n  isSupersetOf(set: ISetMapped<K, KM>): boolean {\n    return set.every((k) => this.has(k));\n  }\n\n  /** @inheritdoc */\n  subtract(set: ISetMapped<K, KM>): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter((k) => !set.has(k)),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  intersect(set: ISetMapped<K, KM>): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter((k) => set.has(k)),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  union(set: ISetMapped<K, KM>): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      [...this.values(), ...set.values()],\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /**\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const collected = Array.from(set);\n   *\n   * assert.deepStrictEqual(collected, [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @inheritdoc\n   */\n  *[Symbol.iterator](): Iterator<K> {\n    for (const k of this.keys()) {\n      yield k;\n    }\n  }\n\n  /** @inheritdoc */\n  *keys(): IterableIterator<K> {\n    for (const km of this.#set) {\n      yield this.#fromKey(km);\n    }\n  }\n\n  /** @inheritdoc */\n  *values(): IterableIterator<K> {\n    for (const km of this.#set) {\n      // JavaScript Set's values() is an alias for keys()\n      yield this.#fromKey(km);\n    }\n  }\n\n  /** @inheritdoc */\n  *entries(): IterableIterator<FixedLengthTuple<2, K>> {\n    for (const km of this.#set) {\n      // JavaScript Set's entries() yields [value, value]\n      const a = this.#fromKey(km);\n\n      yield [a, a];\n    }\n  }\n\n  /** @inheritdoc */\n  toArray(): readonly K[] {\n    return Array.from(this.values());\n  }\n\n  /** @inheritdoc */\n  toRawSet(): ReadonlySet<KM> {\n    return this.#set;\n  }\n}\n"],"names":["ISetMapped"],"mappings":"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"}
+{"version":3,"file":"iset-mapped.mjs","sources":["../../src/collections/iset-mapped.mts"],"sourcesContent":["/* eslint-disable unicorn/prefer-iterator-to-array-at-end */\nimport {\n  type FixedLengthTuple,\n  type ReadonlyRecord,\n  type WidenLiteral,\n} from 'ts-type-forge';\nimport { asUint32 } from '../number/index.mjs';\nimport { unknownToString } from '../others/index.mjs';\nimport { type MapSetKeyType, type SizeType } from '../types.mjs';\n\n/**\n * Interface for an immutable set with custom element mapping and membership\n * testing.\n *\n * ISetMapped allows you to use complex objects as set elements by providing\n * transformation functions that convert between your custom element type `K`\n * and a primitive `MapSetKeyType` `KM` that can be efficiently stored in\n * JavaScript's native Set. This enables set operations on complex elements\n * while maintaining type safety and immutability.\n *\n * **Key Features:**\n *\n * - **Custom Element Types**: Use any type as set elements by providing\n *   `toKey`/`fromKey` functions\n * - **Immutable**: All operations return new instances, preserving immutability\n * - **Set Operations**: Full support for union, intersection, difference,\n *   subset/superset checks\n * - **Type Safe**: Full TypeScript support with generic element types\n *\n * **Performance Characteristics:**\n *\n * - has: O(1) average case (plus element transformation overhead)\n * - add/delete: O(n) due to copying for immutability (plus element\n *   transformation overhead)\n * - set operations (union, intersection, difference): O(n)\n * - map/filter operations: O(n)\n * - iteration: O(n) (plus element transformation overhead)\n *\n * @template K The type of the custom elements in the set.\n * @template KM The type of the mapped primitive keys (string, number, etc.).\n */\ntype ISetMappedInterface<K, KM extends MapSetKeyType> = Readonly<{\n  /**\n   * Creates a new ISetMapped instance.\n   *\n   * @param iterable An iterable of elements.\n   * @param toKey A function that converts an element of type `K` to `KM`.\n   * @param fromKey A function that converts a mapped key of type `KM` back to\n   *   `K`.\n   */\n  new (iterable: Iterable<K>, toKey: (a: K) => KM, fromKey: (k: KM) => K): void;\n\n  // Getting information\n\n  /**\n   * The number of elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const points: readonly Point[] = [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ] as const;\n   *\n   * const set = ISetMapped.create<Point, string>(points, toKey, fromKey);\n   *\n   * assert.isTrue(set.size === 2);\n   * ```\n   */\n  size: SizeType.Arr;\n\n  /**\n   * Checks if the set is empty.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const empty = ISetMapped.create<Point, string>([], toKey, fromKey);\n   *\n   * const points = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(empty.isEmpty);\n   *\n   * assert.isFalse(points.isEmpty);\n   * ```\n   */\n  isEmpty: boolean;\n\n  /**\n   * Checks if an element exists in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(set.has({ x: 1, tag: 'a' }));\n   *\n   * assert.isFalse(set.has({ x: 2, tag: 'b' }));\n   * ```\n   *\n   * @param key The element to check.\n   * @returns `true` if the element exists, `false` otherwise.\n   */\n  has: (key: K | (WidenLiteral<K> & {})) => boolean;\n\n  // Reducing a value\n\n  /**\n   * Checks if all elements in the set satisfy a type predicate. Narrows the\n   * type of elements in the set if the predicate returns true for all\n   * elements.\n   *\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 2, tag: 'even' },\n   *     { x: 4, tag: 'even' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const allEven = set.every((point) => point.x % 2 === 0);\n   *\n   * const narrowed = set.every(\n   *   (point): point is Readonly<{ x: 2 | 4; tag: 'even' }> =>\n   *     point.x % 2 === 0,\n   * );\n   *\n   * assert.isTrue(allEven);\n   *\n   * assert.isTrue(narrowed);\n   * ```\n   *\n   * @template L The narrowed type of the elements.\n   * @param predicate A function to test each element.\n   * @returns `true` if all elements satisfy the predicate, `false` otherwise.\n   */\n  every: ((predicate: (key: K) => boolean) => boolean) &\n    (<L extends K>(\n      predicate: (key: K) => key is L,\n    ) => this is ISetMapped<L, KM>);\n\n  /**\n   * Checks if at least one element in the set satisfies a predicate.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 5, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(set.some((point) => point.x > 4));\n   *\n   * assert.isFalse(set.some((point) => point.x > 10));\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns `true` if at least one element satisfies the predicate, `false`\n   *   otherwise.\n   */\n  some: (predicate: (key: K) => boolean) => boolean;\n\n  // Mutation\n\n  /**\n   * Adds an element to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const base = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const withNew = base.add({ x: 2, tag: 'b' });\n   *\n   * const unchanged = base.add({ x: 1, tag: 'a' });\n   *\n   * assert.deepStrictEqual(Array.from(withNew), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to add.\n   * @returns A new ISetMapped instance with the element added.\n   */\n  add: (key: K) => ISetMapped<K, KM>;\n\n  /**\n   * Deletes an element from the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const base = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const withoutSecond = base.delete({ x: 2, tag: 'b' });\n   *\n   * const unchanged = base.delete({ x: 3, tag: 'c' });\n   *\n   * assert.deepStrictEqual(Array.from(withoutSecond), [{ x: 1, tag: 'a' }]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to delete.\n   * @returns A new ISetMapped instance without the specified element.\n   */\n  delete: (key: K) => ISetMapped<K, KM>;\n\n  /**\n   * Applies a series of mutations to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const base = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const actions: readonly Readonly<\n   *   { type: 'add'; key: Point } | { type: 'delete'; key: Point }\n   * >[] = [\n   *   { type: 'add', key: { x: 3, tag: 'c' } },\n   *   { type: 'delete', key: { x: 1, tag: 'a' } },\n   * ] as const;\n   *\n   * const mutated = base.withMutations(actions);\n   *\n   * assert.deepStrictEqual(Array.from(mutated), [\n   *   { x: 2, tag: 'b' },\n   *   { x: 3, tag: 'c' },\n   * ]);\n   *\n   * assert.deepStrictEqual(Array.from(base), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @param actions An array of mutation actions (add or delete).\n   * @returns A new ISetMapped instance with all mutations applied.\n   */\n  withMutations: (\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ) => ISetMapped<K, KM>;\n\n  // Sequence algorithms\n\n  /**\n   * Maps the elements of the set to new elements. Note: The element type `K`\n   * cannot be changed because `toKey` and `fromKey` would become unusable if\n   * the mapped type `KM` changes.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const shifted = set.map((point) => ({\n   *   x: point.x + 10,\n   *   tag: point.tag.toUpperCase(),\n   * }));\n   *\n   * assert.deepStrictEqual(Array.from(shifted), [\n   *   { x: 11, tag: 'A' },\n   *   { x: 12, tag: 'B' },\n   * ]);\n   * ```\n   *\n   * @param mapFn A function that maps an element to a new element of the same\n   *   type `K`.\n   * @returns A new ISetMapped instance with mapped elements.\n   */\n  map: (mapFn: (key: K) => K) => ISetMapped<K, KM>;\n\n  /**\n   * Filters the elements of the set based on a predicate.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *     { x: 3, tag: 'c' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const evenPoints = set.filter((point) => point.x % 2 === 0);\n   *\n   * assert.deepStrictEqual(Array.from(evenPoints), [{ x: 2, tag: 'b' }]);\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns A new ISetMapped instance with elements that satisfy the\n   *   predicate.\n   */\n  filter: (predicate: (value: K) => boolean) => ISetMapped<K, KM>;\n\n  /**\n   * Filters the elements of the set by excluding elements for which the\n   * predicate returns true.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const withoutEven = set.filterNot((point) => point.x % 2 === 0);\n   *\n   * assert.deepStrictEqual(Array.from(withoutEven), [{ x: 1, tag: 'a' }]);\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns A new ISetMapped instance with elements for which the predicate\n   *   returned `false`.\n   */\n  filterNot: (predicate: (key: K) => boolean) => ISetMapped<K, KM>;\n\n  // Side effects\n\n  /**\n   * Executes a callback function for each element in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const mut_collected: Point[] = [];\n   *\n   * set.forEach((point) => {\n   *   mut_collected.push(point);\n   * });\n   *\n   * assert.deepStrictEqual(mut_collected, [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @param callbackfn A function to execute for each element.\n   */\n  forEach: (callbackfn: (key: K) => void) => void;\n\n  // Comparison\n\n  /**\n   * Checks if this set is a subset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const subset = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const superset = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(subset.isSubsetOf(superset));\n   *\n   * assert.isFalse(superset.isSubsetOf(subset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a subset of the other set, `false`\n   *   otherwise.\n   */\n  isSubsetOf: (set: ISetMapped<K, KM>) => boolean;\n\n  /**\n   * Checks if this set is a superset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const superset = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const subset = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(superset.isSupersetOf(subset));\n   *\n   * assert.isFalse(subset.isSupersetOf(superset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a superset of the other set, `false`\n   *   otherwise.\n   */\n  isSupersetOf: (set: ISetMapped<K, KM>) => boolean;\n\n  /**\n   * Returns a new set with elements that are in this set but not in another\n   * set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *     { x: 3, tag: 'c' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const difference = left.subtract(right);\n   *\n   * assert.deepStrictEqual(Array.from(difference), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 3, tag: 'c' },\n   * ]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISetMapped instance representing the set difference.\n   */\n  subtract: (set: ISetMapped<K, KM>) => ISetMapped<K, KM>;\n\n  /**\n   * Returns a new set with elements that are common to both this set and\n   * another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const intersection = left.intersect(right);\n   *\n   * assert.deepStrictEqual(Array.from(intersection), [{ x: 2, tag: 'b' }]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISetMapped instance representing the set intersection.\n   */\n  intersect: (set: ISetMapped<K, KM>) => ISetMapped<K, KM>;\n\n  /**\n   * Returns a new set with all elements from both this set and another set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const combined = left.union(right);\n   *\n   * assert.deepStrictEqual(Array.from(combined), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISetMapped instance representing the set union.\n   */\n  union: (set: ISetMapped<K, KM>) => ISetMapped<K, KM>;\n\n  // Iterators\n\n  /**\n   * Returns an iterator for the elements in the set (alias for values).\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set.keys()), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  keys: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set.values()), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  values: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the entries (element-element pairs) in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set.entries()), [\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 1, tag: 'a' },\n   *   ],\n   *   [\n   *     { x: 2, tag: 'b' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of entries.\n   */\n  entries: () => IterableIterator<FixedLengthTuple<2, K>>;\n\n  // Conversion\n\n  /**\n   * Converts the elements of the set to an array.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(set.toArray(), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @returns A readonly array of elements.\n   */\n  toArray: () => readonly K[];\n\n  /**\n   * Returns the underlying readonly JavaScript Set of mapped keys.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const raw = set.toRawSet();\n   *\n   * assert.isTrue(isSet(raw));\n   *\n   * assert.isTrue(raw.has(toKey({ x: 1, tag: 'a' })));\n   * ```\n   *\n   * @returns The raw ReadonlySet instance.\n   */\n  toRawSet: () => ReadonlySet<KM>;\n}>;\n\n/**\n * Represents an immutable set with custom element transformation and\n * high-performance operations.\n *\n * ISetMapped is a specialized persistent data structure that enables using\n * complex objects as set elements while maintaining the performance benefits of\n * JavaScript's native Set. It achieves this by requiring bidirectional\n * transformation functions that convert between your custom element type and a\n * primitive type that can be efficiently stored and compared for uniqueness.\n *\n * **Key Features:**\n *\n * - **Complex Elements**: Use objects, arrays, or any custom type as set elements\n * - **Immutable**: All mutation operations return new instances\n * - **Type Safe**: Full TypeScript support with compile-time element type\n *   checking\n * - **Bidirectional**: Maintains ability to reconstruct original elements from\n *   mapped keys\n * - **Set Algebra**: Complete support for mathematical set operations\n *\n * **Use Cases:**\n *\n * - Sets of entities with complex identifiers\n * - Deduplication of objects based on specific properties\n * - Performance-critical sets with non-primitive elements\n * - Mathematical set operations on complex data structures\n *\n * @template K The type of the custom elements in the set.\n * @template KM The type of the mapped primitive keys (string, number, etc.).\n */\nexport type ISetMapped<K, KM extends MapSetKeyType> = Iterable<K> &\n  Readonly<ISetMappedInterface<K, KM>>;\n\n/** Provides utility functions for ISetMapped. */\nexport namespace ISetMapped {\n  /**\n   * Creates a new ISetMapped instance with custom element transformation\n   * functions.\n   *\n   * This factory function creates an immutable set that can use complex objects\n   * as elements by providing bidirectional transformation functions. The\n   * `toKey` function converts your custom element type to a primitive type that\n   * can be efficiently stored, while `fromKey` reconstructs the original\n   * element type for iteration and access.\n   *\n   * **Performance:** O(n) where n is the number of elements in the iterable.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(set), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @template K The type of the custom elements.\n   * @template KM The type of the mapped primitive keys.\n   * @param iterable An iterable of elements using the custom element type.\n   * @param toKey A function that converts a custom element `K` to a primitive\n   *   key `KM`. This function must be deterministic and produce unique values\n   *   for unique elements.\n   * @param fromKey A function that converts a primitive key `KM` back to the\n   *   custom element `K`. This should be the inverse of `toKey`.\n   * @returns A new ISetMapped instance containing all unique elements from the\n   *   iterable.\n   */\n  export const create = <K, KM extends MapSetKeyType>(\n    iterable: Iterable<K>,\n    toKey: (a: K) => KM,\n    fromKey: (k: KM) => K,\n  ): ISetMapped<K, KM> => new ISetMappedClass<K, KM>(iterable, toKey, fromKey);\n\n  /**\n   * Checks if two ISetMapped instances are structurally equal.\n   *\n   * Two ISetMapped instances are considered equal if they have the same size\n   * and contain exactly the same elements. The comparison is performed on the\n   * underlying mapped keys, so the transformation functions themselves don't\n   * need to be identical. Elements are compared based on their mapped key\n   * representations.\n   *\n   * **Performance:** O(n) where n is the size of the smaller set.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const first = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const second = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 2, tag: 'b' },\n   *     { x: 1, tag: 'a' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const third = ISetMapped.create<Point, string>(\n   *   [{ x: 3, tag: 'c' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * assert.isTrue(ISetMapped.equal(first, second));\n   *\n   * assert.isFalse(ISetMapped.equal(first, third));\n   * ```\n   *\n   * @template K The type of the custom elements.\n   * @template KM The type of the mapped primitive keys.\n   * @param a The first ISetMapped instance to compare.\n   * @param b The second ISetMapped instance to compare.\n   * @returns `true` if the sets contain exactly the same elements, `false`\n   *   otherwise.\n   */\n  export const equal = <K, KM extends MapSetKeyType>(\n    a: ISetMapped<K, KM>,\n    b: ISetMapped<K, KM>,\n  ): boolean => a.size === b.size && a.every((e) => b.has(e));\n\n  /**\n   * Computes the difference between two ISetMapped instances.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const previous = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const current = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 2, tag: 'b' },\n   *     { x: 3, tag: 'c' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const { added, deleted } = ISetMapped.diff(previous, current);\n   *\n   * assert.deepStrictEqual(Array.from(added), [{ x: 3, tag: 'c' }]);\n   *\n   * assert.deepStrictEqual(Array.from(deleted), [{ x: 1, tag: 'a' }]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @template KM The type of the mapped keys.\n   * @param oldSet The original set.\n   * @param newSet The new set.\n   * @returns An object containing sets of added and deleted elements.\n   */\n  export const diff = <K, KM extends MapSetKeyType>(\n    oldSet: ISetMapped<K, KM>,\n    newSet: ISetMapped<K, KM>,\n  ): ReadonlyRecord<'added' | 'deleted', ISetMapped<K, KM>> =>\n    ({\n      deleted: oldSet.subtract(newSet),\n      added: newSet.subtract(oldSet),\n    }) as const;\n\n  /**\n   * Computes the intersection of two ISetMapped instances.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const overlap = ISetMapped.intersection(left, right);\n   *\n   * assert.deepStrictEqual(Array.from(overlap), [{ x: 2, tag: 'b' }]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @template KM The type of the mapped keys.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISetMapped instance representing the intersection.\n   */\n  export const intersection = <K, KM extends MapSetKeyType>(\n    a: ISetMapped<K, KM>,\n    b: ISetMapped<K, KM>,\n  ): ISetMapped<K, KM> => a.intersect(b);\n\n  /**\n   * Computes the union of two ISetMapped instances.\n   *\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const left = ISetMapped.create<Point, string>(\n   *   [{ x: 1, tag: 'a' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const right = ISetMapped.create<Point, string>(\n   *   [{ x: 2, tag: 'b' }],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const combined = ISetMapped.union(left, right);\n   *\n   * assert.deepStrictEqual(Array.from(combined), [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @template KM The type of the mapped keys.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISetMapped instance representing the union.\n   */\n  export const union = <K, KM extends MapSetKeyType>(\n    a: ISetMapped<K, KM>,\n    b: ISetMapped<K, KM>,\n  ): ISetMapped<K, KM> => a.union(b);\n}\n\n/**\n * Internal class implementation for ISetMapped providing immutable set\n * operations with element transformation.\n *\n * This class implements the ISetMapped interface by maintaining a JavaScript\n * Set with primitive keys internally while exposing an API that works with\n * custom element types. The transformation between custom and primitive\n * elements is handled transparently through the provided `toKey` and `fromKey`\n * functions.\n *\n * **Implementation Details:**\n *\n * - Uses ReadonlySet<KM> internally where KM is the primitive key type\n * - Stores transformation functions for bidirectional element conversion\n * - Implements copy-on-write semantics for efficiency\n * - Provides optional debug messaging for development\n *\n * @template K The type of the custom elements.\n * @template KM The type of the mapped primitive keys.\n * @implements ISetMapped\n * @implements Iterable\n * @internal This class should not be used directly. Use ISetMapped.create() instead.\n */\nclass ISetMappedClass<K, KM extends MapSetKeyType>\n  implements ISetMapped<K, KM>, Iterable<K>\n{\n  readonly #set: ReadonlySet<KM>;\n  readonly #toKey: (a: K) => KM;\n  readonly #fromKey: (k: KM) => K;\n  readonly #showNotFoundMessage: boolean;\n\n  /**\n   * Constructs an ISetMappedClass instance with custom element transformation.\n   *\n   * @param iterable An iterable of elements using the custom element type K.\n   * @param toKey A function that converts a custom element K to a primitive key\n   *   KM. Must be deterministic and produce unique values for unique elements.\n   * @param fromKey A function that converts a primitive key KM back to the\n   *   custom element K. Should be the inverse of the toKey function.\n   * @param showNotFoundMessage Whether to log warning messages when operations\n   *   are performed on non-existent elements. Useful for debugging. Defaults to\n   *   false for production use.\n   * @internal Use ISetMapped.create() instead of calling this constructor directly.\n   */\n  constructor(\n    iterable: Iterable<K>,\n    toKey: (a: K) => KM,\n    fromKey: (k: KM) => K,\n    showNotFoundMessage: boolean = false,\n  ) {\n    this.#set = new Set(Array.from(iterable, toKey));\n\n    this.#toKey = toKey;\n\n    this.#fromKey = fromKey;\n\n    this.#showNotFoundMessage = showNotFoundMessage;\n  }\n\n  /** @inheritdoc */\n  get size(): SizeType.Arr {\n    return asUint32(this.#set.size);\n  }\n\n  /** @inheritdoc */\n  get isEmpty(): boolean {\n    return this.size === 0;\n  }\n\n  /** @inheritdoc */\n  has(key: K | (WidenLiteral<K> & {})): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return this.#set.has(this.#toKey(key as K));\n  }\n\n  /** @inheritdoc */\n  every<L extends K>(\n    predicate: (key: K) => key is L,\n  ): this is ISetMapped<L, KM>;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (!predicate(key)) return false;\n    }\n\n    return true;\n  }\n\n  /** @inheritdoc */\n  some(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (predicate(key)) return true;\n    }\n\n    return false;\n  }\n\n  /** @inheritdoc */\n  add(key: K): ISetMapped<K, KM> {\n    if (this.has(key)) return this;\n\n    return ISetMapped.create(\n      [...this.#set, this.#toKey(key)].map(this.#fromKey),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  delete(key: K): ISetMapped<K, KM> {\n    if (!this.has(key)) {\n      if (this.#showNotFoundMessage) {\n        console.warn(\n          `ISetMapped.delete: key not found: ${unknownToString(this.#toKey(key))}`,\n        );\n      }\n\n      return this;\n    }\n\n    const keyMapped = this.#toKey(key);\n\n    return ISetMapped.create(\n      Array.from(this.#set)\n        .filter((k) => !Object.is(k, keyMapped))\n        .map(this.#fromKey),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  withMutations(\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ): ISetMapped<K, KM> {\n    const mut_result = new Set<KM>(this.#set);\n\n    const updateFn = (\n      action: Readonly<{ type: 'add'; key: K } | { type: 'delete'; key: K }>,\n    ): void => {\n      const key = this.#toKey(action.key);\n\n      switch (action.type) {\n        case 'delete':\n          mut_result.delete(key);\n\n          break;\n\n        case 'add':\n          mut_result.add(key);\n\n          break;\n      }\n    };\n\n    for (const action of actions) {\n      updateFn(action);\n    }\n\n    return ISetMapped.create<K, KM>(\n      Array.from(mut_result, this.#fromKey),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  map(mapFn: (key: K) => K): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().map(mapFn),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  filter(predicate: (key: K) => boolean): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter(predicate),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  filterNot(predicate: (key: K) => boolean): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter((k) => !predicate(k)),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  forEach(callbackfn: (key: K) => void): void {\n    for (const km of this.#set) {\n      callbackfn(this.#fromKey(km));\n    }\n  }\n\n  /** @inheritdoc */\n  isSubsetOf(set: ISetMapped<K, KM>): boolean {\n    return this.every((k) => set.has(k));\n  }\n\n  /** @inheritdoc */\n  isSupersetOf(set: ISetMapped<K, KM>): boolean {\n    return set.every((k) => this.has(k));\n  }\n\n  /** @inheritdoc */\n  subtract(set: ISetMapped<K, KM>): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter((k) => !set.has(k)),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  intersect(set: ISetMapped<K, KM>): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      this.toArray().filter((k) => set.has(k)),\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /** @inheritdoc */\n  union(set: ISetMapped<K, KM>): ISetMapped<K, KM> {\n    return ISetMapped.create(\n      [...this.values(), ...set.values()],\n      this.#toKey,\n      this.#fromKey,\n    );\n  }\n\n  /**\n   * @example\n   *\n   * ```ts\n   * type Point = Readonly<{ x: number; tag: string }>;\n   *\n   * const toKey = (point: Point) => JSON.stringify(point);\n   *\n   * // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n   * const fromKey = (key: string) => JSON.parse(key) as Point;\n   *\n   * const set = ISetMapped.create<Point, string>(\n   *   [\n   *     { x: 1, tag: 'a' },\n   *     { x: 2, tag: 'b' },\n   *   ],\n   *   toKey,\n   *   fromKey,\n   * );\n   *\n   * const collected = Array.from(set);\n   *\n   * assert.deepStrictEqual(collected, [\n   *   { x: 1, tag: 'a' },\n   *   { x: 2, tag: 'b' },\n   * ]);\n   * ```\n   *\n   * @inheritdoc\n   */\n  *[Symbol.iterator](): Iterator<K> {\n    for (const k of this.keys()) {\n      yield k;\n    }\n  }\n\n  /** @inheritdoc */\n  *keys(): IterableIterator<K> {\n    for (const km of this.#set) {\n      yield this.#fromKey(km);\n    }\n  }\n\n  /** @inheritdoc */\n  *values(): IterableIterator<K> {\n    for (const km of this.#set) {\n      // JavaScript Set's values() is an alias for keys()\n      yield this.#fromKey(km);\n    }\n  }\n\n  /** @inheritdoc */\n  *entries(): IterableIterator<FixedLengthTuple<2, K>> {\n    for (const km of this.#set) {\n      // JavaScript Set's entries() yields [value, value]\n      const a = this.#fromKey(km);\n\n      yield [a, a];\n    }\n  }\n\n  /** @inheritdoc */\n  toArray(): readonly K[] {\n    return Array.from(this.values());\n  }\n\n  /** @inheritdoc */\n  toRawSet(): ReadonlySet<KM> {\n    return this.#set;\n  }\n}\n"],"names":["ISetMapped"],"mappings":"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"}

package/dist/collections/iset.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"iset.mjs","sources":["../../src/collections/iset.mts"],"sourcesContent":["/* eslint-disable unicorn/prefer-iterator-to-array-at-end */\nimport {\n  type FixedLengthTuple,\n  type ReadonlyRecord,\n  type WidenLiteral,\n} from 'ts-type-forge';\nimport { asUint32 } from '../number/index.mjs';\nimport { unknownToString } from '../others/index.mjs';\nimport { type MapSetKeyType, type SizeType } from '../types.mjs';\n\n/**\n * Interface for an immutable set with membership testing and set operation\n * support.\n *\n * This interface defines all methods and properties available on ISet\n * instances. All operations that modify the set return new ISet instances,\n * preserving immutability. The underlying implementation uses JavaScript's\n * native Set but creates copies on mutations to maintain immutability.\n *\n * **Immutability Guarantees:**\n *\n * - All mutation operations (add, delete) return new ISet instances\n * - Original ISet instances are never modified\n * - Safe for concurrent access and functional programming patterns\n *\n * **Performance Characteristics:**\n *\n * - has: O(1) average case\n * - add/delete: O(n) due to copying for immutability\n * - set operations (union, intersection, difference): O(n)\n * - map/filter operations: O(n)\n * - iteration: O(n)\n *\n * @template K The type of the elements in the set. Must extend MapSetKeyType\n *   (string, number, boolean, etc.)\n */\ntype ISetInterface<K extends MapSetKeyType> = Readonly<{\n  // Getting information\n\n  /**\n   * The number of elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create([1, 2, 3]);\n   *\n   * assert.isTrue(set.size === 3);\n   * ```\n   */\n  size: SizeType.Arr;\n\n  /**\n   * Checks if the set is empty.\n   *\n   * @example\n   *\n   * ```ts\n   * const emptySet = ISet.create<number>([]);\n   *\n   * const filledSet = ISet.create([1, 2]);\n   *\n   * assert.isTrue(emptySet.isEmpty);\n   *\n   * assert.isFalse(filledSet.isEmpty);\n   * ```\n   */\n  isEmpty: boolean;\n\n  /**\n   * Checks if an element exists in the set. Allows for wider literal types for\n   * keys during checking.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['apple', 'banana']);\n   *\n   * assert.isTrue(set.has('apple'));\n   *\n   * assert.isFalse(set.has('cherry'));\n   * ```\n   *\n   * @param key The element to check.\n   * @returns `true` if the element exists, `false` otherwise.\n   */\n  has: (key: K | (WidenLiteral<K> & {})) => boolean;\n\n  // Reducing a value\n\n  /**\n   * Checks if all elements in the set satisfy a predicate. Also supports a\n   * type predicate overload that narrows the type of elements in the set if\n   * the predicate returns true for all elements.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([2, 4, 6]);\n   *\n   * const allEven = numbers.every((value) => value % 2 === 0);\n   *\n   * const narrowed = numbers.every(\n   *   (value): value is 2 | 4 | 6 => value % 2 === 0,\n   * );\n   *\n   * assert.isTrue(allEven);\n   *\n   * assert.isTrue(narrowed);\n   * ```\n   *\n   * @template L The narrowed type of the elements.\n   * @param predicate A function to test each element.\n   * @returns `true` if all elements satisfy the predicate, `false` otherwise.\n   */\n  every: ((predicate: (key: K) => boolean) => boolean) &\n    (<L extends K>(predicate: (key: K) => key is L) => this is ISet<L>);\n\n  /**\n   * Checks if at least one element in the set satisfies a predicate.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 3, 5]);\n   *\n   * assert.isTrue(numbers.some((value) => value > 4));\n   *\n   * assert.isFalse(numbers.some((value) => value > 10));\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns `true` if at least one element satisfies the predicate, `false`\n   *   otherwise.\n   */\n  some: (predicate: (key: K) => boolean) => boolean;\n\n  // Mutation\n\n  /**\n   * Adds an element to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const base = ISet.create<number>([1, 2]);\n   *\n   * const withThree = base.add(3);\n   *\n   * const unchanged = base.add(2);\n   *\n   * assert.deepStrictEqual(Array.from(withThree), [1, 2, 3]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to add.\n   * @returns A new ISet instance with the element added.\n   */\n  add: (key: K) => ISet<K>;\n\n  /**\n   * Deletes an element from the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const base = ISet.create<number>([1, 2, 3]);\n   *\n   * const withoutTwo = base.delete(2);\n   *\n   * const unchanged = base.delete(4);\n   *\n   * assert.deepStrictEqual(Array.from(withoutTwo), [1, 3]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to delete.\n   * @returns A new ISet instance without the specified element.\n   */\n  delete: (key: K) => ISet<K>;\n\n  /**\n   * Applies a series of mutations to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const base = ISet.create<string>(['a', 'b']);\n   *\n   * const actions: readonly Readonly<\n   *   { type: 'add'; key: string } | { type: 'delete'; key: string }\n   * >[] = [\n   *   { type: 'add', key: 'c' },\n   *   { type: 'delete', key: 'a' },\n   * ] as const;\n   *\n   * const mutated = base.withMutations(actions);\n   *\n   * assert.deepStrictEqual(Array.from(mutated), ['b', 'c']);\n   *\n   * assert.deepStrictEqual(Array.from(base), ['a', 'b']);\n   * ```\n   *\n   * @param actions An array of mutation actions (add or delete).\n   * @returns A new ISet instance with all mutations applied.\n   */\n  withMutations: (\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ) => ISet<K>;\n\n  // Sequence algorithms\n\n  /**\n   * Maps the elements of the set to new elements.\n   *\n   * @example\n   *\n   * ```ts\n   * const letters = ISet.create(['a', 'b']);\n   *\n   * const upper = letters.map((value) => value.toUpperCase());\n   *\n   * assert.deepStrictEqual(Array.from(upper), ['A', 'B']);\n   * ```\n   *\n   * @template K2 The type of the new elements.\n   * @param mapFn A function that maps an element to a new element.\n   * @returns A new ISet instance with mapped elements.\n   */\n  map: <K2 extends MapSetKeyType>(mapFn: (key: K) => K2) => ISet<K2>;\n\n  /**\n   * Filters the elements of the set based on a predicate. Also supports a type\n   * predicate overload that narrows the type of elements in the resulting set.\n   *\n   * @example\n   *\n   * ```ts\n   * const letters = ISet.create(['apple', 'bee', 'cat']);\n   *\n   * const shortWords = letters.filter((value) => value.length <= 3);\n   *\n   * const narrowed = letters.filter(\n   *   (value): value is 'bee' | 'cat' => value.length === 3,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(shortWords), ['bee', 'cat']);\n   *\n   * assert.deepStrictEqual(Array.from(narrowed), ['bee', 'cat']);\n   * ```\n   *\n   * @template K2 The narrowed type of the elements.\n   * @param predicate A function to test each element.\n   * @returns A new ISet instance with elements that satisfy the predicate.\n   */\n  filter: (<K2 extends K>(predicate: (key: K) => key is K2) => ISet<K2>) &\n    ((predicate: (key: K) => boolean) => ISet<K>);\n\n  /**\n   * Filters the elements of the set by excluding elements for which the\n   * predicate returns true.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 2, 3, 4]);\n   *\n   * const withoutEven = numbers.filterNot((value) => value % 2 === 0);\n   *\n   * assert.deepStrictEqual(Array.from(withoutEven), [1, 3]);\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns A new ISet instance with elements for which the predicate returned\n   *   `false`.\n   */\n  filterNot: (predicate: (key: K) => boolean) => ISet<K>;\n\n  // Set operations\n\n  /**\n   * Checks if this set is a subset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const subset = ISet.create<number>([1, 2]);\n   *\n   * const superset = ISet.create<number>([1, 2, 3]);\n   *\n   * assert.isTrue(subset.isSubsetOf(superset));\n   *\n   * assert.isFalse(superset.isSubsetOf(subset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a subset of the other set, `false`\n   *   otherwise.\n   */\n  isSubsetOf: (set: ISet<WidenLiteral<K>>) => boolean;\n\n  /**\n   * Checks if this set is a superset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const superset = ISet.create<string>(['a', 'b', 'c']);\n   *\n   * const subset = ISet.create<string>(['a', 'c']);\n   *\n   * assert.isTrue(superset.isSupersetOf(subset));\n   *\n   * assert.isFalse(subset.isSupersetOf(superset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a superset of the other set, `false`\n   *   otherwise.\n   */\n  isSupersetOf: (set: ISet<WidenLiteral<K>>) => boolean;\n\n  /**\n   * Returns a new set with elements that are in this set but not in another\n   * set.\n   *\n   * @example\n   *\n   * ```ts\n   * const all = ISet.create<number>([1, 2, 3, 4]);\n   *\n   * const toRemove = ISet.create<number>([2, 4]);\n   *\n   * const difference = all.subtract(toRemove);\n   *\n   * assert.deepStrictEqual(Array.from(difference), [1, 3]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISet instance representing the set difference.\n   */\n  subtract: (set: ISet<K>) => ISet<K>;\n\n  /**\n   * Returns a new set with elements that are common to both this set and\n   * another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const left = ISet.create<string>(['x', 'y']);\n   *\n   * const right = ISet.create<string>(['y', 'z']);\n   *\n   * const shared = left.intersect(right);\n   *\n   * assert.deepStrictEqual(Array.from(shared), ['y']);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISet instance representing the set intersection.\n   */\n  intersect: (set: ISet<K>) => ISet<K>;\n\n  /**\n   * Returns a new set with all elements from both this set and another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 2]);\n   *\n   * const letters = ISet.create(['a', 'b']);\n   *\n   * const combined = numbers.union(letters);\n   *\n   * assert.deepStrictEqual(Array.from(combined), [1, 2, 'a', 'b']);\n   * ```\n   *\n   * @template K2 The type of elements in the other set.\n   * @param set The other set.\n   * @returns A new ISet instance representing the set union.\n   */\n  union: <K2 extends MapSetKeyType>(set: ISet<K2>) => ISet<K | K2>;\n\n  // Side effects\n\n  /**\n   * Executes a callback function for each element in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['alpha', 'beta']);\n   *\n   * const mut_collected: string[] = [];\n   *\n   * set.forEach((value) => {\n   *   mut_collected.push(value);\n   * });\n   *\n   * assert.deepStrictEqual(mut_collected, ['alpha', 'beta']);\n   * ```\n   *\n   * @param callbackfn A function to execute for each element.\n   */\n  forEach: (callbackfn: (key: K) => void) => void;\n\n  // Iterators\n\n  /**\n   * Returns an iterator for the elements in the set (alias for values).\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create([1, 2]);\n   *\n   * const keys = Array.from(set.keys());\n   *\n   * assert.deepStrictEqual(keys, [1, 2]);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  keys: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['x', 'y']);\n   *\n   * const values = Array.from(set.values());\n   *\n   * assert.deepStrictEqual(values, ['x', 'y']);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  values: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the entries (element-element pairs) in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['red', 'blue']);\n   *\n   * const entries = Array.from(set.entries());\n   *\n   * assert.deepStrictEqual(entries, [\n   *   ['red', 'red'],\n   *   ['blue', 'blue'],\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of entries.\n   */\n  entries: () => IterableIterator<FixedLengthTuple<2, K>>;\n\n  // Conversion\n\n  /**\n   * Converts the elements of the set to an array.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['north', 'south']);\n   *\n   * assert.deepStrictEqual(set.toArray(), ['north', 'south']);\n   * ```\n   *\n   * @returns A readonly array of elements.\n   */\n  toArray: () => readonly K[];\n\n  /**\n   * Returns the underlying readonly JavaScript Set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['alpha']);\n   *\n   * const raw = set.toRawSet();\n   *\n   * assert.isTrue(isSet(raw));\n   *\n   * assert.isTrue(raw.has('alpha'));\n   * ```\n   *\n   * @returns The raw ReadonlySet instance.\n   */\n  toRawSet: () => ReadonlySet<K>;\n}>;\n\n/**\n * Represents an immutable set with high-performance operations and\n * comprehensive set algebra support.\n *\n * ISet is a persistent data structure that provides all the functionality of\n * JavaScript's Set while maintaining immutability. All operations that would\n * normally mutate the set instead return new ISet instances, making it safe for\n * functional programming and concurrent access.\n *\n * **Key Features:**\n *\n * - **Immutable**: All mutation operations return new instances\n * - **Set Operations**: Full support for union, intersection, difference,\n *   subset/superset checks\n * - **Type Safe**: Full TypeScript support with generic element types\n * - **Iterable**: Implements standard JavaScript iteration protocols\n * - **Functional**: Rich API for map, filter, and functional composition\n *\n * **When to Use:**\n *\n * - Managing collections of unique values with immutability guarantees\n * - Set algebra operations (unions, intersections, differences)\n * - Membership testing with O(1) performance\n * - Functional programming patterns requiring immutable collections\n *\n * @template K The type of the elements in the set. Must extend MapSetKeyType.\n */\nexport type ISet<K extends MapSetKeyType> = Iterable<K> & ISetInterface<K>;\n\n/** Provides utility functions for ISet. */\nexport namespace ISet {\n  /**\n   * Creates a new ISet instance from an iterable of elements.\n   *\n   * This factory function accepts any iterable of elements, including arrays,\n   * JavaScript Sets, other ISets, or custom iterables. Duplicate elements in\n   * the input iterable will be automatically deduplicated in the resulting\n   * set.\n   *\n   * **Performance:** O(n) where n is the number of elements in the iterable.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['a', 'a', 'b']);\n   *\n   * assert.deepStrictEqual(Array.from(set), ['a', 'b']);\n   * ```\n   *\n   * @template K The type of the elements. Must extend MapSetKeyType.\n   * @param iterable An iterable of elements (e.g., Array, Set, ISet, etc.)\n   * @returns A new ISet instance containing all unique elements from the\n   *   iterable.\n   */\n  export const create = <K extends MapSetKeyType>(\n    iterable: Iterable<K>,\n  ): ISet<K> => new ISetClass<K>(iterable);\n\n  /**\n   * Checks if two ISet instances are structurally equal.\n   *\n   * Two ISets are considered equal if they have the same size and contain\n   * exactly the same elements. The order of elements does not matter for\n   * equality comparison since sets are unordered collections. Elements are\n   * compared using JavaScript's `===` operator.\n   *\n   * **Performance:** O(n) where n is the size of the smaller set.\n   *\n   * @example\n   *\n   * ```ts\n   * const first = ISet.create<number>([1, 2]);\n   *\n   * const second = ISet.create<number>([2, 1]);\n   *\n   * const third = ISet.create<number>([1, 3]);\n   *\n   * assert.isTrue(ISet.equal(first, second));\n   *\n   * assert.isFalse(ISet.equal(first, third));\n   * ```\n   *\n   * @template K The type of the elements.\n   * @param a The first ISet instance to compare.\n   * @param b The second ISet instance to compare.\n   * @returns `true` if the sets contain exactly the same elements, `false`\n   *   otherwise.\n   */\n  export const equal = <K extends MapSetKeyType>(\n    a: ISet<K>,\n    b: ISet<K>,\n  ): boolean => a.size === b.size && a.every((e) => b.has(e));\n\n  /**\n   * Computes the difference between two ISet instances, identifying added and\n   * deleted elements.\n   *\n   * This function performs a set difference operation to determine what\n   * elements were added and what elements were deleted when transitioning from\n   * the old set to the new set. This is useful for change detection, state\n   * management, and synchronization scenarios.\n   *\n   * **Performance:** O(n + m) where n and m are the sizes of the old and new\n   * sets respectively.\n   *\n   * @example\n   *\n   * ```ts\n   * const previous = ISet.create<string>(['draft', 'review']);\n   *\n   * const current = ISet.create<string>(['review', 'published']);\n   *\n   * const { added, deleted } = ISet.diff(previous, current);\n   *\n   * assert.deepStrictEqual(Array.from(added), ['published']);\n   *\n   * assert.deepStrictEqual(Array.from(deleted), ['draft']);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @param oldSet The original set representing the previous state.\n   * @param newSet The new set representing the current state.\n   * @returns An object with `added` and `deleted` properties, each containing\n   *   an ISet of elements that were added or removed respectively.\n   */\n  export const diff = <K extends MapSetKeyType>(\n    oldSet: ISet<K>,\n    newSet: ISet<K>,\n  ): ReadonlyRecord<'added' | 'deleted', ISet<K>> =>\n    ({\n      deleted: oldSet.subtract(newSet),\n      added: newSet.subtract(oldSet),\n    }) as const;\n\n  /**\n   * Computes the intersection of two ISet instances.\n   *\n   * Returns a new set containing only the elements that are present in both\n   * input sets. This operation is commutative: `intersection(a, b) ===\n   * intersection(b, a)`.\n   *\n   * **Performance:** O(min(n, m)) where n and m are the sizes of the input\n   * sets.\n   *\n   * @example\n   *\n   * ```ts\n   * const left = ISet.create<number>([1, 2, 3]);\n   *\n   * const right = ISet.create<number>([2, 4]);\n   *\n   * const overlap = ISet.intersection(left, right);\n   *\n   * assert.deepStrictEqual(Array.from(overlap), [2]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISet instance containing elements common to both sets.\n   */\n  export const intersection = <K extends MapSetKeyType>(\n    a: ISet<K>,\n    b: ISet<K>,\n  ): ISet<K> => a.intersect(b);\n\n  /**\n   * Computes the union of two ISet instances.\n   *\n   * Returns a new set containing all elements that are present in either input\n   * set. Duplicate elements are automatically handled since sets only contain\n   * unique values. This operation is commutative: `union(a, b) === union(b,\n   * a)`.\n   *\n   * **Performance:** O(n + m) where n and m are the sizes of the input sets.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 2]);\n   *\n   * const words = ISet.create(['one', 'two']);\n   *\n   * const union = ISet.union(numbers, words);\n   *\n   * assert.deepStrictEqual(Array.from(union), [1, 2, 'one', 'two']);\n   * ```\n   *\n   * @template K1 The type of elements in the first set.\n   * @template K2 The type of elements in the second set.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISet instance containing all elements from both sets.\n   */\n  export const union = <K1 extends MapSetKeyType, K2 extends MapSetKeyType>(\n    a: ISet<K1>,\n    b: ISet<K2>,\n  ): ISet<K1 | K2> => a.union(b);\n}\n\n/**\n * Internal class implementation for ISet providing immutable set operations.\n *\n * This class implements the ISet interface using JavaScript's native Set as the\n * underlying storage mechanism for optimal performance. All mutation operations\n * create new instances rather than modifying the existing set, ensuring\n * immutability.\n *\n * **Implementation Details:**\n *\n * - Uses ReadonlySet<K> internally for type safety and performance\n * - Implements copy-on-write semantics for efficiency\n * - Provides optional debug messaging for development\n *\n * @template K The type of the elements. Must extend MapSetKeyType.\n * @implements ISet\n * @implements Iterable\n * @internal This class should not be used directly. Use ISet.create() instead.\n */\nclass ISetClass<K extends MapSetKeyType> implements ISet<K>, Iterable<K> {\n  readonly #set: ReadonlySet<K>;\n  readonly #showNotFoundMessage: boolean;\n\n  /**\n   * Constructs an ISetClass instance with the given elements.\n   *\n   * @param iterable An iterable of elements to populate the set.\n   * @param showNotFoundMessage Whether to log warning messages when operations\n   *   are performed on non-existent elements. Useful for debugging. Defaults to\n   *   false for production use.\n   * @internal Use ISet.create() instead of calling this constructor directly.\n   */\n  constructor(iterable: Iterable<K>, showNotFoundMessage: boolean = false) {\n    this.#set = new Set(iterable);\n\n    this.#showNotFoundMessage = showNotFoundMessage;\n  }\n\n  /** @inheritdoc */\n  get size(): SizeType.Arr {\n    return asUint32(this.#set.size);\n  }\n\n  /** @inheritdoc */\n  get isEmpty(): boolean {\n    return this.size === 0;\n  }\n\n  /** @inheritdoc */\n  has(key: K | (WidenLiteral<K> & {})): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return this.#set.has(key as K);\n  }\n\n  /** @inheritdoc */\n  every<L extends K>(predicate: (key: K) => key is L): this is ISet<L>;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (!predicate(key)) return false;\n    }\n\n    return true;\n  }\n\n  /** @inheritdoc */\n  some(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (predicate(key)) return true;\n    }\n\n    return false;\n  }\n\n  /** @inheritdoc */\n  add(key: K): ISet<K> {\n    if (this.has(key)) return this;\n\n    return ISet.create([...this.#set, key]);\n  }\n\n  /** @inheritdoc */\n  delete(key: K): ISet<K> {\n    if (!this.has(key)) {\n      if (this.#showNotFoundMessage) {\n        const keyStr = unknownToString(key);\n\n        console.warn(`ISet.delete: key not found: ${keyStr}`);\n      }\n\n      return this;\n    }\n\n    return ISet.create(Array.from(this.#set).filter((k) => !Object.is(k, key)));\n  }\n\n  /** @inheritdoc */\n  withMutations(\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ): ISet<K> {\n    const mut_result = new Set<K>(this.#set);\n\n    const updateFn = (\n      action: Readonly<{ type: 'add'; key: K } | { type: 'delete'; key: K }>,\n    ): void => {\n      switch (action.type) {\n        case 'delete':\n          mut_result.delete(action.key);\n\n          break;\n\n        case 'add':\n          mut_result.add(action.key);\n\n          break;\n      }\n    };\n\n    for (const action of actions) {\n      updateFn(action);\n    }\n\n    return ISet.create(mut_result);\n  }\n\n  /** @inheritdoc */\n  map<K2 extends MapSetKeyType>(mapFn: (key: K) => K2): ISet<K2> {\n    return ISet.create(this.toArray().map(mapFn));\n  }\n\n  /** @inheritdoc */\n  filter<K2 extends K>(predicate: (key: K) => key is K2): ISet<K2>;\n\n  /** @inheritdoc */\n  filter(predicate: (key: K) => boolean): ISet<K>;\n\n  /** @inheritdoc */\n  filter(predicate: (key: K) => boolean): ISet<K> {\n    return ISet.create(this.toArray().filter(predicate));\n  }\n\n  /** @inheritdoc */\n  filterNot(predicate: (key: K) => boolean): ISet<K> {\n    return ISet.create(this.toArray().filter((e) => !predicate(e)));\n  }\n\n  /** @inheritdoc */\n  forEach(callbackfn: (key: K) => void): void {\n    for (const v of this.#set) {\n      callbackfn(v);\n    }\n  }\n\n  /** @inheritdoc */\n  isSubsetOf(set: ISet<WidenLiteral<K>>): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return this.every((k) => set.has(k as WidenLiteral<K>));\n  }\n\n  /** @inheritdoc */\n  isSupersetOf(set: ISet<WidenLiteral<K>>): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return set.every((k) => this.has(k as K));\n  }\n\n  /** @inheritdoc */\n  subtract(set: ISet<K>): ISet<K> {\n    return ISet.create(this.toArray().filter((k) => !set.has(k)));\n  }\n\n  /** @inheritdoc */\n  intersect(set: ISet<K>): ISet<K> {\n    return ISet.create(this.toArray().filter((k) => set.has(k)));\n  }\n\n  /** @inheritdoc */\n  union<K2 extends MapSetKeyType>(set: ISet<K2>): ISet<K | K2> {\n    return ISet.create([...this, ...set]);\n  }\n\n  /**\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['first', 'second']);\n   *\n   * const collected = Array.from(set);\n   *\n   * assert.deepStrictEqual(collected, ['first', 'second']);\n   * ```\n   *\n   * @inheritdoc\n   */\n  [Symbol.iterator](): Iterator<K> {\n    return this.#set[Symbol.iterator]();\n  }\n\n  /** @inheritdoc */\n  keys(): IterableIterator<K> {\n    return this.#set.keys();\n  }\n\n  /** @inheritdoc */\n  values(): IterableIterator<K> {\n    return this.#set.values();\n  }\n\n  /** @inheritdoc */\n  entries(): IterableIterator<FixedLengthTuple<2, K>> {\n    return this.#set.entries();\n  }\n\n  /** @inheritdoc */\n  toArray(): readonly K[] {\n    return Array.from(this.values());\n  }\n\n  /** @inheritdoc */\n  toRawSet(): ReadonlySet<K> {\n    return this.#set;\n  }\n}\n"],"names":["ISet"],"mappings":"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"}
+{"version":3,"file":"iset.mjs","sources":["../../src/collections/iset.mts"],"sourcesContent":["/* eslint-disable unicorn/prefer-iterator-to-array-at-end */\nimport {\n  type FixedLengthTuple,\n  type ReadonlyRecord,\n  type WidenLiteral,\n} from 'ts-type-forge';\nimport { asUint32 } from '../number/index.mjs';\nimport { unknownToString } from '../others/index.mjs';\nimport { type MapSetKeyType, type SizeType } from '../types.mjs';\n\n/**\n * Interface for an immutable set with membership testing and set operation\n * support.\n *\n * This interface defines all methods and properties available on ISet\n * instances. All operations that modify the set return new ISet instances,\n * preserving immutability. The underlying implementation uses JavaScript's\n * native Set but creates copies on mutations to maintain immutability.\n *\n * **Immutability Guarantees:**\n *\n * - All mutation operations (add, delete) return new ISet instances\n * - Original ISet instances are never modified\n * - Safe for concurrent access and functional programming patterns\n *\n * **Performance Characteristics:**\n *\n * - has: O(1) average case\n * - add/delete: O(n) due to copying for immutability\n * - set operations (union, intersection, difference): O(n)\n * - map/filter operations: O(n)\n * - iteration: O(n)\n *\n * @template K The type of the elements in the set. Must extend MapSetKeyType\n *   (string, number, boolean, etc.)\n */\ntype ISetInterface<K extends MapSetKeyType> = Readonly<{\n  // Getting information\n\n  /**\n   * The number of elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create([1, 2, 3]);\n   *\n   * assert.isTrue(set.size === 3);\n   * ```\n   */\n  size: SizeType.Arr;\n\n  /**\n   * Checks if the set is empty.\n   *\n   * @example\n   *\n   * ```ts\n   * const emptySet = ISet.create<number>([]);\n   *\n   * const filledSet = ISet.create([1, 2]);\n   *\n   * assert.isTrue(emptySet.isEmpty);\n   *\n   * assert.isFalse(filledSet.isEmpty);\n   * ```\n   */\n  isEmpty: boolean;\n\n  /**\n   * Checks if an element exists in the set. Allows for wider literal types for\n   * keys during checking.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['apple', 'banana']);\n   *\n   * assert.isTrue(set.has('apple'));\n   *\n   * assert.isFalse(set.has('cherry'));\n   * ```\n   *\n   * @param key The element to check.\n   * @returns `true` if the element exists, `false` otherwise.\n   */\n  has: (key: K | (WidenLiteral<K> & {})) => boolean;\n\n  // Reducing a value\n\n  /**\n   * Checks if all elements in the set satisfy a predicate. Also supports a\n   * type predicate overload that narrows the type of elements in the set if\n   * the predicate returns true for all elements.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([2, 4, 6]);\n   *\n   * const allEven = numbers.every((value) => value % 2 === 0);\n   *\n   * const narrowed = numbers.every(\n   *   (value): value is 2 | 4 | 6 => value % 2 === 0,\n   * );\n   *\n   * assert.isTrue(allEven);\n   *\n   * assert.isTrue(narrowed);\n   * ```\n   *\n   * @template L The narrowed type of the elements.\n   * @param predicate A function to test each element.\n   * @returns `true` if all elements satisfy the predicate, `false` otherwise.\n   */\n  every: ((predicate: (key: K) => boolean) => boolean) &\n    (<L extends K>(predicate: (key: K) => key is L) => this is ISet<L>);\n\n  /**\n   * Checks if at least one element in the set satisfies a predicate.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 3, 5]);\n   *\n   * assert.isTrue(numbers.some((value) => value > 4));\n   *\n   * assert.isFalse(numbers.some((value) => value > 10));\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns `true` if at least one element satisfies the predicate, `false`\n   *   otherwise.\n   */\n  some: (predicate: (key: K) => boolean) => boolean;\n\n  // Mutation\n\n  /**\n   * Adds an element to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const base = ISet.create<number>([1, 2]);\n   *\n   * const withThree = base.add(3);\n   *\n   * const unchanged = base.add(2);\n   *\n   * assert.deepStrictEqual(Array.from(withThree), [1, 2, 3]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to add.\n   * @returns A new ISet instance with the element added.\n   */\n  add: (key: K) => ISet<K>;\n\n  /**\n   * Deletes an element from the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const base = ISet.create<number>([1, 2, 3]);\n   *\n   * const withoutTwo = base.delete(2);\n   *\n   * const unchanged = base.delete(4);\n   *\n   * assert.deepStrictEqual(Array.from(withoutTwo), [1, 3]);\n   *\n   * assert.isTrue(unchanged === base);\n   * ```\n   *\n   * @param key The element to delete.\n   * @returns A new ISet instance without the specified element.\n   */\n  delete: (key: K) => ISet<K>;\n\n  /**\n   * Applies a series of mutations to the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const base = ISet.create<string>(['a', 'b']);\n   *\n   * const actions: readonly Readonly<\n   *   { type: 'add'; key: string } | { type: 'delete'; key: string }\n   * >[] = [\n   *   { type: 'add', key: 'c' },\n   *   { type: 'delete', key: 'a' },\n   * ] as const;\n   *\n   * const mutated = base.withMutations(actions);\n   *\n   * assert.deepStrictEqual(Array.from(mutated), ['b', 'c']);\n   *\n   * assert.deepStrictEqual(Array.from(base), ['a', 'b']);\n   * ```\n   *\n   * @param actions An array of mutation actions (add or delete).\n   * @returns A new ISet instance with all mutations applied.\n   */\n  withMutations: (\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ) => ISet<K>;\n\n  // Sequence algorithms\n\n  /**\n   * Maps the elements of the set to new elements.\n   *\n   * @example\n   *\n   * ```ts\n   * const letters = ISet.create(['a', 'b']);\n   *\n   * const upper = letters.map((value) => value.toUpperCase());\n   *\n   * assert.deepStrictEqual(Array.from(upper), ['A', 'B']);\n   * ```\n   *\n   * @template K2 The type of the new elements.\n   * @param mapFn A function that maps an element to a new element.\n   * @returns A new ISet instance with mapped elements.\n   */\n  map: <K2 extends MapSetKeyType>(mapFn: (key: K) => K2) => ISet<K2>;\n\n  /**\n   * Filters the elements of the set based on a predicate. Also supports a type\n   * predicate overload that narrows the type of elements in the resulting set.\n   *\n   * @example\n   *\n   * ```ts\n   * const letters = ISet.create(['apple', 'bee', 'cat']);\n   *\n   * const shortWords = letters.filter((value) => value.length <= 3);\n   *\n   * const narrowed = letters.filter(\n   *   (value): value is 'bee' | 'cat' => value.length === 3,\n   * );\n   *\n   * assert.deepStrictEqual(Array.from(shortWords), ['bee', 'cat']);\n   *\n   * assert.deepStrictEqual(Array.from(narrowed), ['bee', 'cat']);\n   * ```\n   *\n   * @template K2 The narrowed type of the elements.\n   * @param predicate A function to test each element.\n   * @returns A new ISet instance with elements that satisfy the predicate.\n   */\n  filter: (<K2 extends K>(predicate: (key: K) => key is K2) => ISet<K2>) &\n    ((predicate: (key: K) => boolean) => ISet<K>);\n\n  /**\n   * Filters the elements of the set by excluding elements for which the\n   * predicate returns true.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 2, 3, 4]);\n   *\n   * const withoutEven = numbers.filterNot((value) => value % 2 === 0);\n   *\n   * assert.deepStrictEqual(Array.from(withoutEven), [1, 3]);\n   * ```\n   *\n   * @param predicate A function to test each element.\n   * @returns A new ISet instance with elements for which the predicate returned\n   *   `false`.\n   */\n  filterNot: (predicate: (key: K) => boolean) => ISet<K>;\n\n  // Set operations\n\n  /**\n   * Checks if this set is a subset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const subset = ISet.create<number>([1, 2]);\n   *\n   * const superset = ISet.create<number>([1, 2, 3]);\n   *\n   * assert.isTrue(subset.isSubsetOf(superset));\n   *\n   * assert.isFalse(superset.isSubsetOf(subset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a subset of the other set, `false`\n   *   otherwise.\n   */\n  isSubsetOf: (set: ISet<WidenLiteral<K>>) => boolean;\n\n  /**\n   * Checks if this set is a superset of another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const superset = ISet.create<string>(['a', 'b', 'c']);\n   *\n   * const subset = ISet.create<string>(['a', 'c']);\n   *\n   * assert.isTrue(superset.isSupersetOf(subset));\n   *\n   * assert.isFalse(subset.isSupersetOf(superset));\n   * ```\n   *\n   * @param set The other set.\n   * @returns `true` if this set is a superset of the other set, `false`\n   *   otherwise.\n   */\n  isSupersetOf: (set: ISet<WidenLiteral<K>>) => boolean;\n\n  /**\n   * Returns a new set with elements that are in this set but not in another\n   * set.\n   *\n   * @example\n   *\n   * ```ts\n   * const all = ISet.create<number>([1, 2, 3, 4]);\n   *\n   * const toRemove = ISet.create<number>([2, 4]);\n   *\n   * const difference = all.subtract(toRemove);\n   *\n   * assert.deepStrictEqual(Array.from(difference), [1, 3]);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISet instance representing the set difference.\n   */\n  subtract: (set: ISet<K>) => ISet<K>;\n\n  /**\n   * Returns a new set with elements that are common to both this set and\n   * another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const left = ISet.create<string>(['x', 'y']);\n   *\n   * const right = ISet.create<string>(['y', 'z']);\n   *\n   * const shared = left.intersect(right);\n   *\n   * assert.deepStrictEqual(Array.from(shared), ['y']);\n   * ```\n   *\n   * @param set The other set.\n   * @returns A new ISet instance representing the set intersection.\n   */\n  intersect: (set: ISet<K>) => ISet<K>;\n\n  /**\n   * Returns a new set with all elements from both this set and another set.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 2]);\n   *\n   * const letters = ISet.create(['a', 'b']);\n   *\n   * const combined = numbers.union(letters);\n   *\n   * assert.deepStrictEqual(Array.from(combined), [1, 2, 'a', 'b']);\n   * ```\n   *\n   * @template K2 The type of elements in the other set.\n   * @param set The other set.\n   * @returns A new ISet instance representing the set union.\n   */\n  union: <K2 extends MapSetKeyType>(set: ISet<K2>) => ISet<K | K2>;\n\n  // Side effects\n\n  /**\n   * Executes a callback function for each element in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['alpha', 'beta']);\n   *\n   * const mut_collected: string[] = [];\n   *\n   * set.forEach((value) => {\n   *   mut_collected.push(value);\n   * });\n   *\n   * assert.deepStrictEqual(mut_collected, ['alpha', 'beta']);\n   * ```\n   *\n   * @param callbackfn A function to execute for each element.\n   */\n  forEach: (callbackfn: (key: K) => void) => void;\n\n  // Iterators\n\n  /**\n   * Returns an iterator for the elements in the set (alias for values).\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create([1, 2]);\n   *\n   * const keys = Array.from(set.keys());\n   *\n   * assert.deepStrictEqual(keys, [1, 2]);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  keys: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the elements in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['x', 'y']);\n   *\n   * const values = Array.from(set.values());\n   *\n   * assert.deepStrictEqual(values, ['x', 'y']);\n   * ```\n   *\n   * @returns An iterable iterator of elements.\n   */\n  values: () => IterableIterator<K>;\n\n  /**\n   * Returns an iterator for the entries (element-element pairs) in the set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['red', 'blue']);\n   *\n   * const entries = Array.from(set.entries());\n   *\n   * assert.deepStrictEqual(entries, [\n   *   ['red', 'red'],\n   *   ['blue', 'blue'],\n   * ]);\n   * ```\n   *\n   * @returns An iterable iterator of entries.\n   */\n  entries: () => IterableIterator<FixedLengthTuple<2, K>>;\n\n  // Conversion\n\n  /**\n   * Converts the elements of the set to an array.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['north', 'south']);\n   *\n   * assert.deepStrictEqual(set.toArray(), ['north', 'south']);\n   * ```\n   *\n   * @returns A readonly array of elements.\n   */\n  toArray: () => readonly K[];\n\n  /**\n   * Returns the underlying readonly JavaScript Set.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['alpha']);\n   *\n   * const raw = set.toRawSet();\n   *\n   * assert.isTrue(isSet(raw));\n   *\n   * assert.isTrue(raw.has('alpha'));\n   * ```\n   *\n   * @returns The raw ReadonlySet instance.\n   */\n  toRawSet: () => ReadonlySet<K>;\n}>;\n\n/**\n * Represents an immutable set with high-performance operations and\n * comprehensive set algebra support.\n *\n * ISet is a persistent data structure that provides all the functionality of\n * JavaScript's Set while maintaining immutability. All operations that would\n * normally mutate the set instead return new ISet instances, making it safe for\n * functional programming and concurrent access.\n *\n * **Key Features:**\n *\n * - **Immutable**: All mutation operations return new instances\n * - **Set Operations**: Full support for union, intersection, difference,\n *   subset/superset checks\n * - **Type Safe**: Full TypeScript support with generic element types\n * - **Iterable**: Implements standard JavaScript iteration protocols\n * - **Functional**: Rich API for map, filter, and functional composition\n *\n * **When to Use:**\n *\n * - Managing collections of unique values with immutability guarantees\n * - Set algebra operations (unions, intersections, differences)\n * - Membership testing with O(1) performance\n * - Functional programming patterns requiring immutable collections\n *\n * @template K The type of the elements in the set. Must extend MapSetKeyType.\n */\nexport type ISet<K extends MapSetKeyType> = Iterable<K> & ISetInterface<K>;\n\n/** Provides utility functions for ISet. */\nexport namespace ISet {\n  /**\n   * Creates a new ISet instance from an iterable of elements.\n   *\n   * This factory function accepts any iterable of elements, including arrays,\n   * JavaScript Sets, other ISets, or custom iterables. Duplicate elements in\n   * the input iterable will be automatically deduplicated in the resulting\n   * set.\n   *\n   * **Performance:** O(n) where n is the number of elements in the iterable.\n   *\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['a', 'a', 'b']);\n   *\n   * assert.deepStrictEqual(Array.from(set), ['a', 'b']);\n   * ```\n   *\n   * @template K The type of the elements. Must extend MapSetKeyType.\n   * @param iterable An iterable of elements (e.g., Array, Set, ISet, etc.)\n   * @returns A new ISet instance containing all unique elements from the\n   *   iterable.\n   */\n  export const create = <K extends MapSetKeyType>(\n    iterable: Iterable<K>,\n  ): ISet<K> => new ISetClass<K>(iterable);\n\n  /**\n   * Checks if two ISet instances are structurally equal.\n   *\n   * Two ISets are considered equal if they have the same size and contain\n   * exactly the same elements. The order of elements does not matter for\n   * equality comparison since sets are unordered collections. Elements are\n   * compared using JavaScript's `===` operator.\n   *\n   * **Performance:** O(n) where n is the size of the smaller set.\n   *\n   * @example\n   *\n   * ```ts\n   * const first = ISet.create<number>([1, 2]);\n   *\n   * const second = ISet.create<number>([2, 1]);\n   *\n   * const third = ISet.create<number>([1, 3]);\n   *\n   * assert.isTrue(ISet.equal(first, second));\n   *\n   * assert.isFalse(ISet.equal(first, third));\n   * ```\n   *\n   * @template K The type of the elements.\n   * @param a The first ISet instance to compare.\n   * @param b The second ISet instance to compare.\n   * @returns `true` if the sets contain exactly the same elements, `false`\n   *   otherwise.\n   */\n  export const equal = <K extends MapSetKeyType>(\n    a: ISet<K>,\n    b: ISet<K>,\n  ): boolean => a.size === b.size && a.every((e) => b.has(e));\n\n  /**\n   * Computes the difference between two ISet instances, identifying added and\n   * deleted elements.\n   *\n   * This function performs a set difference operation to determine what\n   * elements were added and what elements were deleted when transitioning from\n   * the old set to the new set. This is useful for change detection, state\n   * management, and synchronization scenarios.\n   *\n   * **Performance:** O(n + m) where n and m are the sizes of the old and new\n   * sets respectively.\n   *\n   * @example\n   *\n   * ```ts\n   * const previous = ISet.create<string>(['draft', 'review']);\n   *\n   * const current = ISet.create<string>(['review', 'published']);\n   *\n   * const { added, deleted } = ISet.diff(previous, current);\n   *\n   * assert.deepStrictEqual(Array.from(added), ['published']);\n   *\n   * assert.deepStrictEqual(Array.from(deleted), ['draft']);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @param oldSet The original set representing the previous state.\n   * @param newSet The new set representing the current state.\n   * @returns An object with `added` and `deleted` properties, each containing\n   *   an ISet of elements that were added or removed respectively.\n   */\n  export const diff = <K extends MapSetKeyType>(\n    oldSet: ISet<K>,\n    newSet: ISet<K>,\n  ): ReadonlyRecord<'added' | 'deleted', ISet<K>> =>\n    ({\n      deleted: oldSet.subtract(newSet),\n      added: newSet.subtract(oldSet),\n    }) as const;\n\n  /**\n   * Computes the intersection of two ISet instances.\n   *\n   * Returns a new set containing only the elements that are present in both\n   * input sets. This operation is commutative: `intersection(a, b) ===\n   * intersection(b, a)`.\n   *\n   * **Performance:** O(min(n, m)) where n and m are the sizes of the input\n   * sets.\n   *\n   * @example\n   *\n   * ```ts\n   * const left = ISet.create<number>([1, 2, 3]);\n   *\n   * const right = ISet.create<number>([2, 4]);\n   *\n   * const overlap = ISet.intersection(left, right);\n   *\n   * assert.deepStrictEqual(Array.from(overlap), [2]);\n   * ```\n   *\n   * @template K The type of the elements.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISet instance containing elements common to both sets.\n   */\n  export const intersection = <K extends MapSetKeyType>(\n    a: ISet<K>,\n    b: ISet<K>,\n  ): ISet<K> => a.intersect(b);\n\n  /**\n   * Computes the union of two ISet instances.\n   *\n   * Returns a new set containing all elements that are present in either input\n   * set. Duplicate elements are automatically handled since sets only contain\n   * unique values. This operation is commutative: `union(a, b) === union(b,\n   * a)`.\n   *\n   * **Performance:** O(n + m) where n and m are the sizes of the input sets.\n   *\n   * @example\n   *\n   * ```ts\n   * const numbers = ISet.create([1, 2]);\n   *\n   * const words = ISet.create(['one', 'two']);\n   *\n   * const union = ISet.union(numbers, words);\n   *\n   * assert.deepStrictEqual(Array.from(union), [1, 2, 'one', 'two']);\n   * ```\n   *\n   * @template K1 The type of elements in the first set.\n   * @template K2 The type of elements in the second set.\n   * @param a The first set.\n   * @param b The second set.\n   * @returns A new ISet instance containing all elements from both sets.\n   */\n  export const union = <K1 extends MapSetKeyType, K2 extends MapSetKeyType>(\n    a: ISet<K1>,\n    b: ISet<K2>,\n  ): ISet<K1 | K2> => a.union(b);\n}\n\n/**\n * Internal class implementation for ISet providing immutable set operations.\n *\n * This class implements the ISet interface using JavaScript's native Set as the\n * underlying storage mechanism for optimal performance. All mutation operations\n * create new instances rather than modifying the existing set, ensuring\n * immutability.\n *\n * **Implementation Details:**\n *\n * - Uses ReadonlySet<K> internally for type safety and performance\n * - Implements copy-on-write semantics for efficiency\n * - Provides optional debug messaging for development\n *\n * @template K The type of the elements. Must extend MapSetKeyType.\n * @implements ISet\n * @implements Iterable\n * @internal This class should not be used directly. Use ISet.create() instead.\n */\nclass ISetClass<K extends MapSetKeyType> implements ISet<K>, Iterable<K> {\n  readonly #set: ReadonlySet<K>;\n  readonly #showNotFoundMessage: boolean;\n\n  /**\n   * Constructs an ISetClass instance with the given elements.\n   *\n   * @param iterable An iterable of elements to populate the set.\n   * @param showNotFoundMessage Whether to log warning messages when operations\n   *   are performed on non-existent elements. Useful for debugging. Defaults to\n   *   false for production use.\n   * @internal Use ISet.create() instead of calling this constructor directly.\n   */\n  constructor(iterable: Iterable<K>, showNotFoundMessage: boolean = false) {\n    this.#set = new Set(iterable);\n\n    this.#showNotFoundMessage = showNotFoundMessage;\n  }\n\n  /** @inheritdoc */\n  get size(): SizeType.Arr {\n    return asUint32(this.#set.size);\n  }\n\n  /** @inheritdoc */\n  get isEmpty(): boolean {\n    return this.size === 0;\n  }\n\n  /** @inheritdoc */\n  has(key: K | (WidenLiteral<K> & {})): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion, @typescript-eslint/no-unnecessary-type-assertion -- unnecessary only under the strict standard library; the stock one types `has` as taking exactly `K`\n    return this.#set.has(key as K);\n  }\n\n  /** @inheritdoc */\n  every<L extends K>(predicate: (key: K) => key is L): this is ISet<L>;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean;\n\n  /** @inheritdoc */\n  every(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (!predicate(key)) return false;\n    }\n\n    return true;\n  }\n\n  /** @inheritdoc */\n  some(predicate: (key: K) => boolean): boolean {\n    for (const key of this.values()) {\n      if (predicate(key)) return true;\n    }\n\n    return false;\n  }\n\n  /** @inheritdoc */\n  add(key: K): ISet<K> {\n    if (this.has(key)) return this;\n\n    return ISet.create([...this.#set, key]);\n  }\n\n  /** @inheritdoc */\n  delete(key: K): ISet<K> {\n    if (!this.has(key)) {\n      if (this.#showNotFoundMessage) {\n        const keyStr = unknownToString(key);\n\n        console.warn(`ISet.delete: key not found: ${keyStr}`);\n      }\n\n      return this;\n    }\n\n    return ISet.create(Array.from(this.#set).filter((k) => !Object.is(k, key)));\n  }\n\n  /** @inheritdoc */\n  withMutations(\n    actions: readonly Readonly<\n      { type: 'add'; key: K } | { type: 'delete'; key: K }\n    >[],\n  ): ISet<K> {\n    const mut_result = new Set<K>(this.#set);\n\n    const updateFn = (\n      action: Readonly<{ type: 'add'; key: K } | { type: 'delete'; key: K }>,\n    ): void => {\n      switch (action.type) {\n        case 'delete':\n          mut_result.delete(action.key);\n\n          break;\n\n        case 'add':\n          mut_result.add(action.key);\n\n          break;\n      }\n    };\n\n    for (const action of actions) {\n      updateFn(action);\n    }\n\n    return ISet.create(mut_result);\n  }\n\n  /** @inheritdoc */\n  map<K2 extends MapSetKeyType>(mapFn: (key: K) => K2): ISet<K2> {\n    return ISet.create(this.toArray().map(mapFn));\n  }\n\n  /** @inheritdoc */\n  filter<K2 extends K>(predicate: (key: K) => key is K2): ISet<K2>;\n\n  /** @inheritdoc */\n  filter(predicate: (key: K) => boolean): ISet<K>;\n\n  /** @inheritdoc */\n  filter(predicate: (key: K) => boolean): ISet<K> {\n    return ISet.create(this.toArray().filter(predicate));\n  }\n\n  /** @inheritdoc */\n  filterNot(predicate: (key: K) => boolean): ISet<K> {\n    return ISet.create(this.toArray().filter((e) => !predicate(e)));\n  }\n\n  /** @inheritdoc */\n  forEach(callbackfn: (key: K) => void): void {\n    for (const v of this.#set) {\n      callbackfn(v);\n    }\n  }\n\n  /** @inheritdoc */\n  isSubsetOf(set: ISet<WidenLiteral<K>>): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return this.every((k) => set.has(k as WidenLiteral<K>));\n  }\n\n  /** @inheritdoc */\n  isSupersetOf(set: ISet<WidenLiteral<K>>): boolean {\n    // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n    return set.every((k) => this.has(k as K));\n  }\n\n  /** @inheritdoc */\n  subtract(set: ISet<K>): ISet<K> {\n    return ISet.create(this.toArray().filter((k) => !set.has(k)));\n  }\n\n  /** @inheritdoc */\n  intersect(set: ISet<K>): ISet<K> {\n    return ISet.create(this.toArray().filter((k) => set.has(k)));\n  }\n\n  /** @inheritdoc */\n  union<K2 extends MapSetKeyType>(set: ISet<K2>): ISet<K | K2> {\n    return ISet.create([...this, ...set]);\n  }\n\n  /**\n   * @example\n   *\n   * ```ts\n   * const set = ISet.create(['first', 'second']);\n   *\n   * const collected = Array.from(set);\n   *\n   * assert.deepStrictEqual(collected, ['first', 'second']);\n   * ```\n   *\n   * @inheritdoc\n   */\n  [Symbol.iterator](): Iterator<K> {\n    return this.#set[Symbol.iterator]();\n  }\n\n  /** @inheritdoc */\n  keys(): IterableIterator<K> {\n    return this.#set.keys();\n  }\n\n  /** @inheritdoc */\n  values(): IterableIterator<K> {\n    return this.#set.values();\n  }\n\n  /** @inheritdoc */\n  entries(): IterableIterator<FixedLengthTuple<2, K>> {\n    return this.#set.entries();\n  }\n\n  /** @inheritdoc */\n  toArray(): readonly K[] {\n    return Array.from(this.values());\n  }\n\n  /** @inheritdoc */\n  toRawSet(): ReadonlySet<K> {\n    return this.#set;\n  }\n}\n"],"names":["ISet"],"mappings":"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"}

package/dist/entry-point.mjs

@@ -1,13 +1,15 @@
 import * as index from './array/impl/index.mjs';
 export { index as Arr };
+import * as index$1 from './functional/async-result/impl/index.mjs';
+export { index$1 as AsyncResult };
 export { match } from './functional/match.mjs';
-import * as index$1 from './functional/optional/impl/index.mjs';
-export { index$1 as Optional };
+import * as index$2 from './functional/optional/impl/index.mjs';
+export { index$2 as Optional };
 export { pipe } from './functional/pipe.mjs';
-import * as index$2 from './functional/result/impl/index.mjs';
-export { index$2 as Result };
-import * as index$3 from './functional/ternary-result/impl/index.mjs';
-export { index$3 as TernaryResult };
+import * as index$3 from './functional/result/impl/index.mjs';
+export { index$3 as Result };
+import * as index$4 from './functional/ternary-result/impl/index.mjs';
+export { index$4 as TernaryResult };
 export { IMapMapped } from './collections/imap-mapped.mjs';
 export { IMap } from './collections/imap.mjs';
 export { ISetMapped } from './collections/iset-mapped.mjs';

package/dist/entry-point.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"entry-point.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"entry-point.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/functional/async-result/async-result.d.mts

@@ -0,0 +1,16 @@
+import { type Result } from '../result/index.mjs';
+/**
+ * Represents an asynchronous computation that can either succeed (`Ok`) or
+ * fail (`Err`) — a `Promise` that resolves to a `Result<S, E>`.
+ *
+ * Unlike a raw `Promise`, an `AsyncResult` never rejects for expected
+ * failures: errors are carried in the `Err` channel with a concrete type `E`,
+ * so they can be handled with the same combinators as a synchronous
+ * `Result`.
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ */
+export type AsyncResult<S, E> = Promise<Result<S, E>>;
+export * as AsyncResult from './impl/index.mjs';
+//# sourceMappingURL=async-result.d.mts.map

package/dist/functional/async-result/async-result.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-result.d.mts","sourceRoot":"","sources":["../../../src/functional/async-result/async-result.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEtD,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC"}

package/dist/functional/async-result/async-result.mjs

@@ -0,0 +1,3 @@
+import * as index from './impl/index.mjs';
+export { index as AsyncResult };
+//# sourceMappingURL=async-result.mjs.map

package/dist/functional/async-result/async-result.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-result.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/functional/async-result/impl/async-result-flat-map.d.mts

@@ -0,0 +1,39 @@
+import { type UnknownResult } from '../../result/index.mjs';
+import { type AsyncResult } from '../async-result.mjs';
+import { type UnknownAsyncResult, type UnwrapErr, type UnwrapOk } from './types.mjs';
+/**
+ * Applies a function that returns an `AsyncResult` or a `Result` to the
+ * success value of an `AsyncResult`. If the input resolves to `Err`, the
+ * original `Err` is passed through and the function is not called. This is
+ * the monadic bind operation for `AsyncResult`.
+ *
+ * @example
+ *
+ * ```ts
+ * const parseNumber = (input: string): Result<number, string> => {
+ *   const num = Number.parseInt(input, 10);
+ *
+ *   return Number.isNaN(num) ? Result.err('not a number') : Result.ok(num);
+ * };
+ *
+ * const input = AsyncResult.fromPromise(
+ *   Promise.resolve('42'),
+ *   () => 'failed',
+ * );
+ *
+ * const parsed = await AsyncResult.flatMap(input, parseNumber);
+ *
+ * assert.deepStrictEqual(parsed, Result.ok(42));
+ * ```
+ *
+ * @template S The type of the success value of the input.
+ * @template E The type of the error value of the input.
+ * @template R2 The `AsyncResult` or `Result` type returned by the function.
+ * @param asyncResult The `AsyncResult` to flat map.
+ * @param flatMapFn The function to apply that returns an `AsyncResult` or a
+ *   `Result`.
+ * @returns The result of applying the function, or the original `Err`.
+ */
+export declare function flatMap<S, E, R2 extends UnknownAsyncResult | UnknownResult>(asyncResult: AsyncResult<S, E>, flatMapFn: (value: S) => R2): AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>;
+export declare function flatMap<S, R2 extends UnknownAsyncResult | UnknownResult>(flatMapFn: (value: S) => R2): <E>(asyncResult: AsyncResult<S, E>) => AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>;
+//# sourceMappingURL=async-result-flat-map.d.mts.map

package/dist/functional/async-result/impl/async-result-flat-map.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-result-flat-map.d.mts","sourceRoot":"","sources":["../../../../src/functional/async-result/impl/async-result-flat-map.mts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,kBAAkB,GAAG,aAAa,EACzE,WAAW,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAC9B,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,GAC1B,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;AAWhD,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,SAAS,kBAAkB,GAAG,aAAa,EACtE,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,GAC1B,CAAC,CAAC,EACH,WAAW,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,KAC3B,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/functional/async-result/impl/async-result-flat-map.mjs

@@ -0,0 +1,25 @@
+import { isErr } from '../../result/impl/result-is-err.mjs';
+import '@sindresorhus/is';
+
+function flatMap(...args) {
+  switch (args.length) {
+    case 2: {
+      const [asyncResult, flatMapFn] = args;
+      return flatMapImpl(asyncResult, flatMapFn);
+    }
+    case 1: {
+      const [flatMapFn] = args;
+      return (asyncResult) => flatMapImpl(asyncResult, flatMapFn);
+    }
+  }
+}
+const flatMapImpl = async (asyncResult, flatMapFn) => {
+  const result = await asyncResult;
+  return isErr(result) ? result : (
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+    await flatMapFn(result.value)
+  );
+};
+
+export { flatMap };
+//# sourceMappingURL=async-result-flat-map.mjs.map

package/dist/functional/async-result/impl/async-result-flat-map.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-result-flat-map.mjs","sources":["../../../../src/functional/async-result/impl/async-result-flat-map.mts"],"sourcesContent":["import { Result, type UnknownResult } from '../../result/index.mjs';\nimport { type AsyncResult } from '../async-result.mjs';\nimport {\n  type UnknownAsyncResult,\n  type UnwrapErr,\n  type UnwrapOk,\n} from './types.mjs';\n\n/**\n * Applies a function that returns an `AsyncResult` or a `Result` to the\n * success value of an `AsyncResult`. If the input resolves to `Err`, the\n * original `Err` is passed through and the function is not called. This is\n * the monadic bind operation for `AsyncResult`.\n *\n * @example\n *\n * ```ts\n * const parseNumber = (input: string): Result<number, string> => {\n *   const num = Number.parseInt(input, 10);\n *\n *   return Number.isNaN(num) ? Result.err('not a number') : Result.ok(num);\n * };\n *\n * const input = AsyncResult.fromPromise(\n *   Promise.resolve('42'),\n *   () => 'failed',\n * );\n *\n * const parsed = await AsyncResult.flatMap(input, parseNumber);\n *\n * assert.deepStrictEqual(parsed, Result.ok(42));\n * ```\n *\n * @template S The type of the success value of the input.\n * @template E The type of the error value of the input.\n * @template R2 The `AsyncResult` or `Result` type returned by the function.\n * @param asyncResult The `AsyncResult` to flat map.\n * @param flatMapFn The function to apply that returns an `AsyncResult` or a\n *   `Result`.\n * @returns The result of applying the function, or the original `Err`.\n */\nexport function flatMap<S, E, R2 extends UnknownAsyncResult | UnknownResult>(\n  asyncResult: AsyncResult<S, E>,\n  flatMapFn: (value: S) => R2,\n): AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>;\n\n// Curried version\n//\n// The function's return type is captured as a whole (`R2`) and unwrapped with\n// `UnwrapOk` / `UnwrapErr`, instead of being written as\n// `AsyncResult<S2, E2> | Result<S2, E2>` with separate `S2` / `E2` type\n// parameters. With the union form, inference for `E2` collects a candidate\n// from matching `Ok<S2>` against `Err<E2>` (both have a `value` property), so\n// `E2` ends up as the success type and the call fails to type-check even for\n// a function annotated as returning `Result<S2, E2>`.\nexport function flatMap<S, R2 extends UnknownAsyncResult | UnknownResult>(\n  flatMapFn: (value: S) => R2,\n): <E>(\n  asyncResult: AsyncResult<S, E>,\n) => AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>;\n\nexport function flatMap<S, E, R2 extends UnknownAsyncResult | UnknownResult>(\n  ...args:\n    | readonly [asyncResult: AsyncResult<S, E>, flatMapFn: (value: S) => R2]\n    | readonly [flatMapFn: (value: S) => R2]\n):\n  | AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>\n  | ((\n      asyncResult: AsyncResult<S, E>,\n    ) => AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>>) {\n  switch (args.length) {\n    case 2: {\n      // Direct version: first argument is asyncResult\n      const [asyncResult, flatMapFn] = args;\n\n      return flatMapImpl(asyncResult, flatMapFn);\n    }\n\n    case 1: {\n      // Curried version\n      const [flatMapFn] = args;\n\n      return (asyncResult: AsyncResult<S, E>) =>\n        flatMapImpl(asyncResult, flatMapFn);\n    }\n  }\n}\n\nconst flatMapImpl = async <S, E, R2 extends UnknownAsyncResult | UnknownResult>(\n  asyncResult: AsyncResult<S, E>,\n  flatMapFn: (value: S) => R2,\n): AsyncResult<UnwrapOk<R2>, E | UnwrapErr<R2>> => {\n  const result = await asyncResult;\n\n  return Result.isErr(result)\n    ? result\n    : // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n      ((await flatMapFn(result.value)) as Result<UnwrapOk<R2>, UnwrapErr<R2>>);\n};\n"],"names":["Result.isErr"],"mappings":";;;AA6DO,SAAS,WACX,IAAA,EAOkD;AACrD,EAAA,QAAQ,KAAK,MAAA;AAAQ,IACnB,KAAK,CAAA,EAAG;AAEN,MAAA,MAAM,CAAC,WAAA,EAAa,SAAS,CAAA,GAAI,IAAA;AAEjC,MAAA,OAAO,WAAA,CAAY,aAAa,SAAS,CAAA;AAAA,IAC3C;AAAA,IAEA,KAAK,CAAA,EAAG;AAEN,MAAA,MAAM,CAAC,SAAS,CAAA,GAAI,IAAA;AAEpB,MAAA,OAAO,CAAC,WAAA,KACN,WAAA,CAAY,WAAA,EAAa,SAAS,CAAA;AAAA,IACtC;AAAA;AAEJ;AAEA,MAAM,WAAA,GAAc,OAClB,WAAA,EACA,SAAA,KACiD;AACjD,EAAA,MAAM,SAAS,MAAM,WAAA;AAErB,EAAA,OAAOA,KAAO,CAAM,MAAM,CAAA,GACtB,MAAA;AAAA;AAAA,IAEE,MAAM,SAAA,CAAU,MAAA,CAAO,KAAK;AAAA,GAAA;AACpC,CAAA;;;;"}

package/dist/functional/async-result/impl/async-result-from-promise.d.mts

@@ -0,0 +1,47 @@
+import { type AsyncResult } from '../async-result.mjs';
+/**
+ * Converts a `Promise` into an `AsyncResult`. If the input Promise resolves,
+ * the `AsyncResult` resolves to `Ok` with the resolved value. If the input
+ * Promise rejects, the rejection reason is passed through `mapError` and the
+ * `AsyncResult` resolves to `Err` with the mapped error.
+ *
+ * Passing `mapError` is what gives the error channel a concrete type `E`.
+ * Omitting it carries the rejection reason through untouched, leaving the
+ * error channel as `unknown` — the same contract as `Result.fromPromise`.
+ *
+ * @example
+ *
+ * ```ts
+ * const resolved = await AsyncResult.fromPromise(
+ *   Promise.resolve('ok'),
+ *   (error) => `failed: ${String(error)}`,
+ * );
+ *
+ * const rejected = await AsyncResult.fromPromise(
+ *   Promise.reject(new Error('boom')),
+ *   (error) => (isError(error) ? error.message : 'unknown'),
+ * );
+ *
+ * assert.deepStrictEqual(resolved, Result.ok('ok'));
+ *
+ * assert.deepStrictEqual(rejected, Result.err('boom'));
+ *
+ * // Without `mapError`, the rejection reason is carried as-is.
+ * const untyped = await AsyncResult.fromPromise(
+ *   Promise.reject(new Error('boom')),
+ * );
+ *
+ * assert.isTrue(Result.isErr(untyped));
+ * ```
+ *
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ * @param promise The Promise to convert.
+ * @param mapError The function applied to the rejection reason to produce the
+ *   error value. Omit it to carry the rejection reason as `unknown`.
+ * @returns An `AsyncResult<S, E>` that never rejects for the input Promise's
+ *   failure.
+ */
+export declare function fromPromise<S>(promise: Promise<S>): AsyncResult<S, unknown>;
+export declare function fromPromise<S, E>(promise: Promise<S>, mapError: (error: unknown) => E): AsyncResult<S, E>;
+//# sourceMappingURL=async-result-from-promise.d.mts.map

package/dist/functional/async-result/impl/async-result-from-promise.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-result-from-promise.d.mts","sourceRoot":"","sources":["../../../../src/functional/async-result/impl/async-result-from-promise.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAE7E,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,GAC9B,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/functional/async-result/impl/async-result-from-promise.mjs

@@ -0,0 +1,11 @@
+import { err } from '../../result/impl/result-err.mjs';
+import { ok } from '../../result/impl/result-ok.mjs';
+import '@sindresorhus/is';
+
+function fromPromise(promise, mapError) {
+  return mapError === void 0 ? fromPromiseImpl(promise, (error) => error) : fromPromiseImpl(promise, mapError);
+}
+const fromPromiseImpl = (promise, mapError) => promise.then((value) => ok(value)).catch((error) => err(mapError(error)));
+
+export { fromPromise };
+//# sourceMappingURL=async-result-from-promise.mjs.map