CacheEngine

High-performance cache with automatic garbage collection and dependency tracking.

Import

import { CacheEngine } from '@soulcache/core';

Constructor

new CacheEngine(options?: CacheEngineOptions)

Parameters

Parameter	Type	Default	Description
`staleTime`	`number`	`300000` (5 min)	Default stale time
`gcTime`	`number`	`1800000` (30 min)	Garbage collection time
`maxSize`	`number`	`100000`	Maximum cache entries

When the cache reaches maxSize, the least-valuable entry is evicted before a new one is inserted. Entries are ranked by a weighted score that favours entries accessed recently and frequently (each access is worth roughly one second of recency) plus a bonus for active observers; the lowest-scoring entry is evicted first. Entries with observers or in-flight fetches are never evicted; if every entry is protected, temporary overflow is permitted until entries become available.

Methods

`get<T>(queryKey)`

Get cache entry by key.

get<T = unknown>(queryKey: QueryKey): QueryEntry<T> | undefined

`getByHash<T>(keyHash)`

Get cache entry by hash.

getByHash<T = unknown>(keyHash: string): QueryEntry<T> | undefined

`set<T>(options)`

Create or update cache entry.

set<T = unknown>(options: {
  queryKey: QueryKey;
  data?: T;
  state?: QueryRecordState;
  status?: CacheStatus;
  error?: Error | null;
  meta?: Record<string, unknown>;
  dependencies?: string[];
}): QueryEntry<T>

`delete(queryKey)`

Delete cache entry.

delete(queryKey: QueryKey): boolean

`invalidate(queryKey)`

Invalidate entry and dependencies.

invalidate(queryKey: QueryKey): boolean

`invalidateAll(predicate?)`

Bulk invalidate entries.

invalidateAll(predicate?: (key: string, entry: QueryEntry) => boolean): number

`clear()`

Clear all entries.

clear(): void

`collectGarbage()`

Remove expired entries.

collectGarbage(): number

`has(queryKey)`

Check if entry exists.

has(queryKey: QueryKey): boolean

`entries()`

Get all cache entries.

entries(): QueryEntry[]

`getStats()`

Get cache statistics.

getStats(): CacheStats

Properties

Property	Type	Description
`size`	`number`	Number of entries

Types

`CacheEngineOptions`

interface CacheEngineOptions {
  staleTime?: number;
  gcTime?: number;
  maxSize?: number;
}

`CacheStats`

interface CacheStats {
  size: number;
  activeEntries: number;
  gcEligibleEntries: number;
  totalAccesses: number;
}

CacheEngine

On this page