@tryghost/express-bookshelf-jsonapi 0.3.4

package/lib/ebja.js

@@ -0,0 +1,24 @@
+'use strict';
+/**
+ * Heavily borrowed from express
+ */
+
+var debug = require('ghost-ignition').debug('main');
+var API = require('./api');
+var mixin = require('merge-descriptors');
+
+function createAPI(options) {
+    var api = function () {};
+
+    debug('createAPI');
+
+    mixin(api, API, false);
+
+    api.init(options);
+
+    return api;
+}
+
+exports = module.exports = createAPI;
+
+exports.plugin = require('./plugin');

package/lib/endpoint.js

@@ -0,0 +1,67 @@
+'use strict';
+var debug = require('ghost-ignition').debug('endpoint');
+var _ = require('lodash');
+var http = require('./http');
+var IncomingMessage = require('http').IncomingMessage;
+var stack = require('./stack');
+var apiWare = require('./apiware');
+
+// @TODO come up with a better way to do this
+// Inspect the request inside the HTTP layer? SO if it is a real-world GET request
+// Or maybe use a different way to define which "type", like manually set the queue type
+var types = {
+    GET: 'query',
+    POST: 'action',
+    PUT: 'action',
+    PATCH: 'action',
+    DELETE: 'destroy'
+};
+
+function prepareStack(options) {
+    var type = types[options.method || 'GET'];
+    debug('STACK TYPE', type);
+    var stack = _.clone(apiWare[type]);
+
+    // Override the queue functions with any matching functions passed in as options
+    // Matches are done between queue keys and option keys
+    _.intersection(Object.keys(stack), Object.keys(options)).forEach(function handleMatch(optionsStackMatch) {
+        stack[optionsStackMatch] = options[optionsStackMatch];
+    });
+
+    return stack;
+}
+
+// @TODO how to keep track of the resource that an endpoint belongs to?
+var Endpoint = function Endpoint(api, options) {
+    var self = this;
+    this.api = api;
+    this.options = _.merge({}, this.api.options, options);
+
+    this.stack = prepareStack(options);
+
+    function doEndpoint(apiReq, apiRes, cb) {
+        debug('Executing apiware stack');
+        stack.handle(_.values(self.stack), apiReq, apiRes, cb);
+    }
+
+    // @TODO move this somewhere else?
+    var handler = function handler() {
+        debug('handling endpoint');
+        var args = Array.from(arguments);
+
+        // @TODO make this adapter logic a bit nicer
+        if (args.length === 3 && args[0] instanceof IncomingMessage) {
+            args.unshift(self.options);
+            args.unshift(self.api);
+            debug('endpoint apply with adapter');
+
+            return doEndpoint.apply(self, http.adapter.apply(self, args));
+        }
+
+        throw new Error('Unimplemented!');
+    };
+
+    return handler;
+};
+
+module.exports = Endpoint;

package/lib/format.js

@@ -0,0 +1,33 @@
+'use strict';
+var _ = require('lodash');
+var debug = require('ghost-ignition').debug('format');
+var Mapper = require('./vendor/jsonapi-mapper');
+
+var defaultSerializerOptions = {};
+var defaultMapperOptions = {enableLinks: true};
+
+module.exports = function format(api, apiReq, apiRes) {
+    if (!apiRes || _.isEmpty(apiRes.model)) {
+        debug('Nothing to format :(');
+        // We don't throw an error, but return empty
+        // This allows us to support, empty delete responses etc
+        return;
+    }
+
+    debug('mapping to JSONAPI');
+    // Apply any defaults that weren't overridden
+    _.defaults(apiRes.serializerOptions, defaultSerializerOptions);
+    _.defaults(apiRes.mapperOptions, defaultMapperOptions);
+    var mapper = Mapper(api.baseUrl, apiRes.serializerOptions);
+    var json = mapper.map(apiRes.model, apiRes.type, apiRes.mapperOptions);
+    var includes = apiReq.query.options.include;
+
+    // Omit data attribute from related models that have not been included
+    // This is a workaround for jsonapi-mapper bug - https://github.com/scoutforpets/jsonapi-mapper/issues/69
+    _.each(json.data.relationships, function (v, k) {
+        json.data.relationships[k] = !_.includes(includes, k) ? _.omit(v, 'data') : v;
+    });
+
+    debug('returning');
+    return json;
+};

