@modular-rest/server 1.11.12 → 1.12.0

package/dist/class/trigger_operator.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Singleton class for managing database triggers
+ * Provides functionality to add and execute triggers based on database operations
+ * @class TriggerOperator
+ * @example
+ * ```typescript
+ * // Add a trigger for user insertions
+ * TriggerOperator.instance.addTrigger({
+ *   operation: 'insert',
+ *   database: 'myDB',
+ *   collection: 'users',
+ *   callback: (data) => {
+ *     console.log('New user inserted:', data);
+ *   }
+ * });
+ * ```
+ */
+class TriggerOperator {
+    constructor() {
+        this.triggers = [];
+    }
+    /**
+     * Gets the singleton instance of TriggerOperator
+     * @static
+     * @returns {TriggerOperator} The singleton instance
+     */
+    static get instance() {
+        if (!TriggerOperator._instance) {
+            TriggerOperator._instance = new TriggerOperator();
+        }
+        return TriggerOperator._instance;
+    }
+    /**
+     * Adds a new trigger to the registry
+     * @param {Trigger} trigger - The trigger configuration to add
+     * @throws {Error} If trigger is invalid or already exists
+     * @example
+     * ```typescript
+     * // Add a trigger for document updates
+     * TriggerOperator.instance.addTrigger({
+     *   operation: 'update',
+     *   database: 'myDB',
+     *   collection: 'documents',
+     *   callback: (data) => {
+     *     console.log('Document updated:', data);
+     *   }
+     * });
+     * ```
+     */
+    addTrigger(trigger) {
+        // Validate trigger
+        if (!trigger.operation || !trigger.database || !trigger.collection || !trigger.callback) {
+            throw new Error('Invalid trigger configuration');
+        }
+        // Check for duplicate triggers
+        const exists = this.triggers.some(t => t.operation === trigger.operation &&
+            t.database === trigger.database &&
+            t.collection === trigger.collection);
+        if (exists) {
+            throw new Error(`Trigger already exists for operation ${trigger.operation} on ${trigger.database}.${trigger.collection}`);
+        }
+        this.triggers.push(trigger);
+    }
+    /**
+     * Executes all matching triggers for a given database operation
+     * @param {DatabaseOperation} operation - The database operation that occurred
+     * @param {string} database - The database where the operation occurred
+     * @param {string} collection - The collection where the operation occurred
+     * @param {any} data - The data associated with the operation
+     * @example
+     * ```typescript
+     * // This would typically be called by the database layer
+     * TriggerOperator.instance.call(
+     *   'insert',
+     *   'myDB',
+     *   'users',
+     *   { id: 1, name: 'John' }
+     * );
+     * ```
+     */
+    call(operation, database, collection, data) {
+        this.triggers.forEach(trigger => {
+            if (operation === trigger.operation &&
+                database === trigger.database &&
+                collection === trigger.collection &&
+                trigger.callback) {
+                try {
+                    trigger.callback(data);
+                }
+                catch (error) {
+                    console.error(`Error executing trigger for ${operation} on ${database}.${collection}:`, error);
+                }
+            }
+        });
+    }
+}
+TriggerOperator._instance = null;
+module.exports = TriggerOperator.instance;

package/dist/class/user.d.ts

@@ -0,0 +1,81 @@
+import { PermissionGroup } from './security';
+import { Model } from 'mongoose';
+/**
+ * User detail interface
+ */
+interface UserDetail {
+    permissionGroup?: string | PermissionGroup;
+    phone?: string;
+    email?: string;
+    password?: string;
+    fullname?: string;
+    type?: string;
+    [key: string]: any;
+}
+/**
+ * User class representing a user in the system
+ *
+ * @public
+ */
+export declare class User {
+    id: string;
+    permissionGroup: string;
+    phone: string;
+    email: string;
+    password: string;
+    type: string;
+    dbModel: any;
+    /**
+     * Create a user
+     * @param id - User ID
+     * @param permissionGroup - Permission group name
+     * @param phone - User phone
+     * @param email - User email
+     * @param password - User password
+     * @param type - User type
+     * @param model - Database model
+     *
+     * @hidden
+     */
+    constructor(id: string, permissionGroup: string, phone: string, email: string, password: string, type: string, model: any);
+    /**
+     * Get brief user information
+     * @returns Brief user info object
+     */
+    getBrief(): UserDetail;
+    /**
+     * Update user details
+     * @param detail - Object containing user details to update
+     */
+    setNewDetail(detail: UserDetail): void;
+    /**
+     * Check if user has a specific permission
+     * @param accessType - Permission to check
+     * @returns True if user has permission, false otherwise
+     */
+    hasPermission(accessType: string): boolean;
+    /**
+     * Save user to database
+     */
+    save(): Promise<void>;
+    /**
+     * Load user from database model
+     * @param model - Database model
+     * @returns Promise resolving to User instance
+     */
+    static loadFromModel(model: any): Promise<User>;
+    /**
+     * Create user from model and details
+     * @param model - Mongoose model
+     * @param detail - User details
+     * @returns Promise resolving to User instance
+     */
+    static createFromModel(model: Model<any>, detail: UserDetail): Promise<User>;
+    /**
+     * Create error for invalid user
+     * @param object - Invalid user object
+     * @returns Error message
+     */
+    static notValid(object: any): string;
+}
+export default User;

