@vida-global/core 2.0.11 → 2.1.0

package/test/server/controllerMixins/callbacks.test.js

@@ -0,0 +1,326 @@
+const { VidaServerController } = require('../../../lib/server/serverController');
+
+
+describe('VidaServerController', () => {
+    describe('#setupCallbacks', () => {
+        it ('is called once during construction and then cleared from the instance', () => {
+            class CallbacksTestController extends VidaServerController {}
+            CallbacksTestController.prototype.setupCallbacks = jest.fn();
+            const controller = new CallbacksTestController({}, {});
+
+            expect(CallbacksTestController.prototype.setupCallbacks).toHaveBeenCalledTimes(1);
+            expect(controller.setupCallbacks).toBe(undefined);
+        });
+
+        it ('is only called once per class across multiple instances', () => {
+            class CallbacksOnceController extends VidaServerController {}
+            CallbacksOnceController.prototype.setupCallbacks = jest.fn();
+
+            new CallbacksOnceController({}, {});
+            new CallbacksOnceController({}, {});
+            new CallbacksOnceController({}, {});
+
+            expect(CallbacksOnceController.prototype.setupCallbacks).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not duplicate registered callbacks across instances of the same class', async () => {
+            const callback = jest.fn();
+
+            class CallbacksAccumController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(callback); }
+            }
+
+            new CallbacksAccumController({}, {});
+            new CallbacksAccumController({}, {});
+            new CallbacksAccumController({}, {});
+            const controller = new CallbacksAccumController({}, {});
+
+            await controller._runCallbacks('before', 'getIndex');
+            expect(callback).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not share callbacks across different controller classes', async () => {
+            const callbackA = jest.fn();
+            const callbackB = jest.fn();
+
+            class CallbacksClassA extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(callbackA); }
+            }
+            class CallbacksClassB extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(callbackB); }
+            }
+
+            const a = new CallbacksClassA({}, {});
+            const b = new CallbacksClassB({}, {});
+
+            await a._runCallbacks('before', 'someAction');
+            expect(callbackA).toHaveBeenCalledTimes(1);
+            expect(callbackB).toHaveBeenCalledTimes(0);
+
+            await b._runCallbacks('before', 'someAction');
+            expect(callbackA).toHaveBeenCalledTimes(1);
+            expect(callbackB).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#_runCallbacks', () => {
+        it ('runs before-callbacks in registration order then the action', async () => {
+            const order = [];
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(() => { order.push('before1') });
+                    this.beforeCallback('namedBefore');
+                }
+                namedBefore() { order.push('before2') }
+                testAction()  { order.push('action');  return {} }
+            }
+            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(order).toEqual(['before1', 'before2', 'action']);
+        });
+
+        it ('runs after-callbacks in registration order after the action', async () => {
+            const order = [];
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.afterCallback(() => { order.push('after1') });
+                    this.afterCallback('namedAfter');
+                }
+                namedAfter() { order.push('after2') }
+                testAction() { order.push('action'); return {} }
+            }
+            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(order).toEqual(['action', 'after1', 'after2']);
+        });
+
+        it ('skips the action when a before-callback returns false', async () => {
+            const testAction = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() { this.beforeCallback(() => false) }
+            }
+            C.prototype.testAction = testAction;
+            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(testAction).not.toHaveBeenCalled();
+        });
+
+        it ('skips remaining before-callbacks when one returns false', async () => {
+            const second = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(() => false);
+                    this.beforeCallback(second);
+                }
+                testAction() { return {} }
+            }
+            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(second).not.toHaveBeenCalled();
+        });
+
+        it ('skips after-callbacks when a before-callback returns false', async () => {
+            const after = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(() => false);
+                    this.afterCallback(after);
+                }
+                testAction() { return {} }
+            }
+            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const controller = new C({}, response);
+
+            await controller.performRequest('testAction');
+            expect(after).not.toHaveBeenCalled();
+        });
+
+        it ('respects only/except options when running callbacks', async () => {
+            const onlyCb   = jest.fn();
+            const exceptCb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(onlyCb,   {only:   ['allowed']});
+                    this.beforeCallback(exceptCb, {except: ['blocked']});
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'allowed');
+            expect(onlyCb).toHaveBeenCalledTimes(1);
+            expect(exceptCb).toHaveBeenCalledTimes(1);
+
+            await controller._runCallbacks('before', 'blocked');
+            expect(onlyCb).toHaveBeenCalledTimes(1);
+            expect(exceptCb).toHaveBeenCalledTimes(1);
+
+            await controller._runCallbacks('before', 'other');
+            expect(onlyCb).toHaveBeenCalledTimes(1);
+            expect(exceptCb).toHaveBeenCalledTimes(2);
+        });
+
+        it ('supports both function and method-name string callbacks', async () => {
+            const fnCb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(fnCb);
+                    this.beforeCallback('namedCb');
+                }
+            }
+            C.prototype.namedCb = jest.fn();
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'someAction');
+            expect(fnCb).toHaveBeenCalledTimes(1);
+            expect(C.prototype.namedCb).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#skipBeforeCallback / #skipAfterCallback', () => {
+        it ('skips a registered before-callback when the same function reference is in the skip list', async () => {
+            const skipped = jest.fn();
+            const kept    = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(skipped);
+                    this.beforeCallback(kept);
+                    this.skipBeforeCallback(skipped);
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'someAction');
+            expect(skipped).not.toHaveBeenCalled();
+            expect(kept).toHaveBeenCalledTimes(1);
+        });
+
+        it ('skips a registered before-callback by method-name string', async () => {
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback('namedCb');
+                    this.skipBeforeCallback('namedCb');
+                }
+            }
+            C.prototype.namedCb = jest.fn();
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'someAction');
+            expect(C.prototype.namedCb).not.toHaveBeenCalled();
+        });
+
+        it ('skips a registered after-callback when in the after skip list', async () => {
+            const skipped = jest.fn();
+            const kept    = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.afterCallback(skipped);
+                    this.afterCallback(kept);
+                    this.skipAfterCallback(skipped);
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('after', 'someAction');
+            expect(skipped).not.toHaveBeenCalled();
+            expect(kept).toHaveBeenCalledTimes(1);
+        });
+
+        it ('only applies the skip on actions matching the skip\'s only option', async () => {
+            const cb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(cb);
+                    this.skipBeforeCallback(cb, {only: 'skipMe'});
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'skipMe');
+            expect(cb).not.toHaveBeenCalled();
+
+            await controller._runCallbacks('before', 'otherAction');
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it ('applies the skip on all actions except those listed in the skip\'s except option', async () => {
+            const cb = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(cb);
+                    this.skipBeforeCallback(cb, {except: 'keepMe'});
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'keepMe');
+            expect(cb).toHaveBeenCalledTimes(1);
+
+            await controller._runCallbacks('before', 'somethingElse');
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not affect callbacks whose identity does not match the skip entry', async () => {
+            const cb    = jest.fn();
+            const other = jest.fn();
+            class C extends VidaServerController {
+                setupCallbacks() {
+                    this.beforeCallback(cb);
+                    this.skipBeforeCallback(other);
+                }
+            }
+            const controller = new C({}, {});
+
+            await controller._runCallbacks('before', 'anyAction');
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+    });
+
+
+    describe('#isAuthenticatedAction', () => {
+        it ('returns false when no authenticateRequest callback is registered', () => {
+            class NoAuthController extends VidaServerController {}
+            const controller = new NoAuthController({}, {});
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(false);
+        });
+
+        it ('returns true for any action when authenticateRequest is registered without restrictions', () => {
+            class AuthAllController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback('authenticateRequest'); }
+                authenticateRequest() {}
+            }
+            const controller = new AuthAllController({}, {});
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(true);
+            expect(controller.isAuthenticatedAction('getOther')).toBe(true);
+        });
+
+        it ('respects the `except` option on the authenticateRequest callback', () => {
+            class AuthExceptController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback('authenticateRequest', {except: 'getOpen'}); }
+                authenticateRequest() {}
+            }
+            const controller = new AuthExceptController({}, {});
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(true);
+            expect(controller.isAuthenticatedAction('getOpen')).toBe(false);
+        });
+
+        it ('respects the `only` option on the authenticateRequest callback', () => {
+            class AuthOnlyController extends VidaServerController {
+                setupCallbacks() { this.beforeCallback('authenticateRequest', {only: ['getSecret']}); }
+                authenticateRequest() {}
+            }
+            const controller = new AuthOnlyController({}, {});
+            expect(controller.isAuthenticatedAction('getSecret')).toBe(true);
+            expect(controller.isAuthenticatedAction('getIndex')).toBe(false);
+        });
+    });
+});

