safe-memory-layer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 safe-memory-layer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,501 @@
+# Safe Memory Layer
+
+Secure, lightweight, dependency-free in-memory storage with TTL support, automatic cleanup, and memory leak prevention for Node.js and modern browsers.
+
+## Features
+
+- **Memory Safety**: Automatic cleanup of expired entries, leak prevention, and safe resource management
+- **TTL Support**: Time-based expiration with lazy and active cleanup
+- **Automatic Cleanup**: Background scheduler that stops when empty to save CPU
+- **WeakMap Support**: Object-only storage with automatic garbage collection
+- **LRU/FIFO Eviction**: Configurable strategies when reaching max entries
+- **Event Callbacks**: Monitor expiration, deletion, and cleanup events
+- **Statistics**: Track entries, expired count, deleted count, and uptime
+- **Auto-Dispose**: Automatically dispose store after being empty for a configurable time
+- **Zero Dependencies**: No external runtime dependencies
+- **TypeScript**: Full generic typing with strict mode compatibility
+- **Tree-Shakeable ESM**: Optimized bundle size
+- **Browser & Node.js**: Works in both environments
+
+## Installation
+
+```bash
+npm install safe-memory-layer
+```
+
+## Quick Start
+
+```typescript
+import { MemoryStore } from "safe-memory-layer";
+
+// Create a store
+const store = new MemoryStore<string, User>();
+
+// Set values with optional TTL
+store.set("user:123", user, { ttl: 60000 }); // Expires in 60 seconds
+
+// Get values
+const user = store.get("user:123");
+
+// Check existence
+if (store.has("user:123")) {
+  console.log("User exists");
+}
+
+// Clean up when done
+store.dispose();
+```
+
+## API Reference
+
+### MemoryStore
+
+The main in-memory store with TTL support and automatic cleanup.
+
+#### Constructor
+
+```typescript
+const store = new MemoryStore<K, V>(options?: MemoryStoreOptions<K, V>);
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultTTL` | `number \| undefined` | `undefined` | Default TTL in milliseconds for all entries |
+| `cleanupInterval` | `number` | `10000` | Interval between automatic cleanup runs (ms) |
+| `autoCleanup` | `boolean` | `true` | Enable automatic cleanup |
+| `autoDispose` | `boolean` | `false` | Auto-dispose after being empty for `autoDisposeDelay` |
+| `autoDisposeDelay` | `number` | `60000` | Delay before auto-dispose (ms) |
+| `maxEntries` | `number \| undefined` | `undefined` | Maximum number of entries |
+| `maxEntriesStrategy` | `"reject" \| "FIFO" \| "LRU"` | `"reject"` | Strategy when max entries is reached |
+| `onExpire` | `(key: K, value: V) => void` | `undefined` | Callback when entry expires |
+| `onDelete` | `(key: K, value: V) => void` | `undefined` | Callback when entry is deleted |
+| `onCleanup` | `(stats: CleanupStats) => void` | `undefined` | Callback after cleanup cycle |
+
+#### Methods
+
+##### set(key, value, options?)
+
+Stores a value with the given key.
+
+```typescript
+store.set("key", value, { ttl: 60000 });
+```
+
+**Returns:** `boolean` - `true` if stored, `false` if rejected (max entries reached)
+
+##### get(key)
+
+Retrieves a value by key.
+
+```typescript
+const value = store.get("key");
+```
+
+**Returns:** `V | undefined` - The value or `undefined` if not found/expired
+
+##### has(key)
+
+Checks if a key exists and is not expired.
+
+```typescript
+if (store.has("key")) {
+  // Key exists
+}
+```
+
+**Returns:** `boolean`
+
+##### delete(key)
+
+Deletes a value by key.
+
+```typescript
+const deleted = store.delete("key");
+```
+
+**Returns:** `boolean` - `true` if key was present
+
+##### clear()
+
+Removes all entries.
+
+```typescript
+store.clear();
+```
+
+##### size
+
+Returns the number of non-expired entries.
+
+```typescript
+const count = store.size;
+```
+
+**Returns:** `number`
+
+##### keys()
+
+Returns an iterator of all keys.
+
+```typescript
+for (const key of store.keys()) {
+  console.log(key);
+}
+```
+
+**Returns:** `IterableIterator<K>`
+
+##### values()
+
+Returns an iterator of all non-expired values.
+
+```typescript
+for (const value of store.values()) {
+  console.log(value);
+}
+```
+
+**Returns:** `IterableIterator<V>`
+
+##### entries()
+
+Returns an iterator of all [key, value] pairs.
+
+```typescript
+for (const [key, value] of store.entries()) {
+  console.log(key, value);
+}
+```
+
+**Returns:** `IterableIterator<[K, V]>`
+
+##### cleanup()
+
+Removes all expired entries.
+
+```typescript
+const removed = store.cleanup();
+```
+
+**Returns:** `number` - Number of entries removed
+
+##### compact()
+
+Alias for `cleanup()`.
+
+```typescript
+const removed = store.compact();
+```
+
+##### stats()
+
+Returns statistics about the store.
+
+```typescript
+const stats = store.stats();
+console.log(stats);
+```
+
+**Returns:** `StoreStats`
+
+```typescript
+interface StoreStats {
+  entries: number;       // Current number of entries
+  expired: number;       // Total expired entries
+  deleted: number;       // Total deleted entries
+  cleaned: number;       // Total cleanup cycles
+  uptime: number;        // Uptime in milliseconds
+  memoryEstimate: number; // Estimated memory usage in bytes
+}
+```
+
+##### dispose()
+
+Disposes the store, stopping all timers and releasing references.
+
+```typescript
+store.dispose();
+```
+
+After disposal, the store cannot be used.
+
+##### disposed
+
+Checks if the store has been disposed.
+
+```typescript
+if (store.disposed) {
+  console.log("Store is disposed");
+}
+```
+
+**Returns:** `boolean`
+
+### WeakMemoryStore
+
+Object-only storage using WeakMap for automatic garbage collection.
+
+#### Constructor
+
+```typescript
+const weakStore = new WeakMemoryStore<V>(options?: WeakMemoryStoreOptions<V>);
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `onDelete` | `(value: V) => void` | `undefined` | Callback when entry is deleted |
+
+#### Methods
+
+##### set(key, value)
+
+Stores a value with an object key.
+
+```typescript
+const obj = { id: 1 };
+weakStore.set(obj, { name: "Alice" });
+```
+
+**Returns:** `boolean`
+
+##### get(key)
+
+Retrieves a value by object key.
+
+```typescript
+const value = weakStore.get(obj);
+```
+
+**Returns:** `V | undefined`
+
+##### has(key)
+
+Checks if a key exists.
+
+```typescript
+if (weakStore.has(obj)) {
+  // Key exists
+}
+```
+
+**Returns:** `boolean`
+
+##### delete(key)
+
+Deletes a value by object key.
+
+```typescript
+const deleted = weakStore.delete(obj);
+```
+
+**Returns:** `boolean`
+
+##### clear()
+
+Removes all entries.
+
+```typescript
+weakStore.clear();
+```
+
+##### deleted
+
+Returns the number of deleted entries.
+
+```typescript
+const count = weakStore.deleted;
+```
+
+**Returns:** `number`
+
+##### stats()
+
+Returns statistics.
+
+```typescript
+const stats = weakStore.stats();
+```
+
+**Returns:** `{ deleted: number; uptime: number }`
+
+##### dispose()
+
+Disposes the store.
+
+```typescript
+weakStore.dispose();
+```
+
+##### disposed
+
+Checks if the store has been disposed.
+
+```typescript
+if (weakStore.disposed) {
+  console.log("Store is disposed");
+}
+```
+
+**Returns:** `boolean`
+
+## Examples
+
+### Basic Cache
+
+```typescript
+const cache = new MemoryStore<string, string>();
+cache.set("key", "value");
+console.log(cache.get("key")); // "value"
+cache.dispose();
+```
+
+### TTL Cache
+
+```typescript
+const ttlCache = new MemoryStore<string, User>({
+  defaultTTL: 60000, // 1 minute
+  cleanupInterval: 10000,
+});
+
+ttlCache.set("user:1", user, { ttl: 30000 }); // 30 seconds
+```
+
+### Session Storage
+
+```typescript
+const sessionStore = new MemoryStore<string, Session>({
+  defaultTTL: 30 * 60 * 1000, // 30 minutes
+  maxEntries: 1000,
+  maxEntriesStrategy: "LRU",
+});
+
+sessionStore.set(sessionId, sessionData);
+```
+
+### Token Storage
+
+```typescript
+const authStore = new MemoryStore<string, TokenData>({
+  defaultTTL: 3600000, // 1 hour
+  maxEntries: 5000,
+  maxEntriesStrategy: "FIFO",
+});
+
+authStore.set(`token:${token}`, tokenData);
+```
+
+### Weak Object Cache
+
+```typescript
+const weakStore = new WeakMemoryStore<UserData>();
+
+const user = { id: 1 };
+weakStore.set(user, { name: "Alice" });
+
+// When 'user' is garbage collected, entry is automatically removed
+```
+
+### Event Monitoring
+
+```typescript
+const store = new MemoryStore<string, Data>({
+  onExpire: (key, value) => {
+    console.log(`Expired: ${key}`);
+  },
+  onDelete: (key, value) => {
+    console.log(`Deleted: ${key}`);
+  },
+  onCleanup: (stats) => {
+    console.log(`Cleaned ${stats.removed} entries`);
+  },
+});
+```
+
+### Auto-Dispose
+
+```typescript
+const store = new MemoryStore<string, Data>({
+  autoDispose: true,
+  autoDisposeDelay: 60000, // 1 minute
+});
+
+store.set("key", value);
+store.delete("key");
+// Store will auto-dispose after 1 minute of being empty
+```
+
+## Best Practices
+
+1. **Always dispose stores**: Call `dispose()` when done to release timers and references
+2. **Use appropriate TTLs**: Set TTLs based on data freshness requirements
+3. **Configure cleanup interval**: Balance between cleanup frequency and CPU usage
+4. **Use LRU for caches**: LRU eviction works well for cache scenarios
+5. **Use FIFO for queues**: FIFO eviction works well for queue-like data
+6. **Monitor with callbacks**: Use event callbacks to track store behavior
+7. **Avoid storing large objects**: Keep values small for better performance
+8. **Use WeakMemoryStore for object metadata**: When keys are objects that may be GC'd
+
+## Performance
+
+- **O(1)** get, set, delete operations
+- **O(n)** cleanup (iterates all entries)
+- **O(n)** size (counts non-expired entries)
+- Minimal memory allocations
+- Single timer for all cleanup operations
+- Automatic scheduler pause when empty
+
+## Browser Compatibility
+
+Works in all modern browsers that support:
+- ES2022
+- WeakMap
+- Map
+- setTimeout/setInterval
+
+No Node.js-specific APIs are used.
+
+## TypeScript Support
+
+Full TypeScript support with generics:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const store = new MemoryStore<string, User>();
+store.set("user:1", { id: "1", name: "Alice", email: "alice@example.com" });
+const user = store.get("user:1"); // Type: User | undefined
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please ensure all tests pass before submitting a PR.
+
+```bash
+npm test
+```
+
+## Changelog
+
+### 1.0.0
+
+- Initial release
+- MemoryStore with TTL support
+- WeakMemoryStore with WeakMap
+- Automatic cleanup scheduler
+- LRU/FIFO eviction strategies
+- Event callbacks
+- Statistics tracking
+- Auto-dispose feature
+- Full TypeScript support