@vida-global/core 2.5.0 → 3.0.1

package/test/search/abstractSearchClient.test.js

@@ -0,0 +1,354 @@
+const { AbstractSearchClient } = require('../../lib/search/abstractSearchClient');
+const { Query }                = require('../../lib/search/query');
+const   TestHelpers            = require('@vida-global/test-helpers');
+const {
+    BACKEND_HOOKS,
+    buildSearchClient,
+    buildSearchClientClass
+} = require('./helpers/searchClient');
+
+
+const randomString = () => TestHelpers.Faker.Text.randomString();
+
+
+describe('AbstractSearchClient', () => {
+    let client;
+
+
+    beforeEach(() => {
+        client = buildSearchClient();
+        client._hitsFromResponse.mockReturnValue({hits: []});
+        client._totalFromResponse.mockReturnValue(0);
+    });
+
+
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+
+    describe('#constructor', () => {
+        it('cannot be constructed directly', () => {
+            expect(() => new AbstractSearchClient()).toThrow(/must be subclasses/);
+        });
+
+
+        it('stores the index suffix it is given', () => {
+            expect(buildSearchClient({indexSuffix: '2026-10'}).indexSuffix).toBe('2026-10');
+        });
+
+
+        it('leaves the index suffix undefined when none is given', () => {
+            expect(client.indexSuffix).toBeUndefined();
+        });
+    });
+
+
+    describe('#query', () => {
+        it('returns a Query bound to this client', async () => {
+            const query = client.query();
+            jest.spyOn(client, 'fetch').mockResolvedValue(null);
+
+            await query.fetch();
+
+            expect(query).toBeInstanceOf(Query);
+            expect(client.fetch).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('backend hooks', () => {
+        it.each(BACKEND_HOOKS.map(hook => [hook]))('%s is not implemented on the base class', (hook) => {
+            class BareClient extends AbstractSearchClient {}
+
+            expect(() => new BareClient()[hook]()).toThrow('Not Implemented');
+        });
+
+
+        it.each([
+            ['index'],
+            ['mapping'],
+        ])('%s is not implemented on the base class', (accessor) => {
+            class BareClient extends AbstractSearchClient {}
+
+            expect(() => new BareClient()[accessor]).toThrow('Not Implemented');
+        });
+    });
+
+
+    describe('#fetch', () => {
+        it('serializes, executes and shapes in order', async () => {
+            const conditions  = client.query().equals('status', 'success').conditions;
+            const options     = {indexWildcard: true};
+            const serialized  = {bool: {}};
+            const rawResponse = {body: {}};
+
+            client._serializeConditions.mockReturnValue(serialized);
+            client._execute.mockResolvedValue(rawResponse);
+            client._totalFromResponse.mockReturnValue(12);
+
+            await expect(client.fetch(conditions, options)).resolves.toEqual({total: 12, results: []});
+
+            expect(client._serializeConditions).toHaveBeenCalledWith(conditions);
+            expect(client._execute).toHaveBeenCalledWith(serialized, options);
+            expect(client._hitsFromResponse).toHaveBeenCalledWith(rawResponse);
+        });
+
+
+        it('defaults the options to an empty object', async () => {
+            await client.fetch({});
+
+            expect(client._execute).toHaveBeenCalledWith(undefined, {});
+        });
+    });
+
+
+    describe('#_processResponse', () => {
+        it('reads the total and the hits through the backend hooks', () => {
+            const response = {body: 'whatever the backend returns'};
+            client._hitsFromResponse.mockReturnValue({hits: ['first', 'second']});
+            client._totalFromResponse.mockReturnValue(99);
+            jest.spyOn(client, '_buildResult').mockImplementation(hit => `built:${hit}`);
+
+            expect(client._processResponse(response)).toEqual({
+                total:   99,
+                results: ['built:first', 'built:second']
+            });
+        });
+    });
+
+
+    describe('#_buildResult', () => {
+        it('assembles one result from the three hit hooks', () => {
+            const hit = {anything: true};
+            client._idFromHit.mockReturnValue('abc');
+            client._scoreFromHit.mockReturnValue(7.5);
+            client._documentFromHit.mockReturnValue({name: 'stored'});
+
+            expect(client._buildResult(hit)).toEqual({
+                id:       'abc',
+                score:    7.5,
+                document: {name: 'stored'}
+            });
+        });
+    });
+
+
+    describe('#upsert', () => {
+        it('passes the id and the document to the backend', async () => {
+            const id       = randomString();
+            const document = {name: randomString()};
+
+            await client.upsert(id, document);
+
+            expect(client._upsert).toHaveBeenCalledTimes(1);
+            expect(client._upsert).toHaveBeenCalledWith(id, document);
+        });
+    });
+
+
+    describe('#append', () => {
+        it('passes the document to the backend', async () => {
+            const document = {name: randomString()};
+
+            await client.append(document);
+
+            expect(client._append).toHaveBeenCalledTimes(1);
+            expect(client._append).toHaveBeenCalledWith(document);
+        });
+    });
+
+
+    describe('#bulkUpsert', () => {
+        it('passes the documents to the backend', async () => {
+            const documents = [{id: randomString()}, {id: randomString()}];
+
+            await client.bulkUpsert(documents);
+
+            expect(client._bulkUpsert).toHaveBeenCalledTimes(1);
+            expect(client._bulkUpsert).toHaveBeenCalledWith(documents);
+        });
+    });
+
+
+    describe('#delete', () => {
+        it('passes the id to the backend', async () => {
+            const id = randomString();
+
+            await client.delete(id);
+
+            expect(client._delete).toHaveBeenCalledTimes(1);
+            expect(client._delete).toHaveBeenCalledWith(id);
+        });
+    });
+
+
+    describe('#deleteWhere', () => {
+        const hitsFor = (...ids) => ({hits: ids.map(id => ({id}))});
+
+
+        beforeEach(() => {
+            client._idFromHit.mockImplementation(hit => hit.id);
+        });
+
+
+        it('deletes every id in every page until the search comes back empty', async () => {
+            client._hitsFromResponse
+                .mockReturnValueOnce(hitsFor('a', 'b'))
+                .mockReturnValueOnce(hitsFor('c'))
+                .mockReturnValueOnce(hitsFor());
+
+            await expect(client.deleteWhere(client.query())).resolves.toBe(3);
+
+            expect(client._delete.mock.calls).toEqual([['a'], ['b'], ['c']]);
+        });
+
+
+        it('limits each search page to the delete batch size', async () => {
+            await client.deleteWhere(client.query());
+
+            const [conditions] = client._serializeConditions.mock.calls[0];
+            expect(conditions.options.limit).toBe(500);
+        });
+
+
+        it('stops when a page repeats ids it has already deleted', async () => {
+            client._hitsFromResponse.mockReturnValue(hitsFor('a'));
+
+            await expect(client.deleteWhere(client.query())).resolves.toBe(1);
+
+            expect(client._delete).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('stops and rethrows when a delete fails', async () => {
+            const failure = new Error(randomString());
+            client._hitsFromResponse.mockReturnValue(hitsFor('a', 'b', 'c'));
+            client._delete.mockResolvedValueOnce(null).mockRejectedValueOnce(failure);
+
+            await expect(client.deleteWhere(client.query())).rejects.toBe(failure);
+
+            expect(client._delete).toHaveBeenCalledTimes(2);
+        });
+    });
+
+
+    describe('#syncIndex', () => {
+        it('creates the index before pushing the mapping when it is missing', async () => {
+            client._indexExists.mockResolvedValue(false);
+
+            await client.syncIndex();
+
+            expect(client._createIndex).toHaveBeenCalledTimes(1);
+            expect(client._putMapping).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('only pushes the mapping when the index already exists', async () => {
+            client._indexExists.mockResolvedValue(true);
+
+            await client.syncIndex();
+
+            expect(client._createIndex).not.toHaveBeenCalled();
+            expect(client._putMapping).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('.syncIndex', () => {
+        it('builds an instance with the given suffix and syncs it', async () => {
+            const MockSearchClient = buildSearchClientClass();
+            MockSearchClient.prototype._indexExists.mockResolvedValue(true);
+
+            await MockSearchClient.syncIndex('2026-10');
+
+            expect(MockSearchClient.prototype._putMapping).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#shouldRetry', () => {
+        it('allows exactly numRetries extra attempts', () => {
+            const retryingClient = buildSearchClient({numRetries: 2});
+
+            expect(retryingClient.shouldRetry(1)).toBe(true);
+            expect(retryingClient.shouldRetry(2)).toBe(true);
+            expect(retryingClient.shouldRetry(3)).toBe(false);
+        });
+
+
+        it('allows nothing when numRetries is zero', () => {
+            expect(client.shouldRetry(1)).toBe(false);
+        });
+    });
+
+
+    describe('#_withRetry', () => {
+        const buildRetryingClient = (numRetries) => {
+            const retryingClient = buildSearchClient({numRetries});
+            retryingClient._hitsFromResponse.mockReturnValue({hits: []});
+            retryingClient._totalFromResponse.mockReturnValue(0);
+            return retryingClient;
+        };
+
+
+        it('does not retry by default', async () => {
+            const failure = new Error(randomString());
+            client._execute.mockRejectedValue(failure);
+
+            await expect(client.fetch({})).rejects.toBe(failure);
+
+            expect(client._execute).toHaveBeenCalledTimes(1);
+        });
+
+
+        it('retries up to numRetries and then succeeds', async () => {
+            const retryingClient = buildRetryingClient(2);
+            retryingClient._execute
+                .mockRejectedValueOnce(new Error(randomString()))
+                .mockResolvedValueOnce({body: {}});
+
+            await retryingClient.fetch({});
+
+            expect(retryingClient._execute).toHaveBeenCalledTimes(2);
+        });
+
+
+        it('gives up after numRetries and rethrows', async () => {
+            const retryingClient = buildRetryingClient(2);
+            const failure        = new Error(randomString());
+            retryingClient._execute.mockRejectedValue(failure);
+
+            await expect(retryingClient.fetch({})).rejects.toBe(failure);
+
+            expect(retryingClient._execute).toHaveBeenCalledTimes(3);
+        });
+
+
+        it.each([
+            ['upsert', ['id', {}], '_upsert'],
+            ['delete', ['id'],     '_delete'],
+        ])('%s is retried', async (method, args, hook) => {
+            const retryingClient = buildRetryingClient(1);
+            retryingClient[hook].mockRejectedValueOnce(new Error(randomString()));
+
+            await retryingClient[method](...args);
+
+            expect(retryingClient[hook]).toHaveBeenCalledTimes(2);
+        });
+
+
+        it.each([
+            ['append',     [{}],   '_append'],
+            ['bulkUpsert', [[{}]], '_bulkUpsert'],
+        ])('%s is never retried, because a resend would duplicate the document', async (method, args, hook) => {
+            const retryingClient = buildRetryingClient(3);
+            const failure        = new Error(randomString());
+            retryingClient[hook].mockRejectedValue(failure);
+
+            await expect(retryingClient[method](...args)).rejects.toBe(failure);
+
+            expect(retryingClient[hook]).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/test/search/errors.test.js

@@ -0,0 +1,41 @@
+const { BulkWriteError, UnsupportedOperationError } = require('../../lib/search/errors');
+const   TestHelpers = require('@vida-global/test-helpers');
+
+
+const randomString = () => TestHelpers.Faker.Text.randomString();
+
+
+describe('UnsupportedOperationError', () => {
+
+    describe('#constructor', () => {
+        it('keeps the message and names itself', () => {
+            const message = randomString();
+            const error   = new UnsupportedOperationError(message);
+
+            expect(error).toBeInstanceOf(Error);
+            expect(error.message).toBe(message);
+            expect(error.name).toBe('UnsupportedOperationError');
+        });
+
+
+        it('keeps the error it was raised from', () => {
+            const cause = new Error(randomString());
+
+            expect(new UnsupportedOperationError('nope', {cause}).cause).toBe(cause);
+        });
+    });
+});
+
+
+describe('BulkWriteError', () => {
+
+    describe('#failures', () => {
+        it('carries the documents that could not be written', () => {
+            const failures = [{id: randomString(), reason: randomString()}];
+            const error    = new BulkWriteError(randomString(), failures);
+
+            expect(error.name).toBe('BulkWriteError');
+            expect(error.failures).toEqual(failures);
+        });
+    });
+});

package/test/search/helpers/searchClient.js

@@ -0,0 +1,137 @@
+/***************************************************************************************************
+* VARIABLES
+***************************************************************************************************/
+const BACKEND_HOOKS = [
+    '_append',
+    '_bulkUpsert',
+    '_createIndex',
+    '_delete',
+    '_documentFromHit',
+    '_execute',
+    '_hitsFromResponse',
+    '_idFromHit',
+    '_indexExists',
+    '_putMapping',
+    '_scoreFromHit',
+    '_serializeConditions',
+    '_totalFromResponse',
+    '_upsert'
+];
+
+const MOCK_ENDPOINT = 'https://mock.collection.us-east-1.aoss.amazonaws.com';
+const MOCK_INDEX    = 'mock-index';
+const MOCK_MAPPING  = {properties: {name: {type: 'keyword'}}};
+
+
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+function buildOpenSearchDouble() {
+    return {
+        bulk:    jest.fn(),
+        delete:  jest.fn(),
+        index:   jest.fn(),
+        search:  jest.fn(),
+        update:  jest.fn(),
+        indices: {
+            create:     jest.fn(),
+            exists:     jest.fn(),
+            putMapping: jest.fn()
+        }
+    };
+}
+
+
+function buildSearchClientClass(settings = {}) {
+    const { AbstractSearchClient } = require('../../../lib/search/abstractSearchClient');
+
+    const numRetries      = settings.numRetries      || 0;
+    const deleteBatchSize = settings.deleteBatchSize || 500;
+
+    class MockSearchClient extends AbstractSearchClient {
+        get numRetries()        { return numRetries; }
+        get deleteBatchSize()   { return deleteBatchSize; }
+        get retryBackoffDelay() { return 0; }
+        get retryMaxDelay()     { return 0; }
+        get index()             { return MOCK_INDEX; }
+        get mapping()           { return MOCK_MAPPING; }
+    }
+
+    for (const hook of BACKEND_HOOKS) {
+        MockSearchClient.prototype[hook] = jest.fn();
+    }
+
+    return MockSearchClient;
+}
+
+
+function buildSearchClient(settings = {}) {
+    return new (buildSearchClientClass(settings))(settings.indexSuffix);
+}
+
+
+function buildOpenSearchClientClass(settings = {}) {
+    const { OpenSearchClient } = require('../../../lib/search/openSearchClient');
+
+    const openSearchDouble  = buildOpenSearchDouble();
+    const signerDouble      = jest.fn(() => ({Connection: 'signed-connection'}));
+    const clientClassDouble = jest.fn(function () { return openSearchDouble; });
+    const numRetries        = settings.numRetries || 0;
+
+    class MockOpenSearchClient extends OpenSearchClient {
+        get openSearchClientClass() { return clientClassDouble; }
+        get awsSignerFactory()      { return signerDouble; }
+        get endpoint()              { return MOCK_ENDPOINT; }
+        get index()                 { return MOCK_INDEX; }
+        get mapping()               { return MOCK_MAPPING; }
+        get numRetries()            { return numRetries; }
+        get retryBackoffDelay()     { return 0; }
+        get retryMaxDelay()         { return 0; }
+
+        get openSearchDouble()  { return openSearchDouble; }
+        get clientClassDouble() { return clientClassDouble; }
+        get signerDouble()      { return signerDouble; }
+    }
+
+    return MockOpenSearchClient;
+}
+
+
+function buildOpenSearchClient(settings = {}) {
+    return new (buildOpenSearchClientClass(settings))(settings.indexSuffix);
+}
+
+
+/***************************************************************************************************
+* VARIABLE GENERATION
+***************************************************************************************************/
+function buildSearchResponse(hits = [], total = hits.length) {
+    return {body: {hits: {total: {value: total}, hits}}};
+}
+
+
+function buildHit(id, source = {}, score = 1) {
+    return {_id: id, _score: score, _source: source};
+}
+
+
+function buildUnsupportedError() {
+    return Object.assign(new Error('Document ID is not supported for this collection'), {
+        statusCode: 400
+    });
+}
+
+
+module.exports = {
+    BACKEND_HOOKS,
+    MOCK_ENDPOINT,
+    MOCK_INDEX,
+    MOCK_MAPPING,
+    buildHit,
+    buildOpenSearchClient,
+    buildOpenSearchClientClass,
+    buildSearchClient,
+    buildSearchClientClass,
+    buildSearchResponse,
+    buildUnsupportedError
+};