Cache

Application-Level Cache Protocol

Multi-tier caching strategy for application data. Supports Memory, Redis, Memcached, and CDN.

Caching in ObjectStack

Application Cache (system/cache.zod.ts) - This File

Purpose: Cache computed data, query results, aggregations
Technologies: Redis, Memcached, in-memory LRU
Configuration: TTL, eviction policies, cache warming
Use case: Cache expensive database queries, computed values
Scope: Application layer, server-side data storage

HTTP Cache (api/http-cache.zod.ts)

Purpose: Cache API responses at HTTP protocol level
Technologies: HTTP headers (ETag, Last-Modified, Cache-Control), CDN
Configuration: Cache-Control headers, validation tokens
Use case: Reduce API response time for repeated metadata requests
Scope: HTTP layer, client-server communication

See also: ../../api/http-cache.zod.ts for HTTP-level caching

Source: packages/spec/src/system/cache.zod.ts

TypeScript Usage

import { CacheAvalanchePreventionSchema, CacheConfigSchema, CacheConsistencySchema, CacheInvalidationSchema, CacheStrategySchema, CacheTierSchema, CacheWarmupSchema, DistributedCacheConfigSchema } from '@objectstack/spec/system';
import type { CacheAvalanchePrevention, CacheConfig, CacheConsistency, CacheInvalidation, CacheStrategy, CacheTier, CacheWarmup, DistributedCacheConfig } from '@objectstack/spec/system';

// Validate data
const result = CacheAvalanchePreventionSchema.parse(data);

CacheAvalanchePrevention

Cache avalanche/stampede prevention configuration

Properties

Property	Type	Required	Description
jitterTtl	`{ enabled: boolean; maxJitterSeconds: number }`	optional	TTL jitter to prevent simultaneous expiration
circuitBreaker	`{ enabled: boolean; failureThreshold: number; resetTimeout: number }`	optional	Circuit breaker for backend protection
lockout	`{ enabled: boolean; lockTimeoutMs: number }`	optional	Lock-based stampede prevention

Nested Shape: `CacheAvalanchePrevention.jitterTtl`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Add random jitter to TTL values
maxJitterSeconds	`number`	optional (default: `60`)	Maximum jitter added to TTL in seconds

Nested Shape: `CacheAvalanchePrevention.circuitBreaker`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable circuit breaker for backend protection
failureThreshold	`number`	optional (default: `5`)	Failures before circuit opens
resetTimeout	`number`	optional (default: `30`)	Seconds before half-open state

Nested Shape: `CacheAvalanchePrevention.lockout`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable cache locking for key regeneration
lockTimeoutMs	`number`	optional (default: `5000`)	Maximum lock wait time in milliseconds

CacheConfig

Top-level application cache configuration

Properties

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable application-level caching
tiers	`{ name: string; type: Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>; maxSize?: number; ttl: number; … }[]`	✅	Ordered cache tier hierarchy
invalidation	`{ trigger: Enum<'create' \| 'update' \| 'delete' \| 'manual'>; scope: Enum<'key' \| 'pattern' \| 'tag' \| 'all'>; pattern?: string; tags?: string[] }[]`	✅	Cache invalidation rules
prefetch	`boolean`	optional (default: `false`)	Enable cache prefetching
compression	`boolean`	optional (default: `false`)	Enable data compression in cache
encryption	`boolean`	optional (default: `false`)	Enable encryption for cached data

Nested Shape: `CacheConfig.tiers[number]`

Configuration for a single cache tier in the hierarchy

Property	Type	Required	Description
name	`string`	✅	Unique cache tier name
type	`Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>`	✅	Cache backend type
maxSize	`number`	optional	Max size in MB
ttl	`number`	optional (default: `300`)	Default TTL in seconds
strategy	`Enum<'lru' \| 'lfu' \| 'fifo' \| 'ttl'>`	optional (default: `"lru"`)	Eviction strategy
warmup	`boolean`	optional (default: `false`)	Pre-populate cache on startup

Nested Shape: `CacheConfig.invalidation[number]`

Rule defining when and how cached entries are invalidated

Property	Type	Required	Description
trigger	`Enum<'create' \| 'update' \| 'delete' \| 'manual'>`	✅	Event that triggers invalidation
scope	`Enum<'key' \| 'pattern' \| 'tag' \| 'all'>`	✅	Invalidation scope
pattern	`string`	optional	Key pattern for pattern-based invalidation
tags	`string[]`	optional	Cache tags to invalidate

CacheConsistency

Distributed cache write consistency strategy

Allowed Values

write_through
write_behind
write_around
refresh_ahead

CacheInvalidation

Rule defining when and how cached entries are invalidated

Properties

Property	Type	Required	Description
trigger	`Enum<'create' \| 'update' \| 'delete' \| 'manual'>`	✅	Event that triggers invalidation
scope	`Enum<'key' \| 'pattern' \| 'tag' \| 'all'>`	✅	Invalidation scope
pattern	`string`	optional	Key pattern for pattern-based invalidation
tags	`string[]`	optional	Cache tags to invalidate

