Documentation rework DO NOT MERGE

docs/.vitepress/config.mts

@@ -249,9 +249,10 @@ export default defineConfig({
     ],
 
     nav: [
-      { text: 'Guide', link: '/guide' },
-      { text: 'Config', link: '/config' },
-      { text: 'Others', link: '/others/license' },
+      { text: 'Journey', link: '/journey/' },
+      { text: 'Concepts', link: '/concepts/' },
+      { text: 'API', link: '/api/' },
+      { text: 'Examples', link: '/examples/' },
       {
         text: VERSION,
         items: [
@@ -293,7 +294,96 @@ export default defineConfig({
         target: '_blank'
       },
       {
-        text: 'Guide',
+        text: 'User Journey',
+        collapsed: false,
+        items: [
+          { text: 'Overview', link: '/journey/' },
+          { text: 'Installation', link: '/journey/installation' },
+          { text: 'Your First Cache', link: '/journey/first-cache' },
+          { text: 'Checking Cache', link: '/journey/checking-cache' },
+          { text: 'Caching POST', link: '/journey/caching-post-requests' },
+          { text: 'Persistent Storage', link: '/journey/persistent-storage' },
+          { text: 'Custom Storage', link: '/journey/custom-storage' },
+          { text: 'Invalidate on Mutation', link: '/journey/invalidate-on-mutation' },
+          { text: 'Preventing Stale Data', link: '/journey/preventing-stale-data' },
+          { text: 'Debugging Issues', link: '/journey/debugging-issues' },
+          { text: 'Production Checklist', link: '/journey/production-checklist' }
+        ]
+      },
+      {
+        text: 'Concepts',
+        collapsed: true,
+        items: [
+          { text: 'Overview', link: '/concepts/' },
+          { text: 'How It Works', link: '/concepts/how-it-works' },
+          { text: 'Request Lifecycle', link: '/concepts/request-lifecycle' },
+          { text: 'Storage States', link: '/concepts/storage-states' },
+          { text: 'Request Deduplication', link: '/concepts/request-deduplication' },
+          { text: 'HTTP Headers', link: '/concepts/http-caching-headers' },
+          { text: 'Cache Keys', link: '/concepts/cache-keys' },
+          { text: 'Storage Architecture', link: '/concepts/storage-architecture' },
+          { text: 'Header Interpretation', link: '/concepts/header-interpretation' },
+          { text: 'Stale Revalidation', link: '/concepts/stale-revalidation' },
+          { text: 'Vary Header', link: '/concepts/vary-header-handling' },
+          { text: 'Performance Model', link: '/concepts/performance-model' }
+        ]
+      },
+      {
+        text: 'API Reference',
+        collapsed: true,
+        items: [
+          { text: 'Overview', link: '/api/' },
+          {
+            text: 'Core API',
+            items: [
+              { text: 'setupCache()', link: '/api/setup-cache' },
+              { text: 'Request Config', link: '/api/request-config' },
+              { text: 'Response Object', link: '/api/response-object' }
+            ]
+          },
+          {
+            text: 'Storage',
+            items: [
+              { text: 'Storage Interface', link: '/api/storage-interface' },
+              { text: 'Memory Storage', link: '/api/memory-storage' },
+              { text: 'Web Storage', link: '/api/web-storage' },
+              { text: 'Build Storage', link: '/api/build-storage' }
+            ]
+          }
+        ]
+      },
+      {
+        text: 'Examples',
+        collapsed: true,
+        items: [
+          { text: 'Overview', link: '/examples/' },
+          { text: 'Basic Setup', link: '/examples/basic-setup' },
+          { text: 'Opt-in Cache', link: '/examples/opt-in-cache' },
+          { text: 'Redis Storage', link: '/examples/redis-storage' },
+          { text: 'IndexedDB Storage', link: '/examples/indexeddb-storage' },
+          { text: 'React Integration', link: '/examples/react-integration' },
+          { text: 'Vue Integration', link: '/examples/vue-integration' },
+          { text: 'Next.js SSR', link: '/examples/nextjs-ssr' },
+          { text: 'Testing', link: '/examples/testing-cached-code' }
+        ]
+      },
+      {
+        text: 'Troubleshooting',
+        collapsed: true,
+        items: [
+          { text: 'Overview', link: '/troubleshooting/' },
+          { text: 'Cache Not Working', link: '/troubleshooting/cache-not-working' },
+          { text: 'Stale Data Served', link: '/troubleshooting/stale-data-served' },
+          { text: 'Memory Leaks', link: '/troubleshooting/memory-leaks' },
+          { text: 'Cache Poisoning', link: '/troubleshooting/cache-poisoning' },
+          { text: 'CORS Errors', link: '/troubleshooting/cors-errors' },
+          { text: 'Concurrent Issues', link: '/troubleshooting/concurrent-issues' },
+          { text: 'TypeScript Errors', link: '/troubleshooting/typescript-errors' }
+        ]
+      },
+      {
+        text: 'Legacy Guide',
+        collapsed: true,
         items: [
           { text: 'Introduction', link: '/guide' },
           { text: 'Getting Started', link: '/guide/getting-started' },
@@ -306,17 +396,15 @@ export default defineConfig({
         ]
       },
       {
-        text: 'Config',
+        text: 'Resources',
+        collapsed: true,
         items: [
-          { text: 'Global Configuration', link: '/config' },
-          { text: 'Request Specifics', link: '/config/request-specifics' },
-          { text: 'Response Object', link: '/config/response-object' }
+          { text: 'MIT License', link: '/others/license' },
+          { text: 'Changelog', link: '/others/changelog' },
+          { text: 'llms.txt', link: '/llms.txt' },
+          { text: 'llms-full.txt', link: `/${llmsFullLink}` }
         ]
-      },
-      { text: 'MIT License', link: '/others/license' },
-      { text: 'Changelog', link: '/others/changelog' },
-      { text: 'llms.txt', link: '/llms.txt' },
-      { text: 'llms-full.txt', link: `/${llmsFullLink}` }
+      }
     ]
   },
 

docs/src/api/build-storage.md

@@ -0,0 +1,3 @@
+# build storage
+
+API reference content coming soon.

docs/src/api/cache-predicate.md

@@ -0,0 +1,3 @@
+# cache predicate
+
+API reference content coming soon.

docs/src/api/cache-properties.md

@@ -0,0 +1,3 @@
+# cache properties
+
+API reference content coming soon.

docs/src/api/header-interpreter.md

@@ -0,0 +1,3 @@
+# header interpreter
+
+API reference content coming soon.

docs/src/api/index.md

@@ -0,0 +1,67 @@
+# API Reference
+
+Complete technical reference for all axios-cache-interceptor configuration options, interfaces, and types.
+
+## Core API
+
+The main functions and configuration options:
+
+- [setupCache()](./setup-cache.md) - Initialize caching on an Axios instance
+- [Request Config](./request-config.md) - Per-request cache configuration
+- [Response Object](./response-object.md) - Properties available on cached responses
+- [Cache Properties](./cache-properties.md) - All available CacheProperties options
+
+## Storage
+
+Storage adapter interfaces and implementations:
+
+- [Storage Interface](./storage-interface.md) - AxiosStorage interface specification
+- [buildMemoryStorage()](./memory-storage.md) - In-memory storage adapter
+- [buildWebStorage()](./web-storage.md) - localStorage/sessionStorage adapter
+- [buildStorage()](./build-storage.md) - Create custom storage adapters
+
+## Advanced Interfaces
+
+Advanced customization interfaces:
+
+- [Key Generator](./key-generator.md) - Custom request ID generation
+- [Header Interpreter](./header-interpreter.md) - Custom header interpretation
+- [Cache Predicate](./cache-predicate.md) - Custom cacheability tests
+- [TypeScript Types](./typescript-types.md) - Complete type reference
+
+## Quick Reference
+
+### Default Values
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `ttl` | `300000` (5 min) | Time to live in milliseconds |
+| `methods` | `['get', 'head']` | Cacheable HTTP methods |
+| `interpretHeader` | `true` | Parse Cache-Control headers |
+| `etag` | `true` | ETag validation |
+| `modifiedSince` | `false` | If-Modified-Since header |
+| `vary` | `true` | Vary header handling |
+| `staleIfError` | `true` | Return stale on error |
+| `enabled` | `true` | Cache enabled |
+
+### Common Patterns
+
+```ts
+// Basic setup
+const axios = setupCache(Axios.create());
+
+// Custom TTL
+axios.get('/api/data', { cache: { ttl: 60000 } });
+
+// Disable cache for specific request
+axios.get('/api/realtime', { cache: { enabled: false } });
+
+// Cache POST requests
+setupCache(instance, { methods: ['get', 'post'] });
+```
+
+## Related Resources
+
+- [User Journey](/journey/) - Learn how to use these APIs
+- [Concepts](/concepts/) - Understand how they work
+- [Examples](/examples/) - See them in action

docs/src/api/key-generator.md

@@ -0,0 +1,3 @@
+# key generator
+
+API reference content coming soon.

docs/src/api/memory-storage.md

@@ -0,0 +1,3 @@
+# memory storage
+
+API reference content coming soon.

docs/src/api/request-config.md

@@ -0,0 +1,3 @@
+# request config
+
+API reference content coming soon.

docs/src/api/response-object.md

@@ -0,0 +1,3 @@
+# response object
+
+API reference content coming soon.

docs/src/api/setup-cache.md

@@ -0,0 +1,3 @@
+# setup cache
+
+API reference content coming soon.

docs/src/api/storage-interface.md

@@ -0,0 +1,3 @@
+# storage interface
+
+API reference content coming soon.

docs/src/api/typescript-types.md

@@ -0,0 +1,3 @@
+# typescript types
+
+API reference content coming soon.

docs/src/api/web-storage.md

@@ -0,0 +1,3 @@
+# web storage
+
+API reference content coming soon.

docs/src/concepts/cache-keys.md

@@ -0,0 +1,122 @@
+# Cache Keys
+
+How request IDs are generated and used as cache keys.
+
+## Default Generation
+
+By default, cache keys are generated from:
+
+1. HTTP method (lowercase)
+2. Base URL (normalized)
+3. URL path (normalized)
+4. Query parameters
+5. Request body (for POST/PUT)
+6. Vary headers (if applicable)
+
+### Example
+
+```ts
+// Request
+axios.get('https://api.example.com/users', {
+  params: { page: 1, limit: 10 }
+});
+
+// Generated ID considers:
+// - method: "get"
+// - baseURL: "https://api.example.com"
+// - url: "/users"
+// - params: { page: 1, limit: 10 }
+// - data: undefined
+
+// Result: "1847392847" (32-bit hash)
+```
+
+## Custom IDs
+
+Specify your own cache key:
+
+```ts
+await axios.get('/api/users', {
+  id: 'users-list'
+});
+
+// Cache key is exactly "users-list"
+```
+
+Benefits:
+- Predictable keys
+- Easy invalidation
+- Human-readable
+- No collision risk
+
+## Hash Collisions
+
+The default generator uses 32-bit hashing:
+
+- Fast and efficient
+- Collision risk at ~77,000 unique requests
+- Acceptable for most use cases
+
+For large-scale applications with persistent storage, use custom IDs or stronger hashing.
+
+## Custom Generator
+
+Implement your own key generation:
+
+```ts
+import { setupCache, buildKeyGenerator } from 'axios-cache-interceptor';
+import { createHash } from 'crypto';
+
+const customGenerator = buildKeyGenerator((request) => {
+  // Use SHA-256 for no collisions
+  const str = JSON.stringify({
+    method: request.method,
+    url: request.url,
+    params: request.params,
+    data: request.data
+  });
+
+  return createHash('sha256').update(str).digest('hex');
+});
+
+const axios = setupCache(instance, {
+  generateKey: customGenerator
+});
+```
+
+## Vary Header Impact
+
+When server sends Vary header, those headers are included in the key:
+
+```ts
+// Request 1
+await axios.get('/api/profile', {
+  headers: { authorization: 'Bearer token-A' }
+});
+// Server responds: Vary: Authorization
+// Key includes: url + method + {authorization: 'Bearer token-A'}
+
+// Request 2
+await axios.get('/api/profile', {
+  headers: { authorization: 'Bearer token-B' }
+});
+// Different key due to different Authorization header
+```
+
+## Retrieving the ID
+
+Get the cache key from the response:
+
+```ts
+const response = await axios.get('/api/users');
+console.log(response.id); // "1847392847"
+
+// Use for manual cache management
+await axios.storage.remove(response.id);
+```
+
+## Next Steps
+
+- [Vary Header Handling](/concepts/vary-header-handling.md) - Headers in cache keys
+- [Request Deduplication](/concepts/request-deduplication.md) - ID matching
+- [Key Generator API](/api/key-generator.md) - Custom generation