package/lib/http.js

@@ -0,0 +1,71 @@
+'use strict';
+
+var http = exports;
+var _private = {};
+var debug = require('ghost-ignition').debug('http');
+var _ = require('lodash');
+var queryParser = require('./vendor/jsonapi-query-parser');
+var formatter = require('./format');
+var APIRequest = require('./request');
+var APIResponse = require('./response');
+
+// TODO: do this based on req.method instead of apiReq.options.method?
+var successCodes = {
+    GET: 200,
+    POST: 201,
+    DELETE: 204,
+    PATCH: 200
+};
+
+_private.toAPI = function toAPI(api, req, options) {
+    var params = queryParser.parseRequest(req.url);
+    var payload = req.body;
+    var source = options.request.sourceProperty ? req[options.request.sourceProperty] : req.user;
+    source.ip = req.headers['x-forwarded-for'] || req.connection.remoteAddress;
+    var custom = {};
+
+    _.each(options.request.customProperties, function (propName) {
+        custom[propName] = req[propName];
+    });
+
+    debug('CONVERT to API');
+    var apiRequest = new APIRequest(api.models[options.model], options, params, payload, source, custom);
+    var apiResponse = new APIResponse(apiRequest);
+
+    return [
+        apiRequest,
+        apiResponse
+    ];
+};
+
+_private.fromAPI = function fromAPI(api, apiReq, apiRes) {
+    debug('CONVERT to HTTP');
+    return {
+        data: formatter(api, apiReq, apiRes),
+        status: apiReq.options.response.successCode || successCodes[apiReq.options.method] || 200
+    };
+};
+
+http.adapter = function adapter(api, options, req, res, next) {
+    var args = _private.toAPI(api, req, options);
+    var callback = function callback(err, apiReq, apiRes) {
+        debug('HTTP callback');
+        if (err) {
+            debug('Got an error');
+            return next(err);
+        }
+
+        var json = _private.fromAPI(api, apiReq, apiRes);
+
+        if (json) {
+            debug('Returning JSON');
+            return res.status(json.status).json(json.data);
+        }
+
+        return next();
+    };
+
+    args.push(callback);
+    return args;
+};
+

package/lib/plugin.js

@@ -0,0 +1,40 @@
+'use strict';
+var debug = require('ghost-ignition').debug('plugin');
+var jsonapiParams = require('bookshelf-jsonapi-params');
+
+var jsonapi = function jsonapi(Bookshelf) {
+    if (!Bookshelf.Model.hasOwnProperty('fetchJsonApi')) {
+        Bookshelf.plugin(jsonapiParams);
+    }
+
+    // Load the pagination plugin if it doesn't already exist
+    if (!Bookshelf.Model.hasOwnProperty('fetchPage')) {
+        Bookshelf.plugin('pagination');
+    }
+
+    var Model = Bookshelf.Model.extend(
+        {
+            jsonapi: true
+        },
+        {
+            getOne: function getOne(query) {
+                debug('getOne', query);
+                var options = query.options || {};
+                // enforce require true for single resource fetches
+                options.require = options.require || true;
+
+                return this
+                    // forge won't work here!
+                    .where(query.data)
+                    .fetchJsonApi(options, false);
+            },
+            getPage: function getPage(query) {
+                debug('getPage');
+                return this.fetchJsonApi(query.options);
+            }
+        });
+
+    Bookshelf.Model = Model;
+};
+
+module.exports = jsonapi;

package/lib/request.js

@@ -0,0 +1,35 @@
+'use strict';
+var debug = require('ghost-ignition').debug('request');
+var _ = require('lodash');
+
+// @TODO resolve this into a sensible signature
+class APIRequest {
+    constructor(model, options, params, payload, source, custom) {
+        debug('APIRequest');
+
+        // Ensure we have response options
+        options.response = options.response || {};
+
+        // The bookshelf model for which this request is being made
+        this.model = model;
+        // The model method that will be called to do a query
+        this.modelMethod = options.modelMethod;
+        // Any other options passed in
+        this.options = options;
+        // Parameters
+        this.params = params;
+        // Payload
+        this.payload = payload;
+        // The query that is going to be passed to the model method
+        this.query = {
+            data: {},
+            options: {}
+        };
+        // Who or what is making the request (usually some sort of user)
+        this.source = source;
+
+        _.extend(this, custom);
+    }
+}
+
+module.exports = APIRequest;

