Skip to content

feat(core): add per-request cache TTL and override options#3

Open
Andrchiamus wants to merge 3 commits intoAllyMurray:mainfrom
Andrchiamus:feat/per-request-cache-ttl
Open

feat(core): add per-request cache TTL and override options#3
Andrchiamus wants to merge 3 commits intoAllyMurray:mainfrom
Andrchiamus:feat/per-request-cache-ttl

Conversation

@Andrchiamus
Copy link

Summary

  • Add cacheTTL and cacheOverrides options to get() for per-request cache configuration, following the same override pattern used by retry
  • Extract CacheOverrideOptions into a reusable exported interface (previously inline in HttpClientOptions)
  • Shallow-merge semantics: per-request fields override constructor fields, unspecified fields fall back to constructor defaults
  • Threaded through all cache paths: fresh store, 304 refresh, SWR background revalidation, ignoreNoStore, ignoreNoCache

Usage

// Override TTL for a specific request
await client.get(url, { cacheTTL: 120 });

// Override cache behavior for a specific request
await client.get(url, {
  cacheOverrides: { ignoreNoStore: true, minimumTTL: 60 },
});

// Combine both
await client.get(url, {
  cacheTTL: 300,
  cacheOverrides: { maximumTTL: 600 },
});

Test plan

  • cacheTTL overrides defaultCacheTTL (no cache headers → uses request TTL)
  • Per-request minimumTTL overrides constructor minimumTTL
  • Per-request maximumTTL overrides constructor maximumTTL
  • Per-request ignoreNoStore: true forces caching despite no-store
  • Per-request ignoreNoCache: true skips revalidation
  • Shallow merge — unspecified per-request fields fall back to constructor
  • Per-request overrides apply on 304 refresh path
  • Per-request cacheTTL applies in backgroundRevalidate (SWR path)
  • No per-request options → unchanged constructor behavior (regression)
  • TypeScript compiles cleanly
  • All 265 existing + new tests pass

🤖 Generated with Claude Code

Andrew Carmichael and others added 3 commits February 16, 2026 16:06
Allow callers to override defaultCacheTTL and cacheOverrides on a
per-request basis via get() options, following the same pattern already
used for retry configuration.

- Extract CacheOverrideOptions into a reusable exported interface
- Add cacheTTL and cacheOverrides to HttpClientContract.get() options
- Add resolveCacheConfig() for shallow-merging per-request over constructor
- Thread resolved config through all cache paths (store, 304, SWR, ignoreNoStore, ignoreNoCache)
- 9 new tests covering all per-request override scenarios

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The store-dynamodb#test override stripped the default test task's
dependsOn, causing it to run before @http-client-toolkit/core was
built. This resulted in a "Failed to resolve entry" error in CI.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ptions

- Remove unused fallback to this.options.cacheOverrides in clampTTL
  (all call sites now pass overrides explicitly via resolveCacheConfig)
- Add cacheTTL, cacheOverrides, headers, and retry to the README
  request options table so all get() options are discoverable

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant