@modular-rest/server 1.11.12 → 1.12.0

package/package.json

@@ -1,47 +1,60 @@
 {
-  "name": "@modular-rest/server",
-  "version": "1.11.12",
-  "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",
-    "generate:types": "tsc"
-  },
-  "types": "./types/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/modular-rest/modular-rest.git"
-  },
-  "keywords": [
-    "app",
-    "rest",
-    "api",
-    "koa"
-  ],
-  "author": "Navid Shad <navidshad72@gmail.com> (http://navid-shad.ir)",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/modular-rest/modular-rest/issues"
-  },
-  "homepage": "https://github.com/modular-rest/modular-rest#readme",
-  "dependencies": {
-    "@koa/cors": "^3.1.0",
-    "colog": "^1.0.4",
-    "file-system": "^2.2.2",
-    "jsonwebtoken": "^8.5.1",
-    "keypair": "^1.0.4",
-    "koa": "^2.5.3",
-    "koa-body": "^4.2.0",
-    "koa-mount": "^4.0.0",
-    "koa-router": "^7.4.0",
-    "koa-static": "^5.0.0",
-    "mongoose": "^5.10.9",
-    "nested-property": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/bson": "4.2.0",
-    "@types/koa": "^2.14.0",
-    "@types/koa__cors": "^5.0.0",
-    "typescript": "^5.3.3"
-  }
+	"name": "@modular-rest/server",
+	"version": "1.12.0",
+	"description": "TypeScript version of a nodejs module based on KOAJS for developing Rest-APIs in a modular solution.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"test": "echo \"Error: no test specified\" && exit 1",
+		"play-test": "tsc -p tsconfig.json && node dist/play-test.js",
+		"docs": "typedoc --router kind src/index.ts"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/modular-rest/modular-rest.git"
+	},
+	"keywords": [
+		"app",
+		"rest",
+		"api",
+		"koa",
+		"typescript"
+	],
+	"author": "Navid Shad <navidshad72@gmail.com> (http://navid-shad.ir)",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/modular-rest/modular-rest/issues"
+	},
+	"homepage": "https://github.com/modular-rest/modular-rest#readme",
+	"dependencies": {
+		"@koa/cors": "^3.1.0",
+		"colog": "^1.0.4",
+		"file-system": "^2.2.2",
+		"jsonwebtoken": "^8.5.1",
+		"keypair": "^1.0.4",
+		"koa": "^2.5.3",
+		"koa-body": "6.0.1",
+		"koa-mount": "^4.0.0",
+		"koa-router": "^7.4.0",
+		"koa-static": "^5.0.0",
+		"mongoose": "^5.10.9",
+		"nested-property": "^4.0.0"
+	},
+	"devDependencies": {
+		"@types/bson": "4.2.0",
+		"@types/jsonwebtoken": "^9.0.5",
+		"@types/koa": "^2.14.0",
+		"@types/koa-mount": "^4.0.5",
+		"@types/koa-router": "^7.4.8",
+		"@types/koa-static": "^4.0.4",
+		"@types/koa__cors": "^5.0.0",
+		"@types/mongoose": "^5.10.5",
+		"@types/node": "^20.10.0",
+		"typedoc": "^0.28.1",
+		"typedoc-plugin-markdown": "^4.6.0",
+		"typedoc-plugin-missing-exports": "^4.0.0",
+		"typescript": "^5.3.3"
+	}
 }

package/src/application.ts

