Cache Utilities

This section covers the utilities provided for cache drivers.

Parse Cache Key

The parseCacheKey function parses a cache key (string or object), sanitizes it, and returns a dot.notation string. This helps avoid key collisions and makes cache keys predictable.

When to Use

• When using objects as cache keys (e.g., for query filters)
• When you want consistent, readable cache keys

Recommended

Prefer using dot notation strings directly in your code. Use parseCacheKey only when you need to programmatically convert complex data structures to keys.

Examples

src/app/main.ts

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

// Converting string formats to dot notation
console.log(parseCacheKey("users:1")); // users.1

// Programmatically generating keys from query filters
const filter = {
  limit: 3,
  page: 1,
  search: "John",
};
const cacheKey = parseCacheKey(filter); // limit.3.page.1.search.John
await cache.set(cacheKey, filteredResults);

const nested = {
  user: { id: 5 },
  tags: ["a", "b"],
};
console.log(parseCacheKey(nested)); // user.id.5.tags.a.b

With Global Prefix

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

// Static global prefix
const options = { globalPrefix: "myapp" };
console.log(parseCacheKey("user:1", options)); // myapp.user.1

// Dynamic global prefix function
const dynamicOptions = {
  globalPrefix: () => {
    const tenant = getCurrentTenant(); // Your function to get tenant
    return `tenant.${tenant.id}`;
  }
};
console.log(parseCacheKey("user:1", dynamicOptions)); // tenant.1.user.1

Complex Object Keys

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

// Nested objects
const complexKey = {
  resource: "posts",
  filters: {
    status: "published",
    category: "tech"
  },
  pagination: {
    page: 1,
    limit: 10
  }
};

console.log(parseCacheKey(complexKey));
// resource.posts.filters.status.published.filters.category.tech.pagination.page.1.pagination.limit.10

// Arrays in keys
const keyWithArray = {
  tags: ["javascript", "typescript"],
  userId: 123
};

console.log(parseCacheKey(keyWithArray));
// tags.javascript.tags.typescript.userId.123

Tip

Use this utility for cache keys in repositories, API responses, or any place where the key might be an object. The function automatically sanitizes special characters and converts objects to dot-notation strings.

Expiration Constants

The CACHE_FOR enum provides common TTL values for easy use:

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

// Common expiration times
await cache.set("temp", data, CACHE_FOR.HALF_HOUR);    // 30 minutes
await cache.set("session", data, CACHE_FOR.ONE_HOUR);  // 1 hour
await cache.set("daily", data, CACHE_FOR.ONE_DAY);     // 24 hours
await cache.set("weekly", data, CACHE_FOR.ONE_WEEK);   // 7 days
await cache.set("monthly", data, CACHE_FOR.ONE_MONTH); // 30 days

Available Constants

Constant	Value (seconds)	Description
HALF_HOUR	1800	30 minutes
ONE_HOUR	3600	1 hour
HALF_DAY	43200	12 hours
ONE_DAY	86400	24 hours
ONE_WEEK	604800	7 days
HALF_MONTH	1296000	15 days
ONE_MONTH	2592000	30 days
TWO_MONTHS	5184000	60 days
SIX_MONTHS	15768000	180 days
ONE_YEAR	31536000	365 days

Real-World Example

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

class UserService {
  async getUser(id: number) {
    const cacheKey = `user.${id}`;
    
    // Try to get from cache first
    let user = await cache.get(cacheKey);
    
    if (!user) {
      // Fetch from database
      user = await this.fetchFromDatabase(id);
      
      // Cache for 1 hour
      await cache.set(cacheKey, user, CACHE_FOR.ONE_HOUR);
    }
    
    return user;
  }
  
  async getUserList(filters: any) {
    const cacheKey = filters; // Object will be parsed automatically
    
    let users = await cache.get(cacheKey);
    
    if (!users) {
      users = await this.fetchUsersFromDatabase(filters);
      
      // Cache for 30 minutes
      await cache.set(cacheKey, users, CACHE_FOR.HALF_HOUR);
    }
    
    return users;
  }
}