api-reference.md

API Reference

Memory Cache Handler

createMemoryDataCacheHandler(options)

Creates a memory-based cache handler.

Options:

{
  maxSize?: number;  // Maximum cache size in bytes (default: 50MB)
  debug?: boolean;   // Enable debug logging (default: false)
}

Example:

import { createMemoryDataCacheHandler } from "@mrjasonroy/cache-components-cache-handler";

export default createMemoryDataCacheHandler({
  maxSize: 100 * 1024 * 1024, // 100MB
  debug: true,
});

Redis Cache Handler

createRedisDataCacheHandler(options)

Creates a Redis-based cache handler.

Options:

{
  redis: RedisClientType;     // Connected Redis client (required)
  keyPrefix?: string;         // Prefix for cache keys (default: "nextjs:cache:")
  tagPrefix?: string;         // Prefix for tag keys (default: "nextjs:tags:")
  defaultTTL?: number;        // Default TTL in seconds (default: 86400)
  debug?: boolean;            // Enable debug logging (default: false)
}

Example:

import { createClient } from "redis";
import { createRedisDataCacheHandler } from "@mrjasonroy/cache-components-cache-handler";

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

export default createRedisDataCacheHandler({
  redis,
  keyPrefix: "myapp:cache:",
  tagPrefix: "myapp:tags:",
  defaultTTL: 3600, // 1 hour
  debug: process.env.NODE_ENV === "development",
});

redis must be a node-redis-style client. node-redis (createClient) works directly; for ioredis, wrap it with createIoredisAdapter (below).

createIoredisAdapter(client)

Wraps an ioredis client (or Cluster) so it satisfies the node-redis-style RedisClient contract expected by createRedisDataCacheHandler. It translates node-redis SET options ({ EX: seconds }) to ioredis positional args ("EX", seconds); without it, Redis rejects writes with ERR syntax error and TTLs silently fail.

import Redis from "ioredis";
import {
  createRedisDataCacheHandler,
  createIoredisAdapter,
} from "@mrjasonroy/cache-components-cache-handler";

const redis = new Redis(process.env.REDIS_URL);

export default createRedisDataCacheHandler({
  redis: createIoredisAdapter(redis),
});

Next.js Cache APIs

These are Next.js built-in APIs that work with this cache handler.

cacheLife(profile)

Set cache lifetime using a profile.

Built-in profiles: "seconds", "minutes", "hours", "days", "weeks"

Example:

import { cacheLife } from "next/cache";

async function MyComponent() {
  "use cache";
  cacheLife("hours");
  // ...
}

cacheTag(...tags)

Tag cache entries for selective invalidation.

Example:

import { cacheTag } from "next/cache";

async function MyComponent({ id }: { id: string }) {
  "use cache";
  cacheTag("my-data", `item:${id}`);
  // ...
}

revalidateTag(tag)

Invalidate all cache entries with a specific tag.

Example:

import { revalidateTag } from "next/cache";

// In an API route
export async function POST() {
  revalidateTag("my-data");
  return Response.json({ revalidated: true });
}

revalidatePath(path)

Invalidate all cache entries for a specific path.

Example:

import { revalidatePath } from "next/cache";

// In an API route
export async function POST() {
  revalidatePath("/products");
  return Response.json({ revalidated: true });
}

Cache Directives

"use cache"

Mark a component for caching.

async function MyComponent() {
  "use cache";
  // Component code
}

"use cache: remote"

Mark for distributed caching across instances.

async function MyComponent() {
  "use cache: remote";
  // Component code
}