@@ -0,0 +1,206 @@
+import Koa from 'koa';
+import cors from '@koa/cors';
+import koaBody from 'koa-body';
+import koaStatic from 'koa-static';
+import mount from 'koa-mount';
+import path from 'path';
+import { Server } from 'http';
+import Combination from './class/combinator';
+import * as DataProvider from './services/data_provider/service';
+import { MongoOption } from './services/data_provider/service';
+import * as UserService from './services/user_manager/service';
+import { config, setConfig, RestOptions, StaticPathOptions } from './config';
+import { permissionGroups as defaultPermissionGroups } from './defult-permissions';
+
+const defaultServiceRoot = __dirname + '/services';
+
+/**
+ * Create a modular REST instance with Koa and MongoDB support.
+ *
+ * @param {RestOptions} options - Options for the REST instance
+ * @expandType RestOptions
+ *
+ * @returns {Promise<{ app: Koa; server?: Server }>} - A promise that resolves to the Koa app and server
+ *
+ * @example
+ * import { createRest } from '@modular-rest/server';
+ *
+ * const app = createRest({
+ *   port: '80',
+ *   mongo: {
+ *     mongoBaseAddress: 'mongodb://localhost:27017',
+ *     dbPrefix: 'mrest_'
+ *   },
+ *   onBeforeInit: (koaApp) => {
+ *     // do something before init with the koa app
+ *   }
+ * })
+ */
+export async function createRest(options: RestOptions): Promise<{ app: Koa; server?: Server }> {
+  setConfig({
+    port: 3000,
+    dontListen: false,
+    mongo: {
+      mongoBaseAddress: 'mongodb://localhost:27017',
+      dbPrefix: 'mrest_',
+    },
+    adminUser: {
+      email: 'admin@email.com',
+      password: '@dmin',
+    },
+    ...options,
+  });
+
+  if (config.permissionGroups === undefined) {
+    config.permissionGroups = defaultPermissionGroups;
+  }
+
+  const app = new Koa();
+
+  /**
+   * Plug in Cors
+   */
+  app.use(cors(config.cors || {}));
+
+  /**
+   * Plug in BodyParser
+   */
+  const bodyParserOptions = {
+    multipart: true,
+    ...(config.koaBodyOptions || {}),
+  };
+  app.use(koaBody(bodyParserOptions));
+
+  /**
+   * Plug In KoaStatic
+   */
+  if (config.staticPath) {
+    const defaultStaticPath = config.staticPath.actualPath || '';
+    const defaultStaticRootPath = config.staticPath.path || '/assets';
+
+    const staticOptions: Partial<StaticPathOptions> = { ...config.staticPath };
+
+    delete staticOptions.actualPath;
+    delete staticOptions.path;
+
+    app.use(mount(defaultStaticRootPath, koaStatic(defaultStaticPath, staticOptions)));
+  }
+
+  /**
+   * Run before hook
+   */
+  if (config.onBeforeInit) config.onBeforeInit(app);
+
+  /**
+   * Setup default services
+   *
+   * - Collect and plug in router.js/db.js of default services
+   * - Setting up default services
+   */
+
+  // 1. Plug in default routes
+  await Combination.combineRoutesByFilePath(path.join(defaultServiceRoot), app);
+
+  // Collect default databaseDefinitions
+  const defaultDatabaseDefinitionList = await Combination.combineModulesByFilePath({
+    rootDirectory: defaultServiceRoot,
+    filename: {
+      name: 'db',
+      extension: '.js',
+    },
+    combineWithRoot: true,
+  });
+
+  // 2. Plug in default databaseDefinitions
+  await DataProvider.addCollectionDefinitionByList({
+    list: defaultDatabaseDefinitionList,
+    mongoOption: config.mongo as MongoOption,
+  });
+
+  /**
+   * User Services
+   *
+   * 3. Plug in routes and database
+   */
+  if (config.modulesPath) {
+    // Plug in user routes
+    await Combination.combineRoutesByFilePath(config.modulesPath, app);
+
+    // Collect user CollectionDefinitions (db.js files)
+    let userDatabaseDetail: any[] = [];
+    userDatabaseDetail = await Combination.combineModulesByFilePath({
+      rootDirectory: config.modulesPath,
+      filename: {
+        name: 'db',
+        extension: '.js',
+      },
+      combineWithRoot: true,
+    });
+
+    // Combine additional CollectionDefinitions
+    if (config.collectionDefinitions) {
+      userDatabaseDetail = userDatabaseDetail.concat(config.collectionDefinitions);
+    }
+
+    // Plug in user CollectionDefinitions
+    await DataProvider.addCollectionDefinitionByList({
+      list: userDatabaseDetail || [],
+      mongoOption: config.mongo as MongoOption,
+    });
+
+    // Plug in Verification method
+    if (typeof config.verificationCodeGeneratorMethod === 'function') {
+      UserService.main.setCustomVerificationCodeGeneratorMethod(
+        config.verificationCodeGeneratorMethod
+      );
+    }
+
+    // 4. plug in modular functions
+    await Combination.combineFunctionsByFilePath({
+      rootDirectory: config.modulesPath,
+      filename: {
+        name: 'functions',
+        extension: '.js',
+      },
+    });
+
+    // 5. Plug in additional defined functions
+    if (config.functions) {
+      Combination.addFunctionsByArray(config.functions);
+    }
+  }
+
+  // 4. Setting up default services
+  try {
+    await require('./helper/presetup_services').setup(options);
+  } catch (e) {
+    return Promise.reject(e);
+  }
+
+  /**
+   * Run the server
+   *
+   * return KOA app object
+   */
+  return new Promise((done, reject) => {
+    try {
+      let server: Server | undefined;
+
+      if (!config.dontListen) {
+        server = app.listen(config.port);
+
+        console.log('\x1b[35m', `KOAS has been launched on: localhost:${config.port}`);
+      }
+
+      // on after init
+      if (config.onAfterInit) config.onAfterInit(app);
+
+      done({
+        app,
+        server,
+      });
+    } catch (err) {
+      reject(err);
+    }
+  });
+}