package/lib/resource.js

@@ -0,0 +1,16 @@
+'use strict';
+var debug = require('ghost-ignition').debug('resource');
+var _ = require('lodash');
+var Endpoint = require('./endpoint');
+
+// @TODO fixup the way this is created vs api and endpoint
+var Resource = function Resource(api, resourceOpts) {
+    debug('Registering resource: ' + resourceOpts.model);
+
+    this.Endpoint = function registerEndpoint(options) {
+        debug('Registering resource endpoint: ' + options.queryMethod);
+        return new Endpoint(api, _.merge({}, resourceOpts, options))
+    };
+};
+
+module.exports = Resource;

package/lib/response.js

@@ -0,0 +1,33 @@
+'use strict';
+var debug = require('ghost-ignition').debug('response');
+var _ = require('lodash');
+var Mapper = require('./vendor/jsonapi-mapper');
+
+function getType(request) {
+    if (request.options.response && request.options.response.type) {
+        return request.options.response.type;
+    }
+    return request.params.relationshipType || request.params.resourceType;
+}
+
+// API Response
+// @TODO resolve this into a sensible signature
+// This object is initially constructed from just the request object
+class APIResponse {
+    constructor(request) {
+        debug('APIResponse');
+        // A reference to the request object
+        this.request = request;
+        // The result of the query (bookshelf model)
+        this.model = {};
+        // The type of object that we are returning
+        this.type = getType(request);
+        // Various convoluted settings/options that get passed to the jsonapi mapper when formatting
+        this.serializerOptions = _.pick(request.options.response, Mapper.knownSerializerOptions.concat(request.options.relations));
+        this.mapperOptions = _.pick(request.options.response, Mapper.knownMapperOptions);
+        // An array of executed model methods
+        this.exec = [];
+    }
+}
+
+module.exports = APIResponse;

package/lib/stack.js

@@ -0,0 +1,30 @@
+'use strict';
+module.exports.handle = function handleStack(stack, apiReq, apiRes, cb) {
+    var idx = 0;
+
+    if (stack.length === 0) {
+        return cb(null, apiReq, apiRes);
+    }
+
+    apiNext();
+
+    function apiNext(err) {
+        var nextFunc = stack[idx];
+        idx += 1;
+
+        if (!nextFunc) {
+            return cb(err, apiReq, apiRes);
+        }
+
+        if (err) {
+            apiRes.err = err;
+            return cb(err, apiReq, apiRes);
+        }
+
+        try {
+            nextFunc(apiReq, apiRes, apiNext);
+        } catch (err) {
+            cb(err, apiReq, apiRes);
+        }
+    }
+};

package/lib/vendor/jsonapi-mapper.js

@@ -0,0 +1,14 @@
+var Mapper = require('@tryghost/jsonapi-mapper');
+
+module.exports = function mapper(url, options) {
+    return new Mapper.Bookshelf(url, options);
+};
+
+module.exports.knownSerializerOptions = [
+    'attributes', 'ref', 'included', 'id', 'topLevelLinks', 'dataLinks', 'relationshipLinks', 'relationshipMeta',
+    'ignoreRelationshipData', 'keyForAttribute', 'nullIfMissing', 'pluralizeType', 'typeForAttribute', 'meta'
+];
+module.exports.knownMapperOptions = [
+    'omitAttrs', 'idAttribute', 'keyForAttr', 'relations', 'typeForModel', 'enableLinks', 'query', 'pagination'
+];
+

package/lib/vendor/jsonapi-query-parser.js

