Cross-platform CommonJS in practice

What are we talking about?

About JS modules that can be used in the browser and on the server. About their interaction and external dependencies. Less theory, more practice. As part of the young fighter's course, we are implementing a simple and very original application based on Node.JS: ToDo-list. For this we have to:

1. “Start” cross-platform modules based on the Express framework;
2. Teach them to work with platform-dependent colleagues;
3. Create a transport layer between the client and the server;
4. Taki make ToDo-list;
5. Comprehend the result.

Application Requirements

Let's focus on the essence of the whole idea and take on the implementation of the minimum functionality. Requirements are formulated as follows:

1. The application is accessible using a browser;
2. The user works with his ToDo list in one session. When reloading the page, the list should remain; after closing the tab or browser, a new one should be created;
3. The user can add new items to the list;
4. The user can mark the added item as completed.

Making a frame

Without problems, we raise the framework of the application based on the Express framework . We will slightly modify the structure we received from the box:

. ├── bin ├── client //     ,   ├── modules //  , ,  CommonJS  ├── public │  └── stylesheets ├── routes └── views 

Let's create our first module from the subject area - Point, the constructor of the ToDo list item:

 // modules/Point/Point.js /** *    * @param {Object} params * @param {String} params.description * @param {String} [params.id] * @param {Boolean} [params.isChecked] * @constructor */ function Point(params) { if (!params.description) { throw 'Invalid argument'; } this._id = params.id; this._description = params.description; this._isChecked = Boolean(params.isChecked); } Point.prototype.toJSON = function () { return { id: this._id, description: this._description, isChecked: this._isChecked }; } 

Wonderful. This is our first cross-platform module and we can already use it on the server, for example, like this:

 // routes/index.js var express = require('express'); var router = express.Router(); /* GET home page. */ router.get('/', function (req, res) { var Point = require('../modules/Point'); var newPoint = new Point({ description: 'Do something' }); console.log('My new point:', newPoint); }); module.exports = router; 

There are several ways to work with the CommonJS module in the browser, the easiest to set up and use is middleware for Express browserify-middleware :

 // app.js // ... var browserify = require('browserify-middleware'); app.use('/client', browserify('./client')); // ... 

By adding such simple code, we can immediately write the first lines of our client application:

 // client/todo.js var console = require('console'); //  `node_modules/browserify/node_modules/console-browserify` var Point = require('../modules/Point'); 

')

Browserify uses the Nodov algorithm for loading modules , and also provides browser implementations of core libraries . This has already been written a lot, so I’ll just say that the script loaded at /client/todo.js is now fully functional in the browser.

Let's talk about the modules

In my project I used the following conditional division of modules:



Utilitarian modules

With their help, the developer organizes and accompanies the code. For example, in our case, this is a library of promises Vow , lodash , console. Most of these modules are not only cross-platform, but also support several download formats (CommonJS, AMD).



Domain Modules

Provide an interface for working with domain objects. We have already created one such module - the Point constructor, soon there will be a list module, providing the interface we need (addPoint, getPoints, checkPoint) and the user module, which is responsible for initializing the user session.



Such modules can be either fully cross-platform or have platform-specific parts. For example, some methods or properties should not be available in the browser. But most often the platform-specific part falls into the following category of modules.



DAL modules (Data Access Layer)

These are modules that are responsible for accessing data from an arbitrary set of sources and their conversion into an internal representation (objects, collections) and vice versa. For the browser, it can be localStorage, sessionStorage, cookies, external API. On the server, the choice is even greater: the whole chain of databases, the file system and, again, some external API.



