Cache

Warlock framework uses the @warlock.js/cache package for caching. This page covers framework-specific features only. For comprehensive cache API documentation, see the Cache Package Documentation.

Full API Documentation

All cache features work in Warlock exactly as documented in the standalone package. See Cache Package Documentation for:

• Complete API reference
• All cache drivers (Memory, Redis, File, LRU, etc.)
• Advanced features (tags, events, atomic operations)
• Best practices and examples

Framework Integration

The Warlock framework provides automatic cache initialization and includes a special Database Cache Driver that stores cache in your MongoDB database.

Key Differences from Standalone Package

Feature	Standalone	Warlock Framework
Initialization	Manual (cache.init())	Automatic during bootstrap
Config Loading	Manual import and setup	Auto-loaded from src/config/cache.ts
DatabaseCacheDriver	Not available	Available and auto-registered

Automatic Initialization

In Warlock, cache is automatically initialized when your application starts. You don't need to call cache.init() manually.

How It Works

1. Configuration is automatically loaded from src/config/cache.ts
2. During bootstrap, setupCache() is called
3. Cache is initialized and ready to use

src/config/cache.ts

import { CacheConfigurations, DatabaseCacheDriver, RedisCacheDriver, CACHE_FOR } from "@warlock.js/cache";

const cacheConfigurations: CacheConfigurations = {
  drivers: {
    database: DatabaseCacheDriver, // Auto-registered but can be explicitly included
    redis: RedisCacheDriver,
  },
  default: "database",
  options: {
    database: {
      globalPrefix: "myapp",
      ttl: CACHE_FOR.ONE_HOUR,
    },
    redis: {
      host: "localhost",
      port: 6379,
      globalPrefix: "myapp",
      ttl: CACHE_FOR.ONE_HOUR,
    },
  },
};

export default cacheConfigurations;

That's it! No manual initialization needed. The cache is automatically configured and ready when your application starts.

Database Cache Driver

The DatabaseCacheDriver is a Warlock-specific cache driver that stores cache entries in your MongoDB database. It's automatically registered when you import @warlock.js/core.

When to Use DatabaseCacheDriver

✅ Good for:

• Applications already using MongoDB
• Single-server deployments
• When you want cache data to persist in the database
• Development environments

❌ Not recommended for:

• High-traffic applications (use Redis instead)
• Distributed/multi-server setups (use Redis)
• Applications that need sub-millisecond cache access

Configuration

src/config/cache.ts

import { CacheConfigurations, DatabaseCacheDriver, CACHE_FOR } from "@warlock.js/cache";
import { CacheModel } from "@warlock.js/core"; // Optional custom model

const cacheConfigurations: CacheConfigurations = {
  drivers: {
    database: DatabaseCacheDriver,
  },
  default: "database",
  options: {
    database: {
      // Optional: Custom model (defaults to CacheModel)
      model: CacheModel,
      
      // Optional: Global prefix for all cache keys
      globalPrefix: "myapp",
      
      // Optional: Default TTL in seconds
      ttl: CACHE_FOR.ONE_HOUR,
    },
  },
};

export default cacheConfigurations;

How It Works

The DatabaseCacheDriver stores cache entries in a MongoDB collection:

• Collection name: cache (by default)
• Key structure: Uses dot notation (e.g., users.123.profile)
• Namespace extraction: Automatically extracts namespaces from keys
• TTL support: Automatic expiration handling
• Namespace invalidation: Supports removeNamespace() for bulk invalidation

Custom Cache Model

You can use a custom model if needed:

src/app/models/custom-cache.ts

import { Model } from "@warlock.js/cascade";
import { DatabaseCacheDriver } from "@warlock.js/core";

export class CustomCacheModel extends Model {
  public static collection = "custom_cache";
}

// In your cache configuration
const cacheConfigurations: CacheConfigurations = {
  drivers: {
    database: DatabaseCacheDriver,
  },
  default: "database",
  options: {
    database: {
      model: CustomCacheModel,
      globalPrefix: "myapp",
    },
  },
};

Framework Integration

Repositories

Repositories automatically use cache when enabled. See Repository Caching for details.

• Automatic cache methods: listCached(), getCached(), etc.
• Automatic cache invalidation on model create/update/delete
• Repository-specific cache namespaces

Restful Controllers

Restful controllers automatically use cached repository methods when cache is enabled. See Restful API for details.

• Automatic use of repository.listCached() in list endpoints
• Automatic use of repository.findCached() in get endpoints

Next Steps

• Cache Package Documentation - Complete API reference
• Repository Caching - Repository-specific caching
• Restful API - RESTful endpoint caching
• Cache Configurations - Configuration options