Caching APIs

ZoneCache

The ZoneCache stores data in a shared cache that is local to a single zone (data center or cluster). Each zone maintains its own independent cache — data written in one zone is not synchronized or replicated to other zones. If the same data is needed in multiple zones, it must be written to each zone's cache independently.

This makes ZoneCache ideal for caching configuration, reference data, or expensive API responses to reduce latency. It is not suitable for transactional, OLTP-style workloads where consistency across locations matters.

The ZoneCache can store any JSON serializable data. Each cached item has a time-to-live (TTL) after which it expires and is removed from the cache. Each cached object can be up to 512 MB in size.

There's an demonstration of ZoneCache use in the Per User Rate Limits Using a Database example.

Constructor

Code
new ZoneCache<T = unknown>(name: string, context: ZuploContext)

Creates a new cache instance for the specified zone.

name - A unique identifier for the cache
context - The ZuploContext object
T - The type of data stored in the cache (defaults to unknown)

Methods

get

Retrieves a value from the cache. Returns undefined if the key doesn't exist or has expired.

Code
get(key: string): Promise<T | undefined>

put

Stores a value in the cache with a time-to-live (TTL) in seconds. The data will be JSON serialized.

Code
put(key: string, data: T, ttlSeconds: number): Promise<void>

Objects that don't serialize cleanly to JSON (like the Headers object) won't be readable after storage.

delete

Removes a value from the cache.

Code
delete(key: string): Promise<void>

Example

Code
import { ZoneCache, ZuploContext, ZuploRequest } from "@zuplo/runtime";

interface UserData {
  id: string;
  name: string;
  email: string;
}

export default async function handler(
  request: ZuploRequest,
  context: ZuploContext,
) {
  const cache = new ZoneCache<UserData>("user-cache", context);

  // Try to get user from cache
  const userId = request.params.userId;
  let userData = await cache.get(userId);

  if (!userData) {
    // Not in cache, fetch from API
    const response = await fetch(`https://api.example.com/users/${userId}`);
    userData = await response.json();

    // Cache for 5 minutes
    await cache.put(userId, userData, 300);
  }

  return new Response(JSON.stringify(userData));
}

Performance tips

When writing to the cache, you may not want to await the operation to complete. This can improve response times:

Code
// Fire and forget pattern - don't wait for cache write
cache.put("key", data, 60).catch((err) => context.log.error(err));

Always catch errors when using the fire-and-forget pattern to avoid unhandled promise rejections.

When to use ZoneCache

ZoneCache works well for:

Configuration and reference data — API keys, feature flags, routing rules, or other config that changes infrequently
Expensive API responses — results from slow or rate-limited upstream services
Computed data — pre-processed results that are costly to regenerate

Not a distributed data store

ZoneCache is a per-zone cache with no cross-zone synchronization. A put() in one data center has no effect on the cache in any other data center. Do not use it as a database, key/value store, or for any OLTP-style read/write workload. It is not appropriate for data where global consistency matters.

Limits

For full Zuplo platform limits see the Zuplo Limits documentation.

Maximum size per cached item: 512 MB
Maximum cache calls per request: 1000