@neezco/cache 0.1.0 → 0.2.0

package/docs/examples.md

@@ -1,145 +1,40 @@
 # Examples
 
-## API Response Caching
+Learn Neezco Cache through practical examples for common use cases.
 
-Cache API responses so you don't hammer your backend with repeated requests:
-
-```javascript
-const cache = new LocalTtlCache();
-
-async function getUser(userId) {
-  // Check cache first
-  const cached = cache.get(`user:${userId}`);
-  if (cached) return cached;
-
-  // Not in cache or expired, fetch it
-  const user = await fetch(`/api/users/${userId}`).then(r => r.json());
-
-  // Store for 5 minutes, but serve stale for 1 more minute while refreshing
-  cache.set(`user:${userId}`, user, {
-    ttl: 5 * 60 * 1000,
-    staleWindow: 1 * 60 * 1000,
-    tags: `user:${userId}`, // Tag it for easy invalidation
-  });
-
-  return user;
-}
-
-// When a user updates their profile
-function handleUserUpdate(userId) {
-  cache.invalidateTag(`user:${userId}`); // Instantly clear their cache
-}
-```
-
-## Database Query Caching
-
-Speed up repeated database queries:
-
-```javascript
-const cache = new LocalTtlCache({
-  defaultTtl: 2 * 60 * 1000, // 2 minutes
-});
-
-async function getProducts() {
-  const cached = cache.get("products:list");
-  if (cached) return cached;
-
-  const products = await db.query("SELECT * FROM products");
-  cache.set("products:list", products, { tags: "products" });
-  return products;
-}
-
-async function deleteProduct(id) {
-  await db.query("DELETE FROM products WHERE id = ?", [id]);
-  cache.invalidateTag("products"); // Clear all product caches
-}
-
-async function updateProduct(id, data) {
-  await db.query("UPDATE products SET ? WHERE id = ?", [data, id]);
-  cache.invalidateTag("products"); // Clear all product caches
-}
-```
-
-## Graceful Stale Data Serving
-
-Keep serving old data while fetching fresh data in the background:
-
-```javascript
-const cache = new LocalTtlCache();
-
-async function getWeatherWithBackground() {
-  // Fresh for 5 minutes, but we'll serve it for 2 more minutes even if expired
-  cache.set(
-    "weather:NYC",
-    { temp: 72, city: "NYC", fetched: Date.now() },
-    {
-      ttl: 5 * 60 * 1000,
-      staleWindow: 2 * 60 * 1000, // Keep serving for 2 extra minutes while fetching
-    },
-  );
-}
-
-// NEXT skipStale, full entry
-// This is perfect for UIs where slight data staleness is acceptable
-// You can serve old data instantly while refreshing in the background
-async function fetchWeatherIfNeeded(city) {
-  let weather = cache.get(`weather:${city}`);
-
-  // Stale? Fetch fresh data in the background
-  if (!weather) {
-    weather = await fetchWeatherAPI(city);
-    getWeatherWithBackground(city, weather);
-  }
-
-  return weather;
-}
-```
-
-## Tag-Based Invalidation
-
-Group related data and clear it all at once:
+---
 
-```javascript
-const cache = new LocalTtlCache();
+## 📚 Learning Examples
 
-// Store user data with a 'user:456' tag
-cache.set("user:456:name", "Bob", { tags: ["user:456"] });
-cache.set("user:456:email", "bob@example.com", { tags: ["user:456"] });
-cache.set("user:456:preferences", { theme: "dark" }, { tags: ["user:456"] });
+Core concepts for using Neezco Cache effectively.
 
-// User updates their profile - invalidate everything at once
-cache.invalidateTag("user:456");
+### [Tag-Based Invalidation](./examples/tag-based-invalidation.md)
 
-// All three are now expired
-console.log(cache.get("user:456:name")); // undefined
-console.log(cache.get("user:456:email")); // undefined
-console.log(cache.get("user:456:preferences")); // undefined
-```
+Learn how to manage cache invalidation—when to use tags and when to use direct deletion.
 
-## Multiple Tags Per Entry
+**Key concepts:**
 
-An entry can have multiple tags for flexible invalidation:
+- `cache.delete()` vs `cache.invalidateTag()`
+- Single tag vs multiple tags
+- When tags are worth the overhead
+- Performance considerations
 
-```javascript
-cache.set("user:789:profile", profileData, {
-  ttl: 10 * 60 * 1000,
-  tags: ["user:789", "profiles", "public-data"], // Multiple tags
-});
+### [Stale Windows](./examples/stale-window.md)
 
-// Invalidate just the user's data
-cache.invalidateTag("user:789");
+Master stale windows to control memory usage and improve responsiveness.
 
-// Or invalidate all profiles
-cache.invalidateTag("profiles");
+**Key concepts:**
 
-// Or invalidate public data across the entire app
-cache.invalidateTag("public-data");
-```
+- What stale windows are and how they work
+- `purgeStaleOnGet` for tight memory constraints
+- `purgeStaleOnSweep` for efficient batch cleanup
+- Stale-while-revalidate pattern
+- Per-entry stale window customization
 
 ---
 
 ## Navigation
 
-- **[Getting Started](./getting-started.md)** - Back to basics
+- **[Getting Started](./getting-started.md)** - Installation and setup
 - **[API Reference](./api-reference.md)** - All methods explained
 - **[Configuration](./configuration.md)** - Customize your cache

package/docs/getting-started.md

@@ -1,4 +1,4 @@
-# Getting Started with Short‑Live
+# Getting Started with Neezco Cache
 
 ## Installation
 

package/package.json

@@ -1,5 +1,4 @@
 {
-  "version": "0.1.0",
   "name": "@neezco/cache",
   "type": "module",
   "module": "./dist/browser/index.js",
@@ -89,5 +88,6 @@
   "engines": {
     "node": ">=24.12.0",
     "pnpm": ">=10.27.0"
-  }
+  },
+  "version": "0.2.0"
 }