CacheStrategy

Cache eviction strategy

Allowed Values

lru
lfu
fifo
ttl

CacheTier

Configuration for a single cache tier in the hierarchy

Properties

Property	Type	Required	Description
name	`string`	✅	Unique cache tier name
type	`Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>`	✅	Cache backend type
maxSize	`number`	optional	Max size in MB
ttl	`number`	optional (default: `300`)	Default TTL in seconds
strategy	`Enum<'lru' \| 'lfu' \| 'fifo' \| 'ttl'>`	optional (default: `"lru"`)	Eviction strategy
warmup	`boolean`	optional (default: `false`)	Pre-populate cache on startup

CacheWarmup

Cache warmup strategy

Properties

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable cache warmup
strategy	`Enum<'eager' \| 'lazy' \| 'scheduled'>`	optional (default: `"lazy"`)	Warmup strategy: eager (at startup), lazy (on first access), scheduled (cron)
schedule	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Cron expression for scheduled warmup
patterns	`string[]`	optional	Key patterns to warm up (e.g., "user:", "config:")
concurrency	`number`	optional (default: `10`)	Maximum concurrent warmup operations

DistributedCacheConfig

Distributed cache configuration with consistency and avalanche prevention

Properties

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable application-level caching
tiers	`{ name: string; type: Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>; maxSize?: number; ttl?: number; … }[]`	✅	Ordered cache tier hierarchy
invalidation	`{ trigger: Enum<'create' \| 'update' \| 'delete' \| 'manual'>; scope: Enum<'key' \| 'pattern' \| 'tag' \| 'all'>; pattern?: string; tags?: string[] }[]`	✅	Cache invalidation rules
prefetch	`boolean`	optional (default: `false`)	Enable cache prefetching
compression	`boolean`	optional (default: `false`)	Enable data compression in cache
encryption	`boolean`	optional (default: `false`)	Enable encryption for cached data
consistency	`Enum<'write_through' \| 'write_behind' \| 'write_around' \| 'refresh_ahead'>`	optional	Distributed cache consistency strategy
avalanchePrevention	`{ jitterTtl?: object; circuitBreaker?: object; lockout?: object }`	optional	Cache avalanche and stampede prevention
warmup	`{ enabled?: boolean; strategy?: Enum<'eager' \| 'lazy' \| 'scheduled'>; schedule?: string \| object; patterns?: string[]; … }`	optional	Cache warmup strategy

Nested Shape: `DistributedCacheConfig.tiers[number]`

Configuration for a single cache tier in the hierarchy

Property	Type	Required	Description
name	`string`	✅	Unique cache tier name
type	`Enum<'memory' \| 'redis' \| 'memcached' \| 'cdn'>`	✅	Cache backend type
maxSize	`number`	optional	Max size in MB
ttl	`number`	optional (default: `300`)	Default TTL in seconds
strategy	`Enum<'lru' \| 'lfu' \| 'fifo' \| 'ttl'>`	optional (default: `"lru"`)	Eviction strategy
warmup	`boolean`	optional (default: `false`)	Pre-populate cache on startup

Nested Shape: `DistributedCacheConfig.invalidation[number]`

Rule defining when and how cached entries are invalidated

Property	Type	Required	Description
trigger	`Enum<'create' \| 'update' \| 'delete' \| 'manual'>`	✅	Event that triggers invalidation
scope	`Enum<'key' \| 'pattern' \| 'tag' \| 'all'>`	✅	Invalidation scope
pattern	`string`	optional	Key pattern for pattern-based invalidation
tags	`string[]`	optional	Cache tags to invalidate

Nested Shape: `DistributedCacheConfig.avalanchePrevention`

Property	Type	Required	Description
jitterTtl	`{ enabled?: boolean; maxJitterSeconds?: number }`	optional	TTL jitter to prevent simultaneous expiration
circuitBreaker	`{ enabled?: boolean; failureThreshold?: number; resetTimeout?: number }`	optional	Circuit breaker for backend protection
lockout	`{ enabled?: boolean; lockTimeoutMs?: number }`	optional	Lock-based stampede prevention

Nested Shape: `DistributedCacheConfig.warmup`

Property	Type	Required	Description
enabled	`boolean`	optional (default: `false`)	Enable cache warmup
strategy	`Enum<'eager' \| 'lazy' \| 'scheduled'>`	optional (default: `"lazy"`)	Warmup strategy: eager (at startup), lazy (on first access), scheduled (cron)
schedule	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Cron expression for scheduled warmup
patterns	`string[]`	optional	Key patterns to warm up (e.g., "user:", "config:")
concurrency	`number`	optional (default: `10`)	Maximum concurrent warmup operations

Cache

On this page