@modular-rest/server 1.11.13 → 1.11.14

package/.nvmrc

@@ -0,0 +1 @@
+v21.5.0

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+	"semi": true,
+	"tabWidth": 2,
+	"printWidth": 100,
+	"singleQuote": true,
+	"trailingComma": "es5",
+	"bracketSpacing": true,
+	"arrowParens": "avoid"
+}

package/.releaserc.json

@@ -0,0 +1,24 @@
+{
+  "extends": "semantic-release-monorepo",
+  "branches": ["main"],
+  "tagFormat": "@modular-rest/server_v${version}",
+  "plugins": [
+    ["@semantic-release/commit-analyzer", {
+      "preset": "angular",
+      "releaseRules": [
+        {"type": "docs", "scope": "README", "release": "patch"},
+        {"type": "feat", "release": "minor"},
+        {"type": "fix", "release": "patch"},
+        {"type": "perf", "release": "patch"},
+        {"type": "revert", "release": "patch"},
+        {"type": "style", "release": "patch"},
+        {"type": "test", "release": "patch"},
+        {"type": "ci", "release": "patch"},
+        {"type": "chore", "release": "patch"}
+      ]
+    }],
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+} 

package/README.md

@@ -1,114 +1,99 @@
-# Modular-Rest
-a nodejs module based on KOAJS for developing Rest-APIs in a modular solution. 
-- modular-rest is only for developing rest api, and is not based on MVC.
-- each route would be a module in this system. you can define your base routes on difrent folders then the Modular-Rest would combine all routes to main app object.
+# @modular-rest/server-ts
 
-this module has one method:
-- `createRest`: is the main functionality of the module.
+TypeScript version of a Node.js module based on Koa.js for developing REST APIs in a modular solution.
 
-**Note**: active "javascript.implicitProjectConfig.checkJs": true in your vscode settings.
+## Version 1.12 Breaking Changes
 
-## Install 
+The 1.12 release includes several breaking changes:
 
-Install using [npm](https://www.npmjs.com/package/modular-rest):
+- Complete rewrite in TypeScript with full type safety and improved IDE support
+- Auto-generated API documentation using TypeDoc
+- Changed configuration structure for better TypeScript support
 
-```sh
-npm i modular-rest --save
+## Migration Status
+
+This is a TypeScript migration of the original [@modular-rest/server](https://github.com/modular-rest/modular-rest) package. While maintaining compatibility with the JavaScript version, it adds type safety and better developer experience.
+
+## Installation
+
+```bash
+npm install @modular-rest/server-ts
+# or
+yarn add @modular-rest/server-ts
 ```
 
-## use modular-rest `createRest`
-
-to work with modular-rest you need an `app.js` and a `routers` folder. then configuring `app.js` and put your each router as a subfolder into the `routers` folder.
-
-
-### configuring `app.js`
-simple configuration of `app.js` with `koa-router` module.
-
-```js
-const modularRest = require('modular-rest');
-let koaBody = require('koa-body');
-
-let option = {
-    root: require('path').join(__dirname, 'routers'),
-    onBeforInit: BeforInit, // befor anything
-    onInit: Init,           // after collecting routers
-    onAfterInit: AfterInit, // affter launch server
-    port: 80,
-
-    // if it would be true, app doesn't listen to port,
-    // and a raw app object with all routers will be returned.
-    // this option is for virtual host middlewares
-    dontlisten: false,
-
-    // collecting other services from subfolders
-    otherSrvice: [
-        {
-            filename: {name: 'fn', extension:'.js'},
-            rootDirectory: require('path').join(__dirname, 'routers'),
-            option: {
-                    // if this option woulde be true, the property of each service will be attached to rootObject
-                    // the `name` property will be rejected and only the main property of each service would be recognize.
-                    // it would be useful when you want to collect all mongoose models in one root object.
-                    combineWithRoot: false,
-
-                    // convert the rootObject to an array
-                    // the `name` property will be rejected and only the main property of each service would be recognize.
-                    convertToArray: false,
-                }
-        }
-    ],
-};
-
-function BeforInit(app)
-{
-    // use a body parser
-    // it must be used befor init
-    app.use(koaBody());
-}
-
-function Init(app, otherSrvice)
-{   
-    // use otherSrvice
-    // all your other services will injected to `otherSrvice` object.
-    // eahc service would be accessible by its filename
-    global.services = otherSrvice['fn'];
-}
-
-function AfterInit(app, otherSrvice) {
-  // do something
-}
-
-modularRest.createRest(option).then(app => {
-    // do something
+## Usage
+
+```typescript
+import { createRest } from '@modular-rest/server-ts';
+
+// Create a Koa application with modular-rest
+createRest({
+  port: 3000,
+  modulesPath: __dirname + '/modules',
+  uploadDirectory: __dirname + '/uploads',
+  staticPath: {
+    rootDir: __dirname + '/assets',
+    rootPath: '/assets'
+  },
+  mongo: {
+    mongoBaseAddress: 'mongodb://localhost:27017',
+    dbPrefix: 'myapp_'
+  },
+  adminUser: {
+    email: 'admin@example.com',
+    password: 'securePassword'
+  }
+}).then(({ app, server }) => {
+  console.log('Server started successfully');
 });
 ```
 
-### configuring a route
-1. go to `routers` folder and create a subfolder called `search` folder. 
-2. go to `search` folder and create a `route.js` file, then put these lines into it.
+## Key Features
 
-```js
-let Router = require('koa-router');
-let name = 'search';
+- Modular REST API development with Koa.js
+- Built-in MongoDB integration
+- User authentication and authorization
+- File upload and management
+- Event system
+- Extensible architecture
 
-let search = new Router();
-search.get('/', (ctx) => {
-    ctx.body = 'send me a post request';
-});
+## TypeScript Support
+
+This package includes full TypeScript type definitions for all API components. The entire codebase is written in TypeScript, providing:
+
+- IntelliSense and autocompletion in modern IDEs
+- Type safety for all API operations
+- Better compile-time error detection
+- Improved developer experience
+
+## Documentation
 
-search.post('/', (ctx) => {
-    ctx.body = `Request Body: ${JSON.stringify(ctx.request.body)}`;
-})
+The API documentation is automatically generated using TypeDoc. You can access the latest documentation:
 
-module.exports.name = name;
-module.exports.main = search;
+- In the `docs` directory of this repository
+- On the [modular-rest documentation site](https://modular-rest.github.io/docs)
+
+## Development
+
+To build the package:
+
+```bash
+yarn build
 ```
 
-### Requesting
-your search web service is:
+To run the development build with watch mode:
+
+```bash
+yarn dev
 ```
-http://localhost:80/search
+
+To generate documentation:
+
+```bash
+yarn docs
 ```
 
+## License
 
-thank you for using Modular-Rest :)
+MIT

package/dist/index.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userManager = exports.middleware = exports.fileService = exports.getCollection = exports.paginator = exports.reply = exports.validator = exports.TypeCasters = exports.defineFunction = exports.AccessTypes = exports.PermissionGroup = exports.PermissionTypes = exports.Permission = exports.AccessDefinition = exports.CmsTrigger = exports.DatabaseTrigger = exports.Schema = exports.schemas = exports.defineCollection = exports.CollectionDefinition = exports.createRest = void 0;
+// Application
+const application_1 = require("./application");
+Object.defineProperty(exports, "createRest", { enumerable: true, get: function () { return application_1.createRest; } });
+const mongoose_1 = require("mongoose");
+Object.defineProperty(exports, "Schema", { enumerable: true, get: function () { return mongoose_1.Schema; } });
+// Utilities
+const paginator = __importStar(require("./class/paginator"));
+exports.paginator = paginator;
+const reply = __importStar(require("./class/reply"));
+exports.reply = reply;
+const validator_1 = require("./class/validator");
+Object.defineProperty(exports, "validator", { enumerable: true, get: function () { return validator_1.validator; } });
+const service_1 = require("./services/data_provider/service");
+Object.defineProperty(exports, "getCollection", { enumerable: true, get: function () { return service_1.getCollection; } });
+const service_2 = require("./services/functions/service");
+Object.defineProperty(exports, "defineFunction", { enumerable: true, get: function () { return service_2.defineFunction; } });
+const typeCasters_1 = __importDefault(require("./services/data_provider/typeCasters"));
+exports.TypeCasters = typeCasters_1.default;
+const service_3 = require("./services/user_manager/service");
+Object.defineProperty(exports, "userManager", { enumerable: true, get: function () { return service_3.main; } });
+const service_4 = require("./services/file/service");
+Object.defineProperty(exports, "fileService", { enumerable: true, get: function () { return service_4.main; } });
+// Base class
+const collection_definition_1 = require("./class/collection_definition");
+Object.defineProperty(exports, "CollectionDefinition", { enumerable: true, get: function () { return collection_definition_1.CollectionDefinition; } });
+Object.defineProperty(exports, "defineCollection", { enumerable: true, get: function () { return collection_definition_1.defineCollection; } });
+const db_schemas_1 = require("./class/db_schemas");
+Object.defineProperty(exports, "schemas", { enumerable: true, get: function () { return db_schemas_1.schemas; } });
+const database_trigger_1 = __importDefault(require("./class/database_trigger"));
+exports.DatabaseTrigger = database_trigger_1.default;
+const cms_trigger_1 = __importDefault(require("./class/cms_trigger"));
+exports.CmsTrigger = cms_trigger_1.default;
+const security_1 = require("./class/security");
+Object.defineProperty(exports, "AccessDefinition", { enumerable: true, get: function () { return security_1.AccessDefinition; } });
+Object.defineProperty(exports, "Permission", { enumerable: true, get: function () { return security_1.Permission; } });
+Object.defineProperty(exports, "PermissionTypes", { enumerable: true, get: function () { return security_1.PermissionTypes; } });
+Object.defineProperty(exports, "PermissionGroup", { enumerable: true, get: function () { return security_1.PermissionGroup; } });
+Object.defineProperty(exports, "AccessTypes", { enumerable: true, get: function () { return security_1.AccessTypes; } });
+const middleware = __importStar(require("./middlewares"));
+exports.middleware = middleware;

package/docs/system-access-type.md

@@ -0,0 +1,26 @@
+### System Access Types
+
+The permission system works by matching the user's assigned permission types (stored in their permission group) against the required permissions defined on collections and functions. This allows for flexible and granular access control.
+
+For example, a collection could be configured to:
+
+- Allow read access for users with 'user_access' permission
+- Restrict write operations to users with 'advanced_settings' permission
+- Only let users who has the 'upload_file_access' access type in their permission group to upload new files
+
+**Built-in Permission Types**
+
+The system comes with the following pre-defined permission types:
+
+| Permission Type      | Description                                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `god_access`         | Grants unrestricted super admin access. Users with this permission can perform any operation and access all collections and functions. |
+| `user_access`        | Basic user-level access for authenticated users. Typically grants read access to most collections and basic functionality.             |
+| `upload_file_access` | Required specifically for file upload operations. Users need this permission to upload files to the system.                            |
+| `remove_file_access` | Required for file deletion operations. Users need this permission to remove files from the system.                                     |
+| `anonymous_access`   | Used for unauthenticated access. Defines what operations are available to users who are not logged in.                                 |
+| `advanced_settings`  | Grants access to advanced system configuration and administrative features. More privileged than basic user access.                    |
+
+These permission types can be combined in permission groups to create different access levels. For example, an admin user might have both `advanced_settings` and `user_access`, while a basic user would only have `user_access`.
+
+You can also define custom permission types for specific needs in your application. The permission system is flexible enough to accommodate any additional access types you require.

package/package.json

@@ -1,47 +1,60 @@
 {
-  "name": "@modular-rest/server",
-  "version": "1.11.13",
-  "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.11.14",
+	"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);
+    }
+  });
+}