@modular-rest/server 1.11.12 → 1.11.14

package/src/class/cms_trigger.ts

@@ -0,0 +1,68 @@
+/**
+ * Type for CMS operations that can trigger a callback
+ * @typedef {('update-one' | 'insert-one' | 'remove-one')} CmsOperation
+ * @description Supported CMS operations:
+ * - 'update-one': Triggered when updating a single document in the CMS
+ * - 'insert-one': Triggered when inserting a new document in the CMS
+ * - 'remove-one': Triggered when removing a document from the CMS
+ */
+export type CmsOperation = 'update-one' | 'insert-one' | 'remove-one';
+
+/**
+ * Context interface for CMS trigger callbacks
+ * @interface CmsTriggerContext
+ * @property {Record<string, any>} query - The query parameters used in the CMS operation
+ * @property {any} queryResult - The result of the CMS operation
+ */
+export interface CmsTriggerContext {
+  query: Record<string, any>;
+  queryResult: any;
+}
+
+/**
+ * Defines a callback to be executed on specific CMS operations
+ * @class CmsTrigger
+ * @property {CmsOperation} operation - The CMS operation that triggers the callback
+ * @property {Function} callback - The callback function to be executed
+ * @example
+ * ```typescript
+ * const trigger = new CmsTrigger('insert-one', (context) => {
+ *   console.log('New CMS document inserted:', context.queryResult);
+ *   // Perform additional actions after CMS document insertion
+ * });
+ *
+ * // Use the trigger in RestOptions
+ * const { app } = await createRest({
+ *   authTriggers: [trigger],
+ *   // ... other options
+ * });
+ * ```
+ */
+export class CmsTrigger {
+  operation: CmsOperation;
+  callback: (context: CmsTriggerContext) => void;
+
+  /**
+   * Creates a new CmsTrigger instance
+   * @param {CmsOperation} operation - The CMS operation to trigger on
+   * @param {Function} [callback=() => {}] - The callback function to execute
+   * @example
+   * ```typescript
+   * // Log all CMS updates
+   * const updateTrigger = new CmsTrigger('update-one', (context) => {
+   *   console.log('CMS document updated:', context.queryResult);
+   * });
+   *
+   * // Track CMS document removals
+   * const removeTrigger = new CmsTrigger('remove-one', (context) => {
+   *   console.log('CMS document removed:', context.queryResult);
+   * });
+   * ```
+   */
+  constructor(operation: CmsOperation, callback: (context: CmsTriggerContext) => void = () => {}) {
+    this.operation = operation;
+    this.callback = callback;
+  }
+}
+
+export default CmsTrigger;

package/src/class/collection_definition.ts

@@ -0,0 +1,134 @@
+import { Schema } from 'mongoose';
+import { Permission } from './security';
+import { DatabaseTrigger } from './database_trigger';
+
+/**
+ * Configuration options for creating a collection definition.
+ * This interface defines the structure for configuring MongoDB collections with their associated
+ * schemas, permissions, and triggers.
+ *
+ * @inline
+ *
+ */
+interface CollectionDefinitionOptions {
+  /** The name of the database where the collection resides */
+  database: string;
+  /** The name of the collection to be configured */
+  collection: string;
+  /** List of permissions controlling access to the collection */
+  permissions: Permission[];
+  /** Optional database triggers for custom operations */
+  triggers?: DatabaseTrigger[];
+
+  /**
+   * Mongoose schema definition for the collection
+   * @type {Schema}
+   * @see https://mongoosejs.com/docs/5.x/docs/guide.html
+   */
+  schema: Schema<any>;
+}
+
+/**
+ * To have define any collection in your database you haveto use below method in your `db.[js|ts]` file and export an array of CollectionDefinition instances.
+ *
+ * @param {CollectionDefinitionOptions} options - The options for the collection
+ * @expandType CollectionDefinitionOptions
+ *
+ * @returns A new instance of CollectionDefinition
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { defineCollection } from '@modular-rest/server';
+ *
+ * export default [
+ *   defineCollection({
+ *     database: 'users',
+ *     collection: 'info',
+ *     // schema: Schema,
+ *     // permissions: Permission[]
+ *     // trigger: DatabaseTrigger[]
+ *   })
+ * ]
+ * ```
+ */
+export function defineCollection(options: CollectionDefinitionOptions) {
+  return new CollectionDefinition(options);
+}
+
+/**
+ * A class that represents a MongoDB collection configuration. Provides full support for schema validation, access control through permissions,
+ * and custom triggers for various database operations.
+ *
+ * @hideconstructor
+ *
+ * @deprecated Use `defineCollection` instead.
+ *
+ * @example
+ * ```typescript
+ * const userSchema = new Schema({
+ *   name: String,
+ *   email: String,
+ *   age: Number
+ * });
+ *
+ * const collection = new CollectionDefinition({
+ *   database: 'myapp',
+ *   collection: 'users',
+ *   schema: userSchema,
+ *   permissions: [
+ *     new Permission({
+ *       type: 'user_access',
+ *       read: true,
+ *       write: true
+ *     })
+ *   ],
+ *   triggers: [
+ *     new DatabaseTrigger('insert-one', (data) => {
+ *       console.log('New user created:', data);
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @private
+ */
+export class CollectionDefinition {
+  /** @readonly The name of the database */
+  database: string;
+
+  /** @readonly The name of the collection */
+  collection: string;
+
+  /** @readonly Mongoose schema definition */
+  schema: Schema<any>;
+
+  /** @readonly List of permissions for the collection */
+  permissions: Permission[];
+
+  /** @readonly Optional database triggers */
+  triggers?: DatabaseTrigger[];
+
+  /**
+   * Creates a new CollectionDefinition instance
+   *
+   * @param options - Configuration options for the collection
+   * @returns A new instance of CollectionDefinition
+   *
+   * @beta
+   */
+  constructor({
+    database,
+    collection,
+    schema,
+    permissions,
+    triggers,
+  }: CollectionDefinitionOptions) {
+    this.database = database;
+    this.collection = collection;
+    this.schema = schema;
+    this.permissions = permissions;
+    this.triggers = triggers;
+  }
+}

