architex-js 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architex-js",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -13,7 +13,9 @@
     "./guards": "./src/guards/index.js",
     "./repository": "./src/repository/index.js",
     "./events": "./src/events/index.js",
-    "./cqrs": "./src/cqrs/index.js"
+    "./cqrs": "./src/cqrs/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

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

package/src/scheduler/Scheduler.js

@@ -0,0 +1,100 @@
+/**
+ * Manages scheduled tasks (repeating intervals and one-time delays).
+ * All registered tasks can be cleared at once.
+ *
+ * @example
+ * const scheduler = new Scheduler();
+ * const stop = scheduler.every(5000, () => console.log('tick'));
+ * stop(); // cancel just this task
+ *
+ * scheduler.clear(); // cancel all tasks
+ */
+class Scheduler {
+    constructor() {
+        /** @type {Set<any>} */
+        this._timers = new Set();
+    }
+
+    /**
+     * Runs a callback repeatedly every `ms` milliseconds.
+     * @param {number} ms - Interval in milliseconds.
+     * @param {() => void | Promise<void>} callback
+     * @returns {() => void} A cancellation function.
+     */
+    every(ms, callback) {
+        if (typeof ms !== 'number' || ms <= 0) {
+            throw new TypeError('Scheduler.every() expects a positive number of milliseconds');
+        }
+        if (typeof callback !== 'function') {
+            throw new TypeError('Scheduler.every() expects a function as second argument');
+        }
+
+        const id = setInterval(async () => {
+            try {
+                await callback();
+            } catch (e) {
+                console.error(`[Scheduler] Error in repeating task:`, e);
+            }
+        }, ms);
+
+        this._timers.add(id);
+
+        return () => {
+            clearInterval(id);
+            this._timers.delete(id);
+        };
+    }
+
+    /**
+     * Runs a callback once after `ms` milliseconds.
+     * @param {number} ms - Delay in milliseconds.
+     * @param {() => void | Promise<void>} callback
+     * @returns {() => void} A cancellation function.
+     */
+    after(ms, callback) {
+        if (typeof ms !== 'number' || ms < 0) {
+            throw new TypeError('Scheduler.after() expects a non-negative number of milliseconds');
+        }
+        if (typeof callback !== 'function') {
+            throw new TypeError('Scheduler.after() expects a function as second argument');
+        }
+
+        const id = setTimeout(async () => {
+            try {
+                await callback();
+            } catch (e) {
+                console.error(`[Scheduler] Error in delayed task:`, e);
+            } finally {
+                this._timers.delete(id);
+            }
+        }, ms);
+
+        this._timers.add(id);
+
+        return () => {
+            clearTimeout(id);
+            this._timers.delete(id);
+        };
+    }
+
+    /**
+     * Returns the number of active timers.
+     * @returns {number}
+     */
+    get size() {
+        return this._timers.size;
+    }
+
+    /**
+     * Cancels all scheduled tasks.
+     */
+    clear() {
+        for (const id of this._timers) {
+            clearInterval(id);
+            clearTimeout(id);
+        }
+        this._timers.clear();
+    }
+}
+
+export { Scheduler };

package/src/scheduler/index.js

@@ -0,0 +1 @@
+export * from "./Scheduler.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);
+    });
+});

package/test/scheduler.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Scheduler } from '../src/scheduler/index.js';
+
+describe('Scheduler', () => {
+    let scheduler;
+
+    beforeEach(() => {
+        scheduler = new Scheduler();
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        scheduler.clear();
+        vi.useRealTimers();
+    });
+
+    it('every() should call callback repeatedly', () => {
+        const fn = vi.fn();
+        scheduler.every(1000, fn);
+
+        vi.advanceTimersByTime(3000);
+        expect(fn).toHaveBeenCalledTimes(3);
+    });
+
+    it('every() should return a cancel function that stops the interval', () => {
+        const fn = vi.fn();
+        const stop = scheduler.every(1000, fn);
+
+        vi.advanceTimersByTime(2000);
+        stop();
+        vi.advanceTimersByTime(3000);
+
+        expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it('after() should call callback once after the delay', () => {
+        const fn = vi.fn();
+        scheduler.after(500, fn);
+
+        vi.advanceTimersByTime(499);
+        expect(fn).not.toHaveBeenCalled();
+
+        vi.advanceTimersByTime(1);
+        expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('after() cancel function should prevent execution', () => {
+        const fn = vi.fn();
+        const cancel = scheduler.after(1000, fn);
+
+        cancel();
+        vi.advanceTimersByTime(2000);
+
+        expect(fn).not.toHaveBeenCalled();
+    });
+
+    it('clear() should stop all active timers', () => {
+        const fn1 = vi.fn();
+        const fn2 = vi.fn();
+        scheduler.every(500, fn1);
+        scheduler.after(1000, fn2);
+
+        scheduler.clear();
+        vi.advanceTimersByTime(2000);
+
+        expect(fn1).not.toHaveBeenCalled();
+        expect(fn2).not.toHaveBeenCalled();
+        expect(scheduler.size).toBe(0);
+    });
+
+    it('should report correct size of active timers', () => {
+        scheduler.every(1000, () => { });
+        scheduler.after(500, () => { });
+        expect(scheduler.size).toBe(2);
+    });
+
+    it('should throw for non-positive interval in every()', () => {
+        expect(() => scheduler.every(0, () => { })).toThrow(TypeError);
+        expect(() => scheduler.every(-1, () => { })).toThrow(TypeError);
+    });
+});