@sera4/essentia 1.0.6 → 1.0.7

package/README.md

@@ -0,0 +1,8 @@
+# ESSENTIA
+
+A collection of small modules providing essential utilities for TWS services:
+
+* [Sequelize Paginator](paginator/README.md)
+* [Sequelize HAL Decorator](hal/README.md)
+* A logging tool
+* A small utility to dump the last commit of the project

package/hal/REAMDE.md

@@ -0,0 +1,54 @@
+# HAL DECORATOR
+
+A module to add HAL decoration to JSON responses in Sequelize ORM based projects.
+
+## Usage
+
+In your model definition, set decoration on your model
+
+```
+const decorator = require("@sera4/essentia).halDecorator;
+...
+
+module.exports = (sequelize, DataTypes) => {
+  const Post = sequelize.define('Post', {...}, {...});
+  // configure the decorator (optional)
+  const configs = {
+    links: {
+      "self" : {
+        "get": "/:id/post/"
+      },
+      "update" : {
+        "post": "/:id/post/"
+      }
+    },
+    resource: "/posts",
+    exclude : ["created_at", "updated_at"],
+    linksTag : "myLinks",
+    resourceTag: "myResource"
+  }
+  decorator.decorate(Post, configs)
+  return Post;
+};
+```
+
+The above configuration (which is optional) should produce the following JSON for each instance of Post sent out to the client:
+```
+{
+    "myLinks": {
+        "self": {
+            "get": "/posts/42801"
+        },
+        "update": {
+            "post": "/posts/42801"
+        }
+    },
+    "myResource": {
+        "id": 42801,
+        "title": "LJitZgbNPLpOlnkYdynKlSYnCjuLBYiVHYMfAPlSALeoVTuNKw",
+        "name": "cvnititqxdPnHdomgxJJVGynNInkScmDlkzAALunYFHNRjffqE",
+        "content": "LcURropLnJiudElgAVhsBSMRBRNUzHLDiTebZxxpplXdpeGEFa"
+    }
+}
+```
+The links use a similar pattern for parameters interpolation like the express route. For example `/posts/:id/by_user/:user_id` becomes `/posts/20/by_user/123`. If no matching attribute is found on the record, the variable is not replaced.

package/hal/index.js

@@ -0,0 +1,74 @@
+"use strict"
+
+function lastElement(arr) {
+  if (arr && arr.length) {
+    return arr[arr.length - 1];
+  } else {
+    return null;
+  }
+}
+
+class HalDecorator {
+
+  decorate(Model, options) {
+    const model = Model.instance || Model;
+    const resource = (options && options.resource) ? options.resource : "";
+    const exclude = (options && options.exclude) ? options.exclude : [];
+    const links = (options && options.links) ? options.links : {};
+    const linksTag = (options && options.linksTag) ? options.linksTag : "_links";
+    const resourceTag = (options && options.resourceTag) ? options.resourceTag : "_resource";
+
+    const link = (name, method, l) => {
+      if (name && method && l) {
+        var aLink = {};
+        alink[method] = l;
+        links[name] = aLink;
+      }
+      return model;
+    }
+
+    const getLinkData = (values) => {
+      var linkData = {};
+      if (links) {
+        for (const key in links) {
+          if (links.hasOwnProperty(key)) {
+            const link = links[key];
+            const method = lastElement(Object.keys(link));
+            var url = link[method];
+            const paramPattern = /\:([a-zA-z_0-9]*)/;
+            const arr = paramPattern.exec(url);
+            if (arr) {
+              // Replace parameters
+              url = `/${resource}/${url.split(arr[0]).join(values[arr[1]])}`;
+              // Remove extra slashes that may have been added
+              url = url.replace(/\/\/*/g, "/");
+              linkData[key] = {}
+              linkData[key][method] = url;
+            }
+          }
+        }
+      }
+      return Object.keys(linkData).length > 0 ? linkData : null;
+    }
+
+    model.link = link;
+    Model.prototype.toJSON = function() {
+      var values = Object.assign({}, this.get());
+      if (exclude) {
+        exclude.forEach(element => {
+          delete values[element];
+        });
+      }
+      const links = getLinkData(values);
+      const result = {}
+      if (links) {
+        result[linksTag] = links;
+      }
+      result[resourceTag] = values;
+      return result;
+    };
+    console.log(model);
+  }
+}
+
+module.exports = new HalDecorator()

package/index.js

@@ -1,5 +1,7 @@
 module.exports = {
   paginator : require("./paginator/s4-pagination"),
+  sqlPaginator : require("./paginator/sql-pagination"),
   logger : require("./logger/s4-logger"),
-  lastCommit : require("./last_commit")
+  lastCommit : require("./last_commit"),
+  halDecorator : require("./hal")
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sera4/essentia",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "A library of utilities for Teleporte Web Services",
   "main": "index.js",
   "scripts": {

package/paginator/README.md

@@ -0,0 +1,183 @@
+# PAGINATOR
+
+This is a module to add pagination to Sequelize ORM based projects.
+
+## Usage
+
+In your model definition, set pagination on your model
+
+```
+const paginator = require("@sera4/essentia).sqlPaginator;
+...
+
+module.exports = (sequelize, DataTypes) => {
+  const Post = sequelize.define('Post', {...}, {...});
+  // Add pagination
+  paginator.paginate(Post);
+  return Post;
+};
+```
+
+Later in your controller you can call the paginate method on your model
+to return paginated results:
+
+```
+app.get('/posts', (req, res) => {
+  Post.using(req.query).paginate()
+  .then(p => res.status(200).json(p));
+})
+```
+
+For example, calling `/posts?page_size=2&page_index=1 will return
+something similar to the following:
+
+```
+{
+    "_pagination": {
+        "current_page": 1,
+        "first_page": false,
+        "last_page": false,
+        "page_size": 2,
+        "total_pages": 2500,
+        "total_size": 5000,
+        "out_of_bounds": false,
+        "previous_page": 0,
+        "next_page": 2
+    },
+    "_collection": [
+        {
+            "id": 42803,
+            "title": "FYrlujXyrcviLIkQNQsyIXEaRdARCJqNPIDsDiFuLxENtFXPRS",
+            "name": "uLHnWSekmNNKueYiglAkAwWckFetoSnudXalelnAkpnayIgiUi",
+            "content": "THISkjbnGVprKVFsMnlNEhgDYSGRZcomhNkcrbnuvnqogCdUen",
+            "created_at": "2018-11-03T16:04:10.526Z",
+            "updated_at": "2018-11-03T16:04:10.526Z"
+        },
+        {
+            "id": 42804,
+            "title": "VHgYIBGIuyObzHjrpAwFwbtZSVMnCZdTIAIzzlQHChEPbwGwmU",
+            "name": "upvMbeIKAcuwHBruLyPcwEUYlAbQqqljUcMajOyvGaqCTahwfs",
+            "content": "EeopiRHsUdNNqzshkafYqkVzACOyWQpdPXCBSzuPBIDHWGqWuk",
+            "created_at": "2018-11-03T16:04:10.534Z",
+            "updated_at": "2018-11-03T16:04:10.534Z"
+        }
+    ]
+}
+```
+
+The `using` method takes 2 parameters:
+
+* options - this is where the pagination parameters are read from. By default the method will be looking for `page_size` and `page_index`
+* res - this is the express js response object and the method will also add pagination in the headers (if configured as such)
+
+You can configure the pagination globally via `paginator.configure(options)`. The following options are available:
+
+* Configuring the url keys for pagination:
+  * `paginateIn.size=page_size` - This is the key that will be used to parse number of items to read when the `using` method is called. Renaming this to `per_page` for examle, the url must contain the following query parameters `/posts?per_page=20` to load 20 posts
+  * `paginateIn.index=page_index` - This is the key that will be used to parse the offset to read when the `using` method is called. Renaming this to `page` requires an url with `/posts?page_size=20&page=2` to read rows 21 through 40 from the database.
+* Configure the way the pagination data is displayed
+  * `paginateOut.current_page=current_page` Label used to show the current page value in the pagination data
+  * `paginateOut.first_page=first_page` Label used to show the first page value in the pagination data
+  * `paginateOut.last_page=last_page` Label used to show the last page value in the pagination data
+  * `paginateOut.next_page=next_page` Label used to show the next page value in the pagination data
+  * `paginateOut.out_of_bounds=out_of_bounds` Label used to show the out of bounds value in the pagination data
+  * `paginateOut.page_size=page_size` Label used to show the page size value in the pagination data
+  * `paginateOut.previous_page=previous_page` Label used to show the previous size value in the pagination data
+  * `paginateOut.total_pages=total_pages` Label used to show the total pages value in the pagination data
+  * `paginateOut.total_size=total_size` Label used to show the total size value in the pagination data
+  * `paginateOut.links=""` Label used to show the links in the pagination data. If this value is empty or null, no links are added in the pagination data. If set to `true`, then a `_links` key is added to the pagination data with links to previous and next pages if available. You can provide a non empty string instead of `true` to use your own lable for this key.
+* Other configurations:
+  * `zeroBasedOffset=true` When false, the indexing is done from 1, otherwise it's done from 0 like in arrays
+  * `paginationHeader=tws-pagination` The name of the pagination header used when adding pagination in the headers
+  * `headersOnly=false` If this is set to true, then the pagination will return an array of objects and all the pagination data can be found in the headers. Otherwise the result will have a key for pagination (`_pagination`) and a key for the results (`_collection`)
+  * `paginationTag=_pagination` Used to overwrite the key name used for pagination
+  * `collectionTag=_collection` Used to overwrite the key name used for results
+
+The configuration is done globally, so you can add something like this as early as possible to your code:
+
+```
+paginator.configure({
+  paginateIn : {
+    size: "items_per_page",
+    index: "page_number",
+  },
+  paginateOut : {
+    links: "myLinks",
+    current_page: "the_current_page"
+  },
+  zeroBasedOffset : false,
+  paginationTag : "paginationData",
+  collectionTag : "paginatedCollection"
+});
+```
+
+This will require an url like `/posts?items_per_page=2&page_number=1` and will produce the following results:
+
+```
+{
+    "paginationData": {
+        "the_current_page": 1,
+        "first_page": true,
+        "last_page": false,
+        "page_size": 2,
+        "total_pages": 2500,
+        "total_size": 5000,
+        "out_of_bounds": false,
+        "next_page": 2,
+        "myLinks": {
+            "first_page": "?page_number=1&items_per_page=2",
+            "last_page": "?page_number=2500&items_per_page=2",
+            "next_page": "?page_number=2&items_per_page=2"
+        }
+    },
+    "paginatedCollection": [
+        {
+            "id": 42801,
+            "title": "LJitZgbNPLpOlnkYdynKlSYnCjuLBYiVHYMfAPlSALeoVTuNKw",
+            "name": "cvnititqxdPnHdomgxJJVGynNInkScmDlkzAALunYFHNRjffqE",
+            "content": "LcURropLnJiudElgAVhsBSMRBRNUzHLDiTebZxxpplXdpeGEFa",
+            "created_at": "2018-11-03T16:04:10.511Z",
+            "updated_at": "2018-11-03T16:04:10.511Z"
+        },
+        {
+            "id": 42802,
+            "title": "mTyXHFoJjgXmwASYvfFgZJcstUTbHjvrcuVoaUMdXZmXuMrfBz",
+            "name": "yxrOfMUdiJqNMNdWAfKXbsMsskKbpeRzxfEoicEcSdNDhGaPBE",
+            "content": "TEAEugRIeOfceEyREmAGcxldDbtzqlaWGDRMIjAhmfAuwJraot",
+            "created_at": "2018-11-03T16:04:10.518Z",
+            "updated_at": "2018-11-03T16:04:10.518Z"
+        }
+    ]
+}
+```
+
+You may notice that the links in the pagination only have query parameters. If you want to include the resource, provide the resource name when adding pagination to your model.
+
+For example:
+```
+const paginator = require("@sera4/essentia).sqlPaginator;
+...
+
+module.exports = (sequelize, DataTypes) => {
+  const Post = sequelize.define('Post', {...}, {...});
+  // Add pagination
+  paginator.paginate(Post, "/posts");
+  return Post;
+};
+```
+This will return pagination links in the pagination data prependend with the provided resource:
+```
+"myLinks": {
+    "first_page": "?page_number=1&items_per_page=2",
+    "last_page": "?page_number=2500&items_per_page=2",
+    "next_page": "?page_number=2&items_per_page=2"
+}
+```
+becomes
+```
+"myLinks": {
+    "first_page": "/posts?page_number=1&items_per_page=2",
+    "last_page": "/posts?page_number=2500&items_per_page=2",
+    "next_page": "/posts?page_number=2&items_per_page=2"
+}
+```

package/paginator/sql-pagination.js

@@ -0,0 +1,169 @@
+"use strict"
+
+class SequelizePaginator {
+
+  constructor() {
+    this.paginateIn = {
+      size: "page_size", 
+      index: "page_index"
+    };
+    this.paginateOut = {
+      current_page: "current_page",
+      first_page: "first_page",
+      last_page: "last_page",
+      next_page: "next_page",
+      out_of_bounds: "out_of_bounds",
+      page_size: "page_size",
+      previous_page: "previous_page",
+      total_pages: "total_pages",
+      total_size: "total_size",
+      links: "",
+    };
+    this.zeroBasedOffset = true;
+    this.paginationHeader = "tws-pagination";
+    this.headersOnly = false;
+    this.paginationTag = "_pagination";
+    this.collectionTag = "_collection";
+  }
+
+  paginate(Model, resource="") {
+    const model = Model.instance || Model;
+    var pagination = {limit : 15, offset: 1}
+    var response = null;
+    var resource = resource;
+
+    const using = (options, resp) => {
+      response = resp;
+      var limit = pagination.limit;
+      var offset = pagination.offset;
+
+      if (options && options[this.paginateIn.size]) {
+        limit = parseInt(options[this.paginateIn.size]);
+      }
+      if (options && options[this.paginateIn.index]) {
+        offset = parseInt(options[this.paginateIn.index]);
+      }
+      if (!Number.isInteger(limit) || limit < 1) {
+        limit = 1;
+      }
+      if (!Number.isInteger(offset) || offset < 0) {
+        offset = 0;
+      }
+      if (!this.zeroBasedOffset) {
+        offset = offset <= 1 ? 0 : offset - 1;
+      }
+
+      pagination.limit = limit;
+      pagination.offset = offset;
+      return model;
+    }
+
+    const paginate = (options) => {
+      if (!options) {
+        options = {};
+      }
+      options.limit = pagination.limit;
+      options.offset = pagination.limit * pagination.offset;
+
+      return new Promise((resolve, reject) => {
+        model.findAndCountAll(options)
+        .then(r => {
+          var paginationData = getPaginationData(r);
+          if (response) {
+            response.set(this.paginationHeader, JSON.stringify(paginationData));
+          }
+          var data = {};
+          if (this.headersOnly) {
+            data = r.rows
+          } else {
+            data[this.paginationTag] = addLinks(paginationData);
+            data[this.collectionTag] = r.rows;
+          }
+          resolve(data);
+        }).catch(e => reject(e));
+      });
+    }
+
+    const addLinks = (data) => {
+      var linksKey = null;
+      if (this.paginateOut.links === true) {
+        linksKey = "links"
+      } else if (this.paginateOut.links) {
+        linksKey = this.paginateOut.links;
+      }
+      if (data && linksKey && !data[this.paginateOut["out_of_bounds"]]) {
+        var links = {}
+        var firstPageIndex = this.zeroBasedOffset ? 0 : 1;
+        var lastPageIndex = this.zeroBasedOffset ? data[this.paginateOut["total_pages"]] - 1 : data[this.paginateOut["total_pages"]];
+        links[this.paginateOut["first_page"]] = `${resource}?${this.paginateIn["index"]}=${firstPageIndex}&${this.paginateIn["size"]}=${data[this.paginateOut["page_size"]]}`;
+        links[this.paginateOut["last_page"]] = `${resource}?${this.paginateIn["index"]}=${lastPageIndex}&${this.paginateIn["size"]}=${data[this.paginateOut["page_size"]]}`;
+        if (!data[this.paginateOut["first_page"]]) {
+          links[this.paginateOut["previous_page"]] = 
+          `${resource}?${this.paginateIn["index"]}=${data[this.paginateOut["previous_page"]]}&${this.paginateIn["size"]}=${data[this.paginateOut["page_size"]]}`;
+        } 
+        if (!data[this.paginateOut["last_page"]]) {
+          links[this.paginateOut["next_page"]] = 
+          `${resource}?${this.paginateIn["index"]}=${data[this.paginateOut["next_page"]]}&${this.paginateIn["size"]}=${data[this.paginateOut["page_size"]]}`;
+        }
+        data[linksKey] = links;
+      }
+      return data;
+    }
+
+    const getPaginationData = (result) => {
+      var currentPage = this.zeroBasedOffset ? pagination.offset : pagination.offset + 1;
+      var outOfBounds = result.rows.length === 0;
+      var totalPages = Math.ceil(result.count / pagination.limit);
+      var data = {};
+      data[this.paginateOut["current_page"]] = currentPage;
+      data[this.paginateOut["first_page"]] = outOfBounds ? false : pagination.offset === 0;
+      data[this.paginateOut["last_page"]] = outOfBounds ? false : (pagination.offset * pagination.limit) + pagination.limit >= result.count;
+      data[this.paginateOut["page_size"]] = pagination.limit;
+      data[this.paginateOut["total_pages"]] = totalPages;
+      data[this.paginateOut["total_size"]] = result.count;
+      data[this.paginateOut["out_of_bounds"]] = outOfBounds;
+      if (!outOfBounds) {
+        if ((this.zeroBasedOffset && currentPage > 0) || (!this.zeroBasedOffset && currentPage > 1)) {
+          data[this.paginateOut["previous_page"]] = currentPage - 1;
+        }
+        if ((this.zeroBasedOffset && currentPage + 1 < totalPages) || (!this.zeroBasedOffset && currentPage < totalPages)) {
+          data[this.paginateOut["next_page"]] = currentPage + 1;
+        }
+      }
+      return data;
+    }
+
+    model.using = using;
+    model.paginate = paginate;
+  }
+
+  configure(options) {
+    // Parse the object options
+    if (options.paginateIn) {
+      var x = options.paginateIn;
+      for (var key in this.paginateIn) {
+        if (this.paginateIn.hasOwnProperty(key) && x.hasOwnProperty(key)) {
+          this.paginateIn[key] = x[key];
+        }
+      }
+    }
+    if (options.paginateOut) {
+      var x = options.paginateOut;
+      for (var key in this.paginateOut) {
+        if (this.paginateOut.hasOwnProperty(key) && x.hasOwnProperty(key)) {
+          this.paginateOut[key] = x[key];
+        }
+      }
+    }
+    // Parse the simple options
+    for(var key in this) {
+      if (!["paginateIn", "paginateOut"].includes(key)) {
+        if (this.hasOwnProperty(key) && options.hasOwnProperty(key)) {
+          this[key] = options[key];
+        }
+      }
+    }
+  }
+}
+
+module.exports = new SequelizePaginator();