package/src/class/combinator.ts

@@ -0,0 +1,176 @@
+import Router from 'koa-router';
+import Koa from 'koa';
+import * as directory from './directory';
+import { addFunction } from '../services/functions/service';
+
+interface FilenameOption {
+  name: string;
+  extension: string;
+}
+
+interface ModuleOptions {
+  rootDirectory: string;
+  filename: FilenameOption;
+  combineWithRoot?: boolean;
+  convertToArray?: boolean;
+}
+
+interface FunctionOptions {
+  rootDirectory: string;
+  filename: FilenameOption;
+}
+
+class Combinator {
+  async combineRoutesByFilePath(rootDirectory: string, app: Koa): Promise<void> {
+    // find route paths
+    const option = {
+      name: 'router',
+      filter: ['.js'],
+    };
+
+    let routerPaths: string[] = [];
+    try {
+      routerPaths = await directory.find(rootDirectory, option);
+    } catch (e) {
+      console.log(e);
+    }
+
+    // create and combine routes into the app
+    for (let i = 0; i < routerPaths.length; i++) {
+      const service = require(routerPaths[i]);
+      const name = service.name;
+
+      const serviceRouter = new Router();
+      serviceRouter.use(`/${name}`, service.main.routes());
+
+      app.use(serviceRouter.routes());
+    }
+  }
+
+  /**
+   * Combine modules from files in a directory
+   * @param options - Configuration options
+   */
+  async combineModulesByFilePath({
+    rootDirectory,
+    filename,
+    combineWithRoot,
+    convertToArray,
+  }: ModuleOptions): Promise<any> {
+    // find route paths
+    let rootObject_temp: any;
+
+    const option = {
+      name: filename.name,
+      filter: [filename.extension],
+    };
+
+    let modulesPath: string[] = [];
+    try {
+      modulesPath = await directory.find(rootDirectory, option);
+    } catch (e) {
+      console.log(e);
+    }
+
+    // create and combine routes into the app
+    for (let i = 0; i < modulesPath.length; i++) {
+      const moduleObject = require(modulesPath[i]);
+
+      // act by otherOption
+      if (combineWithRoot) {
+        if (moduleObject.name) delete moduleObject.name;
+
+        if (Array.isArray(moduleObject)) {
+          if (!rootObject_temp) rootObject_temp = [];
+
+          rootObject_temp = [...rootObject_temp, ...moduleObject];
+        } else {
+          rootObject_temp = this.extendObj(rootObject_temp, moduleObject);
+        }
+      }
+      // default act
+      else {
+        const name = moduleObject.name;
+        rootObject_temp[name] = moduleObject;
+      }
+    }
+
+    // options
+    // convertToArray
+    if (convertToArray) {
+      rootObject_temp = Object.values(rootObject_temp);
+    }
+
+    // set result to main rootObject
+    return rootObject_temp;
+  }
+
+  /**
+   * Combine functions from files in a directory
+   * @param options - Function options
+   */
+  async combineFunctionsByFilePath({ rootDirectory, filename }: FunctionOptions): Promise<void> {
+    // find route paths
+    const option = {
+      name: filename.name,
+      filter: [filename.extension],
+    };
+
+    let functionsPaths: string[] = [];
+    try {
+      functionsPaths = await directory.find(rootDirectory, option);
+    } catch (e) {
+      console.log(e);
+    }
+
+    // create and combine routes into the app
+    for (let i = 0; i < functionsPaths.length; i++) {
+      const modularFunctions = require(functionsPaths[i]);
+
+      if (!modularFunctions.functions) {
+        throw new Error(`Module file ${functionsPaths[i]} does not have functions property.`);
+      }
+
+      // if array
+      if (Array.isArray(modularFunctions.functions)) {
+        for (const moduleFunction of modularFunctions.functions) {
+          addFunction(moduleFunction);
+        }
+      } else {
+        addFunction(modularFunctions.functions);
+      }
+    }
+  }
+
+  /**
+   * Add functions from an array
+   * @param functionList - List of functions to add
+   */
+  addFunctionsByArray(functionList: any[]): void {
+    for (const functionItem of functionList) {
+      addFunction(functionItem);
+    }
+  }
+
+  /**
+   * Extend an object with properties from another
+   * @param obj - Target object
+   * @param src - Source object
+   * @returns Extended object
+   */
+  extendObj(obj: any, src: any): any {
+    obj = obj || {};
+    for (const key in src) {
+      if (Object.prototype.hasOwnProperty.call(src, key)) obj[key] = src[key];
+    }
+    return obj;
+  }
+
+  static get instance(): Combinator {
+    return instance;
+  }
+}
+
+const instance = new Combinator();
+
+export = instance;