If the cross-platform domain module interacts with the DAL, then the DAL module must have a browser and server implementation with a single interface. Technically, we can organize this using a useful browserify feature , which consists in specifying the browser property in the module's package.json. Thus, domain modules can work with different DAL modules depending on the execution environment:

 { "name" : "dal", "main" : "./node.js", //     "browser": "./browser.js" //   browserify     } 

We implement modules

What modules will be required for our task? Let memcache act on the server as storage, we will store our ToDo lists in it. User identification will occur in the browser, put the session identifier in sessionStorage and will transmit with each request to the server. Accordingly, on the server we will need to pick up this identifier from the request parameters.



It turns out that at the DAL level we have to implement the protocol of interaction with sessionStorage and memcache (we implement the retrieval of the request parameters using standard Express tools).





Now we can implement the following User domain module, which will provide us with an object with a single getId method:

 // modules/user/user.js var dal = require('./dal'); //     ./dal/browser.js,   - ./dal/node.js function User() { } /** *    * @returns {String} */ User.prototype.getId = function () { return dal.getId(); } module.exports = new User(); 

We will organize the interaction between the browser and the server based on the REST protocol, which will require us to implement it at the DAL level for the browser:



and a special Express router that will work with our domain modules:

 // routes/api.js // ... router.use('/:module/:method', function (req, res) { var module = require('../modules/' + req.params.module), method = module[req.params.method]; if (!method) { res.send(405); return; } method.apply(module, req.apiParams) .then(function (data) { res.json(data); }, function (err) { res.send(400, JSON.stringify(err)); }); }); // ... 

Based on the conditions of the problem, we must provide the following methods to the API:

1. GET, / list / getPoints - get a to-do list in the ToDo list of the current user;
2. POST, / list / addPoint — get a new item in the ToDo list of the current user;
3. POST, / list / checkPoint - mark the item as done;

In the case of adding a new item, we will have to impose additional responsibilities on the router: converting the request parameters into an internal representation for transfer to the module:

 router.post('/list/addPoint', function (req, res, next) { var Point = require('../modules/Point'), point; req.apiParams = []; try { point = new Point(JSON.parse(req.param('point'))); req.apiParams.push(point); } catch (e) {} next(); }); 

Great, now we can implement the final module of the subject domain list:

 // modules/list/list.js //   var _ = require('lodash'); var vow = require('vow'); var console = require('console'); // DAL- var dal = require('./dal'); //    var Point = require('../Point'); var user = require('../user'); var list = {}; var cache = {}; //   /** *       * @param {Point} newPoint * @returns {vow.Promise} resolve with {Point} */ list.addPoint = function (newPoint) { /* ... */ } /** *     * @param {String} pointId * @returns {vow.Promise} */ list.checkPoint = function (pointId) { /* ... */ } /** *      * @returns {vow.Promise} resolve with {Point[]} */ list.getPoints = function () { console.log('list / getPoints'); return new vow.Promise(function (resolve, reject) { var userId = user.getId(); if (_.isArray(cache[userId])) { resolve(cache[userId]); return; } dal.getPoints(user) .then(function (points) { cache[userId] = points; console.log('list / getPoints: resolve', cache[userId]); resolve(points); }, reject); }); } module.exports = list; 

Structurally, the modules of our application began to look like this:

 modules ├── dal │  ├── browser │  │  ├── rest.js │  │  └── sessionStorage.js │  └── node │  └── memcache.js ├── list │  ├── dal │  │  ├── browser.js //  dal/browser/rest.js │  │  ├── node.js //  dal/node/memcache.js │  │  └── package.json │  ├── list.js │  └── package.json ├── Point │  ├── package.json │  └── Point.js └── user ├── dal │  ├── browser.js //  dal/browser/sessionStorage.js │  ├── node.js │  └── package.json ├── package.json └── user.js 

Together

It's time to implement the logic of our application. Let's start by adding a new item to the ToDo list:

 // client/todo.js // ... //    -           var console = require('console'); var _ = require('lodash'); var list = require('../modules/list'); var Point = require('../modules/Point'); var todo = { addPoint: function (description) { var point = new Point({ description: description }); list.addPoint(point); } }; // ... 

What happens when you call todo.addPoint ('Test')? I will try to draw the main steps in the diagrams. To begin, consider the interaction of modules in the browser:



As you can see, the list module 2 times refers to its DAL-module, which makes http-requests to our API.

This is how the interaction of the same (for the most part) modules on the server side looks like:



Here's what happens: the interaction between the modules of the subject area and the DAL modules in the browser and on the server is identical. Differ, as we planned, the interaction protocols and data sources at the DAL level.



The case will work in the same way with the “crossing out” clause:

 list.checkPoint(pointId); 

Another couple of minutes - and our application is ready.



Repository code : github .

Comprehend

Why, actually, this whole conversation? At the moment I have some moral satisfaction from the work done and a number of questions about its feasibility. How suitable is this model for complex projects and where are the limits of its application? Am I prepared to put up with the inevitable overhead that an application based on cross-platform modules will have?



Until full understanding so far away. In any case, it is good to be able to do something like this and think about the prospects. Cross-platform frameworks and component tests - why not?