@transomjs/transom-mongoose v1.5.4-0

transom-mongoose

Transom-mongoose is a plugin for a TransomJS REST api server. With this plugin, you can define mongoose models quickly and easily, and expose them through a comprehensive set of pre-built CRUD endpoints that are added to the REST API. Include custom logic in pre & post hooks, apply auditing and secure your data.

Installation

$ npm install --save transom-mongoose

Usage

The documentation is still a work in progress ....

The transom-mongoose plugin needs to be configured and initialized on your Transom REST API server as follows:

mongodb://username:password@host:port/database?options...'

var TransomCore = require('@transomjs/transom-core');
var transomMongoose = require('@transomjs/transom-mongoose');

const transom = new TransomCore();

const options = {
    mongodbUri: valueFromTheEnvironment,
    mongooseKey: undefined,
    modelPrefix: undefined,
    preMiddleware: [],
    postMiddleware: [],
    routes: {}
}

transom.configure(transomMongoose, options);

var myApi = require('./myApi');

// Initialize them all at once.
var server = transom.initialize(myApi);

The options object

The options object has the following properties:

• connect: Pass a boolean 'false' to skip internal mongodb connection, an Object to override defaults, or undefined to use the default connection handling.
• mongodbUri: string, mandatory. The connection string to connect the api server to a MongoDB database
• mongooseKey: string optional. The string literal to use for the mongoose instance the in the Transom registry. Default is 'mongoose'.
• modelPrefix: The prefix to use for the mongoose models that are generated from the api definition. Default is 'dynamic-'.
• preMiddleware: Array of mongoose pre- middleware functions.
• postMiddleware: Array of mongoose post- middleware functions.
• routes: (renamed to 'models')
• models: Used to enable REST Api end points on mongoose models that are not defined in the api definition, but are supplied by your server application through another plugin or custom code.

API Definitions for the plugin

You'll need to include a 'mongoose' object in your api definition as a child of definition:

"mongoose": {
    "entities": {
        "address": {
            "attributes": {
                "address_line1": {
                    "name": "Address Line 1",
                    "required": true,
                    "textsearch": 10,
                    "type": "string",
                    "default": "123 Default Street"
                },
                "address_line2": {
                    "name": "Address Line 2",
                    "required": true,
                    "textsearch": 10,
                    "type": "string",
                    "default": "Apartment B3"
                },
                "city": {
                    "name": "City"
                },
                "country": "Country"
            },
            "audit": {
                "createdBy": "createdBy",
                "updatedBy": "updatedBy",
                "createdAt": "createdDate",
                "updatedAt": "updatedDate"
            },
            "acl": {
                "create": ["public", "admin", "agents"],
                "default": {
                    "public": 2,
                    "owner": {
                        "CURRENT_USER": 4
                    }, 
                    "groups": {
                        "agents": 7
                    }
                }
            },
            "actions": {
                "pre": {
                    init: function (server, next) {
                        console.log("This is a pre-init action!");
                        next();
                    },
                    validate: function (server, next) {
                        console.log("This is a pre-validate action!");
                        next();
                    },
                    save: [
                        function (server, next) {
                            console.log("This is ONE pre-save action!");
                            next();
                        },
                        function (server, next) {
                            console.log("This is TWO pre-save action!");
                            // console.log('pre this', this);
                            this.address_line1 = this.address_line1.toUpperCase();
                            next();
                        },
                        function (server, next) {
                            console.log("This is THREE pre-save action!");
                            next();
                        }
                    ],
                    remove: function (server, next) {
                        console.log("This is a pre-remove action!");
                        next();
                    }
                },
                post: {
                    init: function (server, item, next) {
                        console.log("This is a post-init action!");
                        next();
                    },
                    validate: function (server, item, next) {
                        console.log("This is a post-validate action!");
                        next();
                    },
                    save: function (server, item, next) {
                        console.log("This is a post-save action!");
                        // console.log('post item', item);
                        // console.log('post this', this);

                        next();
                    },
                    remove: function (server, item, next) {
                        console.log("This is a post-remove action!");
                        next();
                    }
                }
            }
        },
    },
    ...

The mongoose object has a property for each of the entities in the database. An entity is stored in a dedicated colletion in MongoDb. The schema of the entity is defined using the attributes property, an acl property is used to specfiy authorization characteristics if a security plugin is available, and finally an actions property to specify the custom action functions that are triggerd when interacting with the entity.

The Attribute definition Each property of the attributes object is either a string specifying the datatype or an object. Simplest form:

addressLine1: "string"

The default datatype is string, so the following is equivalent:

addressLine1: {}

A more typical attribute looks something like this:

addressLine1: {
    name: "Address Line 1",
    required: true,
    textsearch: 10,
    type: "string",
    default: "123 Default Street"
}

The object can have the following properties:

* When the Attribute type is connector, the connect_entity is required and must match the name of an existing entity.

Database Action function definitons

The action needs to be configured in the mongoose section of the api definition. There are two types of action functions, the pre action and the post action. The before is typically used to apply business rules and potentially trigger an error in case of validation errors.

The post action is called after the database action is complete. It is used for additional processing on the server, for instance, triggering notifications or performing additional processing.

These functions are implemented using pre and post hooks in mongoose.

Pre Function

function (server, next){
    // [server] is the TransomJS instance
    // [next] is a callback function
    // Note that the record instance is not passed in, it is referenced using `this`.
    if (this.fieldValue === 'bad'){
        next('bad data');
    } else {
        next();
    }
}

Post Function

function (server, item, next) {
    // [server] is the TransomJS instance
    // [item] is the modified record
    // [next] is a callback function that must be called on completion of processing,
    //        optionally with an error object argument, in which case the api request
    //        will return an error, however the database action will not be rolled back.
    try {
        somethingAmazingSync(item);
        next();
    } catch(err) {
       next(err);
    }
}

The Entity Security definition

The security features for the entity are specified in the acl property of the entity (Access Control List).

...More details coming soon.