web / lib/services/cache/types

lib/services/cache/types

Type definitions for the generic caching system.

This module defines the core interfaces and types used throughout the cache implementation. The design is generic enough to support various storage backends (memory, filesystem, Redis, etc.) and different types of cached data.

Interfaces

CacheEntry<T>

Generic cache entry that can store any type of data

Type Parameters

T

T = unknown

Properties

key

key: string

value

value: T

metadata

metadata: CacheEntryMetadata

CacheEntryMetadata

Metadata associated with a cache entry

Properties

createdAt

createdAt: Date

expiresAt?

optional expiresAt: Date

accessCount

accessCount: number

lastAccessedAt

lastAccessedAt: Date

size?

optional size: number

tags?

optional tags: string[]

custom?

optional custom: Record<string, unknown>

CacheSetOptions

Options for setting a cache value

Properties

ttl?

optional ttl: number

Time to live in seconds

tags?

optional tags: string[]

Tags for grouping related entries

metadata?

optional metadata: Record<string, unknown>

Custom metadata

CacheStats

Cache statistics

Properties

entries

entries: number

Number of entries in cache

totalSize

totalSize: number

Total size in bytes

hits

hits: number

Number of cache hits

misses

misses: number

Number of cache misses

evictions

evictions: number

Number of evictions

oldestEntry?

optional oldestEntry: Date

Oldest entry timestamp

newestEntry?

optional newestEntry: Date

Newest entry timestamp

CacheStorage

Cache storage interface for different backends

Methods

get()

get<T>(key): Promise<null | CacheEntry<T>>

Get a value from cache

Type Parameters

T

T = unknown

Parameters

key

string

Returns

Promise<null | CacheEntry<T>>

set()

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

Set a value in cache

Type Parameters

T

T = unknown

Parameters

key

string

value

T

options?

CacheSetOptions

Returns

Promise<void>

delete()

delete(key): Promise<boolean>

Delete a value from cache

Parameters

key

string

Returns

Promise<boolean>

has()

has(key): Promise<boolean>

Check if key exists

Parameters

key

string

Returns

Promise<boolean>

clear()

clear(pattern?): Promise<number>

Clear cache entries matching pattern

Parameters

pattern?

string

Returns

Promise<number>

Number of entries cleared

keys()

keys(pattern?): Promise<string[]>

Get all keys matching pattern

Parameters

pattern?

string

Returns

Promise<string[]>

getMany()

getMany<T>(keys): Promise<Map<string, CacheEntry<T>>>

Get multiple values at once

Type Parameters

T

T = unknown

Parameters

keys

string[]

Returns

Promise<Map<string, CacheEntry<T>>>

setMany()

setMany<T>(entries, options?): Promise<void>

Set multiple values at once

Type Parameters

T

T = unknown

Parameters

entries

Map<string, T>

options?

CacheSetOptions

Returns

Promise<void>

getStats()

getStats(): Promise<CacheStats>

Get cache statistics

Returns

Promise<CacheStats>

cleanup()

cleanup(): Promise<number>

Clean up expired entries

Returns

Promise<number>

Number of entries cleaned

destroy()?

optional destroy(): void

Destroy the storage (cleanup resources)

Returns

void

Serializer

Serializer interface for converting objects to/from storable format

Methods

serialize()

serialize<T>(value): string | Buffer<ArrayBufferLike>

Type Parameters

T

T

Parameters

value

T

Returns

string | Buffer<ArrayBufferLike>

deserialize()

deserialize<T>(data): T

Type Parameters

T

T

Parameters

data

string | Buffer<ArrayBufferLike>

Returns

T

CacheConfig

Cache configuration

Properties

storage

storage: CacheStorage

Storage backend

namespace?

optional namespace: string

Cache namespace for key prefixing

defaultTTL?

optional defaultTTL: number

Default TTL in seconds

maxSize?

optional maxSize: number

Maximum cache size in bytes

maxEntries?

optional maxEntries: number

Maximum number of entries

serializer?

optional serializer: Serializer

Custom serializer

keyPrefix?

optional keyPrefix: string

Key prefix

onEviction()?

optional onEviction: (key, value) => void

Callback when entry is evicted

Parameters

key

string

value

unknown

Returns

void

MemoryCacheOptions

Options for memory cache storage

Properties

maxEntries?

optional maxEntries: number

Maximum number of entries

maxSize?

optional maxSize: number

Maximum total size in bytes

defaultTTL?

optional defaultTTL: number

Default TTL in seconds

onEviction()?

optional onEviction: (key, entry) => void

Callback when entry is evicted

Parameters

key

string

entry

CacheEntry

Returns

void

FileSystemCacheOptions

Options for filesystem cache storage

Properties

cacheDir?

optional cacheDir: string

Cache directory path

maxSize?

optional maxSize: number

Maximum cache size in bytes

cleanupIntervalMs?

optional cleanupIntervalMs: number

Cleanup interval in milliseconds

defaultTTL?

optional defaultTTL: number

Default TTL in seconds

UrlFetchCacheEntry

URL fetch cache entry (for scheduled URL imports)

Properties

url

url: string

method

method: string

data

data: Buffer

headers

headers: Record<string, string>

statusCode

statusCode: number

metadata

metadata: UrlFetchCacheMetadata

UrlFetchCacheMetadata

URL fetch cache metadata

Properties

etag?

optional etag: string

lastModified?

optional lastModified: string

expires?

optional expires: Date

maxAge?

optional maxAge: number

fetchedAt

fetchedAt: Date

contentHash

contentHash: string

size

size: number

UrlFetchCacheOptions

Options for URL fetch cache

Properties

useCache?

optional useCache: boolean

Use cache for this request

bypassCache?

optional bypassCache: boolean

Bypass cache and fetch fresh data

respectCacheControl?

optional respectCacheControl: boolean

Respect Cache-Control headers

forceRevalidate?

optional forceRevalidate: boolean

Force revalidation

returnStaleOnError?

optional returnStaleOnError: boolean

Return stale cache on network error

cache?

optional cache: "default" | "no-cache" | "force-cache" | "only-if-cached"

Cache mode (similar to fetch cache option)