@modular-rest/server 1.11.12 → 1.11.14

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);
+  }
+}

package/src/helper/data_insertion.ts

@@ -0,0 +1,94 @@
+import * as DataProvider from '../services/data_provider/service';
+import {
+  getDefaultAnonymousPermissionGroup,
+  getDefaultAdministratorPermissionGroup,
+} from '../services/user_manager/permissionManager';
+import * as userManager from '../services/user_manager/service';
+
+/**
+ * Admin user credentials interface
+ * @interface AdminCredentials
+ * @property {string} email - Admin user email address
+ * @property {string} password - Admin user password
+ */
+interface AdminCredentials {
+  email: string;
+  password: string;
+}
+
+/**
+ * Creates default system users if they don't exist
+ * @function createAdminUser
+ * @param {AdminCredentials} credentials - Admin user credentials
+ * @returns {Promise<void>} A promise that resolves when the operation is complete
+ * @throws {Error} If admin credentials are invalid or if the operation fails
+ * @description
+ * This function performs the following operations:
+ * 1. Checks if an anonymous user exists, creates one if it doesn't
+ * 2. Checks if an administrator user exists, creates one if it doesn't
+ * 3. Uses the provided credentials for the administrator user
+ *
+ * @example
+ * ```typescript
+ * // Create default system users
+ * await createAdminUser({
+ *   email: 'admin@example.com',
+ *   password: 'secure-password'
+ * });
+ *
+ * // The function will:
+ * // 1. Create an anonymous user if it doesn't exist
+ * // 2. Create an admin user with the provided credentials if it doesn't exist
+ * // 3. Do nothing if both users already exist
+ * ```
+ */
+export async function createAdminUser({ email, password }: AdminCredentials): Promise<void> {
+  const authModel = DataProvider.getCollection('cms', 'auth');
+
+  try {
+    const isAnonymousExisted = await authModel.countDocuments({ type: 'anonymous' }).exec();
+
+    const isAdministratorExisted = await authModel
+      .countDocuments({ type: 'user', email: email })
+      .exec();
+
+    if (isAnonymousExisted === 0) {
+      await userManager.main.registerUser({
+        permissionGroup: getDefaultAnonymousPermissionGroup().title,
+        email: '',
+        phone: '',
+        password: '',
+        type: 'anonymous',
+      });
+      // await new authModel({
+      //   permission: getDefaultAnonymousPermissionGroup().title,
+      //   email: "",
+      //   phone: "",
+      //   password: "",
+      //   type: "anonymous",
+      // }).save();
+    }
+
+    if (isAdministratorExisted === 0) {
+      if (!email || !password) {
+        return Promise.reject('Invalid email or password for admin user.');
+      }
+
+      await userManager.main.registerUser({
+        permissionGroup: getDefaultAdministratorPermissionGroup().title,
+        email: email,
+        password: password,
+        type: 'user',
+      });
+
+      // await new authModel({
+      //   permission: getDefaultAdministratorPermissionGroup().title,
+      //   email: email,
+      //   password: password,
+      //   type: "user",
+      // }).save();
+    }
+  } catch (e) {
+    return Promise.reject(e);
+  }
+}

package/src/helper/presetup_services.ts

@@ -0,0 +1,96 @@
+import * as DataInsertion from './data_insertion';
+import * as JWT from '../services/jwt/service';
+import * as FileService from '../services/file/service';
+import generateKeypair from 'keypair';
+
+/**
+ * Setup options interface for initializing required services
+ * @interface SetupOptions
+ * @property {Object} [keypair] - JWT keypair configuration
+ * @property {string} keypair.private - Private key for JWT signing
+ * @property {string} keypair.public - Public key for JWT verification
+ * @property {Object} adminUser - Admin user configuration
+ * @property {string} adminUser.email - Admin user email address
+ * @property {string} adminUser.password - Admin user password
+ * @property {string} [uploadDirectory] - Directory for file uploads
+ */
+interface SetupOptions {
+  keypair?: {
+    private: string;
+    public: string;
+  };
+  adminUser: {
+    email: string;
+    password: string;
+  };
+  uploadDirectory?: string;
+}
+
+/**
+ * Sets up required services for the application to run
+ * @function setup
+ * @param {SetupOptions} options - Setup configuration options
+ * @returns {Promise<void>} A promise that resolves when setup is complete
+ * @throws {Error} If admin user configuration is missing or if setup fails
+ * @description
+ * This function performs the following setup operations:
+ * 1. Configures JWT with provided or generated keypair
+ * 2. Creates default system users (admin and anonymous)
+ * 3. Configures file upload directory if specified
+ *
+ * @example
+ * ```typescript
+ * // Setup with custom keypair
+ * await setup({
+ *   keypair: {
+ *     private: 'your-private-key',
+ *     public: 'your-public-key'
+ *   },
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   },
+ *   uploadDirectory: './uploads'
+ * });
+ *
+ * // Setup with auto-generated keypair
+ * await setup({
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   }
+ * });
+ * ```
+ */
+export async function setup({ keypair, adminUser, uploadDirectory }: SetupOptions): Promise<void> {
+  /**
+   * Json web Token
+   *
+   * Setup private and public keys for JWT module
+   */
+  let keyPairToUse = keypair;
+  if (!keyPairToUse) {
+    // generate new keypair
+    keyPairToUse = generateKeypair();
+  }
+
+  JWT.main.setKies(keyPairToUse.private, keyPairToUse.public);
+
+  if (!adminUser) {
+    throw new Error('Admin user is not supported in TypeScript version');
+  }
+  /**
+   * Data Insertion
+   *
+   * Insert admin user
+   * for the first time
+   */
+  await DataInsertion.createAdminUser(adminUser);
+
+  /**
+   * File Service
+   */
+  if (uploadDirectory) {
+    FileService.main.setUploadDirectory(uploadDirectory);
+  }
+}