package/src/class/cms_trigger.ts

@@ -0,0 +1,68 @@
+/**
+ * Type for CMS operations that can trigger a callback
+ * @typedef {('update-one' | 'insert-one' | 'remove-one')} CmsOperation
+ * @description Supported CMS operations:
+ * - 'update-one': Triggered when updating a single document in the CMS
+ * - 'insert-one': Triggered when inserting a new document in the CMS
+ * - 'remove-one': Triggered when removing a document from the CMS
+ */
+export type CmsOperation = 'update-one' | 'insert-one' | 'remove-one';
+
+/**
+ * Context interface for CMS trigger callbacks
+ * @interface CmsTriggerContext
+ * @property {Record<string, any>} query - The query parameters used in the CMS operation
+ * @property {any} queryResult - The result of the CMS operation
+ */
+export interface CmsTriggerContext {
+  query: Record<string, any>;
+  queryResult: any;
+}
+
+/**
+ * Defines a callback to be executed on specific CMS operations
+ * @class CmsTrigger
+ * @property {CmsOperation} operation - The CMS operation that triggers the callback
+ * @property {Function} callback - The callback function to be executed
+ * @example
+ * ```typescript
+ * const trigger = new CmsTrigger('insert-one', (context) => {
+ *   console.log('New CMS document inserted:', context.queryResult);
+ *   // Perform additional actions after CMS document insertion
+ * });
+ *
+ * // Use the trigger in RestOptions
+ * const { app } = await createRest({
+ *   authTriggers: [trigger],
+ *   // ... other options
+ * });
+ * ```
+ */
+export class CmsTrigger {
+  operation: CmsOperation;
+  callback: (context: CmsTriggerContext) => void;
+
+  /**
+   * Creates a new CmsTrigger instance
+   * @param {CmsOperation} operation - The CMS operation to trigger on
+   * @param {Function} [callback=() => {}] - The callback function to execute
+   * @example
+   * ```typescript
+   * // Log all CMS updates
+   * const updateTrigger = new CmsTrigger('update-one', (context) => {
+   *   console.log('CMS document updated:', context.queryResult);
+   * });
+   *
+   * // Track CMS document removals
+   * const removeTrigger = new CmsTrigger('remove-one', (context) => {
+   *   console.log('CMS document removed:', context.queryResult);
+   * });
+   * ```
+   */
+  constructor(operation: CmsOperation, callback: (context: CmsTriggerContext) => void = () => {}) {
+    this.operation = operation;
+    this.callback = callback;
+  }
+}
+
+export default CmsTrigger;

package/src/class/collection_definition.ts

