@modular-rest/server 1.11.14 → 1.11.15

package/dist/class/security.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Permission type string literal type that defines various access levels and capabilities
+ 
+ * @inline
+ */
+export type AccessType = 'god_access' | 'user_access' | 'upload_file_access' | 'remove_file_access' | 'anonymous_access' | 'advanced_settings' | string;
+/**
+ * Defines access control for a specific database collection
+ *
+ * @internal
+ */
+export declare class AccessDefinition {
+    /** @hidden */
+    database: string;
+    /** @hidden */
+    collection: string;
+    /** @hidden */
+    permissionList: Permission[];
+    /**
+     * Creates a new AccessDefinition instance
+     * @param {Object} options - Configuration options
+     * @param {string} options.database - The name of the database
+     * @param {string} options.collection - The name of the collection
+     * @param {Permission[]} options.permissionList - List of permissions
+     */
+    constructor({ database, collection, permissionList, }: {
+        database: string;
+        collection: string;
+        permissionList: Permission[];
+    });
+}
+/**
+ * Defines a permission for accessing data within the system. This class is a fundamental component used in both the {@link defineCollection} method and {@link CollectionDefinition} class
+ * by specifying which permission types can interact with them. The permission system matches a user's assigned permission types against
+ * the collection's permissions to determine access levels. For example, a collection can allow read access for 'user_access' while
+ * restricting writes to 'advanced_settings' permissions.
+ *
+ * @remark
+ * {@include ../../docs/system-access-type.md}
+ *
+ * @example
+ * ```typescript
+ * import { Permission } from '@modular-rest/server';
+ *
+ * const permission = new Permission({
+ *   type: 'user_access',
+ *   read: true,
+ *   write: true,
+ *   onlyOwnData: true,
+ *   ownerIdField: 'userId'
+ * });
+ * ```
+ */
+export declare class Permission {
+    /** @hidden */
+    accessType: AccessType;
+    /** @hidden */
+    read: boolean;
+    /** @hidden */
+    write: boolean;
+    /** @hidden */
+    onlyOwnData: boolean;
+    /** @hidden */
+    ownerIdField: string;
+    /**
+     * Creates a new Permission instance
+     * @param {Object} options - Configuration options
+     *
+     * @param {AccessType} options.type - The type of permission,system defined or custom. check the **Remarks section** for more information.
+     *
+     * @param {boolean} [options.read=false] - Whether read access is granted
+     * @param {boolean} [options.write=false] - Whether write access is granted
+     * @param {boolean} [options.onlyOwnData=false] - Whether access is limited to own data
+     * @param {string} [options.ownerIdField='refId'] - Field name for owner identification
+     */
+    constructor({ accessType: type, read, write, onlyOwnData, ownerIdField, }: {
+        accessType: AccessType;
+        read?: boolean;
+        write?: boolean;
+        onlyOwnData?: boolean;
+        ownerIdField?: string;
+    });
+}
+/**
+ * A comprehensive access control mechanism that manages user permissions through grouped access types.
+ *
+ * Permission groups are a fundamental security concept that define and enforce what actions users
+ * can perform within the system. They provide a flexible and maintainable way to handle authorization
+ * by grouping related access types together.
+ *
+ * These groups enable users to:
+ * 1. Read and write data from collections that match their access types, allowing granular control
+ *    over database operations
+ * 2. Execute specific functions that require matching access types, ensuring that sensitive
+ *    operations are only performed by authorized users
+ * 3. Perform custom developer-defined actions by validating against the user's access types,
+ *    enabling extensible permission-based features
+ *
+ * Permission groups can be configured as default groups for new users or anonymous groups for
+ * unauthenticated access, providing a complete authorization framework.
+ *
+ * @class PermissionGroup
+ * @property {string} title - The title of the permission group
+ * @property {boolean} isDefault - This is a default group, on `true` this permission group will be given to any new user automatically.
+ * @property {boolean} isAnonymous - This is a anonymous group, on `true` will be used for anonymous users.
+ * @property {AccessType[]} allowedAccessTypes - List of valid access types.
+ * @example
+ * ```typescript
+ * const group = new PermissionGroup({
+ *   title: 'Admin',
+ *   isDefault: true,
+ *   allowedAccessTypes: ['god_access', 'advanced_settings']
+ * });
+ * ```
+ */
+export declare class PermissionGroup {
+    /** @hidden */
+    title: string;
+    /** @hidden */
+    isDefault: boolean;
+    /** @hidden */
+    isAnonymous: boolean;
+    /** @hidden */
+    allowedAccessTypes: AccessType[];
+    /**
+     * Creates a new PermissionGroup instance
+     * @param {Object} options - Configuration options
+     * @param {string} options.title - The title of the group
+     * @param {boolean} [options.isDefault=false] - Whether this is a default group
+     * @param {boolean} [options.isAnonymous=false] - Whether this group is for anonymous users
+     * @param {AccessType[]} [options.allowedAccessTypes=[]] - List of valid permission types
+     */
+    constructor({ title, isDefault, isAnonymous, allowedAccessTypes, }: {
+        title: string;
+        isDefault?: boolean;
+        isAnonymous?: boolean;
+        allowedAccessTypes?: AccessType[];
+    });
+}
+/**
+ * Provides static access to access type constants
+ * @class AccessTypes
+ */
+export declare class AccessTypes {
+    /**
+     * Get the string representing read access type
+     * @returns {string} The read access type
+     */
+    static get read(): string;
+    /**
+     * Get the string representing write access type
+     * @returns {string} The write access type
+     */
+    static get write(): string;
+}
+/**
+ * Provides static access to permission type constants
+ * @class PermissionTypes
+ */
+export declare class PermissionTypes {
+    /**
+     * Get the string representing god access permission type
+     * @returns {string} The god access permission type
+     */
+    static get god_access(): AccessType;
+    /**
+     * Get the string representing advanced settings permission type
+     * @returns {string} The advanced settings permission type
+     */
+    static get advanced_settings(): AccessType;
+    /**
+     * Get the string representing user access permission type
+     * @returns {string} The user access permission type
+     */
+    static get user_access(): AccessType;
+    /**
+     * Get the string representing upload file access permission type
+     * @returns {string} The upload file access permission type
+     */
+    static get upload_file_access(): AccessType;
+    /**
+     * Get the string representing remove file access permission type
+     * @returns {string} The remove file access permission type
+     */
+    static get remove_file_access(): AccessType;
+}

