@vida-global/core 2.1.0 → 2.1.2

package/lib/activeRecord/baseRecord.js

@@ -33,21 +33,74 @@ class BaseRecord extends Model {
     /***********************************************************************************************
     * QUERIES
     ***********************************************************************************************/
-    static async find(ids) {
+    static async find(ids, { useWriteDB=false, ...options }={}) {
         if (this.isCacheable) {
-            return await this._cachedFind(...arguments);
+            return await this._cachedFind(ids, options);
         } else if (Array.isArray(ids)) {
             const pk = this.primaryKeyAttribute
-            return await this.where({[pk]: ids});
+            return await this.where({[pk]: ids}, { useMaster: useWriteDB });
         } else {
-            return await this.findByPk(ids);
+            return await this.findByPk(ids, { useMaster: useWriteDB });
         }
     }
 
 
     static async where(where, options={}) {
-        const parameters = {...options, where };
-        return await this.findAll(parameters);
+        const { page, pageSize, ...queryOptions } = options;
+
+        if (!page && !pageSize) {
+            const parameters = {...queryOptions, where };
+            return await this.findAll(parameters);
+        }
+
+        const offset = pageSize * (page - 1);
+        const rows = await this.findAll({
+            ...queryOptions,
+            where,
+            order: queryOptions.order || [this.defaultSort()],
+            limit: pageSize,
+            offset,
+        });
+
+        const totalCount = await this.paginatedTotalCount(rows, where,
+            {
+                offset,
+                pageSize,
+                queryOptions,
+            })
+
+        return { rows, totalCount }
+    }
+
+
+    static async transaction(callback) {
+        return await this.connection.queryInterface.transaction(callback);
+    }
+
+
+    static defaultSort() {
+        return ['created_at', 'DESC'];
+    }
+
+
+    static async paginatedTotalCount(rows, where, { offset, pageSize, queryOptions }) {
+        const isFullPage = rows.length === pageSize
+        const isEmptyPageAfterFirst = rows.length === 0 && offset > 0
+
+        if (isFullPage || isEmptyPageAfterFirst) {
+            return await this.count({...queryOptions, where })
+        }
+
+        return offset + rows.length
+    }
+
+
+    static async execute(query, { raw=false, ...options }={}) {
+        return await this.sequelize.query(query, {
+            type: Sequelize.QueryTypes.SELECT,
+            ...(raw ? {} : { model: this, mapToModel: true }),
+            ...options
+        });
     }
 
 
@@ -78,10 +131,16 @@ class BaseRecord extends Model {
             updatedAt: 'updated_at',
         }
 
-        if (!schema.created_at || !schema.updated_at) {
+        const hasTimestamps = schema.created_at && schema.updated_at;
+
+        if (!hasTimestamps) {
             options.timestamps = false;
         }
 
+        if (hasTimestamps && schema.deleted_at) {
+            options.paranoid = true;
+        }
+
         this.configureOverridenAccessors(schema);
         this.configureVirtualAccessors(schema);
 
@@ -376,17 +435,33 @@ class BaseRecord extends Model {
     toApiResponse() {
       const response = {};
       for (const column of this.apiResponseColumns) {
-        response[column] = this[column]; // Use overridden getters when available
+        response[this.apiResponseKey(column)] = this[column]; // Use overridden getters when available
       }
       return response;
     }
 
 
+    toObject() {
+      return this.toApiResponse();
+    }
+
+
     get apiResponseColumns() {
       return Object.keys(this.constructor.documentationSchema());
     }
 
 
+    apiResponseKey(column) {
+      if (!this.camelizeFieldsForApiResponse) return column;
+      return camelize(column, true);
+    }
+
+
+    get camelizeFieldsForApiResponse() {
+      return false;
+    }
+
+
     /***********************************************************************************************
     * DOCUMENTATION
     ***********************************************************************************************/

package/lib/activeRecord/db/queryInterface.js

@@ -25,7 +25,7 @@ class QueryInterface {
 
 
     async transaction(callback) {
-        await this.#sequelize.transaction(callback); 
+        return await this.#sequelize.transaction(callback); 
     }
 
 

package/lib/http/README.md

@@ -25,10 +25,8 @@ class MyApiClient extends HttpClient {
         return this.#dev ? 'https://staging.foo.com' : 'https://foo.com';
     }
 
-    get defaultHeaders() {
-        const headers = super.defaultHeaders;
-        headers.Authorization = `Bearer ${this.#token}`;
-        return headers;
+    get bearerToken() {
+        return this.#token;
     }
 
     async getTickets({ page, pageSize }) {
@@ -104,4 +102,6 @@ Subclasses customize behavior through getters on the class:
 
 - `urlRoot` — base URL prepended to every endpoint.
 - `defaultHeaders` — merged into every request (per-call `headers` override).
+- `bearerToken` — when it returns a value, a `Authorization: Bearer <token>` header is added to `defaultHeaders`.
+- `basicAuthUsername` / `basicAuthPassword` — when both return values, a `Authorization: Basic <base64>` header is added to `defaultHeaders`. `bearerToken` takes precedence if both are set.
 - `logger` — scoped logger used for the `API CALL: ...` debug line emitted on each request (defaults to `logger.http`).

package/lib/http/client.js

@@ -178,10 +178,41 @@ class HttpClient {
 
 
     get defaultHeaders() {
-        return {
+        const headers = {
             Accept: "application/json",
             "Content-Type": "application/json",
-        }
+        };
+        if (this.authorizationHeader) headers.Authorization = this.authorizationHeader;
+        return headers;
+    }
+
+
+    get authorizationHeader() {
+        if (this.bearerToken)          return `Bearer ${this.bearerToken}`;
+        if (this.basicAuthCredentials) return `Basic ${this.basicAuthCredentials}`;
+        return null;
+    }
+
+
+    get bearerToken() {
+        return null;
+    }
+
+
+    get basicAuthCredentials() {
+        if (!this.basicAuthUsername || !this.basicAuthPassword) return null;
+        const credentials = `${this.basicAuthUsername}:${this.basicAuthPassword}`;
+        return Buffer.from(credentials).toString('base64');
+    }
+
+
+    get basicAuthUsername() {
+        return null;
+    }
+
+
+    get basicAuthPassword() {
+        return null;
     }
 
 

package/lib/server/controllerMixins/renderer.js

@@ -51,6 +51,9 @@ function setSseHeaders(controller) {
 
 
 const InstanceMethods = {
+    MIME_TYPES: CONTENT_TYPE_BY_EXTENSION,
+
+
     async render(body, options={}) {
         if (this.rendered)    return;
         if (this.isStreaming) return;
@@ -76,21 +79,21 @@ const InstanceMethods = {
 
 
     renderJSONResponse(body) {
-        this.setHeader('content-type', CONTENT_TYPE_BY_EXTENSION.json);
+        if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.json;
         this._response.json(body);
     },
 
 
     renderXMLResponse(body) {
-        this.setHeader('content-type', CONTENT_TYPE_BY_EXTENSION.xml);
-        const doc = create({ response: body });
+        if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.xml;
+        const doc = create({ [this.xmlRootElement]: body });
         const xml = doc.end();
         this._response.send(xml);
     },
 
 
     renderTextResponse(body) {
-        this.setHeader('content-type', CONTENT_TYPE_BY_EXTENSION.txt);
+        if (!this.responseContentType) this.responseContentType = CONTENT_TYPE_BY_EXTENSION.txt;
         this._response.send(body);
     },
 
@@ -163,7 +166,7 @@ const InstanceMethods = {
 
 
     _serializeDateForResponseBody(date, options) {
-        return date.getTime();
+        return Math.floor(date.getTime() / 1000);
     },
 
 
@@ -186,33 +189,6 @@ const InstanceMethods = {
     },
 
 
-    _setupStatusRenderers() {
-        const successStatuses = {
-            CreationSuccessful: 201,
-            Accepted:           202,
-            NoConent:           204,
-            MovedPermanently:   301,
-            Found:              302,
-            NotModified:        304,
-            TemporaryRedirect:  307,
-            PermanentRedirect:  308,
-        }
-
-        for (let [type, statusCode] of Object.entries(Errors.Statuses)) {
-            if (type == 'Server') type = 'ServerError';
-            this[`render${type}`] = async function(message=null, body=null) {
-                return await this._renderError(statusCode, message, body);
-            }
-        }
-
-        for (let [type, statusCode] of Object.entries(successStatuses)) {
-            this[`render${type}`] = async function(body=null) {
-                return await this._renderSuccess(statusCode, body);
-            }
-        }
-    },
-
-
     async _renderError(statusCode, message, body) {
         this.statusCode     = statusCode;
         body                = structuredClone(body || {});
@@ -305,7 +281,37 @@ const InstanceMethods = {
 }
 
 
+const StatusRenderSuccessStatuses = {
+    CreationSuccessful: 201,
+    Accepted:           202,
+    NoContent:          204,
+    MovedPermanently:   301,
+    Found:              302,
+    NotModified:        304,
+    TemporaryRedirect:  307,
+    PermanentRedirect:  308,
+}
+
+
 const StaticMethods = {
+    // Define render<Status> helpers on the prototype (not per instance) so subclasses and mixins
+    // can override them with a normal method of the same name.
+    setupStatusRenderers() {
+        for (let [type, statusCode] of Object.entries(Errors.Statuses)) {
+            if (type == 'Server') type = 'ServerError';
+            this.prototype[`render${type}`] = async function(message=null, body=null) {
+                return await this._renderError(statusCode, message, body);
+            }
+        }
+
+        for (const [type, statusCode] of Object.entries(StatusRenderSuccessStatuses)) {
+            this.prototype[`render${type}`] = async function(body=null) {
+                return await this._renderSuccess(statusCode, body);
+            }
+        }
+    },
+
+
     formatResponseBody(body, errors, { statusCode, statusText }) {
         const response = {data: body, status: statusText};
         if (errors) response.errors = errors;
@@ -325,7 +331,6 @@ const Accessors = {
         get() {
             const override = `${this.params._format || ''}`.toLowerCase();
             if (override === 'xml' || override === 'json') return override;
-            if (/\bxml\b/i.test(this.requestHeaders.accept || '')) return 'xml';
             return 'json';
         }
     },
@@ -341,6 +346,19 @@ const Accessors = {
     },
 
 
+    responseContentType: {
+        get()     { return this._response.getHeader('content-type') },
+        set(type) { return this._response.setHeader('content-type', type) }
+    },
+
+
+    // Root element wrapped around XML response bodies. Override in a subclass to emit a custom
+    // root (e.g. a TwiML `<Response>` for a telecom webhook).
+    xmlRootElement: {
+        get() { return 'response' }
+    },
+
+
     statusText: {
         get() {
             return STATUS_TEXTS[this.statusCode];

package/lib/server/doc/renderer.md

@@ -47,7 +47,7 @@ Don't set `this.statusCode` directly — use the helper that pairs the status wi
 |---|---|
 | 201 Created | `this.renderCreationSuccessful(body)` |
 | 202 Accepted | `this.renderAccepted(body)` |
-| 204 No Content | `this.renderNoConent(body)` |
+| 204 No Content | `this.renderNoContent(body)` |
 | 301 Moved Permanently | `this.renderMovedPermanently(body)` |
 | 302 Found | `this.renderFound(body)` |
 | 304 Not Modified | `this.renderNotModified(body)` |

package/lib/server/serverController.js

@@ -23,7 +23,6 @@ class VidaServerController {
 
         this._applyCallbacks();
         this._applyDocumentation();
-        this._setupStatusRenderers();
     }
 
 
@@ -260,6 +259,8 @@ VidaServerController.loadMixin(RendererMixin);
 VidaServerController.loadMixin(RoutingMixin);
 VidaServerController.loadMixin(ValidationMixin);
 
+VidaServerController.setupStatusRenderers();
+
 
 /***************************************************************************************************
 * ERRORS

package/package.json

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

package/test/activeRecord/baseRecord.test.js

@@ -165,8 +165,58 @@ describe('BaseRecord', () => {
                                                       sequelize: new Helpers.MockSequelize(),
                                                       tableName: 'users',
                                                       timestamps: false,
-                                                      updatedAt: 'updated_at'
-                                                    });
+                                                       updatedAt: 'updated_at'
+                                                     });
+        });
+
+        it ('uses `paranoid: true` when the schema has timestamps and deleted_at', () => {
+            importSchema.mockImplementation(() => ({
+                created_at: {type: Helpers.dataTypeValue1},
+                deleted_at: {type: Helpers.dataTypeValue2},
+                updated_at: {type: Helpers.dataTypeValue2},
+            }));
+            class User extends BaseRecord {}
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                {
+                    created_at: {type: Sequelize.DataTypes[Helpers.dataTypeKey1]},
+                    deleted_at: {type: Sequelize.DataTypes[Helpers.dataTypeKey2]},
+                    updated_at: {type: Sequelize.DataTypes[Helpers.dataTypeKey2]},
+                },
+                {
+                    createdAt: 'created_at',
+                    deletedAt: 'deleted_at',
+                    modelName: 'User',
+                    paranoid: true,
+                    sequelize: new Helpers.MockSequelize(),
+                    tableName: 'users',
+                    updatedAt: 'updated_at'
+                }
+            );
+        });
+
+        it ('does not use `paranoid: true` when the schema has deleted_at but no timestamps', () => {
+            importSchema.mockImplementation(() => ({
+                deleted_at: {type: Helpers.dataTypeValue2},
+            }));
+            class User extends BaseRecord {}
+            User.initialize();
+
+            expect(Model.init).toHaveBeenCalledWith(
+                {
+                    deleted_at: {type: Sequelize.DataTypes[Helpers.dataTypeKey2]},
+                },
+                {
+                    createdAt: 'created_at',
+                    deletedAt: 'deleted_at',
+                    modelName: 'User',
+                    sequelize: new Helpers.MockSequelize(),
+                    tableName: 'users',
+                    timestamps: false,
+                    updatedAt: 'updated_at'
+                }
+            );
         });
 
         it ('does not run twice on the same model', () => {
@@ -382,7 +432,7 @@ describe('BaseRecord', () => {
             const id = Math.random();
             await Person.find(id);
             expect(Person.findByPk).toHaveBeenCalledTimes(1);
-            expect(Person.findByPk).toHaveBeenCalledWith(id);
+            expect(Person.findByPk).toHaveBeenCalledWith(id, {useMaster: false});
         });
 
         it ('calls the sequelize `findAll` method when passed multiple value', async () => {
@@ -390,7 +440,13 @@ describe('BaseRecord', () => {
             const id2 = Math.random();
             await Person.find([id1, id2]);
             expect(Person.findAll).toHaveBeenCalledTimes(1);
-            expect(Person.findAll).toHaveBeenCalledWith({where: {[pk]: [id1, id2]}});
+            expect(Person.findAll).toHaveBeenCalledWith({useMaster: false, where: {[pk]: [id1, id2]}});
+        });
+
+        it ('forwards useWriteDB to findByPk as useMaster', async () => {
+            const id = Math.random();
+            await Person.find(id, {useWriteDB: true});
+            expect(Person.findByPk).toHaveBeenCalledWith(id, {useMaster: true});
         });
     });
 
@@ -421,6 +477,29 @@ describe('BaseRecord', () => {
     });
 
 
+    describe('BaseRecord.transaction', () => {
+        it ('delegates to the query interface and returns the result', async () => {
+            const expected = {};
+            const callback = jest.fn(() => expected);
+            const queryInterface = {
+                transaction: jest.fn(cb => cb())
+            };
+            class FakeConnection {
+                get queryInterface() { return queryInterface; }
+            }
+            class User extends BaseRecord {
+                static get connectionClass() { return FakeConnection; }
+            }
+
+            const result = await User.transaction(callback);
+
+            expect(queryInterface.transaction).toHaveBeenCalledTimes(1);
+            expect(queryInterface.transaction).toHaveBeenCalledWith(callback);
+            expect(result).toBe(expected);
+        });
+    });
+
+
     describe('Caching', () => {
         class Person extends BaseRecord {
             static get isCacheable()       { return true; }
@@ -439,7 +518,7 @@ describe('BaseRecord', () => {
                 await Person.find(id);
                 expect(Person.findByPk).toHaveBeenCalledTimes(0);
                 expect(findSpy).toHaveBeenCalledTimes(1);
-                expect(findSpy).toHaveBeenCalledWith(id);
+                expect(findSpy).toHaveBeenCalledWith(id, {});
             });
 
             it ('calls _cachedFind when multiple ids are passed', async () => {
@@ -448,7 +527,7 @@ describe('BaseRecord', () => {
                 await Person.find([id1, id2]);
                 expect(Person.findByPk).toHaveBeenCalledTimes(0);
                 expect(findSpy).toHaveBeenCalledTimes(1);
-                expect(findSpy).toHaveBeenCalledWith([id1, id2]);
+                expect(findSpy).toHaveBeenCalledWith([id1, id2], {});
             });
         });
 
@@ -842,5 +921,45 @@ describe('BaseRecord', () => {
 
             expect(record.toApiResponse()).toEqual({ name: 'OVERRIDDEN' });
         });
+
+
+        it ('leaves column keys unchanged when camelizeFieldsForApiResponse is disabled', () => {
+            const record = buildRecord(
+                { org_id: { type: 'integer' }, external_task_id: { type: 'string' } },
+                { org_id: 7, external_task_id: 'abc' },
+            );
+
+            expect(record.toApiResponse()).toEqual({ org_id: 7, external_task_id: 'abc' });
+        });
+
+
+        it ('camelizes column keys when camelizeFieldsForApiResponse is enabled', () => {
+            const record = buildRecord(
+                { org_id: { type: 'integer' }, external_task_id: { type: 'string' } },
+                { org_id: 7, external_task_id: 'abc' },
+            );
+            Object.defineProperty(record, 'camelizeFieldsForApiResponse', { get: () => true, configurable: true });
+
+            expect(record.toApiResponse()).toEqual({ orgId: 7, externalTaskId: 'abc' });
+        });
+    });
+
+
+    describe('#apiResponseKey', () => {
+        it ('returns the column unchanged by default', () => {
+            class Thing extends BaseRecord {}
+            const record = Object.create(Thing.prototype);
+
+            expect(record.apiResponseKey('external_task_id')).toEqual('external_task_id');
+        });
+
+
+        it ('camelizes the column when camelizeFieldsForApiResponse is enabled', () => {
+            class Thing extends BaseRecord {}
+            const record = Object.create(Thing.prototype);
+            Object.defineProperty(record, 'camelizeFieldsForApiResponse', { get: () => true, configurable: true });
+
+            expect(record.apiResponseKey('external_task_id')).toEqual('externalTaskId');
+        });
     });
 });

package/test/activeRecord/db/queryInterface.test.js

@@ -29,10 +29,12 @@ describe('QueryInterface', () => {
 
     describe('QueryInterface#transaction', () => {
         it('delegates transaction callback to sequelize', async () => {
-            const callback = jest.fn();
+            const expected = {};
+            const callback =  jest.fn(() => expected);
 
-            await queryInterface.transaction(callback);
+            const result = await queryInterface.transaction(callback);
 
+            expect(result).toBe(expected);
             expect(connection._sequelize.transaction).toHaveBeenCalledTimes(1);
             expect(connection._sequelize.transaction).toHaveBeenCalledWith(callback);
         });

package/test/http/client.test.js

@@ -26,6 +26,40 @@ describe('HttpClient', () => {
     });
 
 
+    describe('HttpClient#authorizationHeader', () => {
+        it('omits the Authorization header by default', async () => {
+            const client = new HttpClient();
+
+            await client.post(Helpers.apiUrl);
+
+            const callHeaders = fetch.mock.calls[0][1].headers;
+            expect(callHeaders.Authorization).toBeUndefined();
+        });
+
+        it('sets a bearer Authorization header when bearerToken is overridden', async () => {
+            const client = new Helpers.ClientWithBearerToken();
+
+            await client.post(Helpers.apiUrl);
+
+            Helpers.expectRequest('POST', Helpers.apiUrl, {
+                headers: { Authorization: `Bearer ${Helpers.bearerToken}` },
+                body: {},
+            });
+        });
+
+        it('sets a basic Authorization header when username and password are overridden', async () => {
+            const client = new Helpers.ClientWithBasicAuth();
+
+            await client.post(Helpers.apiUrl);
+
+            Helpers.expectRequest('POST', Helpers.apiUrl, {
+                headers: { Authorization: `Basic ${Helpers.basicAuthCredentials}` },
+                body: {},
+            });
+        });
+    });
+
+
     const httpMethods = [
         ['post',   'POST',   { supportsBody: true }],
         ['put',    'PUT',    { supportsBody: true }],

package/test/http/helpers/client.js

@@ -26,6 +26,33 @@ class ClientWithUrlRoot extends HttpClient {
 }
 
 
+const bearerToken = TestHelpers.Faker.Text.randomString();
+
+
+class ClientWithBearerToken extends HttpClient {
+    get bearerToken() {
+        return bearerToken;
+    }
+}
+
+
+const basicAuthUsername    = TestHelpers.Faker.Text.randomString();
+const basicAuthPassword    = TestHelpers.Faker.Text.randomString();
+const basicAuthCredentials = Buffer.from(`${basicAuthUsername}:${basicAuthPassword}`).toString('base64');
+
+
+class ClientWithBasicAuth extends HttpClient {
+    get basicAuthUsername() {
+        return basicAuthUsername;
+    }
+
+
+    get basicAuthPassword() {
+        return basicAuthPassword;
+    }
+}
+
+
 /***************************************************************************************************
 * MOCKS
 ***************************************************************************************************/
@@ -80,6 +107,10 @@ function buildExpectedRequest({ method, headers, body }) {
 
 module.exports = {
     apiUrl,
+    basicAuthCredentials,
+    bearerToken,
+    ClientWithBasicAuth,
+    ClientWithBearerToken,
     ClientWithUrlRoot,
     endpoint,
     expectRequest,

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

@@ -1,4 +1,5 @@
 const { VidaServerController } = require('../../../lib/server/serverController');
+const { buildResponseMock }    = require('../helpers/response');
 
 
 describe('VidaServerController', () => {
@@ -75,7 +76,7 @@ describe('VidaServerController', () => {
                 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 response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -92,7 +93,7 @@ describe('VidaServerController', () => {
                 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 response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -105,7 +106,7 @@ describe('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 response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -121,7 +122,7 @@ describe('VidaServerController', () => {
                 }
                 testAction() { return {} }
             }
-            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -137,7 +138,7 @@ describe('VidaServerController', () => {
                 }
                 testAction() { return {} }
             }
-            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');

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

@@ -1,4 +1,5 @@
 const { FooController }        = require('../helpers/controllers/fooController');
+const { buildResponseMock }    = require('../helpers/response');
 const   TestHelpers            = require('@vida-global/test-helpers');
 const {
     NoActiveStreamError,
@@ -76,7 +77,7 @@ describe('VidaServerController', () => {
         const successHandlers = [
             ['renderCreationSuccessful', 201],
             ['renderAccepted',           202],
-            ['renderNoConent',           204],
+            ['renderNoContent',          204],
             ['renderMovedPermanently',   301],
             ['renderFound',              302],
             ['renderNotModified',        304],
@@ -159,7 +160,7 @@ describe('VidaServerController', () => {
         let response;
         let controller;
         beforeEach(() => {
-            response   = {json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), statusCode: 200};
+            response   = buildResponseMock();
             controller = new FooController({}, response);
         });
 
@@ -221,30 +222,34 @@ describe('VidaServerController', () => {
             expect(await controller._serializeResponseBody(true,    {})).toBe(true);
         });
 
-        it ('returns Date instances as their epoch ms via getTime', async () => {
+        it ('returns Date instances as their epoch seconds', async () => {
             const date = new Date('2020-01-02T03:04:05Z');
-            expect(await controller._serializeResponseBody(date, {})).toBe(date.getTime());
+            const seconds = Math.floor(date.getTime() / 1000);
+            expect(await controller._serializeResponseBody(date, {})).toBe(seconds);
         });
 
         it ('recursively processes Date values inside objects', async () => {
             const date = new Date('2021-02-03T00:00:00Z');
+            const seconds = Math.floor(date.getTime() / 1000);
             const result = await controller._serializeResponseBody({createdAt: date, name: 'foo'}, {});
-            expect(result).toEqual({createdAt: date.getTime(), name: 'foo'});
+            expect(result).toEqual({createdAt: seconds, name: 'foo'});
         });
 
         it ('recursively processes arrays', async () => {
             const date = new Date('2022-03-04T00:00:00Z');
+            const seconds = Math.floor(date.getTime() / 1000);
             const result = await controller._serializeResponseBody([1, date, {ts: date}], {});
-            expect(result).toEqual([1, date.getTime(), {ts: date.getTime()}]);
+            expect(result).toEqual([1, seconds, {ts: seconds}]);
         });
 
         it ('invokes toApiResponse on objects that define it and recurses on the result', async () => {
             const date     = new Date('2023-04-05T00:00:00Z');
+            const seconds  = Math.floor(date.getTime() / 1000);
             const apiModel = {
                 async toApiResponse() { return {id: 1, createdAt: date}; }
             };
             const result = await controller._serializeResponseBody(apiModel, {});
-            expect(result).toEqual({id: 1, createdAt: date.getTime()});
+            expect(result).toEqual({id: 1, createdAt: seconds});
         });
 
         it ('passes the options argument through to toApiResponse', async () => {
@@ -278,24 +283,24 @@ describe('VidaServerController', () => {
             expect(controller.requestedFormat).toBe('json');
         });
 
-        it ('returns "xml" when the Accept header requests xml', () => {
+        it ('ignores an xml Accept header and defaults to json', () => {
             const controller = new FooController({headers: {accept: 'application/xml'}}, {});
-            expect(controller.requestedFormat).toBe('xml');
+            expect(controller.requestedFormat).toBe('json');
         });
 
-        it ('lets the _format param override a conflicting Accept header', () => {
+        it ('honors the _format param regardless of the Accept header', () => {
             const controller = new FooController({query: {_format: 'json'}, headers: {accept: 'application/xml'}}, {});
             expect(controller.requestedFormat).toBe('json');
         });
 
-        it ('defaults to json when neither the param nor the header indicate a format', () => {
+        it ('defaults to json when the param does not indicate a format', () => {
             const controller = new FooController({}, {});
             expect(controller.requestedFormat).toBe('json');
         });
 
-        it ('ignores an unrecognized _format and falls back to the Accept header', () => {
+        it ('defaults to json for an unrecognized _format, ignoring the Accept header', () => {
             const controller = new FooController({query: {_format: 'yaml'}, headers: {accept: 'application/xml'}}, {});
-            expect(controller.requestedFormat).toBe('xml');
+            expect(controller.requestedFormat).toBe('json');
         });
     });
 
@@ -329,7 +334,7 @@ describe('VidaServerController', () => {
     describe('#render format dispatch', () => {
         let response;
         beforeEach(() => {
-            response = {json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), statusCode: 200};
+            response = buildResponseMock();
         });
 
         it ('renders JSON via response.json for a JSON request', async () => {
@@ -367,6 +372,18 @@ describe('VidaServerController', () => {
             expect(sent).toContain('<status>ok</status>');
         });
 
+        it ('wraps the body under a custom root element when xmlRootElement is overridden', async () => {
+            class CustomRootController extends FooController {
+                get xmlRootElement() { return 'Response'; }
+            }
+            const controller = new CustomRootController({query: {_format: 'xml'}}, response);
+            await controller.render({foo: 'bar'});
+            const sent = response.send.mock.calls[0][0];
+            expect(sent).toContain('<Response>');
+            expect(sent).toContain('</Response>');
+            expect(sent).not.toContain('<response>');
+        });
+
         it ('renders array items as separate elements instead of concatenated text', async () => {
             const controller = new FooController({query: {_format: 'xml'}}, response);
             await controller.render({tags: ['one', 'two']});
@@ -384,6 +401,49 @@ describe('VidaServerController', () => {
     });
 
 
+    describe('#render content-type', () => {
+        let response;
+        beforeEach(() => {
+            response = buildResponseMock();
+        });
+
+        const defaultTypeCases = [
+            ['JSON', {},                    'application/json; charset=utf-8'],
+            ['XML',  {query: {_format: 'xml'}}, 'application/xml; charset=utf-8'],
+        ];
+        it.each(defaultTypeCases)('sets the default %s content-type when none is set', async (_label, params, expected) => {
+            const controller = new FooController(params, response);
+            await controller.render({foo: 'bar'});
+            expect(response.setHeader).toHaveBeenCalledWith('content-type', expected);
+        });
+
+        it ('sets the default text content-type when none is set for a string body', async () => {
+            const controller = new FooController({}, response);
+            await controller.render('hello');
+            expect(response.setHeader).toHaveBeenCalledWith('content-type', 'text/plain; charset=utf-8');
+        });
+
+
+        const preexistingTypeCases = [
+            ['JSON',   {}],
+            ['XML',    {query: {_format: 'xml'}}],
+            ['string', {}],
+        ];
+        it.each(preexistingTypeCases)('does not override an already-set content-type for a %s render', async (label, params) => {
+            const customType = TestHelpers.Faker.Text.randomString();
+            response.setHeader('content-type', customType);
+            response.setHeader.mockClear();
+
+            const controller = new FooController(params, response);
+            const body        = label === 'string' ? 'hello' : {foo: 'bar'};
+            await controller.render(body);
+
+            expect(response.setHeader).not.toHaveBeenCalledWith('content-type', expect.anything());
+            expect(response.getHeader('content-type')).toBe(customType);
+        });
+    });
+
+
     describe('#_serializeArrayForResponseBody', () => {
         class FakeRecord {
             constructor(id) { this.id = id; }

package/test/server/helpers/response.js

@@ -0,0 +1,19 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+// A response double that keeps a real header store so getHeader reflects what setHeader wrote.
+// This lets tests exercise the renderer's "don't override an already-set content type" logic.
+function buildResponseMock(overrides = {}) {
+    const headers  = {};
+    const response = {
+        json:       jest.fn(),
+        send:       jest.fn(),
+        setHeader:  jest.fn((name, value) => { headers[`${name}`.toLowerCase()] = value; }),
+        getHeader:  jest.fn((name)        => headers[`${name}`.toLowerCase()]),
+        statusCode: 200,
+    };
+    return Object.assign(response, overrides);
+}
+
+
+module.exports = { buildResponseMock };

package/test/server/serverController.test.js

@@ -1,6 +1,7 @@
 const { FooController }        = require('./helpers/controllers/fooController');
 const   Errors                 = require('../../lib/server/errors');
 const { randomPayload }        = require('./helpers/serverController');
+const { buildResponseMock }    = require('./helpers/response');
 const   TestHelpers            = require('@vida-global/test-helpers');
 const {
     VidaServerController,
@@ -338,7 +339,7 @@ describe('VidaServerController', () => {
         });
 
         it ('awaits render before calling response.end (regression: ERR_HTTP_HEADERS_SENT)', async () => {
-            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const response   = buildResponseMock({ end: jest.fn() });
             const controller = new FooController({}, response);
             controller.testAction = jest.fn(async () => ({foo: TestHelpers.Faker.Text.randomString()}));
 
@@ -360,7 +361,7 @@ describe('VidaServerController', () => {
 
         beforeEach(() => {
             request                         = {headers: randomPayload()};
-            response                        = {headers: randomPayload(), statusCode: TestHelpers.Faker.Math.randomNumber(), json: jest.fn(), send: jest.fn(), setHeader: jest.fn()};
+            response                        = buildResponseMock({headers: randomPayload(), statusCode: TestHelpers.Faker.Math.randomNumber()});
             request.headers['content-type'] = TestHelpers.Faker.Text.randomString();
             controller                      = new FooController(request, response);
         });
@@ -524,7 +525,7 @@ describe('VidaServerController', () => {
                 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 response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -541,7 +542,7 @@ describe('VidaServerController', () => {
                 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 response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -554,7 +555,7 @@ describe('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 response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -570,7 +571,7 @@ describe('VidaServerController', () => {
                 }
                 testAction() { return {} }
             }
-            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');
@@ -586,7 +587,7 @@ describe('VidaServerController', () => {
                 }
                 testAction() { return {} }
             }
-            const response   = { json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), end: jest.fn(), statusCode: 200 };
+            const response   = buildResponseMock({ end: jest.fn() });
             const controller = new C({}, response);
 
             await controller.performRequest('testAction');