@@ -0,0 +1,134 @@
+import { Schema } from 'mongoose';
+import { Permission } from './security';
+import { DatabaseTrigger } from './database_trigger';
+
+/**
+ * Configuration options for creating a collection definition.
+ * This interface defines the structure for configuring MongoDB collections with their associated
+ * schemas, permissions, and triggers.
+ *
+ * @inline
+ *
+ */
+interface CollectionDefinitionOptions {
+  /** The name of the database where the collection resides */
+  database: string;
+  /** The name of the collection to be configured */
+  collection: string;
+  /** List of permissions controlling access to the collection */
+  permissions: Permission[];
+  /** Optional database triggers for custom operations */
+  triggers?: DatabaseTrigger[];
+
+  /**
+   * Mongoose schema definition for the collection
+   * @type {Schema}
+   * @see https://mongoosejs.com/docs/5.x/docs/guide.html
+   */
+  schema: Schema;
+}
+
+/**
+ * To have define any collection in your database you haveto use below method in your `db.[js|ts]` file and export an array of CollectionDefinition instances.
+ *
+ * @param {CollectionDefinitionOptions} options - The options for the collection
+ * @expandType CollectionDefinitionOptions
+ *
+ * @returns A new instance of CollectionDefinition
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { defineCollection } from '@modular-rest/server';
+ *
+ * export default [
+ *   defineCollection({
+ *     database: 'users',
+ *     collection: 'info',
+ *     // schema: Schema,
+ *     // permissions: Permission[]
+ *     // trigger: DatabaseTrigger[]
+ *   })
+ * ]
+ * ```
+ */
+export function defineCollection(options: CollectionDefinitionOptions) {
+  return new CollectionDefinition(options);
+}
+
+/**
+ * A class that represents a MongoDB collection configuration. Provides full support for schema validation, access control through permissions,
+ * and custom triggers for various database operations.
+ *
+ * @hideconstructor
+ *
+ * @deprecated Use `defineCollection` instead.
+ *
+ * @example
+ * ```typescript
+ * const userSchema = new Schema({
+ *   name: String,
+ *   email: String,
+ *   age: Number
+ * });
+ *
+ * const collection = new CollectionDefinition({
+ *   database: 'myapp',
+ *   collection: 'users',
+ *   schema: userSchema,
+ *   permissions: [
+ *     new Permission({
+ *       type: 'user_access',
+ *       read: true,
+ *       write: true
+ *     })
+ *   ],
+ *   triggers: [
+ *     new DatabaseTrigger('insert-one', (data) => {
+ *       console.log('New user created:', data);
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @private
+ */
+export class CollectionDefinition {
+  /** @readonly The name of the database */
+  database: string;
+
+  /** @readonly The name of the collection */
+  collection: string;
+
+  /** @readonly Mongoose schema definition */
+  schema: Schema;
+
+  /** @readonly List of permissions for the collection */
+  permissions: Permission[];
+
+  /** @readonly Optional database triggers */
+  triggers?: DatabaseTrigger[];
+
+  /**
+   * Creates a new CollectionDefinition instance
+   *
+   * @param options - Configuration options for the collection
+   * @returns A new instance of CollectionDefinition
+   *
+   * @beta
+   */
+  constructor({
+    database,
+    collection,
+    schema,
+    permissions,
+    triggers,
+  }: CollectionDefinitionOptions) {
+    this.database = database;
+    this.collection = collection;
+    this.schema = schema;
+    this.permissions = permissions;
+    this.triggers = triggers;
+  }
+}

package/src/class/combinator.ts

