From 4abb7cbd232d0496e87120cbf4f0fd540e0630e4 Mon Sep 17 00:00:00 2001
From: Kyle Peacock <kylpeacock@gmail.com>
Date: Mon, 6 Nov 2023 13:27:42 -0800
Subject: [PATCH 1/4] feat: introduces ExpirableMap

---
 docs/generated/changelog.html                 |   4 +
 packages/agent/src/utils/expirableMap.test.ts |  20 +++
 packages/agent/src/utils/expirableMap.ts      | 144 ++++++++++++++++++
 3 files changed, 168 insertions(+)
 create mode 100644 packages/agent/src/utils/expirableMap.test.ts
 create mode 100644 packages/agent/src/utils/expirableMap.ts

diff --git a/docs/generated/changelog.html b/docs/generated/changelog.html
index 26d0ddbc0..b6a34fdda 100644
--- a/docs/generated/changelog.html
+++ b/docs/generated/changelog.html
@@ -12,6 +12,10 @@ <h1>Agent-JS Changelog</h1>
     <section>
       <h2>Version x.x.x</h2>
       <ul>
+        <li>
+          feat: introduces ExpirableMap, a utility class that will return values up until a
+          configured expiry
+        </li>
         <li>
           chore: increases size limit for agent-js to allow for Ed25519 support for node key
           signature verification
