TtlCache

Example: Usage

import { TtlCache } from "@ende/cache/ttl-cache";
import { assertEquals } from "@ende/assert/equals";
import { delay } from "@ende/async/delay";

const cache = new TtlCache<string, number>(1000);

cache.set("a", 1);
assertEquals(cache.size, 1);
await delay(2000);
assertEquals(cache.size, 0);

Example: Sliding expiration

import { TtlCache } from "@ende/cache/ttl-cache";
import { assertEquals } from "@ende/assert/equals";
import { FakeTime } from "@ende/testing/time";

using time = new FakeTime(0);
const cache = new TtlCache<string, number>(100, {
  slidingExpiration: true,
});

cache.set("a", 1);
time.now = 80;
assertEquals(cache.get("a"), 1); // resets TTL
time.now = 160;
assertEquals(cache.get("a"), 1); // still alive, TTL was reset at t=80
time.now = 260;
assertEquals(cache.get("a"), undefined); // expired

constructor

new TtlCache(defaultTtl: number, options?: TtlCacheOptions<K, V>)

experimental

Constructs a new instance.

defaultTtl: number

The default time-to-live in milliseconds. This value must be a finite, non-negative number. Its upper limit is determined by the current runtime's setTimeout implementation.

options?: TtlCacheOptions<K, V>

Additional options.

set

set(key: K, value: V, options?: TtlCacheSetOptions): this

experimental

Set a value in the cache.

key: K

The cache key.

value: V

The value to set.

options?: TtlCacheSetOptions

Options for this entry.

Returns

this for chaining.

import { TtlCache } from "@ende/cache/ttl-cache";
import { assertEquals } from "@ende/assert/equals";
import { delay } from "@ende/async/delay";

const cache = new TtlCache<string, number>(100);

cache.set("a", 1);
assertEquals(cache.get("a"), 1);

await delay(200);
assertEquals(cache.get("a"), undefined);

get

get(key: K): V | undefined

experimental

Gets the value associated with the specified key.

key: K

The key to get the value for.

Returns

The value associated with the specified key, or undefined if the key is not present in the cache.

import { TtlCache } from "@ende/cache/ttl-cache";
import { assertEquals } from "@ende/assert/equals";

using cache = new TtlCache<string, number>(1000);

cache.set("a", 1);
assertEquals(cache.get("a"), 1);

peek

peek(key: K): V | undefined

experimental

Returns the value associated with the given key, or undefined if the key is not present, without resetting its TTL.

This is the TTL-cache equivalent of LruCache.peek(): a side-effect-free read that leaves the entry's expiration unchanged.

key: K

The key to look up.

Returns

The value, or undefined if not present.

import { TtlCache } from "@ende/cache/ttl-cache";
import { assertEquals } from "@ende/assert/equals";
import { FakeTime } from "@ende/testing/time";

using time = new FakeTime(0);
const cache = new TtlCache<string, number>(100, {
  slidingExpiration: true,
});

cache.set("a", 1);
time.now = 80;

// peek does not reset the TTL
assertEquals(cache.peek("a"), 1);

// entry still expires at t=100
time.now = 100;
assertEquals(cache.peek("a"), undefined);

delete

delete(key: K): boolean

experimental

Deletes the value associated with the given key.

key: K

The key to delete.

Returns

true if the key was deleted, false otherwise.

import { TtlCache } from "@ende/cache";
import { assertEquals } from "@ende/assert/equals";

const cache = new TtlCache<string, number>(1000);

cache.set("a", 1);
cache.delete("a");
assertEquals(cache.has("a"), false);

clear

clear(): void

experimental

Clears the cache.

import { TtlCache } from "@ende/cache";
import { assertEquals } from "@ende/assert/equals";

const cache = new TtlCache<string, number>(1000);

cache.set("a", 1);
cache.set("b", 2);
cache.clear();
assertEquals(cache.size, 0);

[Symbol.dispose]

[Symbol.dispose](): void

experimental

Automatically clears all remaining timeouts once the cache goes out of scope if the cache is declared with using.

import { TtlCache } from "@ende/cache/ttl-cache";
import { assertEquals } from "@ende/assert/equals";

let c: TtlCache<string, number>;
{
 using cache = new TtlCache<string, number>(1000);
 cache.set("a", 1);
 c = cache;
}
assertEquals(c.size, 0);