Event System

The cache event system provides comprehensive observability into every cache operation. Listen to hit, miss, set, removed, and other events to monitor cache behavior.

Available Events

Event	When Fired	Event Data
hit	Value retrieved from cache	{ key, value, driver }
miss	Value not found or expired	{ key, driver }
set	Value stored in cache	{ key, value, ttl, driver }
removed	Key removed from cache	{ key, driver }
flushed	Entire cache cleared	{ driver }
expired	Key expired (TTL reached)	{ key, driver }
connected	Driver connected	{ driver }
disconnected	Driver disconnected	{ driver }
error	Error occurred	{ error, driver, key? }

Monitoring and Metrics

For aggregate observability — hit rate, latency percentiles, per-driver breakdowns — use the built-in collector instead of wiring everything by hand: see Built-in Metrics. Use the raw event listeners below when you need per-event reactions (alerts, audit logs) that the collector doesn’t cover.

Listen to hit and miss events to track cache performance:

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

let hitCount = 0;
let missCount = 0;

cache.on("hit", ({ key }) => {
  hitCount++;
  console.log(`Cache hit: ${key}`);
});

cache.on("miss", ({ key }) => {
  missCount++;
  console.log(`Cache miss: ${key}`);
});

// Log metrics periodically
setInterval(() => {
  const total = hitCount + missCount;
  const hitRate = total > 0 ? (hitCount / total * 100).toFixed(2) : 0;
  console.log(`Hit rate: ${hitRate}% (${hitCount} hits, ${missCount} misses)`);
}, 60000);

For external metrics services:

cache.on("hit", ({ key }) => {
  metricsService.increment("cache.hits", { key });
});

cache.on("miss", ({ key }) => {
  metricsService.increment("cache.misses", { key });
});

Global vs Driver-Specific Listeners

// Global listeners (listen to all drivers)
cache.on("hit", () => {
  console.log("Hit on any driver");
});

// Driver-specific listeners
const redisDriver = await cache.driver("redis");
redisDriver.on("hit", () => {
  console.log("Hit only on Redis driver");
});

Global listeners are automatically attached to all drivers when they’re loaded or switched.

E-Commerce Monitoring Examples

Product Cache Metrics

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

const metrics = {
  productHits: 0,
  productMisses: 0,
  cartHits: 0,
  cartMisses: 0
};

cache.on("hit", ({ key }) => {
  if (key.startsWith("products.")) metrics.productHits++;
  if (key.startsWith("cart.")) metrics.cartHits++;
});

cache.on("miss", ({ key }) => {
  if (key.startsWith("products.")) metrics.productMisses++;
  if (key.startsWith("cart.")) metrics.cartMisses++;
});

// Report metrics every minute
setInterval(() => {
  console.log("Product Cache:", {
    hits: metrics.productHits,
    misses: metrics.productMisses,
    hitRate: (metrics.productHits / (metrics.productHits + metrics.productMisses) * 100).toFixed(2) + "%"
  });
}, 60000);

Error Tracking

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

cache.on("error", ({ error, driver, key }) => {
  console.error(`Cache error on ${driver}:`, {
    key,
    error: error.message
  });

  // Send to error tracking service
  errorTracker.report(error, { driver, key });
});

Development Debugging

if (process.env.NODE_ENV === "development") {
  cache.on("hit", ({ key }) => {
    console.log(`[Cache] HIT: ${key}`);
  });

  cache.on("miss", ({ key }) => {
    console.log(`[Cache] MISS: ${key}`);
  });

  cache.on("set", ({ key, ttl }) => {
    console.log(`[Cache] SET: ${key} (expires in ${ttl}s)`);
  });
}

Advanced Event Handling

One-Time Listeners

Listen to an event once, then automatically remove the listener:

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

// Wait for cache to connect
cache.once("connected", () => {
  console.log("Cache connected! Ready to use.");
  // This listener is automatically removed after firing
});

Remove Listeners

Remove specific event listeners:

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

const handler = ({ key }) => {
  console.log(`Key accessed: ${key}`);
};

// Register
cache.on("hit", handler);
cache.on("miss", handler);

// Later, remove
cache.off("hit", handler);
cache.off("miss", handler);

Async Event Handlers

Event handlers can be async - the cache waits for them to complete:

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

cache.on("set", async ({ key, value, ttl }) => {
  // Async operation in event handler
  await analytics.trackAsync("cache_write", { key, ttl });
  await updateCacheMetrics({ key, ttl });
});

Comprehensive Monitoring Class

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

class CacheMonitor {
  private stats = {
    hits: 0,
    misses: 0,
    sets: 0,
    errors: 0
  };

  constructor() {
    cache.on("hit", () => this.stats.hits++);
    cache.on("miss", () => this.stats.misses++);
    cache.on("set", () => this.stats.sets++);
    cache.on("error", () => this.stats.errors++);
  }

  getStats() {
    const total = this.stats.hits + this.stats.misses;
    return {
      hits: this.stats.hits,
      misses: this.stats.misses,
      sets: this.stats.sets,
      errors: this.stats.errors,
      hitRate: total > 0 ? (this.stats.hits / total * 100).toFixed(2) + "%" : "0%",
      totalRequests: total
    };
  }

  reset() {
    this.stats = { hits: 0, misses: 0, sets: 0, errors: 0 };
  }
}

const monitor = new CacheMonitor();
setInterval(() => {
  console.log("Cache Stats:", monitor.getStats());
}, 60000);

Event Data Types

All events provide a driver field indicating which driver emitted the event:

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

cache.on("hit", (data: CacheEventData) => {
  console.log(`Driver: ${data.driver}`);
  console.log(`Key: ${data.key}`);
  console.log(`Value: ${data.value}`);
});

cache.on("error", (data: CacheEventData) => {
  console.error(`Error on ${data.driver}:`, data.error);
});

Performance Considerations

• Event handlers are non-blocking: They run asynchronously and don’t block cache operations
• Multiple handlers: You can register multiple handlers for the same event
• Error handling: Errors in event handlers are caught and logged, but don’t affect cache operations
• Overhead: Minimal - events are emitted efficiently with minimal performance impact

Best Practices

1. Register listeners early: Set up event listeners before cache operations
2. Keep handlers fast: Event handlers should complete quickly — offload heavy work to background jobs
3. Handle errors: Always handle errors in event handlers gracefully
4. Use once() for one-time operations: Use once() instead of manually removing listeners
5. Filter by key pattern: Listen to specific key patterns to reduce noise in production

Troubleshooting

• Events not firing? Ensure listeners are registered before cache operations occur
• Too many events? Filter events in your handlers or register listeners only in development
• Performance issues? Ensure event handlers are fast — consider using a message queue for heavy operations

See Best Practices for more monitoring patterns.