@modular-rest/server 1.11.13 → 1.11.15

package/src/class/trigger_operator.ts

@@ -0,0 +1,142 @@
+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);
+ *   }
+ * });
+ * ```
+ */
+class TriggerOperator {
+  private triggers: Trigger[] = [];
+  private static _instance: TriggerOperator | null = null;
+
+  private constructor() {}
+
+  /**
+   * Gets the singleton instance of TriggerOperator
+   * @static
+   * @returns {TriggerOperator} The singleton instance
+   */
+  static get instance(): TriggerOperator {
+    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: Trigger): void {
+    // 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: DatabaseOperation, database: string, collection: string, data: any): void {
+    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
+          );
+        }
+      }
+    });
+  }
+}
+
+export = TriggerOperator.instance;

package/src/class/user.ts

@@ -0,0 +1,199 @@
+import { config } from '../config';
+import { PermissionGroup, AccessType } from './security';
+import { validator as validateObject } from './validator';
+import { Document, 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 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
+  ) {
+    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(): UserDetail {
+    const permissionGroup = config.permissionGroups?.find(
+      group => group.title === this.permissionGroup
+    );
+
+    if (!permissionGroup) {
+      throw new Error('Permission group not found on user object');
+    }
+
+    const brief: UserDetail = {
+      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: UserDetail): void {
+    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: string): boolean {
+    const permissionGroup = 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(): Promise<void> {
+    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: any): Promise<User> {
+    return new Promise((done, reject) => {
+      // check required fields
+      const isValidData = validateObject(model, '_id permissionGroup');
+
+      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: Model<any>, detail: UserDetail): Promise<User> {
+    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: any): string {
+    const error = `user detail are not valid ${JSON.stringify(object)}`;
+    console.error(error);
+    return error;
+  }
+}
+
+export default User;

package/src/class/validator.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 function validator(
+  obj: Record<string, any> | null,
+  requiredFields: string | Record<string, string>
+): ValidationResult {
+  /*
+      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: ValidationResult;
+
+  if (type === 'string') result = checkSimple(obj, requiredFields as string);
+  else if (type === 'object') result = checkComplex(obj, requiredFields as Record<string, string>);
+  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: Record<string, any> | null,
+  requiredFields: string = ''
+): ValidationResult {
+  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: Record<string, any> | null,
+  requiredFields: Record<string, string> = {}
+): ValidationResult {
+  let isValid = false;
+  const requireKeys = Object.keys(requiredFields);
+
+  let validMembers = 0;
+  const notValidKeys: string[] = [];
+
+  // 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: boolean, notValidKeys: string[]): ValidationResult {
+  return {
+    isValid: isValid,
+    requires: notValidKeys,
+  };
+}
+
+/**
+ * Return the validator function to maintain compatibility with the JavaScript version
+ */
+export const validateObject = validator;

package/src/config.ts

@@ -0,0 +1,122 @@
+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 { Options as KoaCorsOptions } from '@koa/cors';
+import { Options as KoaStaticOptionsBase } from 'koa-static';
+
+/**
+ * The options for the static file server, it's a combination of modular-rest and [koa-static options](https://github.com/koajs/static?tab=readme-ov-file#options)
+ */
+export type StaticPathOptions = 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
+ */
+interface MongoOptions {
+  dbPrefix: string;
+  mongoBaseAddress: 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 {KoaCorsOptions} [cors] - CORS configuration [options](https://github.com/koajs/cors?tab=readme-ov-file#corsoptions)
+ * @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?: KoaCorsOptions;
+  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 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 function setConfig(options: RestOptions): void {
+  Object.assign(config, options);
+}

package/src/defult-permissions.ts

@@ -0,0 +1,31 @@
+import { PermissionGroup } from './class/security';
+
+export const permissionGroups = [
+  new PermissionGroup({
+    title: 'anonymous',
+    isAnonymous: true,
+    allowedAccessTypes: ['anonymous_access'],
+  }),
+
+  new PermissionGroup({
+    title: 'end-user',
+    isDefault: true,
+    allowedAccessTypes: [
+      'user_access',
+      'anonymous_access',
+      'upload_file_access',
+      'remove_file_access',
+    ],
+  }),
+
+  new PermissionGroup({
+    title: 'administrator',
+    allowedAccessTypes: [
+      'user_access',
+      'anonymous_access',
+      'upload_file_access',
+      'remove_file_access',
+      'advanced_settings',
+    ],
+  }),
+];

package/src/events.ts

@@ -0,0 +1,59 @@
+import Koa from "koa";
+
+/**
+ * Event callback interface
+ */
+interface EventCallback {
+  event: string;
+  callback: (...args: any[]) => void;
+}
+
+/**
+ * Array to store all registered event callbacks
+ */
+const eventCallbacks: EventCallback[] = [];
+
+/**
+ * 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 function registerEventCallback(
+  event: string,
+  callback: (...args: any[]) => void
+): void {
+  if (typeof event !== "string") throw new Error("Event must be a string");
+
+  if (typeof callback !== "function")
+    throw new Error("Callback must be a function");
+
+  eventCallbacks.push({ event, callback });
+}
+
+/**
+ * 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 function getEventCallbacks(event: string): ((...args: any[]) => void)[] {
+  return eventCallbacks
+    .filter((cb) => cb.event === event)
+    .map((cb) => cb.callback);
+}
+
+/**
+ * Trigger an event with arguments
+ * @param event - The event name to trigger
+ * @param args - Arguments to pass to the callback functions
+ */
+export function triggerEvent(event: string, ...args: any[]): void {
+  const callbacks = getEventCallbacks(event);
+  for (const callback of callbacks) {
+    callback(...args);
+  }
+}