@geraintguan/ts-std-lib 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Geraint Guan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @geraintguan/ts-std-lib
+
+[![Coverage
+Status](https://coveralls.io/repos/github/geraintguan/ts-std-lib/badge.svg?branch=main)](https://coveralls.io/github/geraintguan/ts-std-lib?branch=main)
+[![Semantic Release: Conventional Commits](https://img.shields.io/badge/Semantic_Release-Conventional_Commits-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+
+[API Reference](https://ts-std-lib.geraint.io)
+
+A practical and pragmatic standard library for TypeScript (and JavaScript).
+
+## Installation
+
+### NPM
+
+```shell
+npm install -S @geraintguan/ts-std-lib
+```
+
+### PNPM
+
+```shell
+pnpm add @geraintguan/ts-std-lib
+```
+
+## Usage
+
+### Data Structures
+
+#### `HashMap`
+
+[API Reference](https://ts-std-lib.geraint.io/classes/Data.HashMap.html)
+
+Implementation of a key-value map that allows you to customise the way keys are
+stored by using a custom hashing function.
+
+##### Example: `HashMap` of ISO8601 Date String keys
+
+One useful example is using a HashMap that accepts `Date` objects as keys but
+storing them as their [ISO8601 Date
+Strings](https://en.wikipedia.org/wiki/ISO_8601).
+
+```typescript
+import * as Std from "@geraintguan/ts-std-lib";
+
+const map = Std.Data.HashMap.emptyWithCustomHash<Date, number, string>({
+  hash(date) {
+    data.toISOString();
+  },
+});
+
+const today = new Date("2024-11-01T12:00:00.000Z");
+const tomorrow = new Date("2024-11-02T12:00:00.000Z");
+
+map.set(today, 2);
+map.set(tomorrow, 3);
+
+[...map.keys()]; // => [
+//   "2024-11-01T12:00:00.000Z",
+//   "2024-11-02T12:00:00.000Z"
+// ]
+```
+
+#### `DefaultMap`
+
+[API Reference](https://ts-std-lib.geraint.io/classes/Data.DefaultMap.html)
+
+Implementation of a key-value map that allows you to customise the way keys are
+stored by using a custom hashing function **and** specify either a value or
+value generator function that will be returned when trying to access
+non-existant keys.
+
+##### Example: `DefaultMap` of ID of documents with timestamp that defaults to current date and time
+
+```typescript
+import * as Std from "@geraintguan/ts-std-lib";
+
+type Document = {
+  id: string;
+};
+
+const map = Std.Data.DefaultMap.emptyWithCustomHash<Document, Date, string>({
+  defaultValue: {
+    type: "function",
+
+    value() {
+      return new Date(),
+    }
+  },
+  hash(document) {
+    return document.id;
+  },
+});
+
+const documentA = { id: "document-a" };
+const documentB = { id: "document-b" };
+const documentC = { id: "document-c" };
+
+map.set(documentA, new Date("2020-01-01T00:00:00.000Z"));
+map.set(documentB, new Date("2021-01-01T00:00:00.000Z"));
+
+map.get(documentA).toISOString() // => "2020-01-01T00:00:00.000Z"
+map.get(documentB).toISOString() // => "2021-01-01T00:00:00.000Z"
+map.get(documentC).toISOString() // => new Date().toISOString()
+
+[...map.keys()] // => [
+//   "document-a",
+//   "document-b",
+//   "document-c",
+// ]
+```
+
+### Utility Functions
+
+#### `constant()`
+
+[API Reference](https://ts-std-lib.geraint.io/functions/constant.html)
+
+Creates a function that always returns a specific value.
+
+##### Example
+
+```typescript
+import * as Std from "@geraintguan/ts-std-lib";
+
+const nine = Std.constant(9);
+
+nine(); // => 9
+nine(); // => 9
+nine(); // => 9
+```
+
+#### `identity()`
+
+[API Reference](https://ts-std-lib.geraint.io/functions/identity.html)
+
+Creates a function that always returns the value given to it as an argument.
+
+##### Example
+
+```typescript
+import * as Std from "@geraintguan/ts-std-lib";
+
+[true, false, true].filter(Std.identity); // => [
+//   true,
+//   true
+// ]
+```

package/dist/Data/DefaultMap.d.ts

@@ -0,0 +1,310 @@
+import { HashMap, HashMapOptions } from './HashMap.js';
+/**
+ * Function called to filter the entries in a map.
+ *
+ * @remarks
+ *
+ * It is possible to mutate the original map as you filter the entries in the
+ * map though this is not recommended in most cases as it is easy to introduce
+ * bugs in your code this way.
+ *
+ * @param value - The value of the entry in the map being filtered.
+ * @param key - The key of the entry in the map being filtered.
+ * @param index - The index of the entry in the map being filtered.
+ * @param original - The original map instance being filtered.
+ *
+ * @returns `true` to include the entry in the new map or `false` to exclude it.
+ */
+export type DefaultMapFilterFn<TKey, TValue, THashedKey, TDefaultValue extends TValue> = (value: TValue, key: THashedKey, index: number, original: DefaultMap<TKey, TValue, THashedKey, TDefaultValue>) => boolean;
+export interface DefaultMapOptions<TKey, TValue, THashedKey = TKey, TDefaultValue extends TValue = TValue> extends HashMapOptions<TKey, THashedKey> {
+    defaultValue: DefaultMap<TKey, TValue, THashedKey, TDefaultValue>["defaultValue"];
+}
+/**
+ * Implementation of a specialised key-value map, based on map, that
+ * is created with a default value for retrieving keys that have not been set in
+ * the map.
+ *
+ * @remarks
+ *
+ * As this map is based of map it provides the same functionality
+ * such as the ability to customise the hashing function.
+ *
+ * When a default value is returned for a non-existent key, an entry is created
+ * for that key with the default value.
+ *
+ * @example Using a static value as the default value
+ * ```typescript
+ * const map = DefaultMap.empty<string, number>({
+ *   defaultValue: { type: "value", value: 1 },
+ * });
+ *
+ * map.get("a"); // => 1
+ *
+ * map.set("b", 2);
+ * map.get("b"); // => 2
+ *
+ * [...map.keys()]; // => ["a", "b"]
+ * ```
+ *
+ * @example Using a function to generate the default value based on the key
+ * ```typescript
+ * const map = DefaultMap.empty<string, number>({
+ *   defaultValue: { type: "function", value: (key) => key.length },
+ * });
+ *
+ * map.get("cat"); // => 3
+ * map.get("cat-dog"); // => 7
+ *
+ * map.set("dog", 4);
+ * map.get("dog"); // => 4
+ *
+ * [...map.keys()]; // => ["cat", "cat-dog", "dog"]
+ * ```
+ */
+export declare class DefaultMap<TKey, TValue, THashedKey = TKey, TDefaultValue extends TValue = TValue> extends HashMap<TKey, TValue, THashedKey> {
+    /**
+     * 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.
+     */
+    defaultValue: {
+        type: "function";
+        value: (key: TKey) => TDefaultValue;
+    } | {
+        type: "value";
+        value: TDefaultValue;
+    };
+    constructor(defaultValue: DefaultMap<TKey, TValue, THashedKey, TDefaultValue>["defaultValue"], hash: (key: TKey) => THashedKey, map?: Map<THashedKey, TValue>, name?: string);
+    /**
+     * 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<TKey, TValue, TDefaultValue extends TValue = TValue>(options: Omit<DefaultMapOptions<TKey, TValue, TKey, TDefaultValue>, "hash">): DefaultMap<TKey, TValue, TKey, TDefaultValue>;
+    /**
+     * 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<TKey, TValue, THashedKey = TKey, TDefaultValue extends TValue = TValue>(options: DefaultMapOptions<TKey, TValue, THashedKey, TDefaultValue>): DefaultMap<TKey, TValue, THashedKey, TDefaultValue>;
+    /**
+     * 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<TKey, TValue, THashedKey = TKey, TDefaultValue extends TValue = TValue>(entries: [TKey, TValue][], options: DefaultMapOptions<TKey, TValue, THashedKey, TDefaultValue>): DefaultMap<TKey, TValue, THashedKey, TDefaultValue>;
+    /**
+     * 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<TKey, TValue, TDefaultValue extends TValue = TValue>(entries: [TKey, TValue][], options: Omit<DefaultMapOptions<TKey, TValue, TKey, TDefaultValue>, "hash">): DefaultMap<TKey, TValue, TKey, TDefaultValue>;
+    /**
+     * 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: DefaultMapFilterFn<TKey, TValue, THashedKey, TDefaultValue>): DefaultMap<TKey, TValue, THashedKey, TDefaultValue>;
+    /**
+     * 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: TKey): TDefaultValue | TValue;
+    /**
+     * 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: (value: TValue, key: THashedKey, index: number, original: DefaultMap<TKey, TValue, THashedKey, TDefaultValue>) => [THashedKey, TValue]): DefaultMap<TKey, TValue, THashedKey, TDefaultValue>;
+    /**
+     * 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: (key: THashedKey, value: TValue, index: number, original: DefaultMap<TKey, TValue, THashedKey, TDefaultValue>) => THashedKey): DefaultMap<TKey, TValue, THashedKey, TDefaultValue>;
+    /**
+     * 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: (value: TValue, key: THashedKey, index: number, original: DefaultMap<TKey, TValue, THashedKey, TDefaultValue>) => TValue): DefaultMap<TKey, TValue, THashedKey, TDefaultValue>;
+}