package/dist/class/security.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionTypes = exports.AccessTypes = exports.PermissionGroup = exports.Permission = exports.AccessDefinition = void 0;
+/**
+ * Defines access control for a specific database collection
+ *
+ * @internal
+ */
+class AccessDefinition {
+    /**
+     * Creates a new AccessDefinition instance
+     * @param {Object} options - Configuration options
+     * @param {string} options.database - The name of the database
+     * @param {string} options.collection - The name of the collection
+     * @param {Permission[]} options.permissionList - List of permissions
+     */
+    constructor({ database, collection, permissionList, }) {
+        this.database = database;
+        this.collection = collection;
+        this.permissionList = permissionList;
+    }
+}
+exports.AccessDefinition = AccessDefinition;
+/**
+ * Defines a permission for accessing data within the system. This class is a fundamental component used in both the {@link defineCollection} method and {@link CollectionDefinition} class
+ * by specifying which permission types can interact with them. The permission system matches a user's assigned permission types against
+ * the collection's permissions to determine access levels. For example, a collection can allow read access for 'user_access' while
+ * restricting writes to 'advanced_settings' permissions.
+ *
+ * @remark
+ * {@include ../../docs/system-access-type.md}
+ *
+ * @example
+ * ```typescript
+ * import { Permission } from '@modular-rest/server';
+ *
+ * const permission = new Permission({
+ *   type: 'user_access',
+ *   read: true,
+ *   write: true,
+ *   onlyOwnData: true,
+ *   ownerIdField: 'userId'
+ * });
+ * ```
+ */
+class Permission {
+    /**
+     * Creates a new Permission instance
+     * @param {Object} options - Configuration options
+     *
+     * @param {AccessType} options.type - The type of permission,system defined or custom. check the **Remarks section** for more information.
+     *
+     * @param {boolean} [options.read=false] - Whether read access is granted
+     * @param {boolean} [options.write=false] - Whether write access is granted
+     * @param {boolean} [options.onlyOwnData=false] - Whether access is limited to own data
+     * @param {string} [options.ownerIdField='refId'] - Field name for owner identification
+     */
+    constructor({ accessType: type, read = false, write = false, onlyOwnData = false, ownerIdField = 'refId', }) {
+        this.accessType = type;
+        this.read = read;
+        this.write = write;
+        this.onlyOwnData = onlyOwnData;
+        this.ownerIdField = ownerIdField;
+    }
+}
+exports.Permission = Permission;
+/**
+ * A comprehensive access control mechanism that manages user permissions through grouped access types.
+ *
+ * Permission groups are a fundamental security concept that define and enforce what actions users
+ * can perform within the system. They provide a flexible and maintainable way to handle authorization
+ * by grouping related access types together.
+ *
+ * These groups enable users to:
+ * 1. Read and write data from collections that match their access types, allowing granular control
+ *    over database operations
+ * 2. Execute specific functions that require matching access types, ensuring that sensitive
+ *    operations are only performed by authorized users
+ * 3. Perform custom developer-defined actions by validating against the user's access types,
+ *    enabling extensible permission-based features
+ *
+ * Permission groups can be configured as default groups for new users or anonymous groups for
+ * unauthenticated access, providing a complete authorization framework.
+ *
+ * @class PermissionGroup
+ * @property {string} title - The title of the permission group
+ * @property {boolean} isDefault - This is a default group, on `true` this permission group will be given to any new user automatically.
+ * @property {boolean} isAnonymous - This is a anonymous group, on `true` will be used for anonymous users.
+ * @property {AccessType[]} allowedAccessTypes - List of valid access types.
+ * @example
+ * ```typescript
+ * const group = new PermissionGroup({
+ *   title: 'Admin',
+ *   isDefault: true,
+ *   allowedAccessTypes: ['god_access', 'advanced_settings']
+ * });
+ * ```
+ */
+class PermissionGroup {
+    /**
+     * Creates a new PermissionGroup instance
+     * @param {Object} options - Configuration options
+     * @param {string} options.title - The title of the group
+     * @param {boolean} [options.isDefault=false] - Whether this is a default group
+     * @param {boolean} [options.isAnonymous=false] - Whether this group is for anonymous users
+     * @param {AccessType[]} [options.allowedAccessTypes=[]] - List of valid permission types
+     */
+    constructor({ title, isDefault = false, isAnonymous = false, allowedAccessTypes = [], }) {
+        this.title = title;
+        this.isDefault = isDefault;
+        this.isAnonymous = isAnonymous;
+        this.allowedAccessTypes = allowedAccessTypes;
+    }
+}
+exports.PermissionGroup = PermissionGroup;
+/**
+ * Provides static access to access type constants
+ * @class AccessTypes
+ */
+class AccessTypes {
+    /**
+     * Get the string representing read access type
+     * @returns {string} The read access type
+     */
+    static get read() {
+        return 'read';
+    }
+    /**
+     * Get the string representing write access type
+     * @returns {string} The write access type
+     */
+    static get write() {
+        return 'write';
+    }
+}
+exports.AccessTypes = AccessTypes;
+/**
+ * Provides static access to permission type constants
+ * @class PermissionTypes
+ */
+class PermissionTypes {
+    /**
+     * Get the string representing god access permission type
+     * @returns {string} The god access permission type
+     */
+    static get god_access() {
+        return 'god_access';
+    }
+    /**
+     * Get the string representing advanced settings permission type
+     * @returns {string} The advanced settings permission type
+     */
+    static get advanced_settings() {
+        return 'advanced_settings';
+    }
+    /**
+     * Get the string representing user access permission type
+     * @returns {string} The user access permission type
+     */
+    static get user_access() {
+        return 'user_access';
+    }
+    /**
+     * Get the string representing upload file access permission type
+     * @returns {string} The upload file access permission type
+     */
+    static get upload_file_access() {
+        return 'upload_file_access';
+    }
+    /**
+     * Get the string representing remove file access permission type
+     * @returns {string} The remove file access permission type
+     */
+    static get remove_file_access() {
+        return 'remove_file_access';
+    }
+}
+exports.PermissionTypes = PermissionTypes;

