@modular-rest/server 1.11.13 → 1.12.0

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

package/src/class/reply.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 function create(status: ResponseStatus, detail: Record<string, any> = {}): ResponseObject {
+  // Initialize with a default status that will be overwritten
+  const result: ResponseObject = {
+    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/src/class/security.ts

@@ -0,0 +1,250 @@
+/**
+ * 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 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[];
+  }) {
+    this.database = database;
+    this.collection = collection;
+    this.permissionList = permissionList;
+  }
+}
+
+/**
+ * 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 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 = false,
+    write = false,
+    onlyOwnData = false,
+    ownerIdField = 'refId',
+  }: {
+    accessType: AccessType;
+    read?: boolean;
+    write?: boolean;
+    onlyOwnData?: boolean;
+    ownerIdField?: string;
+  }) {
+    this.accessType = type;
+    this.read = read;
+    this.write = write;
+    this.onlyOwnData = onlyOwnData;
+    this.ownerIdField = ownerIdField;
+  }
+}
+
+/**
+ * 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 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 = false,
+    isAnonymous = false,
+    allowedAccessTypes = [],
+  }: {
+    title: string;
+    isDefault?: boolean;
+    isAnonymous?: boolean;
+    allowedAccessTypes?: AccessType[];
+  }) {
+    this.title = title;
+    this.isDefault = isDefault;
+    this.isAnonymous = isAnonymous;
+    this.allowedAccessTypes = allowedAccessTypes;
+  }
+}
+
+/**
+ * Provides static access to access type constants
+ * @class AccessTypes
+ */
+export class AccessTypes {
+  /**
+   * Get the string representing read access type
+   * @returns {string} The read access type
+   */
+  static get read(): string {
+    return 'read';
+  }
+
+  /**
+   * Get the string representing write access type
+   * @returns {string} The write access type
+   */
+  static get write(): string {
+    return 'write';
+  }
+}
+
+/**
+ * Provides static access to permission type constants
+ * @class PermissionTypes
+ */
+export class PermissionTypes {
+  /**
+   * Get the string representing god access permission type
+   * @returns {string} The god access permission type
+   */
+  static get god_access(): AccessType {
+    return 'god_access';
+  }
+
+  /**
+   * Get the string representing advanced settings permission type
+   * @returns {string} The advanced settings permission type
+   */
+  static get advanced_settings(): AccessType {
+    return 'advanced_settings';
+  }
+
+  /**
+   * Get the string representing user access permission type
+   * @returns {string} The user access permission type
+   */
+  static get user_access(): AccessType {
+    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(): AccessType {
+    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(): AccessType {
+    return 'remove_file_access';
+  }
+}