architex-js 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architex-js",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -14,7 +14,8 @@
     "./repository": "./src/repository/index.js",
     "./events": "./src/events/index.js",
     "./cqrs": "./src/cqrs/index.js",
-    "./scheduler": "./src/scheduler/index.js"
+    "./scheduler": "./src/scheduler/index.js",
+    "./cache": "./src/cache/index.js"
   },
   "description": "Architectural Toolbox for JavaScript - Providing high-level building blocks for robust systems.",
   "author": {

package/src/cache/Cache.js

@@ -0,0 +1,115 @@
+/**
+ * In-memory cache with TTL (time-to-live), lazy expiry, and `remember()` helper.
+ *
+ * @example
+ * const cache = new Cache({ ttl: 60000 }); // 60 seconds default TTL
+ * const user = await cache.remember('user:1', () => fetchUser(1));
+ */
+class Cache {
+    /**
+     * @param {{ ttl?: number }} [options]
+     * @param {number} [options.ttl=0] - Default TTL in milliseconds. 0 = no expiry.
+     */
+    constructor({ ttl = 0 } = {}) {
+        /** @type {number} Default TTL in ms */
+        this._defaultTtl = ttl;
+        /** @type {Map<string, { value: any, expiresAt: number | null }>} */
+        this._store = new Map();
+    }
+
+    /**
+     * Stores a value in the cache.
+     * @param {string} key
+     * @param {any} value
+     * @param {number} [ttl] - TTL in milliseconds. Falls back to the default. 0 = no expiry.
+     */
+    set(key, value, ttl = this._defaultTtl) {
+        const expiresAt = ttl > 0 ? Date.now() + ttl : null;
+        this._store.set(key, { value, expiresAt });
+    }
+
+    /**
+     * Retrieves a value. Returns `undefined` if the key doesn't exist or has expired.
+     * @param {string} key
+     * @returns {any | undefined}
+     */
+    get(key) {
+        const entry = this._store.get(key);
+        if (!entry) return undefined;
+
+        if (entry.expiresAt !== null && Date.now() >= entry.expiresAt) {
+            this._store.delete(key);
+            return undefined;
+        }
+
+        return entry.value;
+    }
+
+    /**
+     * Returns true if the key exists and has not expired.
+     * @param {string} key
+     * @returns {boolean}
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+
+    /**
+     * Removes a key from the cache.
+     * @param {string} key
+     */
+    delete(key) {
+        this._store.delete(key);
+    }
+
+    /**
+     * Clears all entries in the cache.
+     */
+    clear() {
+        this._store.clear();
+    }
+
+    /**
+     * Returns the cached value if it exists; otherwise calls the factory,
+     * caches the result, and returns it. (Cache-aside pattern)
+     * @template T
+     * @param {string} key
+     * @param {() => T | Promise<T>} factory - Function that generates the value if cache misses.
+     * @param {number} [ttl] - Optional TTL override.
+     * @returns {Promise<T>}
+     */
+    async remember(key, factory, ttl = this._defaultTtl) {
+        const cached = this.get(key);
+        if (cached !== undefined) return cached;
+
+        const value = await factory();
+        this.set(key, value, ttl);
+        return value;
+    }
+
+    /**
+     * Returns the number of entries in the cache (including potentially expired ones).
+     * @returns {number}
+     */
+    get size() {
+        return this._store.size;
+    }
+
+    /**
+     * Purges all expired entries.
+     * @returns {number} Number of entries removed.
+     */
+    purgeExpired() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of this._store) {
+            if (entry.expiresAt !== null && now >= entry.expiresAt) {
+                this._store.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+}
+
+export { Cache };

package/src/cache/index.js

@@ -0,0 +1 @@
+export * from "./Cache.js";

package/src/index.js

@@ -8,4 +8,5 @@ export * from "./guards/index.js";
 export * from "./repository/index.js";
 export * from "./events/index.js";
 export * from "./cqrs/index.js";
-export * from "./scheduler/index.js";
+export * from "./scheduler/index.js";
+export * from "./cache/index.js";

package/test/cache.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Cache } from '../src/cache/index.js';
+
+describe('Cache', () => {
+    let cache;
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+        cache = new Cache({ ttl: 1000 });
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('should set and get a value', () => {
+        cache.set('key', 'value');
+        expect(cache.get('key')).toBe('value');
+    });
+
+    it('should return undefined for a missing key', () => {
+        expect(cache.get('missing')).toBeUndefined();
+    });
+
+    it('should expire entries after TTL', () => {
+        cache.set('key', 42, 500);
+        vi.advanceTimersByTime(499);
+        expect(cache.get('key')).toBe(42);
+
+        vi.advanceTimersByTime(1);
+        expect(cache.get('key')).toBeUndefined();
+    });
+
+    it('should not expire entries with ttl=0', () => {
+        const persistent = new Cache({ ttl: 0 });
+        persistent.set('forever', 'yes');
+        vi.advanceTimersByTime(9999999);
+        expect(persistent.get('forever')).toBe('yes');
+    });
+
+    it('has() should return true for existing non-expired keys', () => {
+        cache.set('x', 1);
+        expect(cache.has('x')).toBe(true);
+    });
+
+    it('has() should return false for expired keys', () => {
+        cache.set('x', 1, 100);
+        vi.advanceTimersByTime(101);
+        expect(cache.has('x')).toBe(false);
+    });
+
+    it('delete() should remove a key', () => {
+        cache.set('dKey', 'val');
+        cache.delete('dKey');
+        expect(cache.get('dKey')).toBeUndefined();
+    });
+
+    it('clear() should remove all entries', () => {
+        cache.set('a', 1);
+        cache.set('b', 2);
+        cache.clear();
+        expect(cache.size).toBe(0);
+    });
+
+    it('remember() should call the factory on cache miss', async () => {
+        const factory = vi.fn().mockResolvedValue('fetched');
+        const result = await cache.remember('r', factory);
+        expect(result).toBe('fetched');
+        expect(factory).toHaveBeenCalledTimes(1);
+    });
+
+    it('remember() should not call factory on cache hit', async () => {
+        const factory = vi.fn().mockResolvedValue('fetched');
+        await cache.remember('r', factory);
+        await cache.remember('r', factory);
+        expect(factory).toHaveBeenCalledTimes(1);
+    });
+
+    it('purgeExpired() should remove expired entries and return count', () => {
+        cache.set('a', 1, 100);
+        cache.set('b', 2, 100);
+        cache.set('c', 3, 99999);
+        vi.advanceTimersByTime(101);
+        const removed = cache.purgeExpired();
+        expect(removed).toBe(2);
+        expect(cache.has('c')).toBe(true);
+    });
+});