ObjectStackObjectStack
ReferenceSystem Protocol

Cache schema — System Protocol reference

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

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

PropertyTypeRequiredDescription
jitterTtl{ enabled?: boolean; maxJitterSeconds?: number }optionalTTL jitter to prevent simultaneous expiration
circuitBreaker{ enabled?: boolean; failureThreshold?: number; resetTimeoutSeconds?: number }optionalCircuit breaker for backend protection
lockout{ enabled?: boolean; lockTimeoutMs?: number }optionalLock-based stampede prevention

Nested Shape: CacheAvalanchePrevention.jitterTtl

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Add random jitter to TTL values
maxJitterSecondsnumberoptional (default: 60)Maximum jitter added to TTL in seconds

Nested Shape: CacheAvalanchePrevention.circuitBreaker

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable circuit breaker for backend protection
failureThresholdnumberoptional (default: 5)Failures before circuit opens
resetTimeoutSecondsnumberoptional (default: 30)Seconds before half-open state
resetTimeoutneveroptional[REMOVED] CacheAvalanchePrevention.circuitBreaker.resetTimeout was renamed to resetTimeoutSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose, and the sibling lockout block on this same schema already spells lockTimeoutMs. Rename the key to resetTimeoutSeconds; the value (seconds) and the 30 default are unchanged. Note the two are NOT the same unit: this one is seconds, lockTimeoutMs is milliseconds.

Nested Shape: CacheAvalanchePrevention.lockout

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable cache locking for key regeneration
lockTimeoutMsnumberoptional (default: 5000)Maximum lock wait time in milliseconds

CacheConfig

Top-level application cache configuration

