@neezco/cache 0.1.0 → 0.1.1

package/docs/examples/tag-based-invalidation.md

@@ -0,0 +1,183 @@
+# Tag-Based Invalidation
+
+Learn how to manage cache invalidation with tags. **Important:** Use tags only when you truly need group invalidation. For known keys, `cache.delete()` is more efficient.
+
+---
+
+## When to Use Tags vs Direct Deletion
+
+### ✅ Use `cache.delete(key)` when:
+
+- You know the exact key to invalidate
+- You're invalidating a single entry
+- Performance is critical
+- You have few related entries
+
+```javascript
+const cache = new LocalTtlCache();
+
+cache.set("user:123", { name: "Alice" });
+cache.set("user:456", { name: "Bob" });
+
+// If you know the key, just delete it directly
+cache.delete("user:123"); // Single O(1) operation
+```
+
+### 🏷️ Use `invalidateTag()` when:
+
+- You don't know which keys are affected
+- Multiple entries need invalidation together
+- Data relationships are complex
+- Convenience outweighs the performance cost
+
+**Important:** Each tag associated with an entry adds overhead. Use tags strategically, not by default.
+
+---
+
+## Basic Tag Usage
+
+Tags allow you to invalidate multiple entries with one call:
+
+```javascript
+const cache = new LocalTtlCache();
+
+// Store user data with a 'users' tag
+cache.set("user:123:profile", { name: "Alice" }, { tags: ["users"] });
+cache.set("user:123:posts", [...], { tags: ["users"] });
+cache.set("user:123:followers", [...], { tags: ["users"] });
+
+// All three invalidated at once
+cache.invalidateTag("users");
+
+// All three are now expired
+console.log(cache.get("user:123:profile")); // undefined
+console.log(cache.get("user:123:posts")); // undefined
+console.log(cache.get("user:123:followers")); // undefined
+```
+
+---
+
+## Single vs Multiple Tags Per Entry
+
+One entry can have one tag or multiple tags:
+
+```javascript
+// Single tag per entry
+cache.set("product:42", productData, { tags: "products" });
+
+// Multiple tags per entry - can be invalidated multiple ways
+cache.set("post:456", postData, {
+  tags: ["posts", "author:789", "published"],
+});
+
+// Any of these invalidates the post
+cache.invalidateTag("posts"); // All posts
+cache.invalidateTag("author:789"); // Posts by this author
+cache.invalidateTag("published"); // All published content
+```
+
+---
+
+## Designing Your Tag Strategy
+
+Think carefully about the different ways you need to invalidate entries. Use tags that map to your domain concepts:
+
+- **By resource type**: `"users"`, `"posts"`, `"products"`
+- **By relationship**: `"author:789"`, `"follows:123"`, `"category:electronics"`
+- **By state**: `"published"`, `"archived"`, `"pending"`
+- **By context**: `"admin-only"`, `"premium-features"`, `"exports"`
+
+Example: A blog post that belongs to multiple groups:
+
+```javascript
+cache.set("post:456", postData, {
+  tags: [
+    "posts", // Invalidate all posts
+    "author:789", // Invalidate by author
+    "category:technology", // Invalidate by category
+    "published", // Invalidate by state
+  ],
+});
+
+// When the author deletes their account
+cache.invalidateTag("author:789");
+
+// When you want to hide all published content
+cache.invalidateTag("published");
+
+// When the category is renamed
+cache.invalidateTag("category:technology");
+```
+
+---
+
+## Real-World Pattern: User Data
+
+Let's look at a realistic scenario with multiple user-related caches:
+
+```javascript
+const cache = new LocalTtlCache({ defaultTtl: 5 * 60 * 1000 });
+
+// ❌ AVOID THIS - Too many tags per entry
+cache.set("user:123:profile", profileData, {
+  tags: ["users", "user:123", "profiles", "public-data", "profiles:basic"],
+});
+
+// ✅ BETTER - Use tags only for necessary group invalidations
+cache.set("user:123:profile", profileData, {
+  tags: ["users"], // Single tag for bulk operations
+});
+
+// ✅ BEST - Use direct deletion when you know the key
+if (userDeleted) {
+  cache.delete("user:123:profile"); // Direct, efficient
+  cache.delete("user:123:posts");
+  cache.delete("user:123:followers");
+
+  // Use tags only for complex relationships
+  cache.invalidateTag("users"); // Clear all user lists
+}
+```
+
+Compare the approaches:
+
+```javascript
+// Direct deletion - efficient when you know keys
+cache.delete("user:123:profile"); // 1 operation, no tag overhead
+
+// Tag invalidation - convenient for groups
+cache.invalidateTag("users"); // Invalidates all user-related entries
+// But processes every entry with that tag
+
+// Mixed approach - best of both worlds
+cache.delete("user:123:profile"); // Known entry
+cache.invalidateTag("users"); // Group operations only
+```
+
+---
+
+## Performance Consideration
+
+Each tag on an entry adds a small memory and lookup cost. Keep tags minimal:
+
+```javascript
+// ❌ Avoid excessive tags
+cache.set("data", value, {
+  tags: ["all", "group1", "group2", "group3", "special"],
+});
+
+// ✅ Use only tags you'll actually invalidate
+cache.set("data", value, {
+  tags: ["group1"], // Only if you'll use cache.invalidateTag("group1")
+});
+
+// ✅ Prefer direct deletion for single entries
+cache.delete("key");
+```
+
+---
+
+## Next
+
+- **[Stale Windows](./stale-window.md)** - Control memory with graceful expiration
+- **[Back to Examples](../examples.md)**

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,8 +1,7 @@
 {
-  "version": "0.1.0",
   "name": "@neezco/cache",
   "type": "module",
-  "module": "./dist/browser/index.js",
+  "module": "./dist/node/index.mjs",
   "main": "./dist/node/index.cjs",
   "types": "./dist/node/index.d.cts",
   "author": {
@@ -21,7 +20,7 @@
   "exports": {
     ".": {
       "require": "./dist/node/index.cjs",
-      "import": "./dist/browser/index.js"
+      "import": "./dist/node/index.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -89,5 +88,6 @@
   "engines": {
     "node": ">=24.12.0",
     "pnpm": ">=10.27.0"
-  }
+  },
+  "version": "0.1.1"
 }