feat: intent-based cache API (createCache.io, .minimal, .production, .secure)

[27Bslash6]

Summary

• Adds 4 intent-based factory functions to createCache for declarative cache configuration
• createCache.minimal() — speed-first, no circuit breaker or retry
• createCache.production() — reliability-first with circuit breaker (threshold: 5), retry, degradation
• createCache.secure() — production + AES-256-GCM encryption (masterKey from options or CACHEKIT_MASTER_KEY)
• createCache.io() — SaaS backend via cachekit.io (apiKey from options or CACHEKIT_API_KEY)

Each factory builds CacheOptions and delegates to createCache() — thin wrappers, no new abstraction.

Closes #1

Files Changed

File	Change
packages/cachekit/src/intents.ts	New — intent types, factory functions, CreateCacheFn interface
packages/cachekit/src/intents.test.ts	New — 26 tests (validation, defaults, overrides, env var resolution)
packages/cachekit/src/index.ts	Modified — re-exports createCache from intents module

Test plan

• All 26 new intent tests pass
• All 456 existing tests pass (no regressions)
• TypeScript types clean (tsc --noEmit)
• ESLint clean
• Build clean (ESM + CJS)
• CI passes

Summary by CodeRabbit

• New Features

  • Added intent-based factory methods (minimal, production, secure, io) for one-call cache setup and exported additional TypeScript configuration types.

• Tests

  • Added comprehensive tests covering intent-based cache configuration, defaults, overrides, and credential validation.

• Documentation

  • Updated docs and quick-start to showcase intent-based API and examples for different deployment scenarios.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Free

Run ID: fe8b5719-6b06-43ab-998c-6e88d3c4a5eb

📥 Commits

Reviewing files that changed from the base of the PR and between 73c020b and 118b642.

📒 Files selected for processing (5)

• README.md
• packages/cachekit/README.md
• packages/cachekit/src/index.ts
• packages/cachekit/src/intents.test.ts
• packages/cachekit/src/intents.ts

✅ Files skipped from review due to trivial changes (2)

• README.md
• packages/cachekit/src/intents.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/cachekit/src/index.ts
• packages/cachekit/src/intents.test.ts

---

📝 Walkthrough

Walkthrough

Adds an intent-based API for createCache exposing minimal, production, secure, and io factory methods, moves the main createCache export to the new intents module, and adds related exported types; includes a comprehensive test suite and README updates.

Changes

Cohort / File(s)	Summary
Export Reorganization packages/cachekit/src/index.ts	createCache now re-exported from ./intents.js; added type-only exports CreateCacheFn, MinimalOptions, ProductionOptions, SecureOptions, IOOptions.
Intent API Implementation packages/cachekit/src/intents.ts	New module implementing an intent-augmented createCache with methods minimal, production, secure, io; defines intent-specific option interfaces, merges reliability defaults, enforces credential requirements for secure/io, and attaches intent methods to the base factory.
Intent API Tests packages/cachekit/src/intents.test.ts	New Vitest suite mocking underlying cache creation to validate all intent methods: defaults, overrides, L1 behavior, reliability, metrics, encryption/masterKey handling, API key/saas config, and ConfigurationError cases.
Docs / Examples README.md, packages/cachekit/README.md	Documentation updated to describe intents.ts, adjust architecture wording, Quick Start now uses createCache.production({ url }), and adds Intent-Based API examples and mapping table; retains manual createCache(options) documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 I stitched four paths for caches to run,
Minimal, production, secure, and one for SaaS fun—
Keys and defaults snug, options in line,
I hop through the code and leave trails that shine ✨

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}