@@ -0,0 +1,176 @@
+import Router from 'koa-router';
+import Koa from 'koa';
+import * as directory from './directory';
+import { addFunction } from '../services/functions/service';
+
+interface FilenameOption {
+  name: string;
+  extension: string;
+}
+
+interface ModuleOptions {
+  rootDirectory: string;
+  filename: FilenameOption;
+  combineWithRoot?: boolean;
+  convertToArray?: boolean;
+}
+
+interface FunctionOptions {
+  rootDirectory: string;
+  filename: FilenameOption;
+}
+
+class Combinator {
+  async combineRoutesByFilePath(rootDirectory: string, app: Koa): Promise<void> {
+    // find route paths
+    const option = {
+      name: 'router',
+      filter: ['.js'],
+    };
+
+    let routerPaths: string[] = [];
+    try {
+      routerPaths = await directory.find(rootDirectory, option);
+    } catch (e) {
+      console.log(e);
+    }
+
+    // create and combine routes into the app
+    for (let i = 0; i < routerPaths.length; i++) {
+      const service = require(routerPaths[i]);
+      const name = service.name;
+
+      const serviceRouter = new Router();
+      serviceRouter.use(`/${name}`, service.main.routes());
+
+      app.use(serviceRouter.routes());
+    }
+  }
+
+  /**
+   * Combine modules from files in a directory
+   * @param options - Configuration options
+   */
+  async combineModulesByFilePath({
+    rootDirectory,
+    filename,
+    combineWithRoot,
+    convertToArray,
+  }: ModuleOptions): Promise<any> {
+    // find route paths
+    let rootObject_temp: any;
+
+    const option = {
+      name: filename.name,
+      filter: [filename.extension],
+    };
+
+    let modulesPath: string[] = [];
+    try {
+      modulesPath = await directory.find(rootDirectory, option);
+    } catch (e) {
+      console.log(e);
+    }
+
+    // create and combine routes into the app
+    for (let i = 0; i < modulesPath.length; i++) {
+      const moduleObject = require(modulesPath[i]);
+
+      // act by otherOption
+      if (combineWithRoot) {
+        if (moduleObject.name) delete moduleObject.name;
+
+        if (Array.isArray(moduleObject)) {
+          if (!rootObject_temp) rootObject_temp = [];
+
+          rootObject_temp = [...rootObject_temp, ...moduleObject];
+        } else {
+          rootObject_temp = this.extendObj(rootObject_temp, moduleObject);
+        }
+      }
+      // default act
+      else {
+        const name = moduleObject.name;
+        rootObject_temp[name] = moduleObject;
+      }
+    }
+
+    // options
+    // convertToArray
+    if (convertToArray) {
+      rootObject_temp = Object.values(rootObject_temp);
+    }
+
+    // set result to main rootObject
+    return rootObject_temp;
+  }
+
+  /**
+   * Combine functions from files in a directory
+   * @param options - Function options
+   */
+  async combineFunctionsByFilePath({ rootDirectory, filename }: FunctionOptions): Promise<void> {
+    // find route paths
+    const option = {
+      name: filename.name,
+      filter: [filename.extension],
+    };
+
+    let functionsPaths: string[] = [];
+    try {
+      functionsPaths = await directory.find(rootDirectory, option);
+    } catch (e) {
+      console.log(e);
+    }
+
+    // create and combine routes into the app
+    for (let i = 0; i < functionsPaths.length; i++) {
+      const modularFunctions = require(functionsPaths[i]);
+
+      if (!modularFunctions.functions) {
+        throw new Error(`Module file ${functionsPaths[i]} does not have functions property.`);
+      }
+
+      // if array
+      if (Array.isArray(modularFunctions.functions)) {
+        for (const moduleFunction of modularFunctions.functions) {
+          addFunction(moduleFunction);
+        }
+      } else {
+        addFunction(modularFunctions.functions);
+      }
+    }
+  }
+
+  /**
+   * Add functions from an array
+   * @param functionList - List of functions to add
+   */
+  addFunctionsByArray(functionList: any[]): void {
+    for (const functionItem of functionList) {
+      addFunction(functionItem);
+    }
+  }
+
+  /**
+   * Extend an object with properties from another
+   * @param obj - Target object
+   * @param src - Source object
+   * @returns Extended object
+   */
+  extendObj(obj: any, src: any): any {
+    obj = obj || {};
+    for (const key in src) {
+      if (Object.prototype.hasOwnProperty.call(src, key)) obj[key] = src[key];
+    }
+    return obj;
+  }
+
+  static get instance(): Combinator {
+    return instance;
+  }
+}
+
+const instance = new Combinator();
+
+export = instance;