feat: add WeakValueMultiKeyMap and WeakValueMap

Author: giladgd

README.md

@@ -298,6 +298,62 @@ console.log(map.get([provider1, "key2"])); // 3
 console.log([...map.keys()]); // [[{name: "1"}, "key1"], [{name: "2"}, "key1"], [{name: "1"}, "key2"]])
 ```
 
+### `WeakValueMultiKeyMap`
+`WeakValueMultiKeyMap` is a utility class that works like a [`MultiKeyMap`](#multikeymap), but doesn't keep strong references to the values.
+
+When a value is garbage collected, it is automatically removed from the map.
+
+```typescript
+import {WeakValueMultiKeyMap} from "lifecycle-utils";
+
+type Provider = {name: string};
+
+const map = new WeakValueMultiKeyMap<[type: string, name: string], Provider>();
+
+{
+    const provider1: Provider = {name: "1"};
+    map.set(["type1", "key1"], provider1);
+
+    console.log(map.has(["type1", "key1"])); // true
+    console.log(map.get(["type1", "key1"])); // {name: "1"}
+    console.log(map.size); // 1
+}
+
+await new Promise(resolve => setTimeout(resolve, 1000 * 60 * 10)); // wait for the runtime to run garbage collection
+
+console.log(map.has(["type1", "key1"])); // false
+console.log(map.get(["type1", "key1"])); // undefined
+console.log(map.size); // 0
+```
+
+### `WeakValueMap`
+`WeakValueMap` is a utility class that works like a `Map`, but doesn't keep strong references to the values.
+
+When a value is garbage collected, it is automatically removed from the map.
+
+```typescript
+import {WeakValueMap} from "lifecycle-utils";
+
+type Provider = {name: string};
+
+const map = new WeakValueMap<string, Provider>();
+
+{
+    const provider1: Provider = {name: "1"};
+    map.set("provider1", provider1);
+
+    console.log(map.has("provider1")); // true
+    console.log(map.get("provider1")); // {name: "1"}
+    console.log(map.size); // 1
+}
+
+await new Promise(resolve => setTimeout(resolve, 1000 * 60 * 10)); // wait for the runtime to run garbage collection
+
+console.log(map.has("provider1")); // false
+console.log(map.get("provider1")); // undefined
+console.log(map.size); // 0
+```
+
 ### `LongTimeout`
 A timeout that can be set to a delay longer than the maximum timeout delay supported by a regular `setTimeout`.
 

src/MultiKeyMap.ts

@@ -7,7 +7,13 @@ export class MultiKeyMap<const Key extends readonly any[], const V> {
     /** @internal */ public readonly _map: InternalMap<Key> = new Map();
     /** @internal */ private readonly _keys = new Map<Key, V>();
 
-    public constructor(entries?: readonly (readonly [key: Key, value: V])[] | MultiKeyMap<Key, V> | null) {
+    public constructor(
+        entries?:
+            readonly (readonly [key: Key, value: V])[] |
+            MultiKeyMap<Key, V> |
+            ReadonlyMultiKeyMap<Key, V> |
+            null
+    ) {
         if (entries != null) {
             for (const [key, value] of entries)
                 this.set(key, value);

src/WeakValueMap.ts

@@ -0,0 +1,171 @@
+/**
+ * A utility class that works like a `Map`,
+ * but does not keep strong references to the values (allowing them to be garbage collected).
+ *
+ * When a value is garbage collected, it is automatically removed from the map.
+ */
+export class WeakValueMap<const Key, const V extends object> {
+    /** @internal */ private readonly _map = new Map<Key, InternalWeakValue<V>>();
+
+    public constructor(
+        entries?: readonly (readonly [key: Key, value: V])[] |
+            Map<Key, V> |
+            ReadonlyMap<Key, V> |
+            WeakValueMap<Key, V> |
+            ReadonlyWeakValueMap<Key, V> |
+            null
+    ) {
+        if (entries != null) {
+            for (const [key, value] of entries)
+                this.set(key, value);
+        }
+    }
+
+    /**
+     * Add or update a value for a given key.
+     *
+     * Time complexity: O(1), given that the length of the key is constant.
+     */
+    public set(key: Readonly<Key>, value: V): this {
+        const currentWeakValue = this._map.get(key);
+        if (currentWeakValue != null) {
+            const currentValue = currentWeakValue.ref.deref();
+
+            if (currentValue != null)
+                currentWeakValue.tracker.unregister(currentValue);
+        }
+
+        const weakValue: InternalWeakValue<V> = {
+            ref: new WeakRef(value),
+            tracker: null as any // will be set below
+        };
+        weakValue.tracker = new FinalizationRegistry<Readonly<Key>>(this._finalize.bind(this, weakValue));
+        weakValue.tracker.register(value, key);
+
+        this._map.set(key, weakValue);
+        return this;
+    }
+
+    /**
+     * Get a value for a given key.
+     *
+     * Time complexity: O(1), given that the length of the key is constant.
+     */
+    public get(key: Readonly<Key>): V | undefined {
+        const weakValue = this._map.get(key);
+        if (weakValue == null)
+            return undefined;
+
+        const value = weakValue.ref.deref();
+        /* c8 ignore start */
+        if (value == null) {
+            this._map.delete(key);
+            return undefined;
+        } /* c8 ignore stop */
+
+        return value;
+    }
+
+    /**
+     * Check if a value exists for a given key.
+     *
+     * Time complexity: O(1), given that the length of the key is constant.
+     */
+    public has(key: Readonly<Key>): boolean {
+        return this.get(key) != null;
+    }
+
+    /**
+     * Delete the value for a given key.
+     *
+     * Time complexity: O(1), given that the length of the key is constant.
+     */
+    public delete(key: Readonly<Key>): boolean {
+        const weakValue = this._map.get(key);
+        if (weakValue == null)
+            return false;
+
+        const value = weakValue.ref.deref();
+        if (value != null)
+            weakValue.tracker.unregister(value);
+
+        this._map.delete(key);
+        return true;
+    }
+
+    /**
+     * Clear all values from the map.
+     */
+    public clear(): void {
+        for (const [, weakValue] of this._map.entries()) {
+            const value = weakValue.ref.deref();
+            if (value != null)
+                weakValue.tracker.unregister(value);
+        }
+        this._map.clear();
+    }
+
+    /**
+     * Get the number of entries in the map.
+     */
+    public get size(): number {
+        return this._map.size;
+    }
+
+    /**
+     * Get an iterator for all entries in the map.
+     */
+    public *entries(): Generator<[key: Key, value: V]> {
+        for (const [key, weakValue] of this._map.entries()) {
+            const value = weakValue.ref.deref();
+            if (value != null)
+                yield [key, value];
+        }
+    }
+
+    /**
+     * Get an iterator for all keys in the map.
+     */
+    public *keys(): Generator<Key> {
+        for (const [key] of this.entries())
+            yield key;
+    }
+
+    /**
+     * Get an iterator for all values in the map.
+     */
+    public *values(): Generator<V> {
+        for (const [, value] of this.entries())
+            yield value;
+    }
+
+    /**
+     * Call a function for each entry in the map.
+     */
+    public forEach(callbackfn: (value: V, key: Key, map: this) => void, thisArg?: any): void {
+        for (const [key, value] of this.entries()) {
+            if (thisArg !== undefined)
+                callbackfn.call(thisArg, value, key, this);
+            else
+                callbackfn.call(this, value, key, this);
+        }
+    }
+
+    public [Symbol.iterator](): Generator<[key: Key, value: V]> {
+        return this.entries();
+    }
+
+    /** @internal */
+    private _finalize(value: InternalWeakValue<V>, key: Readonly<Key>) {
+        const weakValue = this._map.get(key);
+        if (weakValue === value)
+            this._map.delete(key);
+    }
+}
+
+export type ReadonlyWeakValueMap<Key, V extends object> = Omit<WeakValueMap<Key, V>, "set" | "delete" | "clear">;
+
+type InternalWeakValue<T extends object> = {
+    ref: WeakRef<T>,
+    tracker: FinalizationRegistry<any>
+};