Skip to main content

Cache Manager

This is the core of the entire cache ecosystem. It is responsible for managing the cache drivers, and the cache configurations.

You can access the cache manager by importing cache from warlock.

Setting Configurations​

After you define Cache Configurations, you can set them using the setCacheConfigurations method.

src/config/cache.ts
import { CacheConfigurations } from "@warlock.js/core";
const cacheConfigurations: CacheConfigurations = {
  //...
};

export default cacheConfigurations;

The configuration will be automatically loaded when the cache manager is initialized.

Initializing the cache manager​

By default Warlock initializes the cache manager to start connecting to the default driver when the http server is about to start so you don't really need to take any action in this regard.

Cache Manager is a Cache Driver​

All methods that are available on Cache Driver are available on the cache manager so you will be able to use the cache manager as a cache driver.

Get current driver​

If you want to directly access the current cache driver from the cache manager, use currentDriver property.

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

const currentDriver = cache.currentDriver;
info

If there is no current driver, then the cache manager will use the NullCacheDriver instead.

Set default driver​

To change the default driver, use use method, this method accepts the driver name defined in Cache drivers list or pass the driver object directly.

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

await cache.use("redis");
info

Please note that use method is a async method, as if the driver was not loaded before, the cache manager will load it first before using it so make sure to use await keyword when calling this method.

Get driver​

To get another cache driver (but not set it as a default driver) use driver method, it accepts the driver name.

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

async function main() {
  const redisDriver = await cache.driver("redis");

  const memoryDriver = await cache.driver("memory");
}

main();
info

If the driver is not loaded before, the cache manager will load it first before returning it.

danger

If the given driver name is not listed in Cache drivers list, it will throw an error.

Register Custom Driver​

You can register custom drivers at runtime:

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

cache.registerDriver("custom", CustomCacheDriver);

Global prefix​

Global prefix option is implemented in all built-in drivers, it highly recommended to use it as a way to avoid key conflicts especially if you're using a common cache driver like redis.

info

Consider a global prefix as a database name in a database server, it is used to separate the keys from each other.

Setting a value in the cache​

To set a value in the cache, use set method, this method accepts three parameters:

  • The first one is the key that will be used to store the value in the cache.
  • The second one is the value that will be stored in the cache.
  • The third one is the number of seconds that the value will be stored in the cache.
import { cache } from "@warlock.js/core";

// somewhere in the project
await cache.set("key", "value", 60 * 60 * 24);

The value can be any type of value either a string, number, boolean, or even an object or an array.

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

// somewhere in the project
await cache.set("key", { name: "John Doe" }, 60 * 60 * 24);

The key could be a string or an object, if it is an object, it will be converted to a string using Parse Cache Key utility.

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

// somewhere in the project
await cache.set({ id: 1 }, { name: "John Doe" }, 60 * 60 * 24);

This will result a key like this : id.1.

tip

If the global prefix is set, then it will be prefixed with the global prefix.

If the third parameter is not set ttl then the driver will try to capture it from the driver options, if not found then the value will be stored in the cache forever.

Getting a value from the cache​

To get a value from the cache, use get method, this method accepts one parameter which is the key that will be used to get the value from the cache.

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

// somewhere in the project
const value = await cache.get("key");

It can also accept an object as a key, it will be converted to a string using Parse Cache Key utility.

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

// somewhere in the project
const value = await cache.get({ id: 1 }); // this will be converted to id.1

If the key does not exists a null value will be returned.

Removing a value from the cache​

To remove a value from the cache, use remove method, this method accepts one parameter which is the key that will be used to remove the value from the cache.

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

// somewhere in the project
await cache.remove("key");

It can also accept an object as a key, it will be converted to a string using Parse Cache Key utility.

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

// somewhere in the project
await cache.remove({ id: 1 }); // this will be converted to id.1

Removing all values from the cache​

To clear the entire cache, use flush method.

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

// somewhere in the project
await cache.flush();

Namespaces​

Another good approach that is powered by Warlock Cache is namespaces, it allows you easily to categorize all the cached data by a namespace.

A namespace is a string that is suffixed with a dot then the key, for example, if we have a namespace called users, then the key 1 will be converted to users.1.

Removing all values from a namespace​

To clear the entire cache for a namespace, use removeNamespace method, this method accepts one parameter which is the namespace that will be used to remove the values from the cache.

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

// store a value in the cache
await cache.set("users.1", {
  id: 1,
  name: "John Doe",
});

await cache.set("users.list", [
  {
    id: 1,
    name: "John Doe",
  },
  {
    id: 2,
    name: "Jane Doe",
  },
]);

// somewhere in the project
await cache.removeNamespace("users");

This will clear out all the values that are stored under the users namespace.

Parse Key​

The parseKey method converts keys to a consistent format:

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

// Parse object keys
const key = await cache.parseKey({ id: 1, type: "user" });
// Result: "id.1.type.user"

// Parse string keys
const key = await cache.parseKey("user:1");
// Result: "user.1"

Get Options​

Access the current driver's options:

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

const options = cache.options;

Set Options​

Update the current driver's options:

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

cache.setOptions({
  globalPrefix: "newprefix",
  ttl: 7200,
});

Disconnect​

Disconnect from the current cache driver:

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

await cache.disconnect();

Set Default Driver at Runtime​

You can switch the default driver at runtime using use:

import { cache } from "@warlock.js/core";
await cache.use("memory");

Get a Specific Driver (without switching)​

import { cache } from "@warlock.js/core";
const fileDriver = await cache.driver("file");

Using Multiple Drivers​

You can use different drivers for different use-cases:

import { cache } from "@warlock.js/core";
const redis = await cache.driver("redis");
const memory = await cache.driver("memory");
await redis.set("user:1", { name: "Alice" });
await memory.set("temp", 123);

Real-World Example: Caching API Responses​

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

async function getUser(id) {
  const cached = await cache.get(`user:${id}`);
  if (cached) return cached;
  const user = await fetchUserFromDb(id);
  await cache.set(`user:${id}`, user, 3600);
  return user;
}

Troubleshooting​

  • Driver not found? Make sure it's listed in your config's drivers property.
  • Cache not working? Check your driver options and environment variables.
  • Switching drivers has no effect? Use await cache.use("driverName") and ensure the driver is properly configured.

Namespaces & Prefixes​

  • Use namespaces (e.g., users.1) to group related cache keys.
  • Use globalPrefix to avoid key collisions between apps.

More​

See Cache Driver Interface for all available methods.