@geraintguan/ts-std-lib 1.0.0

package/dist/Data/HashMap.mjs

@@ -0,0 +1,503 @@
+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";
+class HashMapMissingKeyError extends Error {
+  constructor(map, key) {
+    super(
+      `Could not find key ${String(key)} (${typeof key}) in HashMap ${map.name}`
+    );
+    __publicField(this, "key");
+    __publicField(this, "map");
+    this.map = map;
+    this.key = key;
+  }
+}
+const _HashMap = class _HashMap {
+  constructor(hash, _map = /* @__PURE__ */ new Map(), name = "unknown") {
+    this.hash = hash;
+    this._map = _map;
+    this.name = name;
+  }
+  /**
+   * 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.
+   *
+   * @example
+   * ```typescript
+   * const map = HashMap.empty<number, string>();
+   *
+   * [...map]; // => []
+   *
+   * map.set(1, "one");
+   *
+   * [...map]; // => [[1, "one"]]
+   * ```
+   *
+   * @see {@link HashMap.emptyWithCustomHash}
+   *
+   * @param options - Options to use to create the new map instance.
+   *
+   * @returns A new empty map instance.
+   */
+  static empty(options = {}) {
+    return new _HashMap(identity, /* @__PURE__ */ new Map(), options.name);
+  }
+  /**
+   * Create a new empty map 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 _HashMap(
+      options.hash,
+      /* @__PURE__ */ new Map(),
+      options.name
+    );
+  }
+  /**
+   * Create a new map instance from an array of key-value pairs with
+   * a custom hashing function.
+   *
+   * @example Use ISO string representation of Date objects as hash keys
+   * ```typescript
+   * const map = HashMap.fromCustomEntries(
+   * [
+   *   [new Date("2020-01-01"), 1],
+   *   [new Date("2020-02-01"), 2],
+   *   [new Date("2020-03-01"), 3],
+   * ],
+   * {
+   *   hash(key) {
+   *     return key.toISOString();
+   *   },
+   * });
+   *
+   * [...map];
+   * // => [
+   * //   ["2020-01-01T00:00:00.000Z", 1],
+   * //   ["2020-02-01T00:00:00.000Z", 2],
+   * //   ["2020-03-01T00:00:00.000Z", 3],
+   * // ];
+   * ```
+   *
+   * @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 _HashMap(
+      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 which will therefore
+   * use the same behaviour as an ES6 `Map`.
+   *
+   * @example
+   * ```typescript
+   * const map = HashMap.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.
+   */
+  static fromEntries(entries, options = {}) {
+    return new _HashMap(
+      identity,
+      new Map(entries.map(([key, value]) => [key, value])),
+      options.name
+    );
+  }
+  /**
+   * Clears all of the entries in this map.
+   *
+   * @remarks
+   *
+   * This function **will mutate** the map instance it is called on.
+   *
+   *   * @example
+   * ```typescript
+   * const map = HashMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   * ]);
+   *
+   * map.clear();
+   *
+   * [...map]; // => []
+   * ```
+   */
+  clear() {
+    this._map.clear();
+  }
+  /**
+   * Delete an entry from this map by its key, throwing a
+   * {@link HashMap.MissingKeyError} if the key does not exist in this map.
+   *
+   * @example
+   * ```typescript
+   * const map = HashMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   * ]);
+   *
+   * map.delete(2);
+   *
+   * [...map];
+   * // => [
+   * //   [1, "one"],
+   * //   [3, "three"],
+   * // ]
+   *
+   * map.delete(4); // throws HashMap.MissingKeyError
+   * ```
+   *
+   * @param key - The key of the entry to delete.
+   *
+   * @throws {@link HashMap.MissingKeyError} if the key does not exist in this
+   * map.
+   */
+  delete(key) {
+    if (!this.has(key)) {
+      throw new _HashMap.MissingKeyError(this, key);
+    }
+    this._map.delete(this.hash(key));
+  }
+  /**
+   * Delete an entry from this map by its key and returns `true` if it exists,
+   * otherwise it simply returns `false`.
+   *
+   * @example
+   * ```typescript
+   * const map = HashMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   * ]);
+   *
+   * map.deleteIfExists(2); // => true
+   * map.deleteIfExists(4); // => false
+   *
+   * [...map];
+   * // => [
+   * //   [1, "one"],
+   * //   [3, "three"],
+   * // ]
+   * ```
+   *
+   * @param key - The key of the entry to delete.
+   *
+   * @returns `true` if the key existed and the entry was deleted, `false` if
+   * the key did not exist.
+   */
+  deleteIfExists(key) {
+    if (!this.has(key)) {
+      return false;
+    }
+    this.delete(key);
+    return true;
+  }
+  /**
+   * Returns the entries in this map as an {@link IterableIterator} which each
+   * entry as an array of `[key, value]`.
+   *
+   * @example
+   * ```typescript
+   * const map = HashMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   * ]);
+   *
+   * [...map.entries()];
+   * // => [
+   * //   [1, "one"],
+   * //   [2, "two"],
+   * //   [3, "three"],
+   * // ]
+   * ```
+   *
+   * @returns An {@link IterableIterator} of the entries in this
+   * map.
+   */
+  entries() {
+    const _this = this;
+    return function* () {
+      for (const [key, value] of _this._map.entries()) {
+        yield [key, value];
+      }
+    }();
+  }
+  /**
+   * 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
+   * 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"],
+   * ]);
+   *
+   * 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 = HashMap.fromEntries<number, string>([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"],
+   *   [4, "four"],
+   * ]);
+   *
+   * 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 _HashMap(this.hash, new Map(entries), this.name);
+  }
+  /**
+   * Get the value with the given key from this map, throwing a
+   * {@link HashMap.MissingKeyError} if the key does not exist.
+   *
+   * @example
+   * ```typescript
+   * const map = HashMap.fromEntries([
+   *   [1, "one"],
+   *   [2, "two"],
+   *   [3, "three"]
+   * ]);
+   *
+   * map.get(2) // => "two"
+   *
+   * map.get(4) // => throws HashMap.MissingKeyError
+   * ```
+   *
+   * @param key - The key of the value to get.
+   *
+   * @returns The value with the given key.
+   */
+  get(key) {
+    const value = this._map.get(this.hash(key));
+    if (!value) {
+      throw new HashMapMissingKeyError(this, key);
+    }
+    return value;
+  }
+  /**
+   * Get the value with the given key from this map if it exists, otherwise
+   * return the given default value.
+   *
+   * @param key - The key whose associated value is to be returned.
+   * @param defaultValue - The value to return if the key is not found.
+   *
+   * @returns - The value associated with the specified key, or the default
+   * value if the key does not exist.
+   */
+  getOr(key, defaultValue) {
+    const value = this._map.get(this.hash(key));
+    if (!value) {
+      return defaultValue;
+    }
+    return value;
+  }
+  /**
+   * Checks if this map has an entry with the given key.
+   *
+   * @param key - The key to check for.
+   *
+   * @returns `true` if the key exists in this map, `false` otherwise.
+   */
+  has(key) {
+    return this._map.has(this.hash(key));
+  }
+  /**
+   * Get the keys in this map as an {@link IterableIterator}.
+   *
+   * @returns The keys in this map as an {@link IterableIterator}.
+   */
+  keys() {
+    const _this = this;
+    return function* () {
+      for (const key of _this._map.keys()) {
+        yield 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.
+   *
+   * @example Swap the keys and values
+   * ```typescript
+   * const map = HashMap.fromEntries([
+   *  ["one", 1],
+   *  ["two", 2],
+   *  ["three", 3],
+   * ]);
+   *
+   * const swapped = map.map(([key, value]) => [value, key]);
+   * // => HashMap { 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 _HashMap(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)
+    ]);
+  }
+  /**
+   * Set the value of an entry by it's key in the map, creating a new entry if
+   * one doesn't exist or overriding an existing entry if one does.
+   *
+   * @param key - The key of the entry to set.
+   * @param value - The value to set the entry to.
+   */
+  set(key, value) {
+    this._map.set(this.hash(key), value);
+  }
+  /**
+   * Get the iterator over the entires in this map.
+   *
+   * @returns The entries in this map as an array of key-value pairs.
+   */
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+  /**
+   * Get the values in this map as an {@link IterableIterator}.
+   *
+   * @returns The values in this map as an {@link IterableIterator}.
+   */
+  values() {
+    return this._map.values();
+  }
+};
+/**
+ * Error thrown when attempting to access a key in the map that
+ * does not exist.
+ */
+__publicField(_HashMap, "MissingKeyError", HashMapMissingKeyError);
+let HashMap = _HashMap;
+export {
+  HashMap
+};

package/dist/Data/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Provides implementations of various useful data structures.
+ *
+ * @module Data
+ */
+export * from './DefaultMap.js';
+export * from './HashMap.js';

package/dist/Data/index.mjs

@@ -0,0 +1,6 @@
+import { DefaultMap } from "./DefaultMap.mjs";
+import { HashMap } from "./HashMap.mjs";
+export {
+  DefaultMap,
+  HashMap
+};

package/dist/Types/Unpack.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Utility type that returns the element type of an array type.
+ *
+ * @example Get type of element in an array type
+ * ```typescript
+ * type Elements = (string | number)[];
+ *
+ * type Element = Unpack<Elements> // (string | number)
+ * ```
+ */
+export type Unpack<T> = T extends (infer U)[] ? U : T;

package/dist/Types/index.d.ts

@@ -0,0 +1 @@
+export * from './Unpack.js';

package/dist/Types/index.mjs

@@ -0,0 +1 @@
+

package/dist/constant.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns a function that when called always returns the given value.
+ *
+ * @example
+ * ```typescript
+ * const nine = constant(9);
+ *
+ * nine() // => 9
+ * nine() // => 9
+ * nine() // => 9
+ * ```
+ *
+ * @param value - The value that should be returned.
+ *
+ * @returns A function that when called will always return the given value.
+ */
+export declare function constant<T>(value: T): () => T;

package/dist/constant.mjs

@@ -0,0 +1,6 @@
+function constant(value) {
+  return () => value;
+}
+export {
+  constant
+};

package/dist/identity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns the value it is called with.
+ *
+ * @remarks
+ * This function is useful when you want to explicitly pass a function as a
+ * callback that always returns the value it is called with.
+ *
+ * It is functionally equivalent to writing an anonymous function that returns
+ * it's first argument, but can sometimes make your code more readable.
+ *
+ * For example both of these expressions are functionally equivalent:
+ *
+ * ```typescript
+ * [1, 2, 3].map(v => v);
+ *
+ * [1, 2, 3].map(identity);
+ * ```
+ * @param value - The value to return.
+ *
+ * @returns The value the function was called with.
+ */
+export declare function identity<T>(value: T): T;

package/dist/identity.mjs

@@ -0,0 +1,6 @@
+function identity(value) {
+  return value;
+}
+export {
+  identity
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './constant.js';
+export * as Data from './Data/index.js';
+export * from './identity.js';
+export * as Types from './Types/index.js';

package/dist/index.mjs

@@ -0,0 +1,10 @@
+import { constant } from "./constant.mjs";
+import * as index from "./Data/index.mjs";
+import { identity } from "./identity.mjs";
+import * as index$1 from "./Types/index.mjs";
+export {
+  index as Data,
+  index$1 as Types,
+  constant,
+  identity
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@geraintguan/ts-std-lib",
+  "version": "1.0.0",
+  "license": "MIT",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "coverage": "vitest --coverage",
+    "docs": "typedoc",
+    "fix": "eslint --fix",
+    "lint": "eslint",
+    "test": "vitest",
+    "typecheck": "pnpm run typecheck:lib && pnpm run typecheck:node",
+    "typecheck:lib": "tsc --project tsconfig.lib.json --noEmit",
+    "typecheck:node": "tsc --project tsconfig.node.json --noEmit",
+    "prepare": "husky"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "volta": {
+    "node": "22.11.0"
+  },
+  "peerDependencies": {
+    "@types/node": ">=20"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "19.5.0",
+    "@commitlint/config-conventional": "19.5.0",
+    "@eslint/js": "9.15.0",
+    "@tsconfig/node20": "20.1.4",
+    "@types/eslint__js": "8.42.3",
+    "@types/node": "22.9.0",
+    "@vitest/coverage-v8": "2.1.5",
+    "eslint": "9.15.0",
+    "eslint-config-prettier": "9.1.0",
+    "eslint-plugin-perfectionist": "3.9.1",
+    "eslint-plugin-prettier": "5.2.1",
+    "husky": "9.1.6",
+    "semantic-release": "24.2.0",
+    "typedoc": "0.26.11",
+    "typescript": "5.6.3",
+    "typescript-eslint": "8.14.1-alpha.8",
+    "vite": "5.4.11",
+    "vite-plugin-dts": "4.3.0",
+    "vitest": "2.1.5"
+  }
+}