@modular-rest/server 1.11.13 → 1.12.1

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/application.d.ts

@@ -0,0 +1,29 @@
+import Koa from 'koa';
+import { Server } from 'http';
+import { RestOptions } from './config';
+/**
+ * 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 declare function createRest(options: RestOptions): Promise<{
+    app: Koa;
+    server?: Server;
+}>;

package/dist/application.js

@@ -0,0 +1,217 @@
+"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.createRest = createRest;
+const koa_1 = __importDefault(require("koa"));
+const cors_1 = __importDefault(require("@koa/cors"));
+const koa_body_1 = __importDefault(require("koa-body"));
+const koa_static_1 = __importDefault(require("koa-static"));
+const koa_mount_1 = __importDefault(require("koa-mount"));
+const path_1 = __importDefault(require("path"));
+const combinator_1 = __importDefault(require("./class/combinator"));
+const DataProvider = __importStar(require("./services/data_provider/service"));
+const UserService = __importStar(require("./services/user_manager/service"));
+const config_1 = require("./config");
+const defult_permissions_1 = require("./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
+ *   }
+ * })
+ */
+async function createRest(options) {
+    (0, config_1.setConfig)({
+        port: 3000,
+        dontListen: false,
+        mongo: {
+            mongoBaseAddress: 'mongodb://localhost:27017',
+            dbPrefix: 'mrest_',
+        },
+        adminUser: {
+            email: 'admin@email.com',
+            password: '@dmin',
+        },
+        ...options,
+    });
+    if (config_1.config.permissionGroups === undefined) {
+        config_1.config.permissionGroups = defult_permissions_1.permissionGroups;
+    }
+    const app = new koa_1.default();
+    /**
+     * Plug in Cors
+     */
+    app.use((0, cors_1.default)(config_1.config.cors || {}));
+    /**
+     * Plug in BodyParser
+     */
+    const bodyParserOptions = {
+        multipart: true,
+        ...(config_1.config.koaBodyOptions || {}),
+    };
+    app.use((0, koa_body_1.default)(bodyParserOptions));
+    /**
+     * Plug In KoaStatic
+     */
+    if (config_1.config.staticPath) {
+        const defaultStaticPath = config_1.config.staticPath.actualPath || '';
+        const defaultStaticRootPath = config_1.config.staticPath.path || '/assets';
+        const staticOptions = { ...config_1.config.staticPath };
+        delete staticOptions.actualPath;
+        delete staticOptions.path;
+        app.use((0, koa_mount_1.default)(defaultStaticRootPath, (0, koa_static_1.default)(defaultStaticPath, staticOptions)));
+    }
+    /**
+     * Run before hook
+     */
+    if (config_1.config.onBeforeInit)
+        config_1.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 combinator_1.default.combineRoutesByFilePath(path_1.default.join(defaultServiceRoot), app);
+    // Collect default databaseDefinitions
+    const defaultDatabaseDefinitionList = await combinator_1.default.combineModulesByFilePath({
+        rootDirectory: defaultServiceRoot,
+        filename: {
+            name: 'db',
+            extension: '.js',
+        },
+        combineWithRoot: true,
+    });
+    // 2. Plug in default databaseDefinitions
+    await DataProvider.addCollectionDefinitionByList({
+        list: defaultDatabaseDefinitionList,
+        mongoOption: config_1.config.mongo,
+    });
+    /**
+     * User Services
+     *
+     * 3. Plug in routes and database
+     */
+    if (config_1.config.modulesPath) {
+        // Plug in user routes
+        await combinator_1.default.combineRoutesByFilePath(config_1.config.modulesPath, app);
+        // Collect user CollectionDefinitions (db.js files)
+        let userDatabaseDetail = [];
+        userDatabaseDetail = await combinator_1.default.combineModulesByFilePath({
+            rootDirectory: config_1.config.modulesPath,
+            filename: {
+                name: 'db',
+                extension: '.js',
+            },
+            combineWithRoot: true,
+        });
+        // Combine additional CollectionDefinitions
+        if (config_1.config.collectionDefinitions) {
+            userDatabaseDetail = userDatabaseDetail.concat(config_1.config.collectionDefinitions);
+        }
+        // Plug in user CollectionDefinitions
+        await DataProvider.addCollectionDefinitionByList({
+            list: userDatabaseDetail || [],
+            mongoOption: config_1.config.mongo,
+        });
+        // Plug in Verification method
+        if (typeof config_1.config.verificationCodeGeneratorMethod === 'function') {
+            UserService.main.setCustomVerificationCodeGeneratorMethod(config_1.config.verificationCodeGeneratorMethod);
+        }
+        // 4. plug in modular functions
+        await combinator_1.default.combineFunctionsByFilePath({
+            rootDirectory: config_1.config.modulesPath,
+            filename: {
+                name: 'functions',
+                extension: '.js',
+            },
+        });
+        // 5. Plug in additional defined functions
+        if (config_1.config.functions) {
+            combinator_1.default.addFunctionsByArray(config_1.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;
+            if (!config_1.config.dontListen) {
+                server = app.listen(config_1.config.port);
+                console.log('\x1b[35m', `KOAS has been launched on: localhost:${config_1.config.port}`);
+            }
+            // on after init
+            if (config_1.config.onAfterInit)
+                config_1.config.onAfterInit(app);
+            done({
+                app,
+                server,
+            });
+        }
+        catch (err) {
+            reject(err);
+        }
+    });
+}

package/dist/class/cms_trigger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 declare 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);
+}
+export default CmsTrigger;

package/dist/class/cms_trigger.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CmsTrigger = void 0;
+/**
+ * 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
+ * });
+ * ```
+ */
+class CmsTrigger {
+    /**
+     * 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, callback = () => { }) {
+        this.operation = operation;
+        this.callback = callback;
+    }
+}
+exports.CmsTrigger = CmsTrigger;
+exports.default = CmsTrigger;