package/dist/class/trigger_operator.d.ts

@@ -0,0 +1,92 @@
+import { DatabaseOperation } from './database_trigger';
+/**
+ * Interface defining a database trigger
+ * @interface Trigger
+ * @property {DatabaseOperation} operation - The database operation that triggers this callback
+ * @property {string} database - The database name to monitor
+ * @property {string} collection - The collection name to monitor
+ * @property {(data: any) => void} callback - Function to execute when trigger conditions are met
+ * @example
+ * ```typescript
+ * const trigger: Trigger = {
+ *   operation: 'insert',
+ *   database: 'myDB',
+ *   collection: 'users',
+ *   callback: (data) => {
+ *     console.log('New user inserted:', data);
+ *   }
+ * };
+ * ```
+ */
+interface Trigger {
+    operation: DatabaseOperation;
+    database: string;
+    collection: string;
+    callback: (data: any) => void;
+}
+/**
+ * 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);
+ *   }
+ * });
+ * ```
+ */
+declare class TriggerOperator {
+    private triggers;
+    private static _instance;
+    private constructor();
+    /**
+     * Gets the singleton instance of TriggerOperator
+     * @static
+     * @returns {TriggerOperator} The singleton instance
+     */
+    static get instance(): TriggerOperator;
+    /**
+     * 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: Trigger): void;
+    /**
+     * 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: DatabaseOperation, database: string, collection: string, data: any): void;
+}
+declare const _default: TriggerOperator;
+export = _default;

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: 'user' | 'anonymous', 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;