@geraintguan/ts-std-lib 1.0.0

package/dist/Data/DefaultMap.mjs

@@ -0,0 +1,321 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { identity } from "../identity.mjs";
+import { HashMap } from "./HashMap.mjs";
+class DefaultMap extends HashMap {
+  constructor(defaultValue, hash, map = /* @__PURE__ */ new Map(), name = "unknown") {
+    super(hash, map, name);
+    /**
+     * Default value to use in this map when accessing keys that do not exist.
+     *
+     * @remarks
+     *
+     * Two types of default value are supported:
+     *
+     * 1. Providing a **function** will make the map call the given function that
+     *    is called with the current access key to generate the default value.
+     *
+     * 2. Providing a static **value** that will be used as-is as the default
+     *    value.
+     */
+    __publicField(this, "defaultValue");
+    this.defaultValue = defaultValue;
+  }
+  /**
+   * Create a new empty map instance.
+   *
+   * @remarks
+   *
+   * This function uses the {@link identity} function as the hashing function
+   * meaning that keys will be stored without any changes.
+   *
+   * @see {@link DefaultMap.emptyWithCustomHash}
+   *
+   * @param options - Options to use to create the new map instance.
+   *
+   * @returns A new empty map instance.
+   */
+  static empty(options) {
+    return new DefaultMap(
+      options.defaultValue,
+      identity,
+      /* @__PURE__ */ new Map(),
+      options.name
+    );
+  }
+  /**
+   * Create a new empty mao instance with a custom hashing function.
+   *
+   * @param options - Options to use to create the new map instance.
+   *
+   * @returns A new empty map instance.
+   */
+  static emptyWithCustomHash(options) {
+    return new DefaultMap(
+      options.defaultValue,
+      options.hash,
+      /* @__PURE__ */ new Map(),
+      options.name
+    );
+  }
+  /**
+   * Create a new map instance from an array of key-value pairs with a custom
+   * hashing function.
+   *
+   * @param entries - Array of key-value pairs to create the map
+   * with.
+   * @param options - Options to use to create the new map instance.
+   *
+   * @returns A new map instance with the given key-value pairs and a given
+   * custom hashing function.
+   */
+  static fromCustomEntries(entries, options) {
+    return new DefaultMap(
+      options.defaultValue,
+      options.hash,
+      new Map(entries.map(([k, v]) => [options.hash(k), v])),
+      options.name
+    );
+  }
+  /**
+   * Create a new map instance from an array of key-value pairs
+   * using the {@link identity} as the hash function.
+   *
+   * @remarks
+   *
+   * This function uses the {@link identity} function as the hashing function
+   * meaning that keys will be stored without any changes.
+   *
+   * @example
+   * ```typescript
+   * const map = DefaultMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   * ]);
+   *
+   * [...map];
+   * // => [
+   * //   [1, "one"],
+   * //   [2, "two"],
+   * //   [3, "three"],
+   * // ];
+   * ```
+   *
+   * @param entries - Array of key-value pairs to create the map
+   * with.
+   * @param options - Options to use to create the new {map
+   * instance.
+   *
+   * @returns A new map instance with the given key-value pairs
+   * and default value.
+   */
+  static fromEntries(entries, options) {
+    return new DefaultMap(
+      options.defaultValue,
+      identity,
+      new Map(entries.map(([key, value]) => [key, value])),
+      options.name
+    );
+  }
+  /**
+   * Returns a new map with only the key-value pairs where the given function
+   * returns `true`, filtering out those that the given function returns `false`
+   * for.
+   *
+   * @remarks
+   *
+   * The new map will have the same default value as this map.
+   *
+   * This function does not mutate the original map instance **unless** you call
+   * a mutating function on the map (4th argument) inside the given function.
+   *
+   * @example Include entries where key is greater than 2
+   * ```typescript
+   * const map = HashMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   *   [4, "four"],
+   * ], {
+   *   defaultValue: {
+   *     type: "value",
+   *     value: "NaN",
+   *   }
+   * });
+   *
+   * const filtered = map.filter((value, key) => key > 2);
+   *
+   * [...filtered];
+   * // => [
+   * //   [3, "three"],
+   * //   [4, "four"],
+   * // ]
+   * ```
+   * @example Include entries where the value has a length greater than 3
+   * ```typescript
+   * const map = DefaultMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   *   [4, "four"],
+   * ], {
+   *   defaultValue: {
+   *     type: "value",
+   *     value: "NaN",
+   *   }
+   * });
+   *
+   * const filtered = map.filter((value) => value.length > 3);
+   *
+   * [...filtered];
+   * // => [
+   * //   [3, "three"],
+   * //   [4, "four"],
+   * // ]
+   * ```
+   *
+   * @param fn - Function called for each key-value pair in the map that returns
+   * `true` to include the pair in the new map or `false` to exclude it.
+   *
+   * @returns A new map with only the key-value pairs where the given function
+   * returned `true` for.
+   */
+  filter(fn) {
+    const entries = [];
+    for (const [key, value] of this.entries()) {
+      if (fn(value, key, entries.length, this)) {
+        entries.push([key, value]);
+      }
+    }
+    return new DefaultMap(
+      this.defaultValue,
+      this.hash,
+      new Map(entries),
+      this.name
+    );
+  }
+  /**
+   * Get the value with the given key from this map if it exists, if it doesn't
+   * return the default value configured for this map.
+   *
+   * @remarks
+   *
+   * Unlike {@link HashMap.get}, this method will not throw an error if the key
+   * does not exist in the map, instead returning the configured default value.
+   *
+   * Accessing an entry that does not exist with a key will set a new entry on
+   * the map with the given key and the created default value as the value of
+   * that entry.
+   *
+   * @param key - The key of the value to get.
+   *
+   * @returns The value with the given key in this map if it exists, if it
+   * doesn't then the default value configured for this map.
+   */
+  get(key) {
+    if (!this.has(key)) {
+      const defaultValue = this.defaultValue.type === "function" ? this.defaultValue.value(key) : this.defaultValue.value;
+      this.set(key, defaultValue);
+      return defaultValue;
+    }
+    return super.get(key);
+  }
+  /**
+   * Create a new map with entries that are the result of calling the given
+   * callback function on each of the key-value pairs in this map.
+   *
+   * @remarks
+   *
+   * The new map will have the same default value as this map.
+   *
+   * This function does not mutate the original map instance **unless** you call
+   * a mutating function on the map (4th argument) inside the given function.
+   *
+   * @example Swap the keys and values
+   * ```typescript
+   * const map = HashMap.fromEntries([
+   *  ["one", 1],
+   *  ["two", 2],
+   *  ["three", 3],
+   * ], {
+   *   defaultValue: {
+   *     type: "value",
+   *     value: "NaN",
+   *   }
+   * });
+   *
+   * const swapped = map.map(([key, value]) => [value, key]);
+   * // => DefaultMap { 1 => "one", 2 => "two", 3 => "three" }
+   * ```
+   *
+   * @param fn - Function to call on each key-value pair in the map. The result
+   * of this function is used as entries in the new map.
+   *
+   * @returns A new map with the new entries from calling the given function on
+   * each key-value pair in the map.
+   */
+  map(fn) {
+    const entries = [];
+    for (const [key, value] of this.entries()) {
+      entries.push(fn(value, key, entries.length, this));
+    }
+    return new DefaultMap(
+      this.defaultValue,
+      this.hash,
+      new Map(entries),
+      this.name
+    );
+  }
+  /**
+   * Create a new map with entries that have keys that are the result of calling
+   * the given callback function on each of the key-value pairs in this map.
+   *
+   * @remarks
+   *
+   * The new map will have the same default value as this map.
+   *
+   * This function does not mutate the original map instance **unless** you call
+   * a mutating function on the map (4th argument) inside the given function.
+   *
+   * @param fn - Function to call on each key-value pair in the map. The result
+   * of this function is used as the keys for the entries in the new map.
+   *
+   * @returns A new map with the entries with new keys from calling the given
+   * function on each key-value pair in the map.
+   */
+  mapKeys(fn) {
+    return this.map((value, key, index, original) => [
+      fn(key, value, index, original),
+      value
+    ]);
+  }
+  /**
+   * Create a new map with entries that have values that are the result of
+   * calling the given callback function on each of the key-value pairs in this
+   * map.
+   *
+   * @remarks
+   *
+   * The new map will have the same default value as this map.
+   *
+   * This function does not mutate the original map instance **unless** you call
+   * a mutating function on the map (4th argument) inside the given function.
+   *
+   * @param fn - Function to call on each key-value pair in the map. The result
+   * of this function is used as the values for the entries in the new map.
+   *
+   * @returns A new map with the entries with new values from calling the given
+   * function on each key-value pair in the map.
+   */
+  mapValues(fn) {
+    return this.map((value, key, index, original) => [
+      key,
+      fn(value, key, index, original)
+    ]);
+  }
+}
+export {
+  DefaultMap
+};