No native build steps required. localforage is browser-only; do not import it in a Node.js server process.

Project setup

1. Copy the source/ directory into your project root, e.g. ./mesh-cache/.
2. Add path aliases in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@graphql-mesh/cache-cfw-kv": ["./mesh-cache/cache/cfw-kv/src/index.ts"],
      "@graphql-mesh/cache-file": ["./mesh-cache/cache/file/src/index.ts"],
      "@graphql-mesh/cache-inmemory-lru": ["./mesh-cache/cache/inmemory-lru/src/index.ts"],
      "@graphql-mesh/cache-localforage": ["./mesh-cache/cache/localforage/src/index.ts"],
      "@graphql-mesh/cache-redis": ["./mesh-cache/cache/redis/src/index.ts"]
    }
  }
}

3. Set environment variables expected by RedisCache:

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=secret
# Optional:
REDIS_USERNAME=default
REDIS_DB=0

4. For cache/file, ensure the process has write access to the target JSON path.
5. For cache/cfw-kv, bind a KV namespace in your wrangler.toml:

[[kv_namespaces]]
binding = "MY_KV"
id = "<namespace-id>"

Then pass { namespace: env.MY_KV } to the constructor.

Public API

CFWorkerKVCache

class CFWorkerKVCache implements KeyValueCache {
  constructor(config: { namespace: string | KVNamespace; logger?: Logger }): void;
  get<T>(key: string): Promise<T | undefined>;
  set(key: string, value: any, options?: { ttl?: number }): Promise<void>;
  delete(key: string): Promise<boolean>;
  getKeysByPrefix(prefix: string): Promise<string[]>;
}

Use when deploying a Mesh gateway on Cloudflare Workers. Pass the binding name as a string or the KVNamespace object directly. TTL is in seconds and maps to expirationTtl.

InMemoryLRUCache

class InMemoryLRUCache<V = any> implements KeyValueCache<V>, Disposable {
  constructor(options?: { max?: number; ttl?: number; pubsub?: MeshPubSub | HivePubSub }): void;
  get(key: string): V | undefined;
  set(key: string, value: any, options?: KeyValueCacheSetOptions): void;
  delete(key: string): boolean;
  getKeysByPrefix(prefix: string): string[];
  [Symbol.dispose](): void;
}

Use for single-process gateways or tests where no external store is needed. max caps the number of entries; ttl sets a global default expiry in seconds. Subscribes to a destroy pubsub event for graceful cleanup.

FileCache

class FileCache<V = any> implements KeyValueCache<V> {
  constructor(config: { path: string; importFn: ImportFn }): void;
  get(name: string): Promise<V | undefined>;
  set(name: string, value: V): Promise<void>;
  delete(name: string): Promise<boolean>;
  getKeysByPrefix(prefix: string): Promise<string[]>;
}

Use during local development or in CI pipelines where a lightweight persistent cache between restarts is sufficient. All data is serialized to a single JSON file at path. Writes are batched through a DataLoader to avoid redundant disk flushes.

RedisCache

class RedisCache<V = string> implements KeyValueCache<V>, Disposable {
  constructor(options: YamlConfig.Cache['redis'] & {
    pubsub?: MeshPubSub | HivePubSub;
    logger: Logger;
  }): void;
  get(key: string): Promise<V | undefined>;
  set(key: string, value: V, options?: KeyValueCacheSetOptions): Promise<void>;
  delete(key: string): Promise<boolean>;
  getKeysByPrefix(prefix: string): Promise<string[]>;
  [Symbol.dispose](): void;
}

Use for production multi-instance gateway deployments. Supports standalone Redis and Cluster mode via startupNodes. All connection strings support ${env.VAR} interpolation.

Working examples

Scenario - In-memory LRU cache with TTL

A development gateway that caches resolved values for 60 seconds, destroyed when the server shuts down.

import InMemoryLRUCache from './mesh-cache/cache/inmemory-lru/src/index';

const cache = new InMemoryLRUCache({ max: 1000, ttl: 60 });

await cache.set('user:42', { name: 'Alice' }, { ttl: 30 });
const user = cache.get('user:42');
console.log(user); // { name: 'Alice' }

const keys = cache.getKeysByPrefix('user:');
console.log(keys); // ['user:42']

cache[Symbol.dispose]();

Scenario - File cache for local development

Persist introspection results across dev server restarts without running Redis.

import FileCache from './mesh-cache/cache/file/src/index';

const cache = new FileCache({
  path: './.mesh-cache.json',
  importFn: (path: string) => import(path),
});

await cache.set('schema:hash:abc123', { sdl: 'type Query { ping: String }' });
const cached = await cache.get('schema:hash:abc123');
console.log(cached); // { sdl: 'type Query { ping: String }' }

const allKeys = await cache.getKeysByPrefix('schema:');
console.log(allKeys); // ['schema:hash:abc123']

Scenario - Redis cache for a production Node.js gateway

Connect to a standalone Redis instance, using environment-interpolated credentials.

import RedisCache from './mesh-cache/cache/redis/src/index';
import { createLogger } from '@graphql-mesh/utils'; // or your own Logger

const cache = new RedisCache({
  host: '${env.REDIS_HOST}',
  port: '${env.REDIS_PORT}',
  password: '${env.REDIS_PASSWORD}',
  lazyConnect: true,
  logger: console as any,
});

