@modular-rest/server 1.11.14 → 1.11.15

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, defer: true };
+        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,52 @@
+import { DatabaseTriggerContext } from './database_trigger';
+/**
+ * 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';
+/**
+ * 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: DatabaseTriggerContext) => 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: DatabaseTriggerContext) => 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;

package/dist/class/collection_definition.d.ts

@@ -0,0 +1,112 @@
+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<any>;
+}
+/**
+ * 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 declare function defineCollection(options: CollectionDefinitionOptions): CollectionDefinition;
+/**
+ * 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 declare class CollectionDefinition {
+    /** @readonly The name of the database */
+    database: string;
+    /** @readonly The name of the collection */
+    collection: string;
+    /** @readonly Mongoose schema definition */
+    schema: Schema<any>;
+    /** @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);
+}
+export {};

package/dist/class/collection_definition.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectionDefinition = void 0;
+exports.defineCollection = defineCollection;
+/**
+ * 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[]
+ *   })
+ * ]
+ * ```
+ */
+function defineCollection(options) {
+    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
+ */
+class CollectionDefinition {
+    /**
+     * 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, }) {
+        this.database = database;
+        this.collection = collection;
+        this.schema = schema;
+        this.permissions = permissions;
+        this.triggers = triggers;
+    }
+}
+exports.CollectionDefinition = CollectionDefinition;

package/dist/class/combinator.d.ts

@@ -0,0 +1,43 @@
+import Koa from 'koa';
+interface FilenameOption {
+    name: string;
+    extension: string;
+}
+interface ModuleOptions {
+    rootDirectory: string;
+    filename: FilenameOption;
+    combineWithRoot?: boolean;
+    convertToArray?: boolean;
+}
+interface FunctionOptions {
+    rootDirectory: string;
+    filename: FilenameOption;
+}
+declare class Combinator {
+    combineRoutesByFilePath(rootDirectory: string, app: Koa): Promise<void>;
+    /**
+     * Combine modules from files in a directory
+     * @param options - Configuration options
+     */
+    combineModulesByFilePath({ rootDirectory, filename, combineWithRoot, convertToArray, }: ModuleOptions): Promise<any>;
+    /**
+     * Combine functions from files in a directory
+     * @param options - Function options
+     */
+    combineFunctionsByFilePath({ rootDirectory, filename }: FunctionOptions): Promise<void>;
+    /**
+     * Add functions from an array
+     * @param functionList - List of functions to add
+     */
+    addFunctionsByArray(functionList: any[]): void;
+    /**
+     * Extend an object with properties from another
+     * @param obj - Target object
+     * @param src - Source object
+     * @returns Extended object
+     */
+    extendObj(obj: any, src: any): any;
+    static get instance(): Combinator;
+}
+declare const instance: Combinator;
+export = instance;