@neezco/cache 0.1.0

package/docs/examples.md

@@ -0,0 +1,145 @@
+# Examples
+
+## API Response Caching
+
+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();
+
+// 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"] });
+
+// User updates their profile - invalidate everything at once
+cache.invalidateTag("user:456");
+
+// 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
+```
+
+## Multiple Tags Per Entry
+
+An entry can have multiple tags for flexible invalidation:
+
+```javascript
+cache.set("user:789:profile", profileData, {
+  ttl: 10 * 60 * 1000,
+  tags: ["user:789", "profiles", "public-data"], // Multiple tags
+});
+
+// Invalidate just the user's data
+cache.invalidateTag("user:789");
+
+// Or invalidate all profiles
+cache.invalidateTag("profiles");
+
+// Or invalidate public data across the entire app
+cache.invalidateTag("public-data");
+```
+
+---
+
+## Navigation
+
+- **[Getting Started](./getting-started.md)** - Back to basics
+- **[API Reference](./api-reference.md)** - All methods explained
+- **[Configuration](./configuration.md)** - Customize your cache

package/docs/getting-started.md

@@ -0,0 +1,86 @@
+# Getting Started with Short‑Live
+
+## Installation
+
+```bash
+npm install @neezco/cache
+# or
+yarn add @neezco/cache
+# or
+pnpm add @neezco/cache
+```
+
+## Recommended Setup Pattern
+
+For better TypeScript autocomplete, define a dedicated cache module:
+
+```typescript
+import LocalTtlCache from "@neezco/cache";
+
+const cacheInstance = new LocalTtlCache({
+  defaultTtl: 5 * 60 * 1000,
+  maxSize: 1_000,
+});
+
+export const cache = cacheInstance;
+```
+
+## Domain‑oriented singleton caches
+
+Instead of a single global cache, you can maintain **one singleton per domain** to avoid key collisions and keep responsibilities clear:
+
+```typescript
+import LocalTtlCache from "@neezco/cache";
+
+// User‑related data
+export const usersCache = new LocalTtlCache({
+  defaultTtl: 5 * 60 * 1000,
+  maxSize: 1_000,
+});
+
+// Asset metadata
+export const assetsCache = new LocalTtlCache({
+  defaultTtl: 10 * 60 * 1000,
+  maxSize: 2_000,
+});
+```
+
+## Minimal Usage Example
+
+```typescript
+import { cache } from "./path-to-your-cache-instance";
+// or
+// import { usersCache } from "./path-to-your-cache-instance";
+// import { assetsCache } from "./path-to-your-cache-instance";
+
+cache.set("user:123", "cached-data", {
+  ttl: 5 * 60 * 1000, // fresh for 5 minutes
+  staleWindow: 2 * 60 * 1000, // may be served stale for 2 more minutes
+  tags: ["user", "user:123"], // tags for later invalidation
+});
+
+console.log("After set:", cache.get("user:123")); // fresh value
+
+setTimeout(
+  () => {
+    console.log(
+      "After TTL but within stale window:",
+      cache.get("user:123"), // stale value
+    );
+
+    cache.invalidateTag("user:123");
+
+    console.log(
+      "After tag invalidation:",
+      cache.get("user:123"), // undefined
+    );
+  },
+  6 * 60 * 1000,
+); // 6 minutes
+```
+
+## Next Steps
+
+- **[Examples](./examples.md)** - Real-world use cases
+- **[API Reference](./api-reference.md)** – Complete method documentation with edge cases
+- **[Configuration](./configuration.md)** – All options explained in detail

package/package.json

@@ -0,0 +1,93 @@
+{
+  "version": "0.1.0",
+  "name": "@neezco/cache",
+  "type": "module",
+  "module": "./dist/browser/index.js",
+  "main": "./dist/node/index.cjs",
+  "types": "./dist/node/index.d.cts",
+  "author": {
+    "name": "Daniel Hernández Ochoa",
+    "url": "https://github.com/DanhezCode"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/neezco/cache#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neezco/cache.git"
+  },
+  "bugs": {
+    "url": "https://github.com/neezco/cache/issues"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/node/index.cjs",
+      "import": "./dist/browser/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "bench": "node --max-old-space-size=4096 bench/minimal-bench.js",
+    "bench:watch": "node --watch-path dist --max-old-space-size=4096 bench/minimal-bench.js",
+    "bench:dev": "pnpm run build && concurrently \"pnpm run build:watch\" \"pnpm run bench:watch\"",
+    "bench:start": "pnpm run build && pnpm run bench",
+    "build": "tsdown",
+    "build:watch": "chokidar \"src/**/*\" -c \"pnpm run build\"",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "format:prettier": "prettier --write .",
+    "format:all": "pnpm lint:fix && pnpm format:prettier",
+    "check": "concurrently \"pnpm format:all\" \"pnpm typecheck\"",
+    "check:all": "concurrently \"pnpm format:all\" \"pnpm typecheck\" \"pnpm test\"",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "husky"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "description": "A simple and efficient in-memory cache for JavaScript and TypeScript projects, designed to provide fast access to frequently used data while minimizing memory usage.",
+  "keywords": [
+    "cache",
+    "in-memory cache",
+    "javascript cache",
+    "typescript cache",
+    "node.js cache",
+    "browser cache",
+    "ttl cache",
+    "cache library",
+    "stale-while-revalidate"
+  ],
+  "devDependencies": {
+    "@commitlint/cli": "20.3.0",
+    "@commitlint/config-conventional": "20.3.0",
+    "@eslint/js": "9.39.2",
+    "@types/bun": "latest",
+    "@types/node": "25.0.6",
+    "@vitest/coverage-v8": "4.0.17",
+    "chokidar-cli": "3.0.0",
+    "concurrently": "9.2.1",
+    "eslint": "9.39.2",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-react": "7.37.5",
+    "globals": "17.0.0",
+    "husky": "9.1.7",
+    "prettier": "3.7.4",
+    "tsdown": "0.19.0",
+    "typescript-eslint": "8.51.0",
+    "vitest": "4.0.17"
+  },
+  "peerDependencies": {
+    "typescript": "5"
+  },
+  "engines": {
+    "node": ">=24.12.0",
+    "pnpm": ">=10.27.0"
+  }
+}