@vixsonous/map-array 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# MapArray
+
+A TypeScript utility class that converts arrays into an O(1) lookup HashMap while keeping them fully loopable. No dependencies, lightweight, and TypeScript-first.
+
+## Why MapArray?
+
+When working with arrays of objects, lookups like `array.find(item => item.id === id)` are O(N) — they scan the entire array every time. MapArray converts your array into a HashMap on initialization (O(N) once), then every subsequent lookup is O(1).
+
+```ts
+// ❌ Without MapArray — O(N) every lookup
+const user = users.find(u => u.id === "42");
+
+// ✅ With MapArray — O(1) every lookup
+const user = userMap.get("42");
+```
+
+## Installation
+
+```bash
+npm install @vixsonous/map-array
+```
+
+## Usage
+
+### Array of Objects
+
+```ts
+import { MapArray } from "@vixsonous/map-array";
+
+interface User {
+  id: number;
+  name: string;
+  age: number;
+}
+
+const users = [
+  { id: 1, name: "Alice", age: 20 },
+  { id: 2, name: "Bob", age: 24 },
+  { id: 3, name: "Charlie", age: 26 },
+];
+
+const userMap = new MapArray({ array: users, idField: "id" });
+
+userMap.get("1");         // { id: 1, name: "Alice", age: 20 }
+userMap.has("2");         // true
+userMap.has("99");        // false
+```
+
+### Primitive Array
+
+```ts
+const fruits = new MapArray({ array: ["apple", "banana", "cake"] });
+
+fruits.has("apple");      // true
+fruits.has("grape");      // false
+```
+
+> **Note:** Primitive arrays are automatically deduplicated since values are used as keys.
+
+## API
+
+### Constructor
+
+```ts
+new MapArray({ array?, idField? })
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | `Array<T>` | Optional. The array to convert. |
+| `idField` | `keyof T` | Required if `T` is an object. The field to use as the HashMap key. Must be a `string` or `number` field. |
+
+> TypeScript will enforce `idField` at compile time
+
+---
+
+### `get(id)`
+Returns the item with the given ID, or `undefined` if not found.
+```ts
+userMap.get("1"); // { id: 1, name: "Alice", age: 20 }
+userMap.get("99"); // undefined
+```
+
+---
+
+### `has(id)`
+Returns `true` if an item with the given ID exists.
+```ts
+userMap.has("1"); // true
+userMap.has("99"); // false
+```
+
+---
+
+### `add(value, id?)`
+Adds a new item. Optionally pass a custom ID.
+```ts
+userMap.add({ id: 4, name: "Diana", age: 30 });
+userMap.add({ id: 5, name: "Eve", age: 28 }, "custom-key");
+```
+
+---
+
+### `remove(id)`
+Removes the item with the given ID.
+```ts
+userMap.remove("1");
+userMap.has("1"); // false
+```
+
+---
+
+### `set(id, field, value)`
+Updates a specific field on an existing item. Type-safe — value must match the field's type.
+```ts
+userMap.set("2", "name", "Bobby");
+userMap.get("2"); // { id: 2, name: "Bobby", age: 24 }
+```
+
+---
+
+### `map(callback)`
+Works like `Array.map()` — iterates over all items and returns a new array.
+```ts
+const names = userMap.map(user => user.name);
+// ["Alice", "Bob", "Charlie"]
+```
+
+---
+
+### `forEach(callback)`
+Works like `Array.forEach()` — iterates over all items.
+```ts
+userMap.forEach((user, index) => console.log(index, user.name));
+```
+
+---
+
+### `findMap(ids, callback)`
+The standout feature. Maps only over a **subset of IDs** instead of the entire collection — O(K) where K is the number of IDs, instead of O(N).
+```ts
+const result = userMap.findMap(["1", "3"], user => user.name);
+// ["Alice", "Charlie"] — Bob is skipped entirely
+```
+
+Also works with a single ID:
+```ts
+userMap.findMap("1", user => user.name);
+// ["Alice"]
+```
+
+---
+
+### `toArray()`
+Converts the MapArray back to a plain array, reflecting the current state (including any additions or removals).
+```ts
+userMap.remove("1");
+userMap.toArray(); // [{ id: 2, ... }, { id: 3, ... }]
+```
+
+---
+
+### `getIds()`
+Returns all current keys as an array of strings.
+```ts
+userMap.getIds(); // ["1", "2", "3"]
+```
+
+---
+
+### `getLength()`
+Returns the number of items.
+```ts
+userMap.getLength(); // 3
+```
+
+---
+
+### Iterable
+MapArray supports `for...of` natively:
+```ts
+for (const user of userMap) {
+  console.log(user.name);
+}
+```
+
+## Immutability Note
+
+MapArray performs a deep clone (`structuredClone`) of your array on initialization, so mutations to the original array won't affect the MapArray and vice versa.
+
+```ts
+const arr = [{ id: 1, name: "Alice" }];
+const map = new MapArray({ array: arr, idField: "id" });
+
+arr[0].name = "Bob";
+map.get("1")?.name; // Still "Alice" ✅
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+type FieldId<T> = {
+    [TKey in keyof T]: T[TKey] extends string | number ? TKey : never;
+}[keyof T];
+type MapArrayParametersType<T> = T extends string | number | boolean ? {
+    array?: Array<T> | undefined;
+    idField?: never;
+} : {
+    array?: Array<T> | undefined;
+    idField: FieldId<T>;
+};
+export declare class MapArray<T> {
+    private readonly hashMap;
+    private readonly idField?;
+    constructor({ array, idField }: MapArrayParametersType<T>);
+    get(id: string | number): T | undefined;
+    has(id: string | number): boolean;
+    add(value: T, id?: string): void;
+    remove(id: string): void;
+    set<K extends keyof T>(id: string, field: K, value: T[K]): void;
+    map<TData>(callback: (item: T, index: number) => TData): Array<TData>;
+    forEach(callback: (item: T, index: number) => void): void;
+    findMap<TData>(ids: string | Array<string>, callback: (item: T, index: number) => TData): TData[];
+    getIds(): Array<string>;
+    getLength(): number;
+    [Symbol.iterator](): MapIterator<T>;
+    toArray(): Array<T>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,95 @@
+/* Map Array is for object arrays, can also be used for single dimensional arrays but uses their value as accessor instead of index
+ * On initialization, perform O(N) operation to transform array into a HashMap
+ * On Item lookup, perform O(1) operation by using the idField as the field lookup
+ * The items in the hashmap is mutable
+ * If the specified array is a one dimensional array of primary data types, this will create a unique array
+ * If the specified array is a one dimensional array of objects, the uniqueness of the array will depend on the idField specified
+ * */
+export class MapArray {
+    constructor({ array = [], idField = undefined }) {
+        this.hashMap = new Map();
+        this.idField = undefined;
+        const clonedArray = structuredClone(array);
+        clonedArray.forEach((item) => {
+            if (item === undefined || item === null)
+                return;
+            if (typeof item === "object" && idField === undefined) {
+                throw new Error("if the items are objects, idField must be defined!");
+            }
+            if (idField && typeof item === "object" && !(idField in item)) {
+                throw new Error("The specified id field is not in the item!");
+            }
+            /* If the type of the item is an object, then it will use the value of the specified field as the key. Otherwise, it will use itself as the key*/
+            this.hashMap.set(typeof item === "object" && idField ? String(item[idField]) : String(item), item);
+        });
+        this.idField = idField;
+    }
+    /* Gets the item from the hash array using the ID as the hash key */
+    get(id) {
+        return this.hashMap.get(String(id));
+    }
+    /* Checks the hash array if it contains an item with the specified key */
+    has(id) {
+        return this.hashMap.has(String(id));
+    }
+    /* Adds a new item to the hash array
+     * Optional id parameter if custom ID is needed
+     * */
+    add(value, id) {
+        const field = this.idField;
+        if (typeof value === "object" && field === undefined) {
+            throw new Error("The value is an object but the idField is not defined!");
+        }
+        this.hashMap.set(id ? id : String(typeof value === "object" && value !== null && field ? value[field] : value), value);
+    }
+    remove(id) {
+        this.hashMap.delete(id);
+    }
+    /* Sets the value of the specified item key */
+    set(id, field, value) {
+        const item = this.hashMap.get(id);
+        if (item === undefined || item === null) {
+            throw new Error("The item to modify is undefined!");
+        }
+        item[field] = value;
+    }
+    /* This will call the map data */
+    map(callback) {
+        const items = [];
+        let mapCounter = 0;
+        this.hashMap.forEach((item) => {
+            const modifiedItem = callback(item, mapCounter++);
+            items.push(modifiedItem);
+        });
+        return items;
+    }
+    forEach(callback) {
+        let mapCounter = 0;
+        this.hashMap.forEach((item) => callback(item, mapCounter++));
+    }
+    /* This will perform a map operation only on a set of IDs K instead of looping through all array item N :: K < N */
+    findMap(ids, callback) {
+        const items = [];
+        const idsArray = Array.isArray(ids) ? [...ids] : [ids];
+        idsArray.forEach((id, idx) => {
+            const item = this.hashMap.get(id) ? callback(this.hashMap.get(id), idx) : null;
+            if (item === null)
+                return;
+            items.push(item);
+        });
+        return items;
+    }
+    /* Gets the keys of the hashmap and form into an array */
+    getIds() {
+        return Array.from(this.hashMap.keys());
+    }
+    getLength() {
+        return this.hashMap.size;
+    }
+    [Symbol.iterator]() {
+        return this.hashMap.values();
+    }
+    toArray() {
+        return Array.from(this.hashMap.values());
+    }
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest';
+import { MapArray } from "./index";
+const exampleObjectArray = [
+    { id: 1, name: "Alice", age: 20 },
+    { id: 2, name: "Bob", age: 24 },
+    { id: 3, name: "Charlie", age: 26 },
+];
+const examplePrimitiveStringArray = ["apple", "banana", "cake"];
+describe("MapArray", () => {
+    it('should create a MapArray from an array of objects', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        expect(mapArray.has("1")).toBe(true);
+        expect(mapArray.has("2")).toBe(true);
+        expect(mapArray.has("3")).toBe(true);
+        /* Non existent id */
+        expect(mapArray.has("4")).toBe(false);
+        expect(mapArray.get("1")).toStrictEqual({ id: 1, name: "Alice", age: 20 });
+        expect(mapArray.get("2")).toStrictEqual({ id: 2, name: "Bob", age: 24 });
+        expect(mapArray.get("3")).toStrictEqual({ id: 3, name: "Charlie", age: 26 });
+    });
+    it('should create a MapArray from a primitive array', () => {
+        const mapArray = new MapArray({ array: examplePrimitiveStringArray });
+        expect(mapArray.has("apple")).toBe(true);
+        expect(mapArray.has("banana")).toBe(true);
+        expect(mapArray.has("cake")).toBe(true);
+        expect(mapArray.has("Not existing item")).toBe(false);
+    });
+    it('should add an item', () => {
+        const mapArray = new MapArray({ idField: 'id' });
+        mapArray.add({ id: 4, name: "Danil", age: 50 });
+        expect(mapArray.has("4")).toBe(true);
+    });
+    it('should remove an item', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        mapArray.remove("3");
+        /* Map Array should not have the object with the "3" as ID anymore */
+        expect(mapArray.has("3")).toBe(false);
+    });
+    it('should map over items', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        const result = mapArray.map(item => item.name);
+        expect(result).toStrictEqual(exampleObjectArray.map(item => item.name));
+    });
+    it('should find and map over specific IDs', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        const idsToTarget = ["1", "2"]; /* Existing ids from the exampleObjectArray */
+        const result = mapArray.findMap(idsToTarget, (item) => item.name);
+        /* Expect to only map the objects that has the IDs 1 and 2 (from the target ids), leaving out "Charlie" */
+        expect(result).toStrictEqual(["Alice", "Bob"]);
+    });
+    it('should find and map a singular ID', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        const idToTarget = "1"; /* Existing ids from the exampleObjectArray */
+        const result = mapArray.findMap(idToTarget, (item) => item.name);
+        /* Expect to only map the objects that has the ID 1(from the target id), leaving out "Bob" and "Charlie" */
+        expect(result).toStrictEqual(["Alice"]);
+    });
+    it('should set a field value on an existing item in the array of objects', () => {
+        var _a;
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        const toModifyNameValue = "Victor";
+        mapArray.set("1", "name", toModifyNameValue);
+        expect((_a = mapArray.get("1")) === null || _a === void 0 ? void 0 : _a.name).toBe(toModifyNameValue);
+    });
+    it('should iterate over all items with forEach', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        const names = [];
+        mapArray.forEach(item => {
+            names.push(item.name);
+        });
+        expect(names).toStrictEqual(["Alice", "Bob", "Charlie"]);
+    });
+    it('should have an iterator to iterate throughout the map array', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        for (const item of mapArray) {
+            expect(mapArray.has(String(item.id))).toBe(true);
+        }
+    });
+    it('should convert the map array back to an array', () => {
+        const mapArray = new MapArray({ array: exampleObjectArray, idField: 'id' });
+        /* Should be similar to the original object array it came from*/
+        expect(mapArray.toArray()).toStrictEqual(exampleObjectArray);
+        const toModifyNameValue = "Victor";
+        mapArray.set("1", "name", toModifyNameValue);
+        /* It should convert to an array with the modified values */
+        expect(mapArray.toArray()).toStrictEqual([
+            { id: 1, name: toModifyNameValue, age: 20 },
+            { id: 2, name: "Bob", age: 24 },
+            { id: 3, name: "Charlie", age: 26 },
+        ]);
+    });
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@vixsonous/map-array",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "map",
+    "array",
+    "hashmap",
+    "typescript"
+  ],
+  "author": {
+    "name": "Victor Chiong",
+    "email": "chiong.vict@gmail.com",
+    "url": "https://victorchiong.com/"
+  },
+  "license": "MIT",
+  "description": "A typescript class that converts arrays into a loopable, O(1) lookup HashMap",
+  "devDependencies": {
+    "vitest": "^4.1.4",
+    "typescript": "^6.0.2"
+  }
+}