package/src/class/database_trigger.ts

@@ -0,0 +1,99 @@
+/**
+ * Type for database operations that can trigger a callback
+ */
+export type DatabaseOperation =
+  | 'find'
+  | 'find-one'
+  | 'count'
+  | 'update-one'
+  | 'insert-one'
+  | 'remove-one'
+  | 'aggregate';
+
+/**
+ * Context interface for database trigger callbacks
+ * @interface DatabaseTriggerContext
+ * @property {Record<string, any>} query - The query parameters used in the database operation
+ * @property {any | any[]} queryResult - The result of the database operation
+ */
+export interface DatabaseTriggerContext {
+  query: Record<string, any>;
+  queryResult: any | any[];
+}
+
+/**
+ * The callback function to be executed on specific database operations
+ * @param {DatabaseTriggerContext} context - The context of the database operation
+ * @example
+ * ```typescript
+ * const trigger = new DatabaseTrigger('insert-one', (context) => {
+ *   console.log('New document inserted:', context.queryResult);
+ * });
+ * ```
+ */
+type DatabaseTriggerCallback = (context: DatabaseTriggerContext) => void;
+
+/**
+ * in a complex application, you may need to perform additional actions after a database operation.
+ * this is where DatabaseTrigger comes in. so you can define a callback to be executed on specific database operations for a collection.
+ *
+ * Supported triggers are:
+ *
+ * | Trigger      | Description                                                  |
+ * | ------------ | ------------------------------------------------------------ |
+ * | `find`       | Triggered when a find query is executed on collection.       |
+ * | `find-one`   | Triggered when a find one query is executed on collection.   |
+ * | `count`      | Triggered when a count query is executed on collection.      |
+ * | `update-one` | Triggered when a update one query is executed on collection. |
+ * | `insert-one` | Triggered when a insert one query is executed on collection. |
+ * | `remove-one` | Triggered when a remove one query is executed on collection. |
+ * | `aggregate`  | Triggered when a aggregate query is executed on collection.  |
+ *
+ * @property {DatabaseOperation} operation - The database operation that triggers the callback
+ * @property {DatabaseTriggerCallback} callback - The callback function to be executed
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseTrigger } from '@server-ts/database';
+ *
+ * const trigger = new DatabaseTrigger('insert-one', ({ query, queryResult }) => {
+ *   console.log('New document inserted:', queryResult);
+ *
+ *   try {
+ *     // Perform additional actions after document insertion
+ *   } catch (error) {
+ *     console.error('Error performing additional actions:', error);
+ *   }
+ * });
+ *
+ * // Use the trigger in a collection definition
+ * const collection = new CollectionDefinition({
+ *   triggers: [trigger]
+ * });
+ * ```
+ */
+export class DatabaseTrigger {
+  operation: DatabaseOperation;
+  callback: (context: DatabaseTriggerContext) => void;
+
+  /**
+   * @hidden
+   *
+   * Creates a new DatabaseTrigger instance
+   * @param {DatabaseOperation} operation - The database operation to trigger on
+   * @param {DatabaseTriggerCallback} [callback=() => {}] - The callback function to execute
+   *
+   * @example
+   * ```typescript
+   * const trigger = new DatabaseTrigger('insert-one', (context) => {
+   *   console.log('New document inserted:', context.queryResult);
+   * });
+   *
+   */
+  constructor(operation: DatabaseOperation, callback: DatabaseTriggerCallback = () => {}) {
+    this.operation = operation;
+    this.callback = callback;
+  }
+}
+
+export default DatabaseTrigger;