package/test/server/controllerMixins/classScopedRegistry.test.js

@@ -0,0 +1,95 @@
+const { ClassScopedRegistry, appliesToAction } = require('../../../lib/server/controllerMixins/classScopedRegistry');
+
+
+describe('appliesToAction', () => {
+    it.each([
+        ['no options matches every action',        {},                          'getIndex', true],
+        ['only string matches the named action',   { only: 'getIndex' },        'getIndex', true],
+        ['only string excludes other actions',     { only: 'getIndex' },        'getRecord', false],
+        ['only array matches a listed action',     { only: ['getIndex', 'a'] }, 'a',        true],
+        ['only array excludes unlisted actions',   { only: ['getIndex', 'a'] }, 'getRecord', false],
+        ['except string excludes the named one',   { except: 'getIndex' },      'getIndex', false],
+        ['except string matches other actions',    { except: 'getIndex' },      'getRecord', true],
+        ['except array excludes a listed action',  { except: ['a', 'b'] },      'b',        false],
+        ['except array matches unlisted actions',  { except: ['a', 'b'] },      'getRecord', true],
+    ])('%s', (_label, options, actionName, expected) => {
+        expect(appliesToAction(actionName, options)).toBe(expected);
+    });
+});
+
+
+describe('ClassScopedRegistry', () => {
+    describe('#list', () => {
+        it ('returns the same array for repeated calls with the same name and class', () => {
+            const registry   = new ClassScopedRegistry();
+            const controller = { constructor: class A {} };
+
+            const first  = registry.list('callbacks', controller);
+            const second = registry.list('callbacks', controller);
+
+            expect(second).toBe(first);
+        });
+
+        it ('isolates lists by controller class', () => {
+            const registry = new ClassScopedRegistry();
+            const a        = { constructor: class A {} };
+            const b        = { constructor: class B {} };
+
+            registry.list('callbacks', a).push('from-a');
+
+            expect(registry.list('callbacks', b)).toEqual([]);
+        });
+
+        it ('isolates lists by name within the same class', () => {
+            const registry   = new ClassScopedRegistry();
+            const controller = { constructor: class A {} };
+
+            registry.list('before', controller).push('x');
+
+            expect(registry.list('after', controller)).toEqual([]);
+        });
+    });
+
+
+    describe('#applySetupOnce', () => {
+        it ('runs the hook once per class across multiple instances', () => {
+            const registry = new ClassScopedRegistry();
+            class Controller {}
+            Controller.prototype.setup = jest.fn();
+
+            const a = new Controller();
+            registry.applySetupOnce(a, 'setup');
+            const b = new Controller();
+            registry.applySetupOnce(b, 'setup');
+
+            expect(Controller.prototype.setup).toHaveBeenCalledTimes(1);
+        });
+
+        it ('clears the hook from the instance after applying', () => {
+            const registry = new ClassScopedRegistry();
+            class Controller {}
+            Controller.prototype.setup = jest.fn();
+            const controller = new Controller();
+
+            registry.applySetupOnce(controller, 'setup');
+
+            expect(controller.setup).toBe(undefined);
+        });
+
+        it ('runs the hook again for a different class', () => {
+            const registry = new ClassScopedRegistry();
+            const setupA   = jest.fn();
+            const setupB   = jest.fn();
+            class A {}
+            class B {}
+            A.prototype.setup = setupA;
+            B.prototype.setup = setupB;
+
+            registry.applySetupOnce(new A(), 'setup');
+            registry.applySetupOnce(new B(), 'setup');
+
+            expect(setupA).toHaveBeenCalledTimes(1);
+            expect(setupB).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/test/server/controllerMixins/documentation.test.js

@@ -0,0 +1,168 @@
+const { VidaServerController } = require('../../../lib/server/serverController');
+
+
+describe('VidaServerController', () => {
+    describe('#setupDocumentation', () => {
+        it ('is called once during construction and then cleared from the instance', () => {
+            class DocSetupController extends VidaServerController {}
+            DocSetupController.prototype.setupDocumentation = jest.fn();
+            const controller = new DocSetupController({}, {});
+
+            expect(DocSetupController.prototype.setupDocumentation).toHaveBeenCalledTimes(1);
+            expect(controller.setupDocumentation).toBe(undefined);
+        });
+
+        it ('is only called once per class across multiple instances', () => {
+            class DocOnceController extends VidaServerController {}
+            DocOnceController.prototype.setupDocumentation = jest.fn();
+
+            new DocOnceController({}, {});
+            new DocOnceController({}, {});
+            new DocOnceController({}, {});
+
+            expect(DocOnceController.prototype.setupDocumentation).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not duplicate registered tags across instances of the same class', () => {
+            class DocAccumController extends VidaServerController {
+                setupDocumentation() { this.documentationTag('Things'); }
+            }
+
+            new DocAccumController({}, {});
+            new DocAccumController({}, {});
+            const controller = new DocAccumController({}, {});
+
+            expect(controller.tagsForAction('getIndex')).toEqual(['Things']);
+        });
+
+        it ('does not share tags across different controller classes', () => {
+            class DocClassA extends VidaServerController {
+                setupDocumentation() { this.documentationTag('A'); }
+            }
+            class DocClassB extends VidaServerController {
+                setupDocumentation() { this.documentationTag('B'); }
+            }
+
+            const a = new DocClassA({}, {});
+            const b = new DocClassB({}, {});
+
+            expect(a.tagsForAction('someAction')).toEqual(['A']);
+            expect(b.tagsForAction('someAction')).toEqual(['B']);
+        });
+    });
+
+
+    describe('#tagsForAction', () => {
+        it ('returns every declared tag when no only/except option is set', () => {
+            class DocAllController extends VidaServerController {
+                setupDocumentation() {
+                    this.documentationTag('Things');
+                    this.documentationTag('Admin');
+                }
+            }
+            const controller = new DocAllController({}, {});
+
+            expect(controller.tagsForAction('getIndex')).toEqual(['Things', 'Admin']);
+        });
+
+        it ('restricts a tag to the action named in a string only option', () => {
+            class DocOnlyStringController extends VidaServerController {
+                setupDocumentation() { this.documentationTag('Admin', { only: 'deleteRecord' }); }
+            }
+            const controller = new DocOnlyStringController({}, {});
+
+            expect(controller.tagsForAction('deleteRecord')).toEqual(['Admin']);
+            expect(controller.tagsForAction('getIndex')).toEqual([]);
+        });
+
+        it ('restricts a tag to the actions listed in an array only option', () => {
+            class DocOnlyArrayController extends VidaServerController {
+                setupDocumentation() { this.documentationTag('Admin', { only: ['deleteRecord', 'putRecord'] }); }
+            }
+            const controller = new DocOnlyArrayController({}, {});
+
+            expect(controller.tagsForAction('deleteRecord')).toEqual(['Admin']);
+            expect(controller.tagsForAction('putRecord')).toEqual(['Admin']);
+            expect(controller.tagsForAction('getIndex')).toEqual([]);
+        });
+
+        it ('excludes the action named in a string except option', () => {
+            class DocExceptStringController extends VidaServerController {
+                setupDocumentation() { this.documentationTag('Users', { except: 'getHealth' }); }
+            }
+            const controller = new DocExceptStringController({}, {});
+
+            expect(controller.tagsForAction('getIndex')).toEqual(['Users']);
+            expect(controller.tagsForAction('getHealth')).toEqual([]);
+        });
+
+        it ('excludes the actions listed in an array except option', () => {
+            class DocExceptArrayController extends VidaServerController {
+                setupDocumentation() { this.documentationTag('Users', { except: ['getHealth', 'getStatus'] }); }
+            }
+            const controller = new DocExceptArrayController({}, {});
+
+            expect(controller.tagsForAction('getIndex')).toEqual(['Users']);
+            expect(controller.tagsForAction('getHealth')).toEqual([]);
+            expect(controller.tagsForAction('getStatus')).toEqual([]);
+        });
+
+        it ('returns an empty list for a controller that declares no tag', () => {
+            class DocNoneController extends VidaServerController {}
+            const controller = new DocNoneController({}, {});
+
+            expect(controller.tagsForAction('anyAction')).toEqual([]);
+        });
+    });
+
+
+    describe('._tagsDocumentation', () => {
+        it ('returns the tag names honoring only/except for the given action', () => {
+            class DocStaticController extends VidaServerController {
+                setupDocumentation() {
+                    this.documentationTag('Users');
+                    this.documentationTag('Admin', { only: 'deleteRecord' });
+                }
+            }
+
+            expect(DocStaticController._tagsDocumentation('getIndex')).toEqual(['Users']);
+            expect(DocStaticController._tagsDocumentation('deleteRecord')).toEqual(['Users', 'Admin']);
+        });
+
+        it ('returns an empty list for a controller with no tags', () => {
+            class DocStaticNoneController extends VidaServerController {}
+
+            expect(DocStaticNoneController._tagsDocumentation('anyAction')).toEqual([]);
+        });
+    });
+
+
+    describe('.documentationTagDefinitions', () => {
+        it ('returns a de-duplicated catalogue including the option-supplied description', () => {
+            class DocDefsController extends VidaServerController {
+                setupDocumentation() {
+                    this.documentationTag('Users', { description: 'User endpoints', except: 'getHealth' });
+                    this.documentationTag('Admin', { only: 'deleteRecord' });
+                }
+            }
+
+            expect(DocDefsController.documentationTagDefinitions()).toEqual([
+                { name: 'Users', description: 'User endpoints' },
+                { name: 'Admin', description: '' },
+            ]);
+        });
+
+        it ('keeps the first description when the same tag is declared twice', () => {
+            class DocDefsDupController extends VidaServerController {
+                setupDocumentation() {
+                    this.documentationTag('Users', { description: 'First' });
+                    this.documentationTag('Users', { description: 'Second' });
+                }
+            }
+
+            expect(DocDefsDupController.documentationTagDefinitions()).toEqual([
+                { name: 'Users', description: 'First' },
+            ]);
+        });
+    });
+});