skills/docs/persistence/cache/cache/src/abstract/abstract-cache/abstract-cache.md

abstract-cache

(no submodules)

Purpose

AbstractCache<T> is the base class for all cache implementations in @suaveplan/cache. It defines the six primitive abstract methods that every concrete cache must implement, and provides three composite helpers (wrap, getMultiple, setMultiple) that delegate to the primitives. This design separates the concern of cache mechanics (eviction, TTL, storage) from common access patterns, reducing code duplication across implementations.

Features

• Six abstract primitive operations: get, set, delete, clear, has, getStats
• getMultiple(keys) — fetches multiple keys concurrently, returns { found, missing }
• setMultiple(entries) — stores multiple entries concurrently with per-entry options
• wrap(key, fn, options?) — get-or-compute with optional forceRefresh and shouldCache predicate
• AbortSignal support on wrap via options.signal

Usage: Basic Example

import { AbstractCache } from "@suaveplan/cache/abstract/abstract-cache";
import type { CacheStats } from "@suaveplan/cache/types/common";

class MyCache extends AbstractCache<string> {
  readonly store = new Map<string, string>();
  async get(key: string) { return this.store.get(key); }
  async set(key: string, value: string) { this.store.set(key, value); }
  async delete(key: string) { return this.store.delete(key); }
  async clear() { this.store.clear(); }
  async has(key: string) { return this.store.has(key); }
  getStats(): CacheStats { return { hits: 0, misses: 0, size: this.store.size, hitRate: 0, evictions: 0 }; }
}

Usage: Advanced Example

import { MemoryCache } from "@suaveplan/cache/memory/memory-cache";

const cache = new MemoryCache<string>({ maxSize: 100 });

const value = await cache.wrap("api:user:1", async () => {
  const resp = await fetch("/api/user/1");
  return resp.text();
}, { ttl: 30_000, shouldCache: (v) => v.length > 0 });

API Reference

get(key: string): Promise<T | undefined> (abstract)

Returns value or undefined on miss/expiry.

set(key, value, options?): Promise<void> (abstract)

Stores a value. options.ttl overrides the default TTL.

delete(key): Promise<boolean> (abstract)

Returns true if the key was present.

clear(): Promise<void> (abstract)

Removes all entries.

has(key): Promise<boolean> (abstract)

Returns true if present and not expired.

getStats(): CacheStats (abstract)

Returns statistics snapshot.

getMultiple(keys): Promise<CacheMultiGetResult<T>>

Concurrent multi-fetch. found.size + missing.length === keys.length.

setMultiple(entries): Promise<void>

Concurrent multi-store.

wrap(key, fn, options?): Promise<T>

Get-or-compute. forceRefresh: true bypasses cache check.

Implementation Notes

getMultiple uses Promise.all for concurrent fetches. The wrap method's shouldCache predicate runs on both the cached value (to decide whether to serve a cached hit that no longer satisfies the predicate) and the freshly computed value (to decide whether to store it). AbortSignal is checked at the start of wrap before any async operations.