@vida-global/core 2.0.9 → 2.0.11

package/index.js

@@ -4,6 +4,7 @@ const   APM              = require('./lib/apm');
 const   JobQueue        = require('./lib/jobQueue');
 const { logger }        = require('./lib/logger');
 const   redisLibs       = require('./lib/redis');
+const   cacheLibs       = require('./lib/cache');
 const   serverLibs      = require('./lib/server');
 
 
@@ -22,6 +23,7 @@ module.exports = {
     ...httpLibs,
     JobQueue,
     logger,
+    ...cacheLibs,
     ...redisLibs,
     ...serverErrorsToExport,
     ApiDocsGenerator,

package/lib/activeRecord/baseRecord.js

@@ -18,6 +18,11 @@ class BaseRecord extends Model {
     static get col() { return this.connection._sequelize.col }
 
 
+    static sqlLiteral(sql) {
+        return this.sequelize.literal(sql);
+    }
+
+
     constructor() {
         if (new.target == BaseRecord) throw new Error("Cannot create an instance of BaseRecord");
         super(...arguments);
@@ -142,6 +147,23 @@ class BaseRecord extends Model {
     /***********************************************************************************************
     * DB CONNECTION
     ***********************************************************************************************/
+    static async withStatementTimeout(milliseconds, callback) {
+        return await this.sequelize.transaction(
+            {readOnly: true},
+            async(transaction) => {
+                await this.sequelize.query(
+                    'SELECT set_config(\'statement_timeout\', :timeout, true)',
+                    {
+                        replacements: {timeout: String(milliseconds)},
+                        transaction,
+                    }
+                );
+                return await callback(transaction);
+            }
+        );
+    }
+
+
     static get connectionClass() {
         return Connection;
     }

package/lib/cache/index.js

@@ -0,0 +1,4 @@
+const { MemoryCache } = require('./memoryCache');
+
+
+module.exports = { MemoryCache };

package/lib/cache/memoryCache.js

@@ -0,0 +1,155 @@
+class MemoryCache {
+    #entries = new Map();
+    #pendingFetches = new Map();
+    #maxEntries;
+
+
+    constructor({ maxEntries = 1000 } = {}) {
+        const limit = maxEntries;
+        if (limit <= 0 || limit > 1000) {
+            throw new TypeError('MemoryCache maxEntries must be between 1 and 1000.');
+        }
+
+        this.#maxEntries = limit;
+    }
+
+
+    async fetch(options = {}, fetcher) {
+        this.#validateNamespace(options.namespace);
+        this.#validateTtl(options.ttlSeconds);
+        this.#validateFetcher(fetcher);
+
+        const cacheKey = this.#createCacheKey(options);
+        const cached   = this.#get(cacheKey);
+        if (cached) return this.#buildFetchResult(cached.value, true);
+
+        const pending  = this.#pendingFetches.get(cacheKey);
+        if (pending) return this.#buildFetchResult(await pending, false);
+
+        const fetch = this.#fetch(options, fetcher, cacheKey);
+        this.#pendingFetches.set(cacheKey, fetch);
+
+        try {
+            return this.#buildFetchResult(await fetch, false);
+        } finally {
+            this.#pendingFetches.delete(cacheKey);
+        }
+    }
+
+
+    #set(cacheKey, ttlSeconds, value) {
+        this.#ensureSpaceForEntry(cacheKey);
+        this.#moveToRecentlyUsed(cacheKey, {
+            value,
+            expiresAt: Date.now() + (ttlSeconds * 1000),
+        });
+    }
+
+
+    async #fetch(options, fetcher, cacheKey) {
+        const value = await fetcher();
+        this.#set(cacheKey, options.ttlSeconds, value);
+        return value;
+    }
+
+
+    #createCacheKey({ namespace, key }) {
+        return `${namespace}:${serializeCacheKey(key)}`;
+    }
+
+
+    #get(cacheKey) {
+        const cached = this.#entries.get(cacheKey);
+        if (!cached) return null;
+
+        if (this.#isExpired(cached)) {
+            this.#entries.delete(cacheKey);
+            return null;
+        }
+
+        this.#moveToRecentlyUsed(cacheKey, cached);
+        return cached;
+    }
+
+
+    #buildFetchResult(value, cacheHit) {
+        return {
+            value,
+            cacheHit,
+        };
+    }
+
+
+    #validateNamespace(namespace) {
+        if (!namespace || typeof namespace !== 'string') {
+            throw new TypeError('MemoryCache namespace is required.');
+        }
+    }
+
+
+    #validateTtl(ttlSeconds) {
+        if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+            throw new RangeError('ttlSeconds must be a positive integer');
+        }
+    }
+
+
+    #validateFetcher(fetcher) {
+        if (typeof fetcher !== 'function') {
+            throw new TypeError('MemoryCache fetcher must be a function.');
+        }
+    }
+
+
+    #isExpired(entry) {
+        return entry.expiresAt <= Date.now();
+    }
+
+
+    #removeExpiredEntries() {
+        for (const [key, entry] of this.#entries) {
+            if (this.#isExpired(entry)) this.#entries.delete(key);
+        }
+    }
+
+
+    #evictLeastRecentlyUsedEntries() {
+        while (this.#entries.size >= this.#maxEntries) {
+            const [cacheKey] = this.#entries.keys();
+            this.#entries.delete(cacheKey);
+        }
+    }
+
+
+    #ensureSpaceForEntry(cacheKey) {
+        if (this.#entries.has(cacheKey) || this.#entries.size < this.#maxEntries) return;
+        this.#removeExpiredEntries();
+
+        if (this.#entries.size >= this.#maxEntries) {
+            this.#evictLeastRecentlyUsedEntries()
+        }
+    }
+
+
+    #moveToRecentlyUsed(cacheKey, entry) {
+        this.#entries.delete(cacheKey);
+        this.#entries.set(cacheKey, entry);
+    }
+
+}
+
+
+function serializeCacheKey(value) {
+    if (Array.isArray(value)) return `[${value.map((item) => serializeCacheKey(item)).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.keys(value)
+                              .sort()
+                              .map((key) => `${JSON.stringify(key)}:${serializeCacheKey(value[key])}`);
+        return `{${entries.join(',')}}`;
+    }
+
+    return JSON.stringify(value);
+}
+
+
+module.exports = { MemoryCache };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vida-global/core",
-    "version": "2.0.9",
+    "version": "2.0.11",
     "description": "Core libraries for supporting Vida development",
     "author": "",
     "license": "ISC",

package/test/activeRecord/baseRecord.test.js

@@ -80,6 +80,58 @@ describe('BaseRecord', () => {
     });
 
 
+    describe('BaseRecord.withStatementTimeout', () => {
+        it ('runs the callback in a read-only transaction with a local statement timeout', async () => {
+            const callback    = jest.fn().mockResolvedValue('result');
+            const transaction = {};
+            const query       = jest.fn().mockResolvedValue(undefined);
+            const transact    = jest.fn(
+                async (_options, transactionCallback) => {
+                    return await transactionCallback(transaction);
+                }
+            );
+            class User extends BaseRecord {}
+            User.sequelize = {query, transaction: transact};
+
+            await expect(
+                User.withStatementTimeout(15000, callback)
+            ).resolves.toEqual('result');
+
+            expect(transact).toHaveBeenCalledTimes(1);
+            expect(transact).toHaveBeenCalledWith(
+                {readOnly: true},
+                expect.any(Function)
+            );
+            expect(query).toHaveBeenCalledTimes(1);
+            expect(query).toHaveBeenCalledWith(
+                'SELECT set_config(\'statement_timeout\', :timeout, true)',
+                {
+                    replacements: {timeout: '15000'},
+                    transaction,
+                }
+            );
+            expect(callback).toHaveBeenCalledTimes(1);
+            expect(callback).toHaveBeenCalledWith(transaction);
+        });
+    });
+
+
+    describe('BaseRecord.sqlLiteral', () => {
+        it ('returns the SQL literal built by the model sequelize connection', () => {
+            const sql            = TestHelpers.Faker.Text.randomString();
+            const literal        = {};
+            const literalBuilder = jest.fn().mockReturnValue(literal);
+            class User extends BaseRecord {}
+            User.sequelize = {literal: literalBuilder};
+
+            expect(User.sqlLiteral(sql)).toBe(literal);
+
+            expect(literalBuilder).toHaveBeenCalledTimes(1);
+            expect(literalBuilder).toHaveBeenCalledWith(sql);
+        });
+    });
+
+
     describe('BaseRecord.initialize', () => {
         it ('calls `getBaseRecordSchema` and passes the response to init', () => {
             class User extends BaseRecord {}

package/test/cache/memoryCache.test.js

@@ -0,0 +1,233 @@
+const { MemoryCache } = require('../../lib/cache');
+const { MemoryCache: PublicMemoryCache } = require('../../index');
+
+
+describe('MemoryCache', () => {
+    let cache;
+
+
+    beforeEach(() => {
+        cache = new MemoryCache();
+    });
+
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+
+    describe('#fetch', () => {
+        const options = {
+            namespace: 'squire:shop-data',
+            key: { shopId: 'shop-1' },
+            ttlSeconds: 300,
+        };
+
+
+        it('fetches and caches a value', async () => {
+            const value   = { services: ['Cut'] };
+            const fetcher = jest.fn().mockResolvedValue(value);
+
+            const first = await cache.fetch(options, fetcher);
+            const second = await cache.fetch(options, fetcher);
+
+            expect(first).toEqual({ value, cacheHit: false });
+            expect(second).toEqual({ value, cacheHit: true });
+            expect(first.value).toBe(value);
+            expect(second.value).toBe(value);
+            expect(fetcher).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('uses equivalent object keys regardless of property order', async () => {
+            const fetcher = jest.fn().mockResolvedValue({ services: ['Cut'] });
+            const firstOptions = {
+                ...options,
+                key: { agentId: 'agent-1', shopId: 'shop-1' },
+            };
+            const secondOptions = {
+                ...options,
+                key: { shopId: 'shop-1', agentId: 'agent-1' },
+            };
+
+            await cache.fetch(firstOptions, fetcher);
+            const result = await cache.fetch(secondOptions, fetcher);
+
+            expect(result).toEqual({ value: { services: ['Cut'] }, cacheHit: true });
+            expect(fetcher).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('fetches an expired value again', async () => {
+            jest.spyOn(Date, 'now').mockReturnValue(1000);
+            const fetcher = jest.fn()
+                                .mockResolvedValueOnce({ version: 1 })
+                                .mockResolvedValueOnce({ version: 2 });
+            await cache.fetch({ ...options, ttlSeconds: 1 }, fetcher);
+
+            Date.now.mockReturnValue(2000);
+            const result = await cache.fetch({ ...options, ttlSeconds: 1 }, fetcher);
+
+            expect(result).toEqual({ value: { version: 2 }, cacheHit: false });
+            expect(fetcher).toHaveBeenCalledTimes(2);
+        });
+
+
+        it('allows cached values to be mutated', async () => {
+            const value   = { shop: { name: 'Original' } };
+            const fetcher = jest.fn().mockResolvedValue(value);
+            const first   = await cache.fetch(options, fetcher);
+            first.value.shop.name = 'Changed by receiver';
+
+            const second = await cache.fetch(options, fetcher);
+
+            expect(second.value).toEqual({ shop: { name: 'Changed by receiver' } });
+            expect(second.value).toBe(first.value);
+        });
+
+
+        it('caches null values', async () => {
+            const fetcher = jest.fn().mockResolvedValue(null);
+
+            const first  = await cache.fetch(options, fetcher);
+            const second = await cache.fetch(options, fetcher);
+
+            expect(first).toEqual({ value: null, cacheHit: false });
+            expect(second).toEqual({ value: null, cacheHit: true });
+            expect(fetcher).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('shares one fetch between concurrent calls for the same key', async () => {
+            let resolveFetch;
+            const data    = { shop: { name: 'Shop' } };
+            const fetcher = jest.fn(() => new Promise((resolve) => {
+                resolveFetch = resolve;
+            }));
+
+            const first  = cache.fetch(options, fetcher);
+            const second = cache.fetch(options, fetcher);
+            resolveFetch(data);
+            const [firstResult, secondResult] = await Promise.all([first, second]);
+
+            expect(fetcher).toHaveBeenCalledTimes(1);
+            expect(firstResult).toEqual({ value: data, cacheHit: false });
+            expect(secondResult).toEqual({ value: data, cacheHit: false });
+            expect(firstResult.value).toBe(data);
+            expect(secondResult.value).toBe(data);
+        });
+
+
+        it('shares a fetch between equivalent key object order', async () => {
+            const fetcher = jest.fn().mockResolvedValue({ services: ['Cut'] });
+            const first   = cache.fetch({
+                ...options,
+                key: { agentId: 'agent-1', shopId: 'shop-1' },
+            }, fetcher);
+            const second  = cache.fetch({
+                ...options,
+                key: { shopId: 'shop-1', agentId: 'agent-1' },
+            }, fetcher);
+
+            await expect(Promise.all([first, second])).resolves.toEqual([
+                { value: { services: ['Cut'] }, cacheHit: false },
+                { value: { services: ['Cut'] }, cacheHit: false },
+            ]);
+            expect(fetcher).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('fetches different keys independently', async () => {
+            const firstFetcher  = jest.fn().mockResolvedValue({ id: 1 });
+            const secondFetcher = jest.fn().mockResolvedValue({ id: 2 });
+
+            const results = await Promise.all([
+                cache.fetch({ ...options, key: 'first' }, firstFetcher),
+                cache.fetch({ ...options, key: 'second' }, secondFetcher),
+            ]);
+
+            expect(results).toEqual([
+                { value: { id: 1 }, cacheHit: false },
+                { value: { id: 2 }, cacheHit: false },
+            ]);
+            expect(firstFetcher).toHaveBeenCalledTimes(1);
+            expect(secondFetcher).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('rejects concurrent calls and allows the fetch to be retried', async () => {
+            const fetcher = jest.fn()
+                                .mockRejectedValueOnce(new Error('fetch failed'))
+                                .mockResolvedValueOnce({ services: ['Cut'] });
+            const first  = cache.fetch(options, fetcher);
+            const second = cache.fetch(options, fetcher);
+
+            await expect(Promise.all([first, second])).rejects.toThrow('fetch failed');
+            await expect(cache.fetch(options, fetcher)).resolves.toEqual({
+                value: { services: ['Cut'] },
+                cacheHit: false,
+            });
+            expect(fetcher).toHaveBeenCalledTimes(2);
+        });
+
+
+        it('evicts the least recently used value when full', async () => {
+            cache = new MemoryCache({ maxEntries: 2 });
+            const optionsFor = (key) => ({ ...options, key });
+            await cache.fetch(optionsFor('first'), async () => ({ value: 'first' }));
+            await cache.fetch(optionsFor('second'), async () => ({ value: 'second' }));
+            await cache.fetch(optionsFor('first'), async () => ({ value: 'unused' }));
+            await cache.fetch(optionsFor('third'), async () => ({ value: 'third' }));
+            const fetcher = jest.fn().mockResolvedValue({ value: 'new-second' });
+
+            const result = await cache.fetch(optionsFor('second'), fetcher);
+
+            expect(result).toEqual({ value: { value: 'new-second' }, cacheHit: false });
+            expect(fetcher).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('removes expired values before evicting an active value', async () => {
+            cache = new MemoryCache({ maxEntries: 2 });
+            jest.spyOn(Date, 'now').mockReturnValue(1000);
+            await cache.fetch({ ...options, key: 'active' }, async () => ({ value: 'active' }));
+            await cache.fetch({ ...options, key: 'expired', ttlSeconds: 1 }, async () => ({ value: 'expired' }));
+
+            Date.now.mockReturnValue(2000);
+            await cache.fetch({ ...options, key: 'new' }, async () => ({ value: 'new' }));
+            const active = await cache.fetch({ ...options, key: 'active' }, async () => ({ value: 'unused' }));
+
+            expect(active).toEqual({ value: { value: 'active' }, cacheHit: true });
+        });
+
+
+        it('caches values that cannot be structured cloned', async () => {
+            const value = { fetch: () => 'value' };
+
+            const first  = await cache.fetch(options, async () => value);
+            const second = await cache.fetch(options, jest.fn());
+
+            expect(first.value).toBe(value);
+            expect(second.value).toBe(value);
+            expect(second.value.fetch()).toBe('value');
+        });
+
+
+        it('requires a fetcher and valid options', async () => {
+            await expect(cache.fetch(options)).rejects.toThrow('MemoryCache fetcher must be a function.');
+            await expect(cache.fetch({ ...options, ttlSeconds: null }, jest.fn()))
+                .rejects.toThrow('ttlSeconds must be a positive integer');
+            await expect(cache.fetch()).rejects.toThrow('MemoryCache namespace is required.');
+        });
+    });
+
+
+    describe('constructor', () => {
+        it('requires a cache entry limit between 1 and 1000', () => {
+            expect(() => new MemoryCache({ maxEntries: 0 }))
+                .toThrow('MemoryCache maxEntries must be between 1 and 1000.');
+            expect(() => new MemoryCache({ maxEntries: 1001 }))
+                .toThrow('MemoryCache maxEntries must be between 1 and 1000.');
+        });
+    });
+});