File Cache Driver

The File Cache Driver stores cached data as files on disk. Each cache key is a directory containing a cache.json file.

When to Use

• Local development
• Need persistence across restarts, but don't want to set up Redis
• Small to medium-sized cache needs

Best For

• Caching API responses, config, or data that should survive restarts
• Environments where Redis is not available

Limitations

• Slower than memory or Redis for large caches
• Not suitable for distributed/multi-server setups
• Manual cleanup of expired files only happens on access

Alternatives

• Memory Cache Driver: Fast, but not persistent
• Redis Cache Driver: Distributed, production-grade

Configuration

src/config/cache.ts

import { env } from "@mongez/dotenv";
import { CacheConfigurations, FileCacheDriver } from "@warlock.js/core";

const cacheConfigurations: CacheConfigurations = {
  drivers: {
    file: FileCacheDriver,
  },
  default: env("CACHE_DRIVER", "file"),
  options: {
    file: {
      globalPrefix: "my-app",
      ttl: 60 * 60 * 24, // 24 hours
      directory: "./tmp/cache",
      fileName: "data.json",
    },
  },
};

export default cacheConfigurations;

Options

Option	Type	Default	Description
directory	string | Function	storagePath("cache")	Directory for cache files
fileName	string | Function	"cache.json"	File name for cache data
globalPrefix	string | Function	undefined	Global prefix for all cache keys
ttl	number	0	Default TTL in seconds (0 = no expiration)

Directory Configuration

{
  directory: "./tmp/cache",    // Static directory path
  // OR
  directory: () => `./cache/${environment()}`, // Dynamic directory
}

File Name Configuration

{
  fileName: "data.json",       // Custom file name
  // OR
  fileName: () => `cache-${Date.now()}.json`, // Dynamic file name
}

Global Prefix

{
  globalPrefix: "myapp",       // Static prefix
  // OR
  globalPrefix: () => `app-${environment()}`, // Dynamic prefix
}

TTL Configuration

{
  ttl: 0,                      // No expiration (default)
  // OR
  ttl: 3600,                   // 1 hour
  // OR
  ttl: 60 * 60 * 24,          // 24 hours
}

Example Usage

Storing and Retrieving Data

import { cache } from "@warlock.js/core";

await cache.set("settings", { darkMode: true }, 3600);
const settings = await cache.get("settings");

File Structure

The file driver creates a directory structure like this:

./tmp/cache/
├── myapp.settings/
│   └── cache.json
├── myapp.user.1/
│   └── cache.json
└── myapp.config/
    └── cache.json

Each cache entry is stored in its own directory with a JSON file containing the data and metadata.

Expired Cache

• Expired cache is only removed when accessed.
• For automatic cleanup, consider a background job or use Redis.

Troubleshooting

• Cache not persistent? Check your directory path and permissions.
• Performance issues? For large caches, use Redis or Memory drivers.