@modular-rest/server 1.11.13 → 1.12.0

package/dist/class/collection_definition.d.ts

@@ -0,0 +1,112 @@
+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;
+}
+/**
+ * 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 declare function defineCollection(options: CollectionDefinitionOptions): CollectionDefinition;
+/**
+ * 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 declare class CollectionDefinition {
+    /** @readonly The name of the database */
+    database: string;
+    /** @readonly The name of the collection */
+    collection: string;
+    /** @readonly Mongoose schema definition */
+    schema: Schema;
+    /** @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);
+}
+export {};

package/dist/class/collection_definition.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectionDefinition = void 0;
+exports.defineCollection = defineCollection;
+/**
+ * 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[]
+ *   })
+ * ]
+ * ```
+ */
+function defineCollection(options) {
+    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
+ */
+class CollectionDefinition {
+    /**
+     * 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, }) {
+        this.database = database;
+        this.collection = collection;
+        this.schema = schema;
+        this.permissions = permissions;
+        this.triggers = triggers;
+    }
+}
+exports.CollectionDefinition = CollectionDefinition;

package/dist/class/combinator.d.ts

@@ -0,0 +1,43 @@
+import Koa from 'koa';
+interface FilenameOption {
+    name: string;
+    extension: string;
+}
+interface ModuleOptions {
+    rootDirectory: string;
+    filename: FilenameOption;
+    combineWithRoot?: boolean;
+    convertToArray?: boolean;
+}
+interface FunctionOptions {
+    rootDirectory: string;
+    filename: FilenameOption;
+}
+declare class Combinator {
+    combineRoutesByFilePath(rootDirectory: string, app: Koa): Promise<void>;
+    /**
+     * Combine modules from files in a directory
+     * @param options - Configuration options
+     */
+    combineModulesByFilePath({ rootDirectory, filename, combineWithRoot, convertToArray, }: ModuleOptions): Promise<any>;
+    /**
+     * Combine functions from files in a directory
+     * @param options - Function options
+     */
+    combineFunctionsByFilePath({ rootDirectory, filename }: FunctionOptions): Promise<void>;
+    /**
+     * Add functions from an array
+     * @param functionList - List of functions to add
+     */
+    addFunctionsByArray(functionList: any[]): void;
+    /**
+     * Extend an object with properties from another
+     * @param obj - Target object
+     * @param src - Source object
+     * @returns Extended object
+     */
+    extendObj(obj: any, src: any): any;
+    static get instance(): Combinator;
+}
+declare const instance: Combinator;
+export = instance;

package/dist/class/combinator.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const koa_router_1 = __importDefault(require("koa-router"));
+const directory = __importStar(require("./directory"));
+const service_1 = require("../services/functions/service");
+class Combinator {
+    async combineRoutesByFilePath(rootDirectory, app) {
+        // find route paths
+        const option = {
+            name: 'router',
+            filter: ['.js'],
+        };
+        let routerPaths = [];
+        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 koa_router_1.default();
+            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, }) {
+        // find route paths
+        let rootObject_temp;
+        const option = {
+            name: filename.name,
+            filter: [filename.extension],
+        };
+        let modulesPath = [];
+        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 }) {
+        // find route paths
+        const option = {
+            name: filename.name,
+            filter: [filename.extension],
+        };
+        let functionsPaths = [];
+        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) {
+                    (0, service_1.addFunction)(moduleFunction);
+                }
+            }
+            else {
+                (0, service_1.addFunction)(modularFunctions.functions);
+            }
+        }
+    }
+    /**
+     * Add functions from an array
+     * @param functionList - List of functions to add
+     */
+    addFunctionsByArray(functionList) {
+        for (const functionItem of functionList) {
+            (0, service_1.addFunction)(functionItem);
+        }
+    }
+    /**
+     * Extend an object with properties from another
+     * @param obj - Target object
+     * @param src - Source object
+     * @returns Extended object
+     */
+    extendObj(obj, src) {
+        obj = obj || {};
+        for (const key in src) {
+            if (Object.prototype.hasOwnProperty.call(src, key))
+                obj[key] = src[key];
+        }
+        return obj;
+    }
+    static get instance() {
+        return instance;
+    }
+}
+const instance = new Combinator();
+module.exports = instance;

package/dist/class/database_trigger.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 declare 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);
+}
+export default DatabaseTrigger;

package/dist/class/database_trigger.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseTrigger = void 0;
+/**
+ * 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]
+ * });
+ * ```
+ */
+class DatabaseTrigger {
+    /**
+     * @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, callback = () => { }) {
+        this.operation = operation;
+        this.callback = callback;
+    }
+}
+exports.DatabaseTrigger = DatabaseTrigger;
+exports.default = DatabaseTrigger;

package/dist/class/db_schemas.d.ts

@@ -0,0 +1,25 @@
+import mongoose from 'mongoose';
+/**
+ * File schema interface
+ */
+export interface IFile {
+    originalName: string;
+    fileName: string;
+    owner: string;
+    format: string;
+    tag: string;
+    size: number;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * File schema
+ */
+export declare const fileSchema: mongoose.Schema<IFile, mongoose.Model<IFile, any, any>, undefined, {}>;
+/**
+ * Schema definitions
+ */
+export declare const schemas: {
+    file: mongoose.Schema<IFile, mongoose.Model<IFile, any, any>, undefined, {}>;
+};
+export default schemas;

package/dist/class/db_schemas.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemas = exports.fileSchema = void 0;
+const mongoose_1 = __importDefault(require("mongoose"));
+const { Schema } = mongoose_1.default;
+/**
+ * File schema
+ */
+exports.fileSchema = new Schema({
+    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
+ */
+exports.schemas = {
+    file: exports.fileSchema,
+};
+exports.default = exports.schemas;

package/dist/class/directory.d.ts

@@ -0,0 +1,20 @@
+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
+ */
+declare function walk(dir: string, settings: DirectorySettings, done: WalkCallback): void;
+/**
+ * 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
+ */
+declare function find(dir: string, settings: DirectorySettings): Promise<string[]>;
+export { walk, find };