updated docs

Author: izadoesdev

README.md

@@ -584,7 +584,7 @@ const keys = createKeys({
 })
 ```
 
-**Setup Database Schema:**
+**Setup Database Schema (PostgreSQL):**
 
 ```sql
 CREATE TABLE api_keys (
@@ -596,6 +596,8 @@ CREATE TABLE api_keys (
 CREATE INDEX api_keys_key_hash_idx ON api_keys("keyHash");
 ```
 
+> **Note**: The column uses camelCase (`keyHash`) by default. For MySQL, omit the quotes around `keyHash`.
+
 ### Custom Storage
 
 ```typescript

docs/content/docs/concepts/caching.mdx

@@ -19,6 +19,13 @@ const keys = createKeys({
 })
 ```
 
+The in-memory cache includes automatic memory management:
+
+- **Max Size**: Default limit of 10,000 entries to prevent memory leaks
+- **LRU Eviction**: When the cache is full, the oldest entry is evicted
+- **Automatic Cleanup**: Expired entries are removed every 60 seconds
+- **Graceful Shutdown**: Call `dispose()` to clean up timers when shutting down
+
 ### Redis Cache
 
 ```typescript
@@ -39,6 +46,7 @@ const keys = createKeys({
 2. **Cache Lookup**: Subsequent verifications check cache first
 3. **Cache Miss**: If not in cache, query storage and cache result
 4. **TTL**: Cached entries expire after the configured TTL
+5. **Validation**: Cached data is validated on retrieval to prevent corruption issues
 
 ## Cache Invalidation
 
@@ -50,6 +58,7 @@ await keys.invalidateCache(keyHash)
 // - Key is revoked
 // - Key is disabled/enabled
 // - Key is rotated
+// - Corrupted cache data is detected
 ```
 
 ## Skip Cache
@@ -61,10 +70,27 @@ const result = await keys.verify(key, {
 })
 ```
 
+## Advanced: Custom Memory Cache Options
+
+If you need to customize the in-memory cache behavior, you can create a `MemoryCache` instance directly:
+
+```typescript
+import { MemoryCache } from 'keypal'
+
+const cache = new MemoryCache({
+  maxSize: 50000,        // Maximum entries (default: 10,000)
+  cleanupInterval: 30000 // Cleanup interval in ms (default: 60,000)
+})
+
+// Use with createKeys via the cache option
+// Or use directly for custom caching needs
+```
+
 ## Best Practices
 
 1. **Enable caching in production** to reduce database load
 2. **Use Redis cache** for distributed applications
 3. **Set appropriate TTL** based on your needs (60-300 seconds is common)
 4. **Monitor cache hit rates** to optimize performance
+5. **Call `dispose()`** on MemoryCache when shutting down to prevent timer leaks
 

docs/content/docs/storage/kysely.mdx

@@ -25,25 +25,27 @@ Create the table in your database:
 ```sql
 CREATE TABLE api_keys (
   id TEXT PRIMARY KEY,
-  key_hash TEXT UNIQUE NOT NULL,
+  "keyHash" TEXT UNIQUE NOT NULL,
   metadata JSONB NOT NULL
 );
 
-CREATE INDEX api_keys_key_hash_idx ON api_keys(key_hash);
+CREATE INDEX api_keys_key_hash_idx ON api_keys("keyHash");
 ```
 
 For MySQL, use `JSON` instead of `JSONB`:
 
 ```sql
 CREATE TABLE api_keys (
   id TEXT PRIMARY KEY,
-  key_hash TEXT UNIQUE NOT NULL,
+  keyHash TEXT UNIQUE NOT NULL,
   metadata JSON NOT NULL
 );
 
-CREATE INDEX api_keys_key_hash_idx ON api_keys(key_hash);
+CREATE INDEX api_keys_key_hash_idx ON api_keys(keyHash);
 ```
 
+> **Note**: The column name uses camelCase (`keyHash`) to match the default adapter configuration. If you prefer snake_case (`key_hash`), you can customize it using the `apiKeyColumns` option.
+
 ## Setup
 
 ```typescript
@@ -94,7 +96,7 @@ Define your database types for full type safety:
 interface Database {
   api_keys: {
     id: string
-    key_hash: string
+    keyHash: string
     metadata: unknown // or a more specific type
   }
 }

docs/content/docs/storage/memory.mdx

@@ -27,11 +27,26 @@ const keys = createKeys({
 
 ## How It Works
 
-Keys are stored in an in-memory `Map` structure:
-- Key lookups are O(1) hash table operations
-- No external dependencies
-- No network calls
-- Data exists only in the current process
+Keys are stored in an in-memory `Map` structure with optimized indexing:
+
+- **O(1) Hash Lookups**: A dedicated hash index maps key hashes to IDs for instant verification
+- **O(1) Owner Lookups**: An owner index maps owner IDs to their key sets for fast listing
+- **Hash Collision Detection**: Automatically detects and rejects duplicate key hashes
+- **No external dependencies**: Everything runs in-process
+- **No network calls**: Zero latency for storage operations
+
+### Internal Structure
+
+```typescript
+// Primary storage: id -> ApiKeyRecord
+keys: Map<string, ApiKeyRecord>
+
+// Hash index for O(1) verification: keyHash -> id
+hashIndex: Map<string, string>
+
+// Owner index for O(1) listing: ownerId -> Set<id>
+ownerIndex: Map<string, Set<string>>
+```
 
 ## Important Notes
 

docs/content/docs/storage/redis.mdx

@@ -97,6 +97,10 @@ const keys = createKeys({
 
 **High performance**: Redis operations are extremely fast, making it ideal for high-throughput applications.
 
+**Pipeline error checking**: All Redis pipeline operations validate individual command results, ensuring data integrity even when multiple operations run together.
+
+**JSON validation**: Data retrieved from Redis is validated before use, protecting against corruption and ensuring type safety.
+
 ## Production Setup
 
 For production, consider:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "keypal",
-  "version": "0.0.212",
+  "version": "0.0.213",
   "description": "A TypeScript library for secure API key management with cryptographic hashing, expiration, scopes, and pluggable storage",
   "type": "module",
   "main": "./dist/index.mjs",

src/core/cache.test.ts

@@ -1,11 +1,15 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { MemoryCache, RedisCache } from "./cache";
 
 describe("MemoryCache", () => {
 	let cache: MemoryCache;
 
 	beforeEach(() => {
-		cache = new MemoryCache();
+		cache = new MemoryCache({ cleanupInterval: 60_000 });
+	});
+
+	afterEach(() => {
+		cache.dispose();
 	});
 
 	it("should store and retrieve values", () => {
@@ -58,6 +62,83 @@ describe("MemoryCache", () => {
 		expect(cache.get("key1")).toBeNull();
 		expect(cache.get("key2")).toBe("value2");
 	});
+
+	it("should respect max size limit", () => {
+		const smallCache = new MemoryCache({ maxSize: 3, cleanupInterval: 60_000 });
+
+		smallCache.set("key1", "value1", 60);
+		smallCache.set("key2", "value2", 60);
+		smallCache.set("key3", "value3", 60);
+		expect(smallCache.size).toBe(3);
+
+		smallCache.set("key4", "value4", 60);
+		expect(smallCache.size).toBe(3);
+		expect(smallCache.get("key4")).toBe("value4");
+
+		smallCache.dispose();
+	});
+
+	it("should evict expired entries before evicting by LRU", async () => {
+		const smallCache = new MemoryCache({ maxSize: 2, cleanupInterval: 60_000 });
+
+		// biome-ignore lint/style/noMagicNumbers: Short TTL for test
+		smallCache.set("expiring", "will expire", 0.05);
+		smallCache.set("permanent", "stays", 60);
+
+		// biome-ignore lint/style/noMagicNumbers: Wait for expiry
+		await new Promise((resolve) => setTimeout(resolve, 100));
+
+		smallCache.set("new", "entry", 60);
+
+		expect(smallCache.get("expiring")).toBeNull();
+		expect(smallCache.get("permanent")).toBe("stays");
+		expect(smallCache.get("new")).toBe("entry");
+
+		smallCache.dispose();
+	});
+
+	it("should cleanup expired entries", async () => {
+		// biome-ignore lint/style/noMagicNumbers: Short TTL for test
+		cache.set("expiring1", "value1", 0.05);
+		// biome-ignore lint/style/noMagicNumbers: Short TTL for test
+		cache.set("expiring2", "value2", 0.05);
+		cache.set("permanent", "value3", 60);
+
+		expect(cache.size).toBe(3);
+
+		// biome-ignore lint/style/noMagicNumbers: Wait for expiry
+		await new Promise((resolve) => setTimeout(resolve, 100));
+
+		cache.cleanup();
+
+		expect(cache.size).toBe(1);
+		expect(cache.get("permanent")).toBe("value3");
+	});
+
+	it("should report size correctly", () => {
+		expect(cache.size).toBe(0);
+		cache.set("key1", "value1", 60);
+		expect(cache.size).toBe(1);
+		cache.set("key2", "value2", 60);
+		expect(cache.size).toBe(2);
+		cache.del("key1");
+		expect(cache.size).toBe(1);
+	});
+
+	it("should allow updating existing key without eviction", () => {
+		const smallCache = new MemoryCache({ maxSize: 2, cleanupInterval: 60_000 });
+
+		smallCache.set("key1", "value1", 60);
+		smallCache.set("key2", "value2", 60);
+		expect(smallCache.size).toBe(2);
+
+		smallCache.set("key1", "updated", 60);
+		expect(smallCache.size).toBe(2);
+		expect(smallCache.get("key1")).toBe("updated");
+		expect(smallCache.get("key2")).toBe("value2");
+
+		smallCache.dispose();
+	});
 });
 
 describe("RedisCache", () => {

src/core/cache.ts

@@ -6,30 +6,55 @@ export type Cache = {
 	del(key: string): Promise<void> | void;
 };
 
+export type MemoryCacheOptions = {
+	maxSize?: number;
+	cleanupInterval?: number;
+};
+
+// biome-ignore lint/style/noMagicNumbers: Default cache configuration
+const DEFAULT_MAX_SIZE = 10_000;
+// biome-ignore lint/style/noMagicNumbers: Default cleanup interval (1 minute)
+const DEFAULT_CLEANUP_INTERVAL = 60_000;
+
 export class MemoryCache implements Cache {
 	private readonly cache = new Map<
 		string,
 		{ value: string; expires: number }
 	>();
+	private readonly maxSize: number;
+	private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+	constructor(options: MemoryCacheOptions = {}) {
+		this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+		const cleanupInterval = options.cleanupInterval ?? DEFAULT_CLEANUP_INTERVAL;
+
+		this.cleanupTimer = setInterval(() => this.cleanup(), cleanupInterval);
+		this.cleanupTimer.unref?.();
+	}
 
 	get(key: string): string | null {
 		const item = this.cache.get(key);
-		if (!item) {
-			return null;
-		}
+		if (!item) return null;
 
 		if (item.expires < Date.now()) {
 			this.cache.delete(key);
 			return null;
 		}
-
 		return item.value;
 	}
 
 	set(key: string, value: string, ttl = 60): void {
+		if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+			this.cleanup();
+			if (this.cache.size >= this.maxSize) {
+				const firstKey = this.cache.keys().next().value;
+				if (firstKey !== undefined) this.cache.delete(firstKey);
+			}
+		}
+
 		this.cache.set(key, {
 			value,
-			// biome-ignore lint/style/noMagicNumbers: 1000ms to seconds
+			// biome-ignore lint/style/noMagicNumbers: Convert seconds to milliseconds
 			expires: Date.now() + ttl * 1000,
 		});
 	}
@@ -41,6 +66,24 @@ export class MemoryCache implements Cache {
 	clear(): void {
 		this.cache.clear();
 	}
+
+	cleanup(): void {
+		const now = Date.now();
+		for (const [key, item] of this.cache) {
+			if (item.expires < now) this.cache.delete(key);
+		}
+	}
+
+	dispose(): void {
+		if (this.cleanupTimer) {
+			clearInterval(this.cleanupTimer);
+			this.cleanupTimer = null;
+		}
+	}
+
+	get size(): number {
+		return this.cache.size;
+	}
 }
 
 export class RedisCache implements Cache {
@@ -51,7 +94,7 @@ export class RedisCache implements Cache {
 	}
 
 	async get(key: string): Promise<string | null> {
-		return await this.client.get(key);
+		return this.client.get(key);
 	}
 
 	async set(key: string, value: string, ttl = 60): Promise<void> {