Properties

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable application-level caching
tiers{ name: string; type: Enum<'memory' | 'redis' | 'memcached' | 'cdn'>; maxSize?: number; ttlSeconds?: 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
prefetchbooleanoptional (default: false)Enable cache prefetching
compressionbooleanoptional (default: false)Enable data compression in cache
encryptionbooleanoptional (default: false)Enable encryption for cached data

Nested Shape: CacheConfig.tiers[number]

Configuration for a single cache tier in the hierarchy

PropertyTypeRequiredDescription
namestring✅Unique cache tier name
typeEnum<'memory' | 'redis' | 'memcached' | 'cdn'>✅Cache backend type
maxSizenumberoptionalMax size in MB
ttlSecondsnumberoptional (default: 300)Default TTL in seconds
ttlneveroptional[REMOVED] CacheTier.ttl was renamed to ttlSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose, and the sibling maxSize on this same tier is a size in MB. Rename the key to ttlSeconds; the value (seconds) and the 300 default are unchanged.
strategyEnum<'lru' | 'lfu' | 'fifo' | 'ttl'>optional (default: "lru")Eviction strategy
warmupbooleanoptional (default: false)Pre-populate cache on startup

Nested Shape: CacheConfig.invalidation[number]

Rule defining when and how cached entries are invalidated

PropertyTypeRequiredDescription
triggerEnum<'create' | 'update' | 'delete' | 'manual'>✅Event that triggers invalidation
scopeEnum<'key' | 'pattern' | 'tag' | 'all'>✅Invalidation scope
patternstringoptionalKey pattern for pattern-based invalidation
tagsstring[]optionalCache 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

PropertyTypeRequiredDescription
triggerEnum<'create' | 'update' | 'delete' | 'manual'>✅Event that triggers invalidation
scopeEnum<'key' | 'pattern' | 'tag' | 'all'>✅Invalidation scope
patternstringoptionalKey pattern for pattern-based invalidation
tagsstring[]optionalCache tags to invalidate

CacheStrategy

Cache eviction strategy

Allowed Values

  • lru
  • lfu
  • fifo
  • ttl

CacheTier

Configuration for a single cache tier in the hierarchy

Properties

PropertyTypeRequiredDescription
namestring✅Unique cache tier name
typeEnum<'memory' | 'redis' | 'memcached' | 'cdn'>✅Cache backend type
maxSizenumberoptionalMax size in MB
ttlSecondsnumberoptional (default: 300)Default TTL in seconds
ttlneveroptional[REMOVED] CacheTier.ttl was renamed to ttlSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose, and the sibling maxSize on this same tier is a size in MB. Rename the key to ttlSeconds; the value (seconds) and the 300 default are unchanged.
strategyEnum<'lru' | 'lfu' | 'fifo' | 'ttl'>optional (default: "lru")Eviction strategy
warmupbooleanoptional (default: false)Pre-populate cache on startup

CacheWarmup

Cache warmup strategy

Properties

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable cache warmup
strategyEnum<'eager' | 'lazy'>optional (default: "lazy")Warmup strategy: eager (at startup), lazy (on first access)
patternsstring[]optionalKey patterns to warm up (e.g., "user:", "config:")
concurrencynumberoptional (default: 10)Maximum concurrent warmup operations

DistributedCacheConfig

Distributed cache configuration with consistency and avalanche prevention

Properties

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable application-level caching
tiers{ name: string; type: Enum<'memory' | 'redis' | 'memcached' | 'cdn'>; maxSize?: number; ttlSeconds?: 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
prefetchbooleanoptional (default: false)Enable cache prefetching
compressionbooleanoptional (default: false)Enable data compression in cache
encryptionbooleanoptional (default: false)Enable encryption for cached data
consistencyEnum<'write_through' | 'write_behind' | 'write_around' | 'refresh_ahead'>optionalDistributed cache consistency strategy
avalanchePrevention{ jitterTtl?: object; circuitBreaker?: object; lockout?: object }optionalCache avalanche and stampede prevention
warmup{ enabled?: boolean; strategy?: Enum<'eager' | 'lazy'>; patterns?: string[]; concurrency?: number }optionalCache warmup strategy

Nested Shape: DistributedCacheConfig.tiers[number]

Configuration for a single cache tier in the hierarchy

PropertyTypeRequiredDescription
namestring✅Unique cache tier name
typeEnum<'memory' | 'redis' | 'memcached' | 'cdn'>✅Cache backend type
maxSizenumberoptionalMax size in MB
ttlSecondsnumberoptional (default: 300)Default TTL in seconds
ttlneveroptional[REMOVED] CacheTier.ttl was renamed to ttlSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose, and the sibling maxSize on this same tier is a size in MB. Rename the key to ttlSeconds; the value (seconds) and the 300 default are unchanged.
strategyEnum<'lru' | 'lfu' | 'fifo' | 'ttl'>optional (default: "lru")Eviction strategy
warmupbooleanoptional (default: false)Pre-populate cache on startup

Nested Shape: DistributedCacheConfig.invalidation[number]

Rule defining when and how cached entries are invalidated

PropertyTypeRequiredDescription
triggerEnum<'create' | 'update' | 'delete' | 'manual'>✅Event that triggers invalidation
scopeEnum<'key' | 'pattern' | 'tag' | 'all'>✅Invalidation scope
patternstringoptionalKey pattern for pattern-based invalidation
tagsstring[]optionalCache tags to invalidate

Nested Shape: DistributedCacheConfig.avalanchePrevention

PropertyTypeRequiredDescription
jitterTtl{ enabled?: boolean; maxJitterSeconds?: number }optionalTTL jitter to prevent simultaneous expiration
circuitBreaker{ enabled?: boolean; failureThreshold?: number; resetTimeoutSeconds?: number }optionalCircuit breaker for backend protection
lockout{ enabled?: boolean; lockTimeoutMs?: number }optionalLock-based stampede prevention

Nested Shape: DistributedCacheConfig.warmup

PropertyTypeRequiredDescription
enabledbooleanoptional (default: false)Enable cache warmup
strategyEnum<'eager' | 'lazy'>optional (default: "lazy")Warmup strategy: eager (at startup), lazy (on first access)
patternsstring[]optionalKey patterns to warm up (e.g., "user:", "config:")
concurrencynumberoptional (default: 10)Maximum concurrent warmup operations

Tenant

Tenant Schema (Multi-Tenant Architecture) — Defines the tenant/tenancy model for ObjectStack SaaS deployments.

Core Services

Defines the standard built-in services that constitute the ObjectStack Kernel.

On this page

Caching in ObjectStackTypeScript UsageCacheAvalanchePreventionPropertiesNested Shape: CacheAvalanchePrevention.jitterTtlNested Shape: CacheAvalanchePrevention.circuitBreakerNested Shape: CacheAvalanchePrevention.lockoutCacheConfigPropertiesNested Shape: CacheConfig.tiers[number]Nested Shape: CacheConfig.invalidation[number]CacheConsistencyAllowed ValuesCacheInvalidationPropertiesCacheStrategyAllowed ValuesCacheTierPropertiesCacheWarmupPropertiesDistributedCacheConfigPropertiesNested Shape: DistributedCacheConfig.tiers[number]Nested Shape: DistributedCacheConfig.invalidation[number]Nested Shape: DistributedCacheConfig.avalanchePreventionNested Shape: DistributedCacheConfig.warmup