diff --git a/packages/agent/src/utils/expirableMap.test.ts b/packages/agent/src/utils/expirableMap.test.ts
new file mode 100644
index 000000000..829e139fe
--- /dev/null
+++ b/packages/agent/src/utils/expirableMap.test.ts
@@ -0,0 +1,20 @@
+import { ExpirableMap } from './expirableMap';
+
+jest.useFakeTimers();
+describe('ExpirableMap', () => {
+  it('should return undefined if the key is not present', () => {
+    const map = new ExpirableMap(10_000);
+    expect(map.get('key')).toBeUndefined();
+  });
+  it('should return a key if one has been recently set', () => {
+    const map = new ExpirableMap(10_000);
+    map.set('key', 'value');
+    expect(map.get('key')).toBe('value');
+  });
+  it('should return undefined if the key has expired', () => {
+    const map = new ExpirableMap(10);
+    map.set('key', 'value');
+    jest.advanceTimersByTime(11);
+    expect(map.get('key')).toBeUndefined();
+  });
+});
diff --git a/packages/agent/src/utils/expirableMap.ts b/packages/agent/src/utils/expirableMap.ts
new file mode 100644
index 000000000..a7eac7108
--- /dev/null
+++ b/packages/agent/src/utils/expirableMap.ts
@@ -0,0 +1,144 @@
+/**
+ * A map that expires entries after a given time.
+ */
+export class ExpirableMap<K, V> implements Map<K, V> {
+  // Internals
+  #inner: Map<K, { value: V; timestamp: number }>;
+  #expirationTime: number;
+
+  [Symbol.iterator]: () => IterableIterator<[K, V]> = this.entries.bind(this);
+  [Symbol.toStringTag] = 'ExpirableMap';
+
+  constructor(expirationTime: number) {
+    this.#inner = new Map();
+    this.#expirationTime = expirationTime;
+  }
+
+  /**
+   * Prune removes all expired entries.
+   */
+  prune() {
+    const currentTime = Date.now();
+    for (const [key, entry] of this.#inner.entries()) {
+      if (currentTime - entry.timestamp > this.#expirationTime) {
+        this.#inner.delete(key);
+      }
+    }
+    return this;
+  }
+
+  // Implementing the Map interface
+
+  /**
+   * Set the value for the given key.
+   * @param key for the entry
+   * @param value of the entry
+   * @returns this
+   */
+  set(key: K, value: V) {
+    const entry = {
+      value,
+      timestamp: Date.now(),
+    };
+    this.#inner.set(key, entry);
+    return this;
+  }
+
+  /**
+   * Get the value associated with the key, if it exists and has not expired.
+   * @param key K
+   * @returns the value associated with the key, or undefined if the key is not present or has expired.
+   */
+  get(key: K) {
+    const entry = this.#inner.get(key);
+    if (!entry) return undefined;
+
+    const currentTime = Date.now();
+    if (currentTime - entry.timestamp > this.#expirationTime) {
+      this.#inner.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Clear all entries.
+   */
+  clear() {
+    this.#inner.clear();
+  }
+
+  /**
+   * Entries returns the entries of the map, without the expiration time.
+   * @returns an iterator over the entries of the map.
+   */
+  entries(): IterableIterator<[K, V]> {
+    const iterator = this.#inner.entries();
+    const generator = function* () {
+      for (const [key, value] of iterator) {
+        yield [key, value.value] as [K, V];
+      }
+    };
+    return generator();
+  }
+
+  /**
+   * Values returns the values of the map, without the expiration time.
+   * @returns an iterator over the values of the map.
+   */
+  values(): IterableIterator<V> {
+    const iterator = this.#inner.values();
+    const generator = function* () {
+      for (const value of iterator) {
+        yield value.value;
+      }
+    };
+    return generator();
+  }
+
+  /**
+   * Keys returns the keys of the map
+   * @returns an iterator over the keys of the map.
+   */
+  keys(): IterableIterator<K> {
+    return this.#inner.keys();
+  }
+
+  /**
+   * forEach calls the callbackfn on each entry of the map.
+   * @param callbackfn to call on each entry
+   * @param thisArg to use as this when calling the callbackfn
+   */
+  forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: ExpirableMap<K, V>) {
+    for (const [key, value] of this.#inner.entries()) {
+      callbackfn.call(thisArg, value.value, key, this);
+    }
+  }
+
+  /**
+   * has returns true if the key exists and has not expired.
+   * @param key K
+   * @returns true if the key exists and has not expired.
+   */
+  has(key: K): boolean {
+    return this.#inner.has(key);
+  }
+
+  /**
+   * delete the entry for the given key.
+   * @param key K
+   * @returns true if the key existed and has been deleted.
+   */
+  delete(key: K) {
+    return this.#inner.delete(key);
+  }
+
+  /**
+   * get size of the map.
+   * @returns the size of the map.
+   */
+  get size() {
+    return this.#inner.size;
+  }
+}

From cb2d8b59e9b9cf5ca7edfe2573def049d3ac0ba4 Mon Sep 17 00:00:00 2001
From: Kyle Peacock <kylpeacock@gmail.com>
Date: Mon, 6 Nov 2023 13:45:01 -0800
Subject: [PATCH 2/4] prunes on every get

---
 packages/agent/src/utils/expirableMap.ts | 14 +++-----------
 1 file changed, 3 insertions(+), 11 deletions(-)

diff --git a/packages/agent/src/utils/expirableMap.ts b/packages/agent/src/utils/expirableMap.ts
index a7eac7108..19b53e7fa 100644
--- a/packages/agent/src/utils/expirableMap.ts
+++ b/packages/agent/src/utils/expirableMap.ts
@@ -45,21 +45,13 @@ export class ExpirableMap<K, V> implements Map<K, V> {
   }
 
   /**
-   * Get the value associated with the key, if it exists and has not expired.
+   * Get the value associated with the key, if it exists and has not expired. Prunes expired entries.
    * @param key K
    * @returns the value associated with the key, or undefined if the key is not present or has expired.
    */
   get(key: K) {
-    const entry = this.#inner.get(key);
-    if (!entry) return undefined;
-
-    const currentTime = Date.now();
-    if (currentTime - entry.timestamp > this.#expirationTime) {
-      this.#inner.delete(key);
-      return undefined;
-    }
-
-    return entry.value;
+    this.prune();
+    return this.#inner.get(key)?.value;
   }
 
   /**

From eb4b0faa46a2e0d7d598bd825a8660678385faa4 Mon Sep 17 00:00:00 2001
From: Kyle Peacock <kylpeacock@gmail.com>
Date: Mon, 6 Nov 2023 14:00:56 -0800
Subject: [PATCH 3/4] supports source iterator in constructor

---
 packages/agent/src/utils/expirableMap.test.ts | 23 ++++++++++++++++---
 packages/agent/src/utils/expirableMap.ts      | 20 ++++++++++++++--
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/packages/agent/src/utils/expirableMap.test.ts b/packages/agent/src/utils/expirableMap.test.ts
index 829e139fe..9bd0b2e12 100644
--- a/packages/agent/src/utils/expirableMap.test.ts
+++ b/packages/agent/src/utils/expirableMap.test.ts
@@ -3,18 +3,35 @@ import { ExpirableMap } from './expirableMap';
 jest.useFakeTimers();
 describe('ExpirableMap', () => {
   it('should return undefined if the key is not present', () => {
-    const map = new ExpirableMap(10_000);
+    const map = new ExpirableMap();
     expect(map.get('key')).toBeUndefined();
   });
   it('should return a key if one has been recently set', () => {
-    const map = new ExpirableMap(10_000);
+    const map = new ExpirableMap();
     map.set('key', 'value');
     expect(map.get('key')).toBe('value');
   });
   it('should return undefined if the key has expired', () => {
-    const map = new ExpirableMap(10);
+    const map = new ExpirableMap({ expirationTime: 10 });
     map.set('key', 'value');
     jest.advanceTimersByTime(11);
     expect(map.get('key')).toBeUndefined();
   });
+  it('should support iterable operations', () => {
+    const map = new ExpirableMap({
+      source: [
+        ['key1', 8],
+        ['key2', 1234],
+      ],
+    });
+
+    expect(Array.from(map)).toStrictEqual([
+      ['key1', 8],
+      ['key2', 1234],
+    ]);
+
+    for (const [key, value] of map) {
+      expect(map.get(key)).toBe(value);
+    }
+  });
 });
diff --git a/packages/agent/src/utils/expirableMap.ts b/packages/agent/src/utils/expirableMap.ts
index 19b53e7fa..c8bc37f9d 100644
--- a/packages/agent/src/utils/expirableMap.ts
+++ b/packages/agent/src/utils/expirableMap.ts
@@ -1,5 +1,11 @@
+export type ExpirableMapOptions<K, V> = {
+  source?: Iterable<[K, V]>;
+  expirationTime?: number;
+};
+
 /**
  * A map that expires entries after a given time.
+ * Defaults to 10 minutes.
  */
 export class ExpirableMap<K, V> implements Map<K, V> {
   // Internals
@@ -9,8 +15,18 @@ export class ExpirableMap<K, V> implements Map<K, V> {
   [Symbol.iterator]: () => IterableIterator<[K, V]> = this.entries.bind(this);
   [Symbol.toStringTag] = 'ExpirableMap';
 
-  constructor(expirationTime: number) {
-    this.#inner = new Map();
+  /**
+   * Create a new ExpirableMap.
+   * @param {ExpirableMapOptions<any, any>} options - options for the map.
+   * @param {Iterable<[any, any]>} options.source - an optional source of entries to initialize the map with.
+   * @param {number} options.expirationTime - the time in milliseconds after which entries will expire.
+   */
+  constructor(options: ExpirableMapOptions<K, V> = {}) {
+    const { source = [], expirationTime = 10 * 60 * 1000 } = options;
+    const currentTime = Date.now();
+    this.#inner = new Map(
+      [...source].map(([key, value]) => [key, { value, timestamp: currentTime }]),
+    );
     this.#expirationTime = expirationTime;
   }
 

From be4cb21eea5532edcc0c46e7db158fb4d150cfb6 Mon Sep 17 00:00:00 2001
From: Kyle Peacock <kylpeacock@gmail.com>
Date: Mon, 6 Nov 2023 14:59:14 -0800
Subject: [PATCH 4/4] moves pruning to set function

---
 packages/agent/src/utils/expirableMap.ts | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/packages/agent/src/utils/expirableMap.ts b/packages/agent/src/utils/expirableMap.ts
index c8bc37f9d..39657484c 100644
--- a/packages/agent/src/utils/expirableMap.ts
+++ b/packages/agent/src/utils/expirableMap.ts
@@ -46,28 +46,37 @@ export class ExpirableMap<K, V> implements Map<K, V> {
   // Implementing the Map interface
 
   /**
-   * Set the value for the given key.
+   * Set the value for the given key. Prunes expired entries.
    * @param key for the entry
    * @param value of the entry
    * @returns this
    */
   set(key: K, value: V) {
+    this.prune();
     const entry = {
       value,
       timestamp: Date.now(),
     };
     this.#inner.set(key, entry);
+
     return this;
   }
 
   /**
-   * Get the value associated with the key, if it exists and has not expired. Prunes expired entries.
+   * Get the value associated with the key, if it exists and has not expired.
    * @param key K
    * @returns the value associated with the key, or undefined if the key is not present or has expired.
    */
   get(key: K) {
-    this.prune();
-    return this.#inner.get(key)?.value;
+    const entry = this.#inner.get(key);
+    if (entry === undefined) {
+      return undefined;
+    }
+    if (Date.now() - entry.timestamp > this.#expirationTime) {
+      this.#inner.delete(key);
+      return undefined;
+    }
+    return entry.value;
   }
 
   /**