feat(cache/unstable): TtlCache

cache/deno.json

@@ -4,6 +4,7 @@
   "exports": {
     ".": "./mod.ts",
     "./lru-cache": "./lru_cache.ts",
-    "./memoize": "./memoize.ts"
+    "./memoize": "./memoize.ts",
+    "./ttl-cache": "./ttl_cache.ts"
   }
 }

cache/mod.ts

@@ -22,5 +22,6 @@
  * @module
  */
 
-export * from "./memoize.ts";
 export * from "./lru_cache.ts";
+export * from "./memoize.ts";
+export * from "./ttl_cache.ts";

cache/ttl_cache.ts

@@ -0,0 +1,148 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import type { MemoizationCache } from "./memoize.ts";
+
+/**
+ * Time-to-live cache.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * Automatically removes entries once the configured amount of time elapses.
+ *
+ * @typeParam K The type of the cache keys.
+ * @typeParam V The type of the cache values.
+ *
+ * @example Usage
+ * ```ts
+ * import { TtlCache } from "@std/cache/ttl-cache";
+ * import { assertEquals } from "@std/assert/equals";
+ * import { delay } from "@std/async/delay";
+ *
+ * const cache = new TtlCache<string, number>(1000);
+ *
+ * cache.set("a", 1);
+ * assertEquals(cache.size, 1);
+ * await delay(2000);
+ * assertEquals(cache.size, 0);
+ * ```
+ */
+export class TtlCache<K, V> extends Map<K, V>
+  implements MemoizationCache<K, V> {
+  #defaultTtl: number;
+  #timeouts = new Map<K, number>();
+
+  /**
+   * Constructs a new instance.
+   *
+   * @experimental **UNSTABLE**: New API, yet to be vetted.
+   *
+   * @param defaultTtl The default time-to-live in milliseconds
+   */
+  constructor(defaultTtl: number) {
+    super();
+    this.#defaultTtl = defaultTtl;
+  }
+
+  /**
+   * Set a value in the cache.
+   *
+   * @experimental **UNSTABLE**: New API, yet to be vetted.
+   *
+   * @param key The cache key
+   * @param value The value to set
+   * @param ttl A custom time-to-live. If supplied, overrides the cache's default TTL for this entry.
+   * @returns `this` for chaining.
+   *
+   * @example Usage
+   * ```ts
+   * import { TtlCache } from "@std/cache/ttl-cache";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const cache = new TtlCache<string, number>(1000);
+   *
+   * cache.set("a", 1);
+   * assertEquals(cache.get("a"), 1);
+   * ```
+   */
+  override set(key: K, value: V, ttl: number = this.#defaultTtl): this {
+    clearTimeout(this.#timeouts.get(key));
+    super.set(key, value);
+    this.#timeouts.set(key, setTimeout(() => this.delete(key), ttl));
+    return this;
+  }
+
+  /**
+   * Deletes the value associated with the given key.
+   *
+   * @experimental **UNSTABLE**: New API, yet to be vetted.
+   *
+   * @param key The key to delete.
+   * @returns `true` if the key was deleted, `false` otherwise.
+   *
+   * @example Usage
+   * ```ts
+   * import { TtlCache } from "@std/cache";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const cache = new TtlCache<string, number>(1000);
+   *
+   * cache.set("a", 1);
+   * cache.delete("a");
+   * assertEquals(cache.has("a"), false);
+   * ```
+   */
+  override delete(key: K): boolean {
+    clearTimeout(this.#timeouts.get(key));
+    this.#timeouts.delete(key);
+    return super.delete(key);
+  }
+
+  /**
+   * Clears the cache.
+   *
+   * @experimental **UNSTABLE**: New API, yet to be vetted.
+   *
+   * @example Usage
+   * ```ts
+   * import { TtlCache } from "@std/cache";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * const cache = new TtlCache<string, number>(1000);
+   *
+   * cache.set("a", 1);
+   * cache.set("b", 2);
+   * cache.clear();
+   * assertEquals(cache.size, 0);
+   * ```
+   */
+  override clear(): void {
+    for (const timeout of this.#timeouts.values()) {
+      clearTimeout(timeout);
+    }
+    this.#timeouts.clear();
+    super.clear();
+  }
+
+  /**
+   * Automatically clears all remaining timeouts once the cache goes out of
+   * scope if the cache is declared with `using`.
+   *
+   * @experimental **UNSTABLE**: New API, yet to be vetted.
+   *
+   * @example Usage
+   * ```ts no-assert
+   * import { TtlCache } from "@std/cache/ttl-cache";
+   * import { assertEquals } from "@std/assert/equals";
+   *
+   * let c: TtlCache<string, number>;
+   * {
+   *  using cache = new TtlCache<string, number>(1000);
+   *  cache.set("a", 1);
+   *  c = cache;
+   * }
+   * assertEquals(c.size, 0);
+   * ```
+   */
+  [Symbol.dispose](): void {
+    this.clear();
+  }
+}

cache/ttl_cache_test.ts

@@ -0,0 +1,105 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+import { TtlCache } from "./ttl_cache.ts";
+import { assertEquals } from "@std/assert";
+import { FakeTime } from "@std/testing/time";
+
+const UNSET = Symbol("UNSET");
+
+// check `has()`, `get()`, `forEach()`
+function assertEntries<K, V>(
+  cache: TtlCache<K, V>,
+  entries: [key: K, value: V | typeof UNSET][],
+) {
+  for (const [key, value] of entries) {
+    assertEquals(cache.has(key), value !== UNSET);
+    assertEquals(cache.get(key), value === UNSET ? undefined : value);
+  }
+
+  cache.forEach((v, k) => assertEquals(v, entries.find(([x]) => x === k)![1]));
+  assertContentfulEntries(cache, entries.filter(([, v]) => v !== UNSET));
+}
+
+// check `size`, `entries()`, `keys()`, `values()`, `[Symbol.iterator]()`
+function assertContentfulEntries<K, V>(
+  cache: TtlCache<K, V>,
+  entries: [key: K, value: V][],
+) {
+  const keys = entries.map(([key]) => key);
+  const values = entries.map(([, value]) => value);
+
+  assertEquals(cache.size, entries.length);
+
+  assertEquals([...cache.entries()], entries);
+  assertEquals([...cache.keys()], keys);
+  assertEquals([...cache.values()], values);
+  assertEquals([...cache], entries);
+}
+
+Deno.test("TtlCache deletes entries", async (t) => {
+  await t.step("after the default TTL, passed in constructor", () => {
+    using time = new FakeTime(0);
+
+    const cache = new TtlCache<number, string>(10);
+
+    cache.set(1, "one");
+    cache.set(2, "two");
+
+    time.now = 1;
+    assertEntries(cache, [[1, "one"], [2, "two"]]);
+
+    time.now = 5;
+    assertEntries(cache, [[1, "one"], [2, "two"]]);
+    // setting again resets TTL countdown for key 1
+    cache.set(1, "one");
+
+    time.now = 10;
+    assertEntries(cache, [[1, "one"], [2, UNSET]]);
+
+    time.now = 15;
+    assertEntries(cache, [[1, UNSET], [2, UNSET]]);
+  });
+
+  await t.step("after a custom TTL, passed in set()", () => {
+    using time = new FakeTime(0);
+
+    const cache = new TtlCache<number, string>(10);
+
+    cache.set(1, "one");
+    cache.set(2, "two", 3);
+
+    time.now = 1;
+    assertEntries(cache, [[1, "one"], [2, "two"]]);
+
+    time.now = 3;
+    assertEntries(cache, [[1, "one"], [2, UNSET]]);
+
+    time.now = 10;
+    assertEntries(cache, [[1, UNSET], [2, UNSET]]);
+  });
+
+  await t.step("after manually calling delete()", () => {
+    const cache = new TtlCache<number, string>(10);
+
+    cache.set(1, "one");
+    assertEntries(cache, [[1, "one"]]);
+    assertEquals(cache.delete(1), true);
+    assertEntries(cache, [[1, UNSET]]);
+    assertEquals(cache.delete(1), false);
+    assertEntries(cache, [[1, UNSET]]);
+  });
+
+  await t.step("after manually calling clear()", () => {
+    const cache = new TtlCache<number, string>(10);
+
+    cache.set(1, "one");
+    assertEntries(cache, [[1, "one"]]);
+    cache.clear();
+    assertEntries(cache, [[1, UNSET]]);
+  });
+
+  // this test will fail with `error: Leaks detected` if the timeouts are not cleared
+  await t.step("[Symbol.dispose]() clears all remaining timeouts", () => {
+    using cache = new TtlCache<number, string>(10);
+    cache.set(1, "one");
+  });
+});