Getting Started

Install @zap-studio/cache and build your first cache step by step.

Installation

npm install @zap-studio/cache

yarn add @zap-studio/cache

pnpm add @zap-studio/cache

bun add @zap-studio/cache

deno add jsr:@zap-studio/cache

Create a Cache

createCache(capacity, options?) returns a cache bounded to capacity live entries, using lru() by default.

import { createCache } from "@zap-studio/cache";

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

capacity must be a positive integer — createCache throws a RangeError otherwise.

Set and Get Values

cache.set("user:1", 42);

cache.get("user:1"); // 42
cache.get("user:2"); // undefined
cache.has("user:1"); // true

Let It Evict

Once the cache is full, inserting a new key evicts one entry first — which one depends on the configured eviction policy.

const cache = createCache<string, number>(2);

cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3); // evicts "a" (least recently used)

cache.has("a"); // false

Updating an existing key never triggers eviction — only an insert that grows past capacity does.

Pick an Eviction Policy

Import a policy factory and pass it via options.policy:

import { createCache } from "@zap-studio/cache";
import { fifo } from "@zap-studio/cache/fifo";

const cache = createCache<string, number>(100, { policy: fifo() });

See Eviction Policies for lru(), lfu(), mru(), mfu(), and fifo().

Add a TTL

Pass ttl (in milliseconds) to expire entries automatically. TTL is lazy — checked on get/has/peek, no background timer.

const cache = createCache<string, number>(100, { ttl: 60_000 });

cache.set("session:1", { userId: 1 }); // expires in 60s

See TTL for per-entry overrides.