From fb2eac0211aa15322d123aba9a84029be6403d83 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Fri, 14 Aug 2026 07:55:40 +1000 Subject: [PATCH] docs: clarify minimal degradation behavior (LAB-1770) --- packages/cachekit/README.md | 21 ++++++++++++--------- packages/cachekit/src/intents-core.ts | 5 ++++- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/packages/cachekit/README.md b/packages/cachekit/README.md index 175c28f..1e4708a 100644 --- a/packages/cachekit/README.md +++ b/packages/cachekit/README.md @@ -58,7 +58,7 @@ Instead of manually wiring backends, reliability, and encryption, declare what y ```typescript import { createCache } from '@cachekit-io/cachekit'; -// Speed-first — no circuit breaker, no retry (product catalogs, public APIs) +// Speed-first — no circuit breaker, retry, or graceful degradation; errors propagate const fast = createCache.minimal({ url: 'redis://localhost:6379', ttl: 300, @@ -85,12 +85,12 @@ const managed = createCache.io({ Each intent pre-configures the full stack with sensible defaults: -| Intent | Backend | Circuit Breaker | Retry | L1 SWR | Encryption | Default TTL | -| ------------ | ----------- | ----------------- | ----- | ------ | ----------- | ----------- | -| `minimal` | Redis | Off | Off | Off | No | 300s | -| `production` | Redis | On (threshold: 5) | On | On | No | 600s | -| `secure` | Redis | On (threshold: 5) | On | On | AES-256-GCM | 600s | -| `io` | cachekit.io | On (threshold: 5) | On | On | Optional | 3600s | +| Intent | Backend | Circuit Breaker | Retry | Degradation | L1 SWR | Encryption | Default TTL | +| ------------ | ----------- | ----------------- | ----- | ---------------------- | ------ | ----------- | ----------- | +| `minimal` | Redis | Off | Off | Off — errors propagate | Off | No | 300s | +| `production` | Redis | On (threshold: 5) | On | On | On | No | 600s | +| `secure` | Redis | On (threshold: 5) | On | On | On | AES-256-GCM | 600s | +| `io` | cachekit.io | On (threshold: 5) | On | On | On | Optional | 3600s | All defaults are overridable — pass `reliability`, `l1`, or `metrics` to customize. @@ -156,8 +156,11 @@ const cache = createCache({ `serializer.maxEncodedSize` — **1 MiB by default** — with `ValueTooLargeError`. Two things make this rejection easy to miss in production: -- **Graceful degradation is on by default**, and it treats a failed `set()` - as "skip silently" — the call resolves normally. +- **Graceful degradation is on for `production`, `secure`, and `io`**, and it + treats a failed `set()` as "skip silently" — the call resolves normally. +- **`minimal` disables graceful degradation**, so an oversized `set()` throws + `ValueTooLargeError` loudly; the caller's own try/catch is the failure + boundary. The `minimal` example below raises the limit to avoid that failure. - Consumers that guard `set()` with try/catch (correctly — cache failures shouldn't fail requests) absorb the error the same way. diff --git a/packages/cachekit/src/intents-core.ts b/packages/cachekit/src/intents-core.ts index e964099..0363be1 100644 --- a/packages/cachekit/src/intents-core.ts +++ b/packages/cachekit/src/intents-core.ts @@ -62,6 +62,9 @@ type IntentBackendOptions = * Options for `createCache.minimal()` — speed-first, no protection. * * Disables circuit breaker, retry, and degradation for maximum throughput. + * With degradation off, backend or decode failures make `get()`, `set()`, and + * `wrap()` throw rather than return null or skip a cache write; the caller's + * own try/catch is the failure boundary. * Use for read-heavy, non-critical caching (product catalogs, public APIs). * * Read-heavy public APIs routinely serve multi-MB responses — mind the @@ -160,7 +163,7 @@ export interface CreateCacheFn { /** Create a cache with explicit options. */ (options: CacheOptions): TCache; - /** Speed-first cache: no circuit breaker, no retry, minimal L1. */ + /** Speed-first cache: no circuit breaker, retry, or degradation; errors propagate. */ minimal(options: MinimalOptions): TCache; /** Reliability-first cache: circuit breaker + retry + degradation + full L1. */