package/src/index.ts

@@ -0,0 +1,146 @@
+// Application
+import { createRest } from './application';
+import { Schema } from 'mongoose';
+
+// Utilities
+import * as paginator from './class/paginator';
+import * as reply from './class/reply';
+import { validator } from './class/validator';
+import { getCollection } from './services/data_provider/service';
+import { defineFunction } from './services/functions/service';
+import TypeCasters from './services/data_provider/typeCasters';
+
+import { main as userManager } from './services/user_manager/service';
+import { main as fileService } from './services/file/service';
+
+// Base class
+import { CollectionDefinition, defineCollection } from './class/collection_definition';
+import { schemas } from './class/db_schemas';
+import DatabaseTrigger from './class/database_trigger';
+import CmsTrigger from './class/cms_trigger';
+import {
+  AccessDefinition,
+  Permission,
+  PermissionTypes,
+  PermissionGroup,
+  AccessTypes,
+} from './class/security';
+import * as middleware from './middlewares';
+
+/**
+ * @description Creates a new REST API instance
+ * @example
+ * ```typescript
+ * const rest = createRest();
+ * ```
+ * @returns A new REST API instance
+ */
+export { createRest };
+
+export { CollectionDefinition, defineCollection };
+
+/**
+ * @description Provides predefined database schemas
+ * @example
+ * ```typescript
+ * const userSchema = new Schema({
+ *   name: String,
+ *   avatar: Schemas.file
+ * });
+ * ```
+ */
+export { schemas };
+
+/**
+ * @description Mongoose Schema class for defining data models
+ */
+export { Schema };
+
+/**
+ * @description Handles database triggers and events
+ * @example
+ * ```typescript
+ * const trigger = new DatabaseTrigger('insert-one', (data) => {
+ *   // Handle insert event
+ * });
+ * ```
+ */
+export { DatabaseTrigger };
+
+/**
+ * @description Handles CMS triggers and events
+ */
+export { CmsTrigger };
+
+/**
+ * @description Security and access control definitions
+ * @example
+ * ```typescript
+ * const permission = new Permission({
+ *   type: 'user_access',
+ *   read: true,
+ *   write: true
+ * });
+ * ```
+ */
+export { AccessDefinition, Permission, PermissionTypes, PermissionGroup, AccessTypes };
+
+/**
+ * @description Defines custom functions for the API
+ * @example
+ * ```typescript
+ * defineFunction('sendEmail', async (data) => {
+ *   // Send email logic
+ * });
+ * ```
+ */
+export { defineFunction };
+
+/**
+ * @description Type casting utilities for data transformation
+ */
+export { TypeCasters };
+
+/**
+ * @description Input validation utilities
+ */
+export { validator };
+
+/**
+ * @description Response handling utilities
+ */
+export { reply };
+
+/**
+ * @description Pagination utilities
+ */
+export { paginator };
+
+/**
+ * @description Database collection access utilities
+ */
+export { getCollection };
+
+/**
+ * @description File handling utilities
+ * @example
+ * ```typescript
+ * const file = await fileService.getFile('fileId');
+ * const link = fileService.getFileLink('fileId');
+ * ```
+ */
+export { fileService };
+
+/**
+ * @description Middleware utilities
+ */
+export { middleware };
+
+/**
+ * @description User management utilities
+ * @example
+ * ```typescript
+ * const user = await userManager.getUserById('userId');
+ * ```
+ */
+export { userManager };