package/src/class/db_schemas.ts

@@ -0,0 +1,44 @@
+import mongoose from 'mongoose';
+const { Schema } = mongoose;
+
+/**
+ * File schema interface
+ */
+export interface IFile {
+  originalName: string;
+  fileName: string;
+  owner: string;
+  format: string;
+  // Tag being used as the parent dir for files
+  // uploadDir/$format/$tag/timestamp.format
+  tag: string;
+  size: number;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+/**
+ * File schema
+ */
+export const fileSchema = new Schema<IFile>(
+  {
+    originalName: String,
+    fileName: String,
+    owner: String,
+    format: String,
+    // Tag being used as the parent dir for files
+    // uploadDir/$format/$tag/timestamp.format
+    tag: String,
+    size: Number,
+  },
+  { timestamps: true }
+);
+
+/**
+ * Schema definitions
+ */
+export const schemas = {
+  file: fileSchema,
+};
+
+export default schemas;

package/src/class/{directory.js → directory.ts}

@@ -1,19 +1,39 @@
-const fs = require("fs");
-const path = require("path");
+import fs from 'fs';
+import path from 'path';
 
-function walk(dir, settings, done) {
-  let results = [];
+interface DirectorySettings {
+  name?: string;
+  filter?: string[];
+}
+
+type WalkCallback = (err: Error | null, results: string[]) => void;
+
+/**
+ * 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: string, settings: DirectorySettings, done: WalkCallback): void {
+  let results: string[] = [];
 
   // Read director file and folders
   fs.readdir(dir, function (err, list) {
     if (err) return done(err, results);
 
-    var pending = list.length;
+    let pending = list.length;
     if (!pending) return done(null, results);
 
     list.forEach(function (file) {
       file = path.join(dir, file);
       fs.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]
@@ -24,9 +44,9 @@ function walk(dir, settings, done) {
           });
         } else {
           // file filter
-          var extension = path.extname(file);
-          var fileName = path.basename(file).split(".")[0];
-          var fileNameKey = true;
+          const extension = path.extname(file);
+          const fileName = path.basename(file).split('.')[0];
+          let fileNameKey = true;
 
           // name filter
           if (settings.name && settings.name === fileName) fileNameKey = true;
@@ -35,9 +55,8 @@ function walk(dir, settings, done) {
           // extension filter
           if (settings.filter && fileNameKey) {
             settings.filter.forEach(function (element) {
-              if (element.toLowerCase() === extension.toLowerCase())
-                results.push(file);
-            }, this);
+              if (element.toLowerCase() === extension.toLowerCase()) results.push(file);
+            });
           }
 
           // push any file if no option
@@ -50,16 +69,19 @@ function walk(dir, settings, done) {
   });
 }
 
-function find(dir, settings) {
-  return new Promise((don, reject) => {
+/**
+ * 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: string, settings: DirectorySettings): Promise<string[]> {
+  return new Promise((resolve, reject) => {
     walk(dir, settings, (err, result) => {
       if (err) reject(err);
-      else don(result);
+      else resolve(result);
     });
   });
 }
 
-module.exports = {
-  walk,
-  find,
-};
+export { walk, find };

package/src/class/paginator.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 function create(count: number, perPage: number, page: number): PaginationResult {
+  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: PaginationResult = {
+    pages: totalPages,
+    page: page,
+    from: from,
+    to: perPage,
+  };
+
+  return result;
+}