@geraintguan/ts-std-lib 1.0.0 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @geraintguan/ts-std-lib
+# Typescript Standard Library
 
 [![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)
@@ -6,7 +6,7 @@ Status](https://coveralls.io/repos/github/geraintguan/ts-std-lib/badge.svg?branc
 
 [API Reference](https://ts-std-lib.geraint.io)
 
-A practical and pragmatic standard library for TypeScript (and JavaScript).
+A practical and pragmatic universal standard library for TypeScript targeting Browser/Node.js runtimes.
 
 ## Installation
 

package/dist/Data/DefaultMap.mjs

@@ -1,25 +1,22 @@
-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 {
+  /**
+   * 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;
   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;
   }
   /**

package/dist/Data/HashMap.d.ts

@@ -1,8 +1,20 @@
-declare class HashMapMissingKeyError<TKey, TValue, TSerializedKey> extends Error {
-    readonly key: TKey;
-    readonly map: HashMap<TKey, TValue, TSerializedKey>;
-    constructor(map: HashMap<TKey, TValue, TSerializedKey>, key: TKey);
-}
+/**
+ * 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 HashMapFilterFn<TKey, TValue, THashedKey> = (value: TValue, key: THashedKey, index: number, original: HashMap<TKey, TValue, THashedKey>) => boolean;
 /**
  * Options for creating a new map instance.
  */
@@ -22,23 +34,11 @@ export interface HashMapOptions<TKey, THashedKey = TKey> {
      */
     name?: string;
 }
-/**
- * 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 HashMapFilterFn<TKey, TValue, THashedKey> = (value: TValue, key: THashedKey, index: number, original: HashMap<TKey, TValue, THashedKey>) => boolean;
+declare class HashMapMissingKeyError<TKey, TValue, TSerializedKey> extends Error {
+    readonly key: TKey;
+    readonly map: HashMap<TKey, TValue, TSerializedKey>;
+    constructor(map: HashMap<TKey, TValue, TSerializedKey>, key: TKey);
+}
 /**
  * Implementation of a key-value map that allows you to customise the way keys
  * are stored by using a custom hashing function.

package/dist/Data/HashMap.mjs

@@ -1,24 +1,26 @@
-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 {
+  key;
+  map;
   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 {
+class HashMap {
   constructor(hash, _map = /* @__PURE__ */ new Map(), name = "unknown") {
     this.hash = hash;
     this._map = _map;
     this.name = name;
   }
+  /**
+   * Error thrown when attempting to access a key in the map that
+   * does not exist.
+   */
+  static MissingKeyError = HashMapMissingKeyError;
   /**
    * Create a new empty map instance.
    *
@@ -45,7 +47,7 @@ const _HashMap = class _HashMap {
    * @returns A new empty map instance.
    */
   static empty(options = {}) {
-    return new _HashMap(identity, /* @__PURE__ */ new Map(), options.name);
+    return new HashMap(identity, /* @__PURE__ */ new Map(), options.name);
   }
   /**
    * Create a new empty map instance with a custom hashing function.
@@ -55,7 +57,7 @@ const _HashMap = class _HashMap {
    * @returns A new empty map instance.
    */
   static emptyWithCustomHash(options) {
-    return new _HashMap(
+    return new HashMap(
       options.hash,
       /* @__PURE__ */ new Map(),
       options.name
@@ -95,7 +97,7 @@ const _HashMap = class _HashMap {
    * a given custom hashing function.
    */
   static fromCustomEntries(entries, options) {
-    return new _HashMap(
+    return new HashMap(
       options.hash,
       new Map(entries.map(([k, v]) => [options.hash(k), v])),
       options.name
@@ -134,7 +136,7 @@ const _HashMap = class _HashMap {
    * @returns A new map instance with the given key-value pairs.
    */
   static fromEntries(entries, options = {}) {
-    return new _HashMap(
+    return new HashMap(
       identity,
       new Map(entries.map(([key, value]) => [key, value])),
       options.name
@@ -193,7 +195,7 @@ const _HashMap = class _HashMap {
    */
   delete(key) {
     if (!this.has(key)) {
-      throw new _HashMap.MissingKeyError(this, key);
+      throw new HashMap.MissingKeyError(this, key);
     }
     this._map.delete(this.hash(key));
   }
@@ -319,7 +321,7 @@ const _HashMap = class _HashMap {
         entries.push([key, value]);
       }
     }
-    return new _HashMap(this.hash, new Map(entries), this.name);
+    return new HashMap(this.hash, new Map(entries), this.name);
   }
   /**
    * Get the value with the given key from this map, throwing a
@@ -416,7 +418,7 @@ const _HashMap = class _HashMap {
     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);
+    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
@@ -491,13 +493,7 @@ const _HashMap = class _HashMap {
   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/groupByUnique.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Groups elements of an array by a key derived from each element, keeping only
+ * the last occurrence of each key.
+ *
+ * @remarks
+ * This function is useful when you want to group elements by a key but you know
+ * that each element can only appear once per key, or when you only care about
+ * the most recent value for each key.
+ *
+ * Unlike a traditional `groupBy()` function which returns an array of values
+ * for each key, this function returns a single value per key. If multiple
+ * elements produce the same key, only the latest (last) element in the array
+ * will be retained.
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { id: 1, name: "Alice" },
+ *   { id: 2, name: "Bob" },
+ *   { id: 3, name: "Charlie" },
+ * ];
+ *
+ * groupByUnique(users, (user) => user.id);
+ * // => {
+ * //   1: { id: 1, name: "Alice" },
+ * //   2: { id: 2, name: "Bob" },
+ * //   3: { id: 3, name: "Charlie" },
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // When there are duplicate keys, the last value wins
+ * const items = [
+ *   { key: "a", value: 1 },
+ *   { key: "b", value: 2 },
+ *   { key: "a", value: 3 },
+ * ];
+ *
+ * groupByUnique(items, (item) => item.key);
+ * // => {
+ * //   a: { key: "a", value: 3 },
+ * //   b: { key: "b", value: 2 },
+ * // }
+ * ```
+ *
+ * @param array - The array of elements to group.
+ * @param keyFn - A function that takes each element and returns the key to
+ *   group by.
+ *
+ * @returns An object where each key is derived from the key function and each
+ *   value is the corresponding (last) element from the array.
+ */
+export declare function groupByUnique<T, K extends PropertyKey>(array: T[], keyFn: (value: T) => K): Record<K, T>;

package/dist/groupByUnique.mjs

@@ -0,0 +1,11 @@
+function groupByUnique(array, keyFn) {
+  const result = {};
+  for (const item of array) {
+    const key = keyFn(item);
+    result[key] = item;
+  }
+  return result;
+}
+export {
+  groupByUnique
+};

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@geraintguan/ts-std-lib",
-  "version": "1.0.0",
+  "description": "A practical and pragmatic universal standard library for TypeScript targeting Browser/Node.js runtimes.",
+  "version": "1.2.0",
   "license": "MIT",
+  "repository": {
+    "url": "https://github.com/geraintguan/ts-std-lib"
+  },
   "type": "module",
-  "module": "./dist/index.mjs",
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.mjs"
+        "types": "./dist/*.d.ts",
+        "default": "./dist/*.mjs"
       }
     }
   },
@@ -19,39 +22,36 @@
     "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",
+    "typecheck": "tsc --noEmit",
     "prepare": "husky"
   },
   "publishConfig": {
     "access": "public"
   },
   "volta": {
-    "node": "22.11.0"
+    "node": "24.12.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"
+    "@commitlint/cli": "19.8.1",
+    "@commitlint/config-conventional": "19.8.1",
+    "@eslint/js": "9.31.0",
+    "@tsconfig/node20": "20.1.6",
+    "@types/node": "24.0.14",
+    "@vitest/coverage-v8": "3.2.4",
+    "eslint": "9.31.0",
+    "eslint-config-prettier": "10.1.5",
+    "eslint-plugin-perfectionist": "4.15.0",
+    "eslint-plugin-prettier": "5.5.1",
+    "husky": "9.1.7",
+    "semantic-release": "24.2.7",
+    "typedoc": "0.28.15",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.37.0",
+    "vite": "7.0.4",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "3.2.4"
   }
 }

package/dist/Data/index.d.ts

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

package/dist/Data/index.mjs

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

package/dist/Types/index.d.ts

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

package/dist/index.d.ts

@@ -1,4 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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
-};