@@ -0,0 +1,2 @@
+var JsonApiQueryParser = require('jsonapi-query-parser');
+module.exports = new JsonApiQueryParser();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tryghost/express-bookshelf-jsonapi",
+  "version": "0.3.4",
+  "description": "Create JSON API endpoints from bookshelf",
+  "main": "index.js",
+  "alias": "ebja",
+  "repository": {
+    "type": "git",
+    "url": "ssh://git@github.com/TryGhost/Pro-Packages",
+    "directory": "packages/express-bookshelf-jsonapi"
+  },
+  "author": "Hannah Wolfe",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/TryGhost/Pro-Packages/issues"
+  },
+  "homepage": "https://github.com/TryGhost/Pro-Packages/tree/main/packages/express-bookshelf-jsonapi",
+  "dependencies": {
+    "bookshelf-jsonapi-params": "1.5.3",
+    "debug": "2.2.0",
+    "express": "4.14.0",
+    "ghost-ignition": "2.3.0",
+    "jsonapi-query-parser": "1.3.1",
+    "lodash": "4.16.4",
+    "merge-descriptors": "1.0.1",
+    "@tryghost/jsonapi-mapper": "^1.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.1.6",
+    "create-error": "0.3.1",
+    "sinon": "21.0.3",
+    "vitest": "4.1.6"
+  },
+  "scripts": {
+    "dev": "echo \"Implement me!\"",
+    "test": "NODE_ENV=testing vitest run --coverage",
+    "lint": "oxlint -c ../../.oxlintrc.json .",
+    "posttest": "pnpm lint"
+  }
+}

package/test/apiware/payload.test.js

@@ -0,0 +1,230 @@
+var sinon = require('sinon');
+var utils = require('../utils');
+
+var payload = require('../../lib/apiware/payload');
+
+var sandbox = sinon.createSandbox();
+
+describe('apiware: payload', function () {
+    var req, res;
+
+    afterEach(function () {
+        sandbox.restore();
+    });
+
+    beforeEach(function () {
+        req = {
+            options: {},
+            payload: {},
+            query: {
+                data: {},
+                options: {}
+            }
+        };
+
+        res = {
+            exec: []
+        };
+    });
+
+    it('does nothing for empty payloads', function () {
+        return new Promise(function (resolve, reject) {
+            payload(req, res, function next(err) {
+                if (err) {
+                    return reject(err);
+                }
+
+                expect(typeof req.query.data).toBe('object');
+                expect(Object.keys(req.query.data)).toHaveLength(0);
+                resolve();
+            });
+        });
+    });
+
+    describe('data validation', function () {
+        it('errors for payloads without a data param', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {id: 'a1b'};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('errors for payloads with a string data param', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: 'a1b'};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('errors for payloads with an empty array data param', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: []};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('errors for payloads with an empty object data param', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: {}};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('errors for payloads with object and no type or attributes', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: {id: 'a1b'}};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('errors for payloads with object, type, but no attributes', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: {
+                    id: 'a1b',
+                    type: 'thing'
+                }};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('errors for payloads with object, attributes, but no type', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: {
+                    id: 'a1b',
+                    attributes: {cat: 'hat'}
+                }};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        utils.expectIgnitionError(err, 'BadRequestError', /Malformed payload/);
+
+                        return resolve();
+                    }
+
+                    reject(new Error('This should have thrown an error'));
+                });
+            });
+        });
+
+        it('does not error for payload with data, attributes and type', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: {
+                    id: 'a1b',
+                    type: 'thing',
+                    attributes: {cat: 'hat'}
+                }};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        return reject(err);
+                    }
+
+                    expect(typeof req.query.data).toBe('object');
+                    expect(req.query.data).toHaveProperty('cat', 'hat');
+                    resolve();
+                });
+            });
+        });
+
+        it('can handle a data array with length 1', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: [{
+                    id: 'a1b',
+                    type: 'thing',
+                    attributes: {cat: 'hat'}
+                }]};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        return reject(err);
+                    }
+
+                    expect(typeof req.query.data).toBe('object');
+                    expect(req.query.data).toHaveProperty('cat', 'hat');
+                    resolve();
+                });
+            });
+        });
+
+        it('does not error for data array with multiple items, but also does nothing with it :(', function () {
+            return new Promise(function (resolve, reject) {
+                req.payload = {data: [
+                    {
+                        id: 'a1b',
+                        type: 'thing1',
+                        attributes: {cat: 'hat'}
+                    },
+                    {
+                        id: 'a2z',
+                        type: 'thing2',
+                        attributes: {mad: 'hat'}
+                    }
+                ]};
+
+                payload(req, res, function next(err) {
+                    if (err) {
+                        return reject(err);
+                    }
+
+                    expect(typeof req.query.data).toBe('object');
+                    expect(Object.keys(req.query.data)).toHaveLength(0);
+                    resolve();
+                });
+            });
+        });
+    });
+});