await cache.set('response:query1', JSON.stringify({ data: {} }), { ttl: 300 });
const hit = await cache.get('response:query1');
console.log(hit);

const keys = await cache.getKeysByPrefix('response:');
console.log(keys);

cache[Symbol.dispose]();

Scenario - Cloudflare Workers KV cache

Use a bound KV namespace inside a Cloudflare Worker handler.

import CFWorkerKVCache from './mesh-cache/cache/cfw-kv/src/index';

export default {
  async fetch(request: Request, env: { MY_KV: KVNamespace }) {
    const cache = new CFWorkerKVCache({ namespace: env.MY_KV });
    const cached = await cache.get<string>('greeting');
    if (cached) return new Response(cached);

    await cache.set('greeting', 'hello world', { ttl: 3600 });
    return new Response('hello world');
  },
};

File walkthrough

• cache/cfw-kv/ - Wraps KVNamespace from @cloudflare/workers-types; constructor accepts string (globalThis lookup) or direct namespace reference.
• cache/file/ - Reads and writes a JSON file on disk; uses DataLoader to batch concurrent writes into a single flush.
• cache/inmemory-lru/ - Wraps an LRU map with per-key TTL timeouts; subscribes to pubsub destroy for lifecycle management.
• cache/localforage/ - Wraps LocalForage for browser storage; falls back to InMemoryLRUCache when no supported driver is available.
• cache/redis/ - Full ioredis integration supporting standalone and Cluster; uses ioredis-mock in test environments and OpenTelemetry tracing.
• cache/upstash-redis/ - HTTP-based Upstash Redis client suitable for edge and serverless runtimes.
• compose-cli/ - CLI binary and getComposedSchemaFromConfig for building a composed supergraph from a Mesh config file.
• cross-helpers/ - Shims for path and process that resolve correctly across Node, browser, and React Native.
• fusion/composition/ - compose function, federation directives utilities, and schema transforms (encapsulate, hoist-field, filter-schema).
• include/ - Shared TypeScript type declarations and constants consumed across packages.
• json-machete/ - JSON Schema and OpenAPI dereferencing, circular-reference handling, and schema diff utilities.
• legacy/ - Mesh v0 runtime kept for backwards compatibility during migration.
• loaders/ - Protocol-specific source handlers that convert remote APIs into GraphQL subgraph schemas.
• plugins/ - Gateway-level plugins for concerns such as authentication, tracing, response caching, and rate limiting.
• string-interpolation/ - stringInterpolator.parse() resolving ${env.VAR} and context tokens in config strings.
• testing/ - Mock caches, pubsub stubs, and test utilities for writing unit tests against Mesh internals.
• transports/ - Runtime fetch/socket logic for executing requests against subgraphs over HTTP, WebSocket, and gRPC.
• incontext-sdk-codegen/ - GraphQL Code Generator plugin that emits a strongly typed in-context SDK from a composed schema.

Common pitfalls and fixes

• KVNamespace not found at runtime on Cloudflare Workers: Pass env.MY_KV directly instead of the binding name string; string lookup uses globalThis[name] which is not always populated.
• FileCache writes stale data after concurrent set calls: The DataLoader batches by tick; avoid awaiting set in a tight loop without allowing the event loop to drain between calls.
• InMemoryLRUCache timeouts keeping the Node.js process alive: Call cache[Symbol.dispose]() or publish destroy to the linked pubsub on graceful shutdown to clear all setTimeout handles.
• RedisCache constructor throws on missing logger: The logger field is required in the options type; pass console cast to Logger if you have no Mesh logger instance available.
• localforage imported in a Node.js server bundle: It is browser-only; guard with an environment check or exclude it from server bundles via your bundler's resolve.alias or externals.
• ioredis-mock used unintentionally in production: RedisCache imports ioredis-mock at the top level; if your bundler tree-shakes poorly, pin ioredis-mock to devDependencies and ensure it is excluded from production builds.

Vibe-coding prompt template

I have copied the GraphQL Mesh cache backends source into `./mesh-cache/` in my project.
The relevant USAGE.md is at `./mesh-cache/USAGE.md`.
The upstream package is `graphql-mesh` by The Guild.

Please help me integrate one or more of these cache backends into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` and the source files under `./mesh-cache/cache/` to understand the available cache implementations.
2. Based on my environment (tell the AI: local dev / production Node.js / Cloudflare Workers / browser), recommend the appropriate cache class.
3. Add the required `npm install` commands for that cache's dependencies.
4. Add the TypeScript path alias for the chosen cache package to my `tsconfig.json`.
5. Write a `cache.ts` module that instantiates the cache with my configuration and exports it.
6. Show me how to call `get`, `set`, `delete`, and `getKeysByPrefix` in my application code.
7. Add teardown logic (Symbol.dispose or pubsub destroy) to my server shutdown handler.
8. If I am using Redis, show how to set environment variables and use string interpolation for credentials.

Use only the real class names, constructor signatures, and method signatures from USAGE.md. Do not invent new APIs.

License and credit

This source is part of graphql-mesh by The Guild, released under the MIT License. See source/LICENSE if present, or refer to the repository root. Original package registry entry: graphql-mesh on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Hive Gateway GraphQL Federation and Proxy Gateway

SaaS, AI & Subscription Products

Free