Cache

services.cache stores reusable expiring optimization data.

Good uses

• API responses that may be fetched again.
• Computed lookup tables.
• Temporary access metadata.
• Expensive pure calculations.

Cache may be discarded, expired, or rebuilt. Never use it as the only record that an order was paid, an approval was granted, or work completed. Put authoritative cross-run values in Durable State or a database.

Use stable keys, bounded values, and an explicit TTL appropriate to the source data.

Implement cache-aside behavior

const key = `customer:${context.payload.customerId}`;
const cached = await services.cache.get(key);

if (cached.hit) {
  return { customer: cached.value, source: "cache" };
}

const response = await services.http.request({
  url: `https://api.example.com/customers/${context.payload.customerId}`
}, { name: "load-customer" });

await services.cache.set(key, response.data, {
  ttl: "15m",
  name: "cache-customer"
});

return { customer: response.data, source: "api" };

The workflow remains correct when the cache misses. That is the defining rule.

Use atomic helpers

increment performs safe-integer addition and setIfAbsent provides one-winner initialization. These are useful for optimization counters and coordination that may be discarded, not for permanent business decisions.

Local cache entries expire and may be evicted under limits. They can survive a restart but are never authoritative. If losing the value changes business truth, use durable state or a database instead.