@modular-rest/server 1.11.12 → 1.12.0

package/dist/class/directory.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walk = walk;
+exports.find = find;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Walk through a directory and its subdirectories
+ * @param dir - Directory to walk
+ * @param settings - Settings for filtering files
+ * @param done - Callback function
+ */
+function walk(dir, settings, done) {
+    let results = [];
+    // Read director file and folders
+    fs_1.default.readdir(dir, function (err, list) {
+        if (err)
+            return done(err, results);
+        let pending = list.length;
+        if (!pending)
+            return done(null, results);
+        list.forEach(function (file) {
+            file = path_1.default.join(dir, file);
+            fs_1.default.stat(file, function (err, stat) {
+                if (err) {
+                    // Handle file stat error but continue with other files
+                    console.error(`Error reading file stats for ${file}:`, err);
+                    if (!--pending)
+                        done(null, results);
+                    return;
+                }
+                // If directory, execute a recursive call
+                if (stat && stat.isDirectory()) {
+                    // Add directory to array [comment if you need to remove the directories from the array]
+                    // results.push(file);
+                    walk(file, settings, function (err, res) {
+                        results = results.concat(res);
+                        if (!--pending)
+                            done(null, results);
+                    });
+                }
+                else {
+                    // file filter
+                    const extension = path_1.default.extname(file);
+                    const fileName = path_1.default.basename(file).split('.')[0];
+                    let fileNameKey = true;
+                    // name filter
+                    if (settings.name && settings.name === fileName)
+                        fileNameKey = true;
+                    else
+                        fileNameKey = false;
+                    // extension filter
+                    if (settings.filter && fileNameKey) {
+                        settings.filter.forEach(function (element) {
+                            if (element.toLowerCase() === extension.toLowerCase())
+                                results.push(file);
+                        });
+                    }
+                    // push any file if no option
+                    else if (fileNameKey)
+                        results.push(file);
+                    if (!--pending)
+                        done(null, results);
+                }
+            });
+        });
+    });
+}
+/**
+ * Find files in a directory with Promise API
+ * @param dir - Directory to search
+ * @param settings - Settings for filtering files
+ * @returns Promise resolving to an array of file paths
+ */
+function find(dir, settings) {
+    return new Promise((resolve, reject) => {
+        walk(dir, settings, (err, result) => {
+            if (err)
+                reject(err);
+            else
+                resolve(result);
+        });
+    });
+}

package/dist/class/paginator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pagination result interface
+ */
+export interface PaginationResult {
+    pages: number;
+    page: number;
+    from: number;
+    to: number;
+}
+/**
+ * Creates a pagination object based on the given parameters.
+ * @param count - The total number of items to paginate.
+ * @param perPage - The number of items to display per page.
+ * @param page - The current page number.
+ * @returns An object containing pagination information.
+ *
+ * @example
+ * ```typescript
+ * import { paginator } from '@modular-rest/server';
+ *
+ * const pagination = paginator.create(100, 10, 1);
+ * // json response will be like this
+ * // {
+ * //   pages: 10,
+ * //   page: 1,
+ * //   from: 0,
+ * //   to: 10,
+ * // }
+ * ```
+ */
+export declare function create(count: number, perPage: number, page: number): PaginationResult;

package/dist/class/paginator.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.create = create;
+/**
+ * Creates a pagination object based on the given parameters.
+ * @param count - The total number of items to paginate.
+ * @param perPage - The number of items to display per page.
+ * @param page - The current page number.
+ * @returns An object containing pagination information.
+ *
+ * @example
+ * ```typescript
+ * import { paginator } from '@modular-rest/server';
+ *
+ * const pagination = paginator.create(100, 10, 1);
+ * // json response will be like this
+ * // {
+ * //   pages: 10,
+ * //   page: 1,
+ * //   from: 0,
+ * //   to: 10,
+ * // }
+ * ```
+ */
+function create(count, perPage, page) {
+    const totalPages = Math.ceil(count / perPage);
+    if (page > totalPages)
+        page = 1;
+    let from = 0;
+    if (perPage === 1)
+        from = page - 1;
+    else
+        from = perPage * page - perPage;
+    if (page <= 1)
+        from = 0;
+    const result = {
+        pages: totalPages,
+        page: page,
+        from: from,
+        to: perPage,
+    };
+    return result;
+}

package/dist/class/reply.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Response status type
+ */
+export type ResponseStatus = 's' | 'f' | 'e';
+/**
+ * Response object interface
+ */
+export interface ResponseObject {
+    status: 'success' | 'fail' | 'error';
+    [key: string]: any;
+}
+/**
+ * Creates a response object with the given status and detail.
+ *
+ * @param status - The status of the response. Can be "s" for success, "f" for fail, or "e" for error.
+ * @param detail - The detail of the response. Can contain any additional information about the response.
+ * @returns The response object with the given status and detail.
+ *
+ * @example
+ * ```typescript
+ * import { reply } from '@modular-rest/server';
+ *
+ * // inside the router
+ * const response = reply.create("s", { message: "Hello, world!" });
+ * ctx.body = response;
+ * ctx.status = 200;
+ * ```
+ */
+export declare function create(status: ResponseStatus, detail?: Record<string, any>): ResponseObject;

package/dist/class/reply.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.create = create;
+/**
+ * Creates a response object with the given status and detail.
+ *
+ * @param status - The status of the response. Can be "s" for success, "f" for fail, or "e" for error.
+ * @param detail - The detail of the response. Can contain any additional information about the response.
+ * @returns The response object with the given status and detail.
+ *
+ * @example
+ * ```typescript
+ * import { reply } from '@modular-rest/server';
+ *
+ * // inside the router
+ * const response = reply.create("s", { message: "Hello, world!" });
+ * ctx.body = response;
+ * ctx.status = 200;
+ * ```
+ */
+function create(status, detail = {}) {
+    // Initialize with a default status that will be overwritten
+    const result = {
+        status: 'success',
+        ...detail,
+    };
+    // define status
+    switch (status) {
+        case 's':
+            result.status = 'success';
+            break;
+        case 'f':
+            result.status = 'fail';
+            break;
+        case 'e':
+            result.status = 'error';
+            break;
+        default:
+            result.status = 'success';
+            break;
+    }
+    // return
+    return result;
+}

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;