Skip to main content
Version: Next

cacheTag Function

The cacheTag function allows you to add tags to your cache entries, making it easier to manage and invalidate related cache entries together.

Basic Usage​

async function fetchUserData(userId: string) {
  'use cache';

  // Add a tag to this cache entry
  cacheTag(`user:${userId}`);

  const userData = await db.users.findOne(userId);
  return userData;
}

Why Use Tags?​

Tags are useful when you want to:

  • Group related cache entries
  • Invalidate multiple cache entries at once
  • Manage cache entries by category
  • Implement targeted cache invalidation

Example Use Cases​

async function fetchGuildData(guildId: string) {
  'use cache';

  // Tag all guild-related data
  cacheTag(`guild:${guildId}`);

  const [settings, members, roles] = await Promise.all([
    db.guilds.findOne(guildId),
    db.members.find({ guildId }),
    db.roles.find({ guildId }),
  ]);

  return { settings, members, roles };
}

Categorizing Cache Entries​

async function fetchUserStats(userId: string) {
  'use cache';

  // Add multiple tags for different categories
  cacheTag(`user:${userId}`);
  cacheTag('stats');

  const stats = await calculateUserStats(userId);
  return stats;
}

Targeted Revalidation​

// Later in your code
import { revalidateTag } from '@commandkit/cache';

// This will invalidate all cache entries tagged with 'user:123'
await revalidateTag('user:123');

Best Practices​

  1. Use Consistent Naming:

    • Follow a consistent pattern (e.g., type:id)
    • Make tags descriptive and meaningful
    • Use hierarchical tags when appropriate

  2. Group Related Data:

    • Tag related cache entries with the same tag
    • Use multiple tags for cross-category entries
    • Consider data relationships when tagging

  3. Avoid Over-tagging:

    • Don't add unnecessary tags
    • Use tags purposefully
    • Consider the impact on revalidation

Common Patterns​

Resource-based Tags​

async function fetchUserResources(userId: string) {
  'use cache';

  // User resources
  cacheTag(`user:${userId}`);
  cacheTag(`user:${userId}:profile`);
  cacheTag(`user:${userId}:settings`);

  return await Promise.all([
    fetchUserProfile(userId),
    fetchUserSettings(userId),
  ]);
}

async function fetchGuildResources(guildId: string) {
  'use cache';

  // Guild resources
  cacheTag(`guild:${guildId}`);
  cacheTag(`guild:${guildId}:members`);
  cacheTag(`guild:${guildId}:roles`);

  return await Promise.all([
    fetchGuildMembers(guildId),
    fetchGuildRoles(guildId),
  ]);
}

Category-based Tags​

async function fetchContent() {
  'use cache';

  // Content categories
  cacheTag('content:announcements');
  cacheTag('content:rules');
  cacheTag('content:welcome');

  return await Promise.all([
    fetchAnnouncements(),
    fetchRules(),
    fetchWelcomeMessage(),
  ]);
}

async function fetchSystemData() {
  'use cache';

  // System categories
  cacheTag('system:config');
  cacheTag('system:stats');
  cacheTag('system:logs');

  return await Promise.all([fetchConfig(), fetchStats(), fetchLogs()]);
}