@modular-rest/server 1.6.5 → 1.7.0

package/README.md

@@ -6,6 +6,8 @@ a nodejs module based on KOAJS for developing Rest-APIs in a modular solution.
 this module has one method:
 - `createRest`: is the main functionality of the module.
 
+**Note**: active "javascript.implicitProjectConfig.checkJs": true in your vscode settings.
+
 ## Install 
 
 Install using [npm](https://www.npmjs.com/package/modular-rest):

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@modular-rest/server",
-  "version": "1.6.5",
+  "version": "1.7.0",
   "description": "a nodejs module based on KOAJS for developing Rest-APIs in a modular solution.",
   "main": "src/index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "generate:types": "tsc"
   },
+  "types": "./types/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/navidshad/modular-rest.git"
@@ -35,5 +37,8 @@
     "mongoose": "^5.10.9",
     "nested-property": "^4.0.0"
   },
-  "devDependencies": {}
+  "devDependencies": {
+    "@types/koa": "^2.14.0",
+    "typescript": "^5.3.3"
+  }
 }

package/src/application.js

@@ -1,89 +1,53 @@
-let koa = require("koa");
+const koa = require("koa");
 const cors = require("@koa/cors");
 const koaBody = require("koa-body");
 const koaStatic = require("koa-static-server");
-var path = require("path");
-var Combination = require("./class/combinator");
-let DataProvider = require("./services/data_provider/service");
-let UserService = require("./services/user_manager/service");
+const path = require("path");
+const Combination = require("./class/combinator");
+const DataProvider = require("./services/data_provider/service");
+const UserService = require("./services/user_manager/service");
 
 let defaultServiceRoot = __dirname + "/services";
 
-// staticOptions = {
-//     /**
-//          * directory that is to be served
-//          */
-// rootDir?: string | undefined;
-// /**
-//  * optional rewrite path
-//  */
-// rootPath?: string | undefined;
-// /**
-//  * optional default file to serve if requested static is missing
-//  */
-// notFoundFile?: string | undefined;
-// /**
-//  * request access log to console
-//  */
-// log?: boolean | undefined;
-// /**
-//  * don't execute any downstream middleware. defaults to true
-//  */
-// last?: boolean | undefined;
-// /**
-//  * Browser cache max-age in milliseconds. defaults to 0
-//  */
-// maxage?: number | undefined;
-// /**
-//  * Allow transfer of hidden files. defaults to false
-//  */
-// hidden?: boolean | undefined;
-// /**
-//  * Try to serve the gzipped version of a file automatically when gzip is supported by a client and if the requested
-//  */
-// gzip?: boolean | undefined;
-// /**
-//  * Try to serve the brotli version of a file automatically when brotli is supported by a client and in the requested
-//  */
-// brotli?: boolean | undefined;
-// index?: string | undefined;
-// }
+/**
+ * @typedef {import('koa')} Koa
+ */
 
 /**
  * @param {{
- *   cors: any; // Options for @koa/cors middleware.
- *   modulesPath: string; // Root directory of your router.js/db.js files.
- *   static: {
- *      rootDir: string; // Root directory of your static files.
- *      rootPath: string; // Root path of your static files.
- *      notFoundFile: string; // Not found file.
- *      log: boolean; // Log requests to console.
- *      last: boolean; // Don't execute any downstream middleware.
- *      maxage: number; // Browser cache max-age in milliseconds.
- *      hidden: boolean; // Allow transfer of hidden files.
- *      gzip: boolean; // Try to serve the gzipped version of a file automatically when gzip is supported by a client and if the requested
- *      brotli: boolean; // Try to serve the brotli version of a file automatically when brotli is supported by a client and in the requested
- *      index: string; // Index file.
+ *   cors?: any; // Options for @koa/cors middleware.
+ *   modulesPath?: string; // Root directory of your router.js/db.js files.
+ *   staticPath?: {
+ *      rootDir?: string; // Root directory of your static files.
+ *      rootPath?: string; // Root path of your static files.
+ *      notFoundFile?: string; // Not found file.
+ *      log?: boolean; // Log requests to console.
+ *      last?: boolean; // Don't execute any downstream middleware.
+ *      maxage?: number; // Browser cache max-age in milliseconds.
+ *      hidden?: boolean; // Allow transfer of hidden files.
+ *      gzip?: boolean; // Try to serve the gzipped version of a file automatically when gzip is supported by a client and if the requested file exists.
+ *      brotli?: boolean; // Try to serve the brotli version of a file automatically when brotli is supported by a client and if the requested file exists.
+ *      index?: string; // Index file.
  *   };
- *   onBeforeInit: (koaApp) => void; // A callback called before initializing the Koa server.
- *   onAfterInit: (koaApp) => void; // A callback called after server initialization.
- *   port: number; // Server port.
- *   dontListen: boolean; // If true, the server will not run and will only return the Koa app object.
- *   mongo: {
+ *   onBeforeInit?: (koaApp:Koa) => void; // A callback called before initializing the Koa server.
+ *   onAfterInit?: (koaApp:Koa) => void; // A callback called after server initialization.
+ *   port?: number; // Server port.
+ *   dontListen?: boolean; // If true, the server will not run and will only return the Koa app object.
+ *   mongo?: {
  *     dbPrefix: string; // A prefix for your database name.
  *     mongoBaseAddress: string; // The address of your MongoDB server without any database specification.
- *     addressMap: string; // Specific addresses for each database.
+ *     addressMap?: string; // Specific addresses for each database.
  *   };
- *   keypair: {
+ *   keypair?: {
  *     private: string; // Private key for RSA authentication.
  *     public: string; // Public key for RSA authentication.
  *   };
- *   adminUser: {
+ *   adminUser?: {
  *     email: string; // Admin user email.
  *     password: string; // Admin user password.
  *   };
  *   verificationCodeGeneratorMethod: () => string; // A method to return a verification code when registering a new user.
- *   collectionDefinitions: CollectionDefinition[]; // An array of additional collection definitions.
+ *   collectionDefinitions?: CollectionDefinition[]; // An array of additional collection definitions.
  * }} options
  */
 module.exports = async function createRest(options) {
@@ -121,8 +85,8 @@ module.exports = async function createRest(options) {
   /**
    * Plug In KoaStatic
    */
-  if (options.static) {
-    app.use(koaStatic(options.static));
+  if (options.staticPath) {
+    app.use(koaStatic(options.staticPath));
   }
 
   /**

package/src/class/collection_definition.js

@@ -1,25 +1,33 @@
-module.exports = class CollectionDefinition {
-    /**
-     * This class helps to create a mongoose collection 
-     * associated with permissions and triggers .
-     * 
-     * @param {object} option
-     * @param {string} option.db database name
-     * @param {string} option.collection collection name
-     * @param {object} option.schema mongoose schema
-     * @param {array} option.permissions a list of Permission for this collection 
-     * @param {array} option.trigger a DatabaseTrigger
-     */
-    constructor({ db, collection, schema, permissions, trigger }) {
-        // string
-        this.database = db;
-        // string
-        this.collection = collection;
-        // schema object of mongoose
-        this.schema = schema;
-        // a list of Permission for this collection
-        this.permissions = permissions;
+/**
+ * @typedef {import('./security.js').Permission} Permission
+ * @typedef {import('./database_trigger.js')} DatabaseTrigger
+ */
 
-        this.trigger = trigger;
-    }
-}
+class CollectionDefinition {
+  /**
+   * This class helps to create a mongoose collection
+   * associated with permissions and triggers.
+   *
+   * @class
+   * @param {Object} option
+   * @param {string} option.db - Database name
+   * @param {string} option.collection - Collection name
+   * @param {Object} option.schema - Mongoose schema
+   * @param {Array<Permission>} option.permissions - A list of permissions for this collection
+   * @param {Array<DatabaseTrigger>} option.trigger - A database trigger
+   */
+  constructor({ db, collection, schema, permissions, trigger }) {
+    // string
+    this.database = db;
+    // string
+    this.collection = collection;
+    // schema object of mongoose
+    this.schema = schema;
+    // a list of Permission for this collection
+    this.permissions = permissions;
+
+    this.trigger = trigger;
+  }
+}
+
+module.exports = CollectionDefinition;

package/src/class/combinator.js

@@ -1,90 +1,101 @@
-let Router = require('koa-router');
-let directory = require('./directory.js');
+let Router = require("koa-router");
+let directory = require("./directory.js");
 
 class Combinator {
+  async combineRoutesByFilePath(rootDirectory, app) {
+    // find route paths
+    let option = { name: "router", filter: [".js"] };
+    let routerPaths = await directory
+      .find(rootDirectory, option)
+      .then()
+      .catch((e) => {
+        console.log(e);
+      });
 
-    async combineRoutesByFilePath(rootDirectory, app) {
-        // find route paths
-        let option = { name: 'router', filter: ['.js'] }
-        let routerPaths = await directory.find(rootDirectory, option).then()
-            .catch(e => { console.log(e) });
+    // create and combine routes into the app
+    for (let i = 0; i < routerPaths.length; i++) {
+      let service = require(routerPaths[i]);
+      let name = service.name;
 
-        // create and combine routes into the app
-        for (let i = 0; i < routerPaths.length; i++) {
-            let service = require(routerPaths[i]);
-            let name = service.name;
+      var serviceRouter = new Router();
+      serviceRouter.use(`/${name}`, service.main.routes());
 
-
-            var serviceRouter = new Router();
-            serviceRouter.use(`/${name}`, service.main.routes());
-
-            app.use(serviceRouter.routes());
-        }
+      app.use(serviceRouter.routes());
     }
+  }
 
-    /**
-     * 
-     * @param {object} option
-     * @param {string} option.rootDirectory root directory of files
-     * @param {object} option.filename an object of {name, extension} 
-     * @param {string} option.filename.name name of file
-     * @param {string} option.filename.extension the extension of the file
-     * @param {boolean} option.combineWithRoot combine all file content and return theme as a object
-     * @param {boolean} option.convertToArray return file content as an array instead an object
-     */
-    async combineModulesByFilePath({
-        rootDirectory, filename, combineWithRoot, convertToArray
-    }) {
-        // find route paths
-        let rootObject_temp;
-        let option = { name: filename.name, filter: [filename.extension] }
-        let modulesPath = await directory.find(rootDirectory, option).then()
-            .catch(e => { console.log(e) });
+  /**
+   *
+   * @param {object} option
+   * @param {string} option.rootDirectory root directory of files
+   * @param {object} option.filename an object of {name, extension}
+   * @param {string} option.filename.name name of file
+   * @param {string} option.filename.extension the extension of the file
+   * @param {boolean} option.combineWithRoot combine all file content and return theme as a object
+   * @param {boolean} option.convertToArray return file content as an array instead an object
+   */
+  async combineModulesByFilePath({
+    rootDirectory,
+    filename,
+    combineWithRoot,
+    convertToArray,
+  }) {
+    // find route paths
+    let rootObject_temp;
+    let option = { name: filename.name, filter: [filename.extension] };
+    let modulesPath = await directory
+      .find(rootDirectory, option)
+      .then()
+      .catch((e) => {
+        console.log(e);
+      });
 
-        // create and combine routes into the app
-        for (let i = 0; i < modulesPath.length; i++) {
-            let moduleObject = require(modulesPath[i]);
+    // create and combine routes into the app
+    for (let i = 0; i < modulesPath.length; i++) {
+      let moduleObject = require(modulesPath[i]);
 
-            //act by otherOption
-            if (combineWithRoot) {
-                if(moduleObject.name)
-                    delete moduleObject.name;
+      //act by otherOption
+      if (combineWithRoot) {
+        if (moduleObject.name) delete moduleObject.name;
 
-                if(moduleObject.length) {
-                    if(!rootObject_temp) rootObject_temp = [];
-
-                    rootObject_temp = [...rootObject_temp, ...moduleObject];
-                }
-                else {
-                    rootObject_temp = this.extendObj(rootObject_temp, moduleObject);
-                }
-                // else if (typeof)
-            }
-            // default act
-            else {
-                let name = moduleObject.name;
-                rootObject_temp[name] = moduleObject;
-            }
-        }
+        if (moduleObject.length) {
+          if (!rootObject_temp) rootObject_temp = [];
 
-        // options 
-        // convertToArray
-        if (convertToArray) {
-            rootObject_temp = Object.values(rootObject_temp);
+          rootObject_temp = [...rootObject_temp, ...moduleObject];
+        } else {
+          rootObject_temp = this.extendObj(rootObject_temp, moduleObject);
         }
+        // else if (typeof)
+      }
+      // default act
+      else {
+        let name = moduleObject.name;
+        rootObject_temp[name] = moduleObject;
+      }
+    }
 
-        // set result to main rootObject
-        return rootObject_temp;
+    // options
+    // convertToArray
+    if (convertToArray) {
+      rootObject_temp = Object.values(rootObject_temp);
     }
 
-    extendObj(obj, src) {
-        for (var key in src) {
-            if (src.hasOwnProperty(key))
-                obj[key] = src[key];
-        }
-        return obj;
+    // set result to main rootObject
+    return rootObject_temp;
+  }
+
+  extendObj(obj, src) {
+    for (var key in src) {
+      if (src.hasOwnProperty(key)) obj[key] = src[key];
     }
+    return obj;
+  }
+
+  static get instance() {
+    return instance;
+  }
 }
 
-Combinator.instance = new Combinator();
+const instance = new Combinator();
+
 module.exports = Combinator.instance;

package/src/class/database_trigger.js

@@ -1,15 +1,21 @@
+/**
+ * `DatabaseTrigger` is a class that defines a callback to be called on a specific database transaction.
+ *
+ * @class
+ */
 class DatabaseTrigger {
-    /**
-     * Is a definition for a callback being called on 
-     * a specific database transaction.
-     * 
-     * @param {string} operation Operation name
-     * @param {function} callback trigger callback
-     */
-    constructor(operation, callback = (query, queryResult) => { }) {
-        this.operation = operation;
-        this.callback = callback;
-    }
+  /**
+   * Creates a new instance of `DatabaseTrigger`.
+   *
+   * @param {string} operation - The name of the operation on which the callback should be triggered.
+   * @param {function} [callback=(query, queryResult) => {}] - The callback function to be triggered. It accepts two parameters:
+   * 1. `query` - The query that is being executed.
+   * 2. `queryResult` - The result of the query execution.
+   */
+  constructor(operation, callback = (query, queryResult) => {}) {
+    this.operation = operation;
+    this.callback = callback;
+  }
 }
 
-module.exports = DatabaseTrigger;
+module.exports = DatabaseTrigger;

package/src/class/db_schemas.js

@@ -1,14 +1,14 @@
-var mongoose = require('mongoose');
+var mongoose = require("mongoose");
 var Schema = mongoose.Schema;
 
 module.exports = {
-    'file': new Schema({
-        originalName: String,
-        fileName: String,
-        owner: String,
-        format: String,
-        // Tag being used as the parent dir for files
-        // uploaddir/$format/$tag/timestamp.format
-        tag: String,
-    })
-}
+  file: new Schema({
+    originalName: String,
+    fileName: String,
+    owner: String,
+    format: String,
+    // Tag being used as the parent dir for files
+    // uploadDir/$format/$tag/timestamp.format
+    tag: String,
+  }),
+};

package/src/class/security.js

@@ -1,44 +1,118 @@
+/**
+ * Class representing an access definition.
+ */
 class AccessDefinition {
-    constructor({ database, collection, permissionList }) {
-        this.database = database;
-        this.collection = collection;
-        this.permissionList = permissionList;
-    }
+  /**
+   * Create an access definition.
+   * @param {Object} options - The options for the access definition.
+   * @param {string} options.database - The name of the database.
+   * @param {string} options.collection - The name of the collection.
+   * @param {Array.<Permission>} options.permissionList - The list of permissions.
+   */
+  constructor({ database, collection, permissionList }) {
+    this.database = database;
+    this.collection = collection;
+    this.permissionList = permissionList;
+  }
 }
 
+/**
+ * @typedef {('god_access'|'user_access'|'delete'|'upload_file_access'|'remove_file_access'|'anonymous_access')} PermissionType
+ */
+
+/**
+ * Class representing a permission.
+ */
 class Permission {
-    constructor({ type, read = false, write = false, onlyOwnData = false }) {
-        this.type = type;
-        this.read = read;
-        this.write = write;
-        /**
-         * If true users can perform CRUD on documents that they created already.
-         */
-        this.onlyOwnData = onlyOwnData;
-    }
+  /**
+   * Create a permission.
+   * @param {Object} options - The options for the permission.
+   * @param {PermissionType} options.type - The type of the permission.
+   * @param {boolean} [options.read=false] - The read access of the permission.
+   * @param {boolean} [options.write=false] - The write access of the permission.
+   * @param {boolean} [options.onlyOwnData=false] - If true, users can perform CRUD on documents that they created already.
+   */
+  constructor({ type, read = false, write = false, onlyOwnData = false }) {
+    this.type = type;
+    this.read = read;
+    this.write = write;
+    this.onlyOwnData = onlyOwnData;
+  }
 }
 
+/**
+ * Class representing different types of permissions.
+ * Each static getter returns a string that represents a specific type of permission.
+ */
 class PermissionTypes {
-    constructor() {
-        this.god_access = 'god_access';
-        this.user_access = 'user_access';
-        this.upload_file_access = 'upload_file_access';
-        this.remove_file_access = 'remove_file_access';
-        this.anonymous_access = 'anonymous_access';
-    }
-
-    static get god_access() { return 'god_access' };
-    static get user_access() { return 'user_access' };
-    static get upload_file_access() { return 'upload_file_access' };
-    static get remove_file_access() { return 'remove_file_access' };
-    static get anonymous_access() { return 'anonymous_access' };
+  /**
+   * Create permission types.
+   * Each property represents a specific type of permission.
+   */
+  constructor() {
+    this.god_access = "god_access"; // Represents god access permission type
+    this.user_access = "user_access"; // Represents user access permission type
+    this.upload_file_access = "upload_file_access"; // Represents upload file access permission type
+    this.remove_file_access = "remove_file_access"; // Represents remove file access permission type
+    this.anonymous_access = "anonymous_access"; // Represents anonymous access permission type
+  }
+
+  /**
+   * Get the string representing god access permission type.
+   * @return {string} The god access permission type.
+   */
+  static get god_access() {
+    return "god_access";
+  }
+
+  /**
+   * Get the string representing user access permission type.
+   * @return {string} The user access permission type.
+   */
+  static get user_access() {
+    return "user_access";
+  }
+
+  /**
+   * Get the string representing upload file access permission type.
+   * @return {string} The upload file access permission type.
+   */
+  static get upload_file_access() {
+    return "upload_file_access";
+  }
+
+  /**
+   * Get the string representing remove file access permission type.
+   * @return {string} The remove file access permission type.
+   */
+  static get remove_file_access() {
+    return "remove_file_access";
+  }
+
+  /**
+   * Get the string representing anonymous access permission type.
+   * @return {string} The anonymous access permission type.
+   */
+  static get anonymous_access() {
+    return "anonymous_access";
+  }
 }
 
+/**
+ * Class representing access types.
+ */
 class AccessTypes {
-    static get read() { return 'read' };
-    static get write() { return 'write' };
+  static get read() {
+    return "read";
+  }
+  static get write() {
+    return "write";
+  }
 }
 
 module.exports = {
-    AccessDefinition, Permission, PermissionTypes, AccessTypes
-}
+  AccessDefinition,
+  Permission,
+  PermissionTypes,
+  AccessTypes,
+};