@vida-global/core 2.4.0 → 2.4.1

package/index.js

@@ -1,11 +1,12 @@
-const   ActiveRecord    = require('./lib/activeRecord');
-const   httpLibs        = require('./lib/http/client');
-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');
+const   ActiveRecord      = require('./lib/activeRecord');
+const   httpLibs          = require('./lib/http/client');
+const   APM               = require('./lib/apm');
+const { AppDependencies } = require('./lib/appDependencies');
+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');
 
 
 const {
@@ -27,6 +28,7 @@ module.exports = {
     ...redisLibs,
     ...serverErrorsToExport,
     ApiDocsGenerator,
+    AppDependencies,
     VidaServer,
     VidaServerController,
 };

package/lib/appDependencies/index.js

@@ -0,0 +1,48 @@
+class AppDependencies {
+    #dependencies    = {};
+    #controllerClass = null;
+
+
+    installOn(controllerClass) {
+        this.#controllerClass = controllerClass;
+        for (const name of Object.keys(this.#dependencies)) this.#defineAccessor(name);
+    }
+
+
+    setDependency(name, dependency) {
+        this.#dependencies[name] = dependency;
+        this.#defineAccessor(name);
+    }
+
+
+    get(name) {
+        return this.#dependencies[name] ?? null;
+    }
+
+
+    // Mainly for tests, which register their own doubles and must not leak them into the next one.
+    reset() {
+        this.#dependencies = {};
+    }
+
+
+    // Registering after `installOn` still defines the accessor, so wiring order does not matter.
+    // An existing property is left alone: a controller that defines the name itself wins.
+    #defineAccessor(name) {
+        if (!this.#controllerClass) return;
+
+        const prototype = this.#controllerClass.prototype;
+        if (Object.getOwnPropertyDescriptor(prototype, name)) return;
+
+        const dependencies = this;
+        Object.defineProperty(prototype, name, {
+            configurable: false,
+            get() { return dependencies.get(name); }
+        });
+    }
+}
+
+
+module.exports = {
+    AppDependencies: new AppDependencies()
+};

package/lib/server/README.md

@@ -130,7 +130,38 @@ See [Callbacks](./doc/callbacks.md) — before/after action callbacks and how su
 
 ## Rendering responses
 
-See [Rendering responses](./doc/renderer.md) — the render envelope, status-code helpers, error handling, and Server-Sent Events / streaming.
+See [Rendering responses](./doc/renderer.md) — the render envelope, status-code helpers, binary and file responses, error handling, and Server-Sent Events / streaming.
+
+
+## App dependencies
+
+`AppDependencies` is a registry for the long-lived collaborators an application builds at boot — helper libraries, service objects, queues. Code that runs far from that wiring reaches them by name instead of having them threaded through every call.
+
+```js
+// at boot
+const { AppDependencies } = require('@vida-global/core');
+
+AppDependencies.setDependency('billingHelper', billingHelper);
+AppDependencies.installOn(MyBaseController);
+```
+
+`installOn` exposes every registered name as a getter on that controller class, so controllers read the dependency directly:
+
+```js
+class InvoicesController extends MyBaseController {
+    async getIndex() {
+        return await this.billingHelper.invoicesFor(this.currentUser);
+    }
+}
+```
+
+Anything else reads them off the registry:
+
+```js
+const helper = AppDependencies.get('billingHelper');   // null when nothing is registered
+```
+
+Registration order does not matter — a dependency registered after `installOn` still gets its accessor. A controller that already defines the name keeps its own property. `reset()` clears the registry, which tests need so their doubles do not leak into the next one.
 
 
 ## Documentation

package/lib/server/controllerMixins/renderer.js

@@ -244,6 +244,17 @@ const InstanceMethods = {
     /***********************************************************************************************
     * FILE RENDERING
     ***********************************************************************************************/
+    renderBinary(body, { contentType, filename } = {}) {
+        if (this.rendered)    return;
+        if (this.isStreaming) return;
+
+        this._response.setHeader('Content-Type', contentType);
+        if (filename) this._response.attachment(filename);
+        this._send(body);
+        this.markRendered();
+    },
+
+
     renderFile(filePath, { contentType, cacheControl, maxAge } = {}) {
         if (!filePath) throw new Error('renderFile requires a filePath');
         const resolvedType = contentType || guessContentType(filePath);

package/lib/server/doc/renderer.md

@@ -70,6 +70,29 @@ Don't set `this.statusCode` directly — use the helper that pairs the status wi
 After a render helper runs, the action does not need to return — the response has already been sent.
 
 
+## Binary responses
+
+`render` JSON encodes its body, which corrupts anything that is not text. Use `renderBinary` for a
+body you already hold in memory — a buffer proxied from another service, a generated document.
+
+```js
+async getRecordRecording() {
+    const { body, contentType } = await fetchRecording(sid);
+    this.renderBinary(body, { contentType });
+}
+```
+
+Naming a `filename` sets `Content-Disposition`, so the browser downloads the body instead of
+displaying it:
+
+```js
+this.renderBinary(csv, { contentType: 'text/csv', filename: 'report.csv' });
+```
+
+To send a file from disk rather than from memory, use `renderFile(path, { contentType,
+cacheControl, maxAge })` instead — it streams and guesses the content type from the extension.
+
+
 ## Error handling
 
 ```js

package/package.json

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

package/test/appDependencies/appDependencies.test.js

@@ -0,0 +1,93 @@
+const { AppDependencies } = require('../../lib/appDependencies');
+
+
+class FooController {}
+class BarController {}
+
+
+afterEach(() => AppDependencies.reset());
+
+
+describe('AppDependencies', () => {
+    describe('#get', () => {
+        it ('returns what was registered', () => {
+            const helper = { name: 'helper' };
+
+            AppDependencies.setDependency('myHelper', helper);
+
+            expect(AppDependencies.get('myHelper')).toBe(helper);
+        });
+
+
+        // Null rather than undefined, so a missing dependency reads the same as one registered as
+        // nothing and callers can test it with a single check.
+        it ('returns null for a name nothing registered', () => {
+            expect(AppDependencies.get('nothingHere')).toBeNull();
+        });
+
+
+        it ('replaces a name that is registered twice', () => {
+            AppDependencies.setDependency('myHelper', 'first');
+            AppDependencies.setDependency('myHelper', 'second');
+
+            expect(AppDependencies.get('myHelper')).toBe('second');
+        });
+    });
+
+
+    describe('#reset', () => {
+        it ('forgets everything registered', () => {
+            AppDependencies.setDependency('myHelper', 'something');
+
+            AppDependencies.reset();
+
+            expect(AppDependencies.get('myHelper')).toBeNull();
+        });
+    });
+
+
+    describe('#installOn', () => {
+        it ('exposes what was registered before the install as a getter', () => {
+            AppDependencies.setDependency('myHelper', 'early');
+
+            AppDependencies.installOn(FooController);
+
+            expect(new FooController().myHelper).toBe('early');
+        });
+
+
+        // Wiring order must not matter: a dependency registered after the install still appears.
+        it ('exposes what is registered after the install', () => {
+            AppDependencies.installOn(FooController);
+
+            AppDependencies.setDependency('lateHelper', 'late');
+
+            expect(new FooController().lateHelper).toBe('late');
+        });
+
+
+        it ('reads through, so a later replacement is picked up', () => {
+            AppDependencies.installOn(FooController);
+            AppDependencies.setDependency('myHelper', 'first');
+            const controller = new FooController();
+
+            AppDependencies.setDependency('myHelper', 'second');
+
+            expect(controller.myHelper).toBe('second');
+        });
+
+
+        // A controller that defines the name itself keeps its own.
+        it ('does not overwrite a property the controller already has', () => {
+            Object.defineProperty(BarController.prototype, 'ownProperty', {
+                configurable: true,
+                get() { return 'mine' },
+            });
+
+            AppDependencies.setDependency('ownProperty', 'theirs');
+            AppDependencies.installOn(BarController);
+
+            expect(new BarController().ownProperty).toBe('mine');
+        });
+    });
+});

package/test/server/controllerMixins/renderer.test.js

@@ -751,6 +751,65 @@ describe('VidaServerController', () => {
     });
 
 
+    describe('#renderBinary', () => {
+        let request;
+        let response;
+        let controller;
+
+
+        beforeEach(() => {
+            request    = {};
+            response   = {
+                setHeader:  jest.fn(),
+                attachment: jest.fn(),
+                send:       jest.fn(),
+            };
+            controller = new FooController(request, response);
+        });
+
+
+        it ('sends the body untouched with the given content type', () => {
+            const body = Buffer.from([0x00, 0x01, 0x02]);
+
+            controller.renderBinary(body, { contentType: 'audio/wav' });
+
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'audio/wav');
+            expect(response.send).toHaveBeenCalledWith(body);
+        });
+
+
+        it ('marks the response rendered', () => {
+            controller.renderBinary(Buffer.from('x'), { contentType: 'audio/wav' });
+
+            expect(controller.rendered).toBe(true);
+        });
+
+
+        it ('sets a download filename when one is given', () => {
+            controller.renderBinary(Buffer.from('x'), { contentType: 'audio/wav', filename: 'call.wav' });
+
+            expect(response.attachment).toHaveBeenCalledWith('call.wav');
+        });
+
+
+        // Without a filename the body is displayed rather than downloaded.
+        it ('sets no filename when none is given', () => {
+            controller.renderBinary(Buffer.from('x'), { contentType: 'audio/wav' });
+
+            expect(response.attachment).not.toHaveBeenCalled();
+        });
+
+
+        it ('is a no-op once something has already been rendered', () => {
+            controller.markRendered();
+
+            controller.renderBinary(Buffer.from('x'), { contentType: 'audio/wav' });
+
+            expect(response.send).not.toHaveBeenCalled();
+        });
+    });
+
+
     describe('#renderFile', () => {
         let request;
         let response;