package/dist/class/user.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.User = void 0;
+const config_1 = require("../config");
+const validator_1 = require("./validator");
+/**
+ * User class representing a user in the system
+ *
+ * @public
+ */
+class User {
+    /**
+     * Create a user
+     * @param id - User ID
+     * @param permissionGroup - Permission group name
+     * @param phone - User phone
+     * @param email - User email
+     * @param password - User password
+     * @param type - User type
+     * @param model - Database model
+     *
+     * @hidden
+     */
+    constructor(id, permissionGroup, phone, email, password, type, model) {
+        this.id = id;
+        this.permissionGroup = permissionGroup;
+        this.email = email;
+        this.phone = phone;
+        this.password = password;
+        this.type = type;
+        this.dbModel = model;
+    }
+    /**
+     * Get brief user information
+     * @returns Brief user info object
+     */
+    getBrief() {
+        const permissionGroup = config_1.config.permissionGroups?.find(group => group.title === this.permissionGroup);
+        if (!permissionGroup) {
+            throw new Error('Permission group not found on user object');
+        }
+        const brief = {
+            id: this.id,
+            permissionGroup: permissionGroup,
+            phone: this.phone,
+            email: this.email,
+            type: this.type,
+        };
+        return brief;
+    }
+    /**
+     * Update user details
+     * @param detail - Object containing user details to update
+     */
+    setNewDetail(detail) {
+        if (detail.phone)
+            this.phone = detail.phone;
+        if (detail.email)
+            this.email = detail.email;
+        if (detail.password)
+            this.password = detail.password;
+    }
+    /**
+     * Check if user has a specific permission
+     * @param accessType - Permission to check
+     * @returns True if user has permission, false otherwise
+     */
+    hasPermission(accessType) {
+        const permissionGroup = config_1.config.permissionGroups?.find(group => group.title === this.permissionGroup);
+        if (permissionGroup == null)
+            return false;
+        let key = false;
+        if (permissionGroup.allowedAccessTypes) {
+            for (let i = 0; i < permissionGroup.allowedAccessTypes.length; i++) {
+                const userPermissionType = permissionGroup.allowedAccessTypes[i];
+                if (userPermissionType === accessType) {
+                    key = true;
+                    break;
+                }
+            }
+        }
+        return key;
+    }
+    /**
+     * Save user to database
+     */
+    async save() {
+        if (!this.dbModel) {
+            throw new Error('User model is not initialized');
+        }
+        this.dbModel['permissionGroup'] = this.permissionGroup;
+        this.dbModel['phone'] = this.phone;
+        this.dbModel['email'] = this.email;
+        this.dbModel['password'] = this.password;
+        await this.dbModel.save();
+    }
+    /**
+     * Load user from database model
+     * @param model - Database model
+     * @returns Promise resolving to User instance
+     */
+    static loadFromModel(model) {
+        return new Promise((done, reject) => {
+            // check required fields
+            const isValidData = (0, validator_1.validator)(model, 'fullname email password permission');
+            if (!isValidData.isValid) {
+                return reject(User.notValid(model));
+            }
+            const id = model.id;
+            const permissionGroup = model.permissionGroup;
+            const phone = model.phone;
+            const email = model.email;
+            const password = model.password;
+            const type = model.type;
+            //create user
+            const newUser = new User(id, permissionGroup, phone, email, password, type, model);
+            done(newUser);
+        });
+    }
+    /**
+     * Create user from model and details
+     * @param model - Mongoose model
+     * @param detail - User details
+     * @returns Promise resolving to User instance
+     */
+    static createFromModel(model, detail) {
+        return new Promise(async (done, reject) => {
+            //create user
+            try {
+                const newUserDoc = await new model(detail).save();
+                const newUser = await User.loadFromModel(newUserDoc);
+                done(newUser);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Create error for invalid user
+     * @param object - Invalid user object
+     * @returns Error message
+     */
+    static notValid(object) {
+        const error = `user detail are not valid ${JSON.stringify(object)}`;
+        console.error(error);
+        return error;
+    }
+}
+exports.User = User;
+exports.default = User;

package/dist/class/validator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Validation result interface
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    requires: string[];
+}
+/**
+ * Validates an object by checking if it contains all the required fields.
+ * @param obj - The object to be validated.
+ * @param requiredFields - The list of required fields. If it's a string, it should contain keys separated by spaces. If it's an object, it should contain key-value pairs where the key is the field name and the value is a boolean indicating whether the field is required or not.
+ * @returns Returns a ValidationResult object with validation status and missing fields.
+ * @throws Throws an error if the requiredFields parameter is not a string or an object.
+ */
+export declare function validator(obj: Record<string, any> | null, requiredFields: string | Record<string, string>): ValidationResult;
+/**
+ * Return the validator function to maintain compatibility with the JavaScript version
+ */
+export declare const validateObject: typeof validator;

package/dist/class/validator.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateObject = void 0;
+exports.validator = validator;
+/**
+ * Validates an object by checking if it contains all the required fields.
+ * @param obj - The object to be validated.
+ * @param requiredFields - The list of required fields. If it's a string, it should contain keys separated by spaces. If it's an object, it should contain key-value pairs where the key is the field name and the value is a boolean indicating whether the field is required or not.
+ * @returns Returns a ValidationResult object with validation status and missing fields.
+ * @throws Throws an error if the requiredFields parameter is not a string or an object.
+ */
+function validator(obj, requiredFields) {
+    /*
+        this method could validate an Object by given field's name list and return bool.
+        - requiredFields: is a string that contains keys being spared by " ".
+    */
+    const type = typeof requiredFields;
+    let result;
+    if (type === 'string')
+        result = checkSimple(obj, requiredFields);
+    else if (type === 'object')
+        result = checkComplex(obj, requiredFields);
+    else
+        throw 'requiredFields has wrong form, it must be string or object';
+    return result;
+}
+/**
+ * Check simple validation with space-separated string of keys
+ */
+function checkSimple(obj, requiredFields = '') {
+    let isValid = false;
+    const requires = requiredFields.split(' ');
+    const validMembers = [];
+    const notValidKeys = [];
+    // return if obj is null
+    if (obj == null)
+        return _returnResult(isValid, requires);
+    // Filter empty strings that might result from extra spaces
+    const requiredKeys = requires.filter(key => key !== '');
+    for (const key of requiredKeys) {
+        if (obj[key] !== undefined && obj[key] !== null)
+            validMembers.push(key);
+        else
+            notValidKeys.push(key);
+    }
+    // check validation
+    isValid = requiredKeys.length === validMembers.length;
+    return _returnResult(isValid, notValidKeys);
+}
+/**
+ * Check complex validation with object containing expected values
+ */
+function checkComplex(obj, requiredFields = {}) {
+    let isValid = false;
+    const requireKeys = Object.keys(requiredFields);
+    let validMembers = 0;
+    const notValidKeys = [];
+    // return if obj is null
+    if (obj == null)
+        return _returnResult(isValid, requireKeys);
+    for (let i = 0; i < requireKeys.length; i++) {
+        const key = requireKeys[i];
+        let isValidField = false;
+        // if field has specific values
+        if (requiredFields[key].length > 0) {
+            const expectedValues = requiredFields[key].split(' ');
+            if (typeof expectedValues !== 'object')
+                throw `${key} must be array of strings`;
+            for (const value of expectedValues) {
+                if (obj[key] === value) {
+                    isValidField = true;
+                    break;
+                }
+            }
+        }
+        // else does not have specific value
+        else if (obj[key] != null) {
+            isValidField = true;
+        }
+        if (isValidField)
+            validMembers++;
+        else
+            notValidKeys.push(key);
+    }
+    // check validation
+    isValid = requireKeys.length === validMembers;
+    return _returnResult(isValid, notValidKeys);
+}
+/**
+ * Create a validation result object
+ */
+function _returnResult(isValid, notValidKeys) {
+    return {
+        isValid: isValid,
+        requires: notValidKeys,
+    };
+}
+/**
+ * Return the validator function to maintain compatibility with the JavaScript version
+ */
+exports.validateObject = validator;

package/dist/config.d.ts

@@ -0,0 +1,112 @@
+import Koa from 'koa';
+import { CollectionDefinition } from './class/collection_definition';
+import { PermissionGroup } from './class/security';
+import { CmsTrigger } from './class/cms_trigger';
+import { DefinedFunction } from './services/functions/service';
+import cors from '@koa/cors';
+import { Options as KoaStaticOptionsBase } from 'koa-static';
+export interface StaticPathOptions extends KoaStaticOptionsBase {
+    /**
+     * The actual path of the static files on your server
+     */
+    actualPath: string;
+    /**
+     * The path you want to serve the static files from
+     */
+    path: string;
+}
+/**
+ * JWT keypair configuration
+ * @interface KeyPair
+ * @property {string} private - Private key for JWT signing
+ * @property {string} public - Public key for JWT verification
+ */
+interface KeyPair {
+    private: string;
+    public: string;
+}
+/**
+ * MongoDB connection options
+ * @interface MongoOptions
+ * @property {string} dbPrefix - Prefix for database names
+ * @property {string} mongoBaseAddress - MongoDB connection URL
+ * @property {string} [addressMap] - Optional address mapping configuration
+ */
+interface MongoOptions {
+    dbPrefix: string;
+    mongoBaseAddress: string;
+    addressMap?: string;
+}
+/**
+ * Admin user configuration
+ * @interface AdminUser
+ * @property {string} email - Admin user email
+ * @property {string} password - Admin user password
+ */
+interface AdminUser {
+    email: string;
+    password: string;
+}
+/**
+ * Configuration options for creating a REST API instance
+ * @interface RestOptions
+ * @property {cors.Options} [cors] - CORS configuration options
+ * @property {string} [modulesPath] - Path to custom modules directory
+ * @property {string} [uploadDirectory] - Directory for file uploads
+ * @property {any} [koaBodyOptions] - Options for koa-body middleware
+ * @property {StaticPathOptions} [staticPath] - Static file serving options
+ * @property {Function} [onBeforeInit] - Hook called before initialization
+ * @property {Function} [onAfterInit] - Hook called after initialization
+ * @property {number} [port] - Port to listen on
+ * @property {boolean} [dontListen] - Don't start the server
+ * @property {MongoOptions} [mongo] - MongoDB connection options
+ * @property {Object} [keypair] - JWT keypair for authentication
+ * @property {AdminUser} [adminUser] - Admin user configuration
+ * @property {Function} [verificationCodeGeneratorMethod] - Custom verification code generator
+ * @property {CollectionDefinition[]} [collectionDefinitions] - Custom collection definitions
+ * @property {PermissionGroup[]} [permissionGroups] - Custom permission groups
+ * @property {CmsTrigger[]} [authTriggers] - Authentication triggers
+ * @property {CmsTrigger[]} [fileTriggers] - File handling triggers
+ * @property {DefinedFunction[]} [functions] - Custom API functions
+ */
+export interface RestOptions {
+    cors?: cors.Options;
+    modulesPath?: string;
+    uploadDirectory?: string;
+    koaBodyOptions?: any;
+    staticPath?: StaticPathOptions;
+    onBeforeInit?: (koaApp: Koa) => void;
+    onAfterInit?: (koaApp: Koa) => void;
+    port?: number;
+    dontListen?: boolean;
+    mongo?: MongoOptions;
+    keypair?: KeyPair;
+    adminUser?: AdminUser;
+    verificationCodeGeneratorMethod?: () => string;
+    collectionDefinitions?: CollectionDefinition[];
+    permissionGroups?: PermissionGroup[];
+    authTriggers?: CmsTrigger[];
+    fileTriggers?: CmsTrigger[];
+    functions?: DefinedFunction[];
+}
+/**
+ * Global configuration object
+ * @type {RestOptions}
+ */
+export declare const config: RestOptions;
+/**
+ * Updates the global configuration with new options
+ * @param {RestOptions} options - New configuration options to merge
+ * @example
+ * ```typescript
+ * setConfig({
+ *   port: 3000,
+ *   mongo: {
+ *     mongoBaseAddress: 'mongodb://localhost:27017',
+ *     dbPrefix: 'myapp_'
+ *   }
+ * });
+ * ```
+ */
+export declare function setConfig(options: RestOptions): void;
+export {};

package/dist/config.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.setConfig = setConfig;
+/**
+ * Global configuration object
+ * @type {RestOptions}
+ */
+exports.config = {};
+/**
+ * Updates the global configuration with new options
+ * @param {RestOptions} options - New configuration options to merge
+ * @example
+ * ```typescript
+ * setConfig({
+ *   port: 3000,
+ *   mongo: {
+ *     mongoBaseAddress: 'mongodb://localhost:27017',
+ *     dbPrefix: 'myapp_'
+ *   }
+ * });
+ * ```
+ */
+function setConfig(options) {
+    Object.assign(exports.config, options);
+}

package/dist/defult-permissions.d.ts

@@ -0,0 +1,2 @@
+import { PermissionGroup } from './index';
+export declare const permissionGroups: PermissionGroup[];

package/dist/defult-permissions.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.permissionGroups = void 0;
+const index_1 = require("./index");
+exports.permissionGroups = [
+    new index_1.PermissionGroup({
+        title: 'anonymous',
+        isAnonymous: true,
+        allowedAccessTypes: ['anonymous_access'],
+    }),
+    new index_1.PermissionGroup({
+        title: 'end-user',
+        isDefault: true,
+        allowedAccessTypes: [
+            'user_access',
+            'anonymous_access',
+            'upload_file_access',
+            'remove_file_access',
+        ],
+    }),
+    new index_1.PermissionGroup({
+        title: 'administrator',
+        allowedAccessTypes: [
+            'user_access',
+            'anonymous_access',
+            'upload_file_access',
+            'remove_file_access',
+            'advanced_settings',
+        ],
+    }),
+];

package/dist/events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Supported event types:
+ * - onBeforeInit: (koaApp: Koa) => void; // A callback called before initializing the Koa server.
+ * - onAfterInit: (koaApp: Koa) => void; // A callback called after server initialization.
+ * - onNewUser: (user: any) => void; // A callback called when a new user is created.
+ *
+ * @param event - The event name to register
+ * @param callback - The callback function to be called when the event is triggered
+ * @throws Error if event is not a string or callback is not a function
+ */
+export declare function registerEventCallback(event: string, callback: (...args: any[]) => void): void;
+/**
+ * Get all registered callbacks for a specific event
+ * @param event - The event name to get callbacks for
+ * @returns Array of callbacks registered for the event
+ */
+export declare function getEventCallbacks(event: string): ((...args: any[]) => void)[];
+/**
+ * Trigger an event with arguments
+ * @param event - The event name to trigger
+ * @param args - Arguments to pass to the callback functions
+ */
+export declare function triggerEvent(event: string, ...args: any[]): void;