@neezco/cache 0.1.0 → 0.2.0

package/docs/api-reference.md

@@ -14,7 +14,13 @@ Creates a new cache instance.
 
 **Parameters:**
 
-- `options` (optional) - Configuration object. See [Configuration Guide](./configuration.md) for details.
+- `options` (optional) - Configuration object. See [Configuration Guide](./configuration.md) for details, including:
+  - `defaultTtl` - Default entry lifetime
+  - `defaultStaleWindow` - Default stale serving window
+  - `maxSize` - Maximum number of entries allowed
+  - `maxMemorySize` - Maximum memory usage (MB) allowed
+  - `purgeStaleOnGet` / `purgeStaleOnSweep` - Stale entry handling
+  - `onExpire` / `onDelete` - Lifecycle callbacks
 
 ---
 
@@ -33,7 +39,7 @@ set(
     staleWindow?: number;
     tags?: string | string[];
   }
-): void
+): boolean
 ```
 
 **Parameters:**
@@ -44,16 +50,20 @@ set(
 - `options.staleWindow` - How long to serve stale data after expiration (in milliseconds)
 - `options.tags` - One or more tags for group invalidation
 
-**Returns:** Nothing (void)
+**Returns:** `true` if the entry was set or updated, `false` if rejected due to limits or invalid input
 
 **Example:**
 
 ```javascript
-cache.set("user:123", "cached-value", {
+const success = cache.set("user:123", "cached-value", {
   ttl: 5 * 60 * 1000, // Expires in 5 minutes
   staleWindow: 1 * 60 * 1000, // Serve stale for 1 more minute
   tags: ["user:123"], // Tag for invalidation
 });
+
+if (!success) {
+  console.log("Entry rejected: cache at maxSize or maxMemorySize limit");
+}
 ```
 
 **Edge Cases:**
@@ -64,6 +74,9 @@ cache.set("user:123", "cached-value", {
 - If `staleWindow` is larger than `ttl`, the entry can be served as stale for longer than it was fresh
 - Tags are optional; only necessary for group invalidation via `invalidateTag()`
 - Setting a key to `null` is valid; calling `cache.set("user:123", null)` overwrites any previous value and stores `null` as the new value
+- Returns `false` if value is `undefined` (existing value remains untouched if it exists)
+- Returns `false` if new entry would exceed [`maxSize`](./configuration.md#maxsize-number) limit, but updating existing keys always succeeds
+- Returns `false` if new entry would exceed [`maxMemorySize`](./configuration.md#maxmemorysize-number) limit, but updating existing keys always succeeds (not supported in browsers)
 
 ---
 
@@ -210,17 +223,19 @@ console.log(cache.size); // 0
 
 ---
 
-### `invalidateTag(tags, asStale)`
+### `invalidateTag(tags, options)`
 
 Mark all entries with one or more tags as expired (or stale, if requested).
 
 ```typescript
 invalidateTag(
   tags: string | string[],
-  options: { asStale?: boolean }
+  options?: InvalidateTagOptions
 ): void
 ```
 
+Options type: `InvalidateTagOptions` — an extensible object with `asStale?: boolean`.
+
 **Parameters:**
 
 - `tags` - A single tag (string) or array of tags to invalidate

package/docs/configuration.md

@@ -49,7 +49,7 @@ cache.set("data", { value: "old" });
 
 ### `maxSize` (number)
 
-The maximum number of entries the cache can hold. When the limit is reached, the cache automatically cleans up expired entries and removes less-used items.
+The maximum number of entries the cache can hold. When the limit is reached, new entries are ignored while existing keys can still be updated.
 
 - **Type**: `number`
 - **Default**: `Infinite` (no limit)
@@ -60,9 +60,46 @@ const cache = new LocalTtlCache({
   maxSize: 10_000, // Only keep up to 10,000 items
 });
 
-// When you exceed 10_000 items new entries are ignored
+cache.set("key1", "value1"); // OK - within limit
+cache.set("key10001", "value"); // Ignored - would exceed maxSize
+cache.set("key1", "updated"); // OK - updating existing key is always allowed
 ```
 
+**Edge Cases:**
+
+- New entries are rejected silently when maxSize is reached
+- Updating existing keys is **always allowed**, regardless of maxSize limit
+- Value set to `Infinity` or `0` means unlimited entries
+
+---
+
+### `maxMemorySize` (number)
+
+The maximum memory size in MB the cache can consume. When the limit is reached, new entries are ignored while existing keys can still be updated.
+
+- **Type**: `number` (in megabytes)
+- **Default**: `Infinite` (no limit)
+- **Example**: `maxMemorySize: 512` (512 MB)
+- **Note**: Only enforced in Node.js environments (browser environments ignore this setting)
+
+```javascript
+const cache = new LocalTtlCache({
+  maxMemorySize: 512, // Cache uses at most 512 MB
+});
+
+cache.set("key1", largeObject); // OK - within memory limit
+cache.set("key2", anotherLargeObject); // May be ignored if total memory would exceed 512 MB
+cache.set("key1", "updated"); // OK - updating existing key is allowed
+```
+
+**Edge Cases:**
+
+- New entries are rejected silently when memory limit is reached
+- Updating existing keys is **always allowed**, regardless of memory limit
+- Measured via Node.js `process.memoryUsage().rss`
+- Value set to `Infinity` or `0` means unlimited memory
+- **Not supported in browser environments** — this setting is ignored when running in a browser
+
 ### `purgeStaleOnGet` (boolean)
 
 Whether to delete stale entries immediately after retrieving them.
@@ -84,6 +121,8 @@ cache.set("data", "value");
 // Subsequent calls return undefined
 ```
 
+---
+
 ### `purgeStaleOnSweep` (boolean)
 
 Whether to delete stale entries during automatic cleanup (sweep) operations.
@@ -105,7 +144,7 @@ const cache = new LocalTtlCache({
 
 ### Callbacks
 
-Short-Live supports callbacks for monitoring cache operations:
+Neezco Cache supports callbacks for monitoring cache operations:
 
 #### `onExpire(key, value)`
 

package/docs/contributing/code-style.md

@@ -0,0 +1,40 @@
+# Code Style Guidelines
+
+This project prioritizes **functional programming with controlled mutability for maximum performance**.
+
+## Core Principles
+
+- **Pure Functions First**: All business logic implemented as pure functions without side effects
+- **One Function = One Responsibility**: Keep functions small and focused on a single task
+- **Dependency Injection**: Inject dependencies when they can change or have multiple implementations
+- **Explicit Behavior**: Functions only do what they promise, with no hidden state or implicit behavior
+- **Strict Type Safety**: Avoid `any` and use precise, verifiable TypeScript types
+- **Controlled Mutability**: State mutations are explicit and localized, never global
+- **Testable in Isolation**: Functions must be testable without global dependencies
+
+## Documentation Standards
+
+- Use **advanced TSDoc** for all functions: document purpose, parameters, return types, and edge cases
+- Adjust documentation level to actual complexity
+- Document technical or internal information with inline comments or TSDoc
+- Update `/doc` directory only for externally relevant or highly complex features
+- Keep explanations direct, user-focused, and free of internal implementation details
+
+### Example
+
+```typescript
+/**
+ * Validates if an entry is fresh and can be used.
+ * @param state - The cache state.
+ * @param entry - The cache entry to validate.
+ * @param now - The current timestamp.
+ * @returns True if the entry is fresh, false otherwise.
+ */
+export const isFresh = (state: CacheState, entry: CacheEntry, now: number): boolean => {
+  return entry[0][1] > now;
+};
+```
+
+---
+
+**Remember:** Keep it simple, keep it functional, keep it tested.

package/docs/contributing/issues.md

@@ -0,0 +1,30 @@
+# Opening Issues
+
+Thank you for helping improve Neezco Cache!
+
+## 🐛 Bug Reports
+
+When reporting a bug, please include:
+
+- **Clear description** of the issue
+- **Steps to reproduce** the problem
+- **Expected vs actual behavior**
+- **Your environment**: Node.js version, OS, etc.
+
+**[Open a bug report →](https://github.com/neezco/cache/issues)**
+
+## ✨ Feature Requests
+
+When requesting a feature, please:
+
+- **Describe** what you want to achieve
+- **Explain why** this feature would be useful
+- **Provide examples** or use cases
+
+**[Open a feature request →](https://github.com/neezco/cache/issues)**
+
+---
+
+## Questions?
+
+Feel free to open a discussion on GitHub. We're happy to help!

package/docs/contributing/project-structure.md

@@ -0,0 +1,35 @@
+# Project Structure
+
+Neezco Cache follows a **functional, domain-driven architecture**.
+
+## Directory Layout
+
+```
+src/
+├── index.ts              # Public API exports and LocalTtlCache class
+├── types.ts              # Type definitions
+├── defaults.ts           # Default configuration values
+├── cache/                # Core caching operations
+│   ├── set.ts            # Set/update cache entries
+│   ├── get.ts            # Get entries (with expiration/stale checks)
+│   ├── delete.ts         # Delete entries
+│   └── ...
+├── sweep/                # Automatic cleanup operations
+│   ├── sweep.ts          # Main sweep loop
+│   └── ...               # Optimization utilities
+└── utils/                # Utilities (memory monitoring, etc.)
+    └── ...
+```
+
+## Core Philosophy
+
+- **Pure Functions First**: All business logic is implemented as pure functions
+- **Dependency Injection**: Dependencies that can change are injected
+- **Simple & Testable**: Each function has a single responsibility
+- **Type Safety**: Strict TypeScript typing throughout
+
+The [`LocalTtlCache`](../../src/index.ts) class is a convenience wrapper around these pure functions. It provides object-oriented API while maintaining functional code inside.
+
+---
+
+**When adding new functionality:** Follow the domain structure. Create functions in the appropriate `src/` subdirectory.

package/docs/contributing/scripts.md

@@ -0,0 +1,38 @@
+# Available Scripts
+
+Use these scripts during development:
+
+## Building
+
+| Script             | Purpose                                        |
+| ------------------ | ---------------------------------------------- |
+| `pnpm build`       | Transpiles TypeScript to JavaScript            |
+| `pnpm build:watch` | Watches for changes and rebuilds automatically |
+
+## Linting & Formatting
+
+| Script                 | Purpose                                   |
+| ---------------------- | ----------------------------------------- |
+| `pnpm lint`            | Runs ESLint to detect code quality issues |
+| `pnpm lint:fix`        | Automatically fixes ESLint problems       |
+| `pnpm format:prettier` | Formats the entire codebase with Prettier |
+| `pnpm format:all`      | Runs linting fixes and Prettier together  |
+
+## Type Checking & Validation
+
+| Script           | Purpose                                                                  |
+| ---------------- | ------------------------------------------------------------------------ |
+| `pnpm typecheck` | Runs TypeScript type checker without emitting files                      |
+| `pnpm check:all` | **Run before committing.** Runs formatting and type checking in parallel |
+
+## Testing
+
+| Script               | Purpose                                              |
+| -------------------- | ---------------------------------------------------- |
+| `pnpm test`          | Runs the test suite once                             |
+| `pnpm test:watch`    | Runs tests in watch mode (useful during development) |
+| `pnpm test:coverage` | Generates test coverage reports                      |
+
+---
+
+**Before committing:** Always run `pnpm check:all` to ensure everything passes.

package/docs/contributing/setup.md

@@ -0,0 +1,49 @@
+# Setting Up Your Environment
+
+## Prerequisites
+
+This repository comes pre-configured with:
+
+- **ESLint** for linting
+- **Prettier** for formatting
+- **Husky** for Git hooks
+- **Conventional Commits** validation
+- **Type checking** and **test scripts**
+
+## Installation
+
+1. **Fork and clone** the repository:
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/cache.git
+   cd cache
+   ```
+
+2. **Add upstream repository**:
+
+   ```bash
+   git remote add upstream https://github.com/neezco/cache.git
+   ```
+
+3. **Install dependencies**:
+
+   ```bash
+   pnpm install
+   ```
+
+4. **Initialize Husky** for Git hooks:
+
+   ```bash
+   pnpm prepare
+   ```
+
+## What Husky Does
+
+Once initialized, Husky automatically validates your changes:
+
+| Hook           | What it runs                        |
+| -------------- | ----------------------------------- |
+| **Pre-commit** | ESLint, Prettier, and type checking |
+| **Pre-push**   | Full test suite                     |
+
+You're ready to start contributing!

package/docs/contributing/workflow.md

@@ -0,0 +1,71 @@
+# Contribution Workflow
+
+## 1. Create a Feature Branch
+
+```bash
+git checkout -b feat/your-feature-name
+```
+
+Use conventional commit types for branch names:
+
+- `feat/` for features
+- `fix/` for bug fixes
+- `docs/` for documentation
+- `refactor/` for refactoring
+
+## 2. Make Your Changes
+
+Follow the [Code Style Guidelines](code-style.md).
+
+## 3. Verify Your Work
+
+Run the full check suite before committing:
+
+```bash
+pnpm check:all
+```
+
+This runs formatting, linting, and type checking in parallel.
+
+## 4. Commit with Conventional Commits
+
+```bash
+git commit -m "feat: add your feature"
+```
+
+Husky validates your commit message. Use these types:
+
+| Type        | Purpose                                   |
+| ----------- | ----------------------------------------- |
+| `feat:`     | A new feature                             |
+| `fix:`      | A bug fix                                 |
+| `docs:`     | Documentation changes                     |
+| `style:`    | Formatting only (no code changes)         |
+| `refactor:` | Code refactoring without behavior changes |
+| `test:`     | Adding or updating tests                  |
+| `chore:`    | Maintenance tasks (configs, tooling, CI)  |
+
+### Examples
+
+```bash
+git commit -m "feat: add has method to LocalTtlCache"
+git commit -m "fix: prevent expired entries from being returned"
+git commit -m "test: add test coverage for stale window behavior"
+git commit -m "docs: update API reference"
+```
+
+## 5. Push and Create a Pull Request
+
+```bash
+git push origin feat/your-feature-name
+```
+
+Then create a pull request on GitHub:
+
+- Reference any related issues
+- Provide a clear description of your changes
+- Ensure all tests and checks pass
+
+---
+
+**That's it!** The maintainers will review your PR soon.

package/docs/examples/stale-window.md

@@ -0,0 +1,66 @@
+# Stale Windows
+
+Understand how to use stale windows to control memory usage and improve performance gracefully.
+
+---
+
+## What is a Stale Window?
+
+A stale window is a period after an entry expires where it can still be served. Instead of immediately removing expired data, Neezco Cache allows you to keep serving it while managing memory:
+
+```javascript
+const cache = new LocalTtlCache({
+  defaultTtl: 5 * 60 * 1000, // Fresh for 5 minutes
+  defaultStaleWindow: 2 * 60 * 1000, // Serve stale for 2 more minutes
+});
+
+cache.set("data", "current value");
+
+// Minutes 0-5: data is fresh
+console.log(cache.get("data")); // "current value"
+
+// Minutes 5-7: data is expired but still served (stale)
+console.log(cache.get("data")); // "current value" (as stale)
+
+// After 7 minutes: data is completely gone
+console.log(cache.get("data")); // undefined
+```
+
+---
+
+## Stale Windows as Memory Control
+
+The real power of stale windows is **controlling how memory is freed** in response to application needs.
+
+After an entry expires, it can still be served as stale data. What happens next depends on your configuration: you can delete it immediately, delete it during background cleanup, or keep it around until memory is needed.
+
+---
+
+## Memory Control: Purging Stale Entries
+
+By default, stale entries remain in cache until explicitly deleted or storage is needed. Two options control what happens:
+
+**`purgeStaleOnGet: true`** — Delete stale entries immediately when accessed.
+
+**`purgeStaleOnSweep: true`** — Delete stale entries during background cleanup operations.
+
+Both are optional and default to `false`, meaning stale data persists until you need the memory.
+
+---
+
+## Summary
+
+Stale windows give your application flexibility to match its memory profile:
+
+- **Need tight memory control?** Use `purgeStaleOnGet` to delete immediately
+- **Normal resource availability?** Let stale data remain—it's useful
+- **Configurable behavior** through `purgeStaleOnGet` and `purgeStaleOnSweep`
+
+The key benefit: graceful degradation. Your app continues serving data even after expiration, keeping the user experience responsive while managing memory appropriately.
+
+---
+
+## Next
+
+- **[Tag-Based Invalidation](./tag-based-invalidation.md)** - Control cache invalidation
+- **[Back to Examples](../examples.md)**

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)**