Class CacheService

Cache Service

Type-safe wrapper around Cloudflare KV namespaces for caching operations.

Features:

Mirrors all KVNamespace methods with full type safety
Supports multiple KV bindings via withBinding()
Automatic error handling with logging
Security: Raw errors are logged, not exposed to users

Usage:

class MyService {
  private readonly uploadsCache: CacheService

  constructor(
    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,
    @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env
  ) {
    // Initialize specialized caches in constructor
    this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)
  }

  async cacheData(key: string, value: string) {
    await this.cache.put(key, value, { expirationTtl: 3600 })
    await this.uploadsCache.put(`upload:${key}`, value)
  }
}

See

https://developers.cloudflare.com/kv/api/

Index

Constructors

constructor

Methods

delete get getWithMetadata list put setKV withBinding

Constructors

constructor

new CacheService(env: StratalEnv, logger: LoggerService): CacheService
Parameters
- env: StratalEnv
- logger: LoggerService
Returns CacheService
- Defined in packages/core/src/cache/services/cache.service.ts:51

Methods

delete

delete(key: string): Promise<void>
Delete a value from cache
Parameters
- key: string
  Cache key to delete
Returns Promise<void>
Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:235

get

get(
key: string,
typeOrOptions?: "text" | KVNamespaceGetOptions<"text">,
): Promise<string | null>
Get a value from cache
Parameters
- key: string
  Cache key
- OptionaltypeOrOptions: "text" | KVNamespaceGetOptions<"text">
  Type string or options object (defaults to 'text')
Returns Promise<string | null>
Value in specified type, or null if not found

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:111
get<ExpectedValue = unknown>(
key: string,
typeOrOptions: "json" | KVNamespaceGetOptions<"json">,
): Promise<ExpectedValue | null>
Get a value from cache
Type Parameters
- ExpectedValue = unknown
Parameters
- key: string
  Cache key
- typeOrOptions: "json" | KVNamespaceGetOptions<"json">
  Type string or options object (defaults to 'text')
Returns Promise<ExpectedValue | null>
Value in specified type, or null if not found

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:112
get(
key: string,
typeOrOptions: "arrayBuffer" | KVNamespaceGetOptions<"arrayBuffer">,
): Promise<ArrayBuffer | null>
Get a value from cache
Parameters
- key: string
  Cache key
- typeOrOptions: "arrayBuffer" | KVNamespaceGetOptions<"arrayBuffer">
  Type string or options object (defaults to 'text')
Returns Promise<ArrayBuffer | null>
Value in specified type, or null if not found

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:113
get(
key: string,
typeOrOptions: "stream" | KVNamespaceGetOptions<"stream">,
): Promise<ReadableStream<any> | null>
Get a value from cache
Parameters
- key: string
  Cache key
- typeOrOptions: "stream" | KVNamespaceGetOptions<"stream">
  Type string or options object (defaults to 'text')
Returns Promise<ReadableStream<any> | null>
Value in specified type, or null if not found

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:114

getWithMetadata

getWithMetadata<Metadata = unknown>(
key: string,
typeOrOptions?: "text" | KVNamespaceGetOptions<"text">,
): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>
Get a value with metadata from cache
Type Parameters
- Metadata = unknown
Parameters
- key: string
  Cache key
- OptionaltypeOrOptions: "text" | KVNamespaceGetOptions<"text">
  Type string or options object (defaults to 'text')
Returns Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>
Object with value, metadata, and cacheStatus

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:148
getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
key: string,
typeOrOptions: "json" | KVNamespaceGetOptions<"json">,
): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>
Get a value with metadata from cache
Type Parameters
- ExpectedValue = unknown
- Metadata = unknown
Parameters
- key: string
  Cache key
- typeOrOptions: "json" | KVNamespaceGetOptions<"json">
  Type string or options object (defaults to 'text')
Returns Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>
Object with value, metadata, and cacheStatus

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:152
getWithMetadata<Metadata = unknown>(
key: string,
typeOrOptions: "arrayBuffer" | KVNamespaceGetOptions<"arrayBuffer">,
): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>
Get a value with metadata from cache
Type Parameters
- Metadata = unknown
Parameters
- key: string
  Cache key
- typeOrOptions: "arrayBuffer" | KVNamespaceGetOptions<"arrayBuffer">
  Type string or options object (defaults to 'text')
Returns Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>
Object with value, metadata, and cacheStatus

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:156
getWithMetadata<Metadata = unknown>(
key: string,
typeOrOptions: "stream" | KVNamespaceGetOptions<"stream">,
): Promise<KVNamespaceGetWithMetadataResult<ReadableStream<any>, Metadata>>
Get a value with metadata from cache
Type Parameters
- Metadata = unknown
Parameters
- key: string
  Cache key
- typeOrOptions: "stream" | KVNamespaceGetOptions<"stream">
  Type string or options object (defaults to 'text')
Returns Promise<KVNamespaceGetWithMetadataResult<ReadableStream<any>, Metadata>>
Object with value, metadata, and cacheStatus

Throws
If operation fails
- Defined in packages/core/src/cache/services/cache.service.ts:160

list

list<Metadata = unknown>(
options?: KVNamespaceListOptions,
): Promise<KVNamespaceListResult<Metadata, string>>
List keys in cache
Type Parameters
- Metadata = unknown
Parameters
- Optionaloptions: KVNamespaceListOptions
  List options (limit, prefix, cursor)
Returns Promise<KVNamespaceListResult<Metadata, string>>
List result with keys and pagination info
Throws
If operation fails
Example
```
// List all keys
const result = await cache.list()

// List with prefix
const result = await cache.list({ prefix: 'user:' })

// Paginated list
const result = await cache.list({ limit: 100 })
if (!result.list_complete) {
  const nextPage = await cache.list({ cursor: result.cursor })
}
```
- Defined in packages/core/src/cache/services/cache.service.ts:269

put

put(
    key: string,
    value:
        | string
        | ArrayBuffer
        | ReadableStream<any>
        | ArrayBufferView<ArrayBufferLike>,
    options?: KVNamespacePutOptions,
): Promise<void>
Store a value in cache
Parameters
- key: string
  Cache key
- value: string | ArrayBuffer | ReadableStream<any> | ArrayBufferView<ArrayBufferLike>
  Value to store (string, ArrayBuffer, ArrayBufferView, or ReadableStream)
- Optionaloptions: KVNamespacePutOptions
  Put options (expiration, expirationTtl, metadata)
Returns Promise<void>
Throws
If operation fails
Example
```
// Simple put
await cache.put('key', 'value')

// With TTL
await cache.put('key', 'value', { expirationTtl: 3600 })

// With metadata
await cache.put('key', 'value', { metadata: { created: Date.now() } })
```
- Defined in packages/core/src/cache/services/cache.service.ts:214

setKV

setKV(kv: KVNamespace): void
Set the KV namespace binding

Used internally by withBinding() to configure different KV instances.
Parameters
- kv: KVNamespace
  KV namespace to use
Returns void
- Defined in packages/core/src/cache/services/cache.service.ts:65

withBinding

withBinding(kv: KVNamespace): CacheService

Create a new CacheService instance with a different KV binding

Pattern: Returns a new instance (immutable)

Best Practice: Initialize specialized caches as class properties in constructor

Parameters

kv: KVNamespace
KV namespace to use

Returns CacheService

New CacheService instance with the specified binding

Example

class MyService {
  private readonly uploadsCache: CacheService
  private readonly systemCache: CacheService

  constructor(
    @inject(CACHE_TOKENS.CacheService) private readonly cache: CacheService,
    @inject(DI_TOKENS.CloudflareEnv) private readonly env: Env
  ) {
    this.uploadsCache = this.cache.withBinding(this.env.UPLOADS_CACHE)
    this.systemCache = this.cache.withBinding(this.env.SYSTEM_CONFIG_KV)
  }
}

Class CacheService

See

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CacheService

Methods

delete

Parameters

Returns Promise<void>

Throws

get

Parameters

Returns Promise<string | null>

Throws

Type Parameters

Parameters

Returns Promise<ExpectedValue | null>

Throws

Parameters

Returns Promise<ArrayBuffer | null>

Throws

Parameters

Returns Promise<ReadableStream<any> | null>

Throws

getWithMetadata

Type Parameters

Parameters

Returns Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>

Throws

Type Parameters

Parameters

Returns Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>

Throws

Type Parameters

Parameters

Returns Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>

Throws

Type Parameters

Parameters

Returns Promise<KVNamespaceGetWithMetadataResult<ReadableStream<any>, Metadata>>

Throws

list

Type Parameters

Parameters

Returns Promise<KVNamespaceListResult<Metadata, string>>

Throws

Example

put

Parameters

Returns Promise<void>

Throws

Example

setKV

Parameters

Returns void

withBinding

Parameters

Returns CacheService

Example

Settings

On This Page