@modular-rest/server 1.11.13 → 1.12.1

package/dist/services/file/service.js

@@ -0,0 +1,341 @@
+"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 };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.name = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DataProvider = __importStar(require("../data_provider/service"));
+const trigger_operator_1 = __importDefault(require("../../class/trigger_operator"));
+const config_1 = require("../../config");
+/**
+ * Service name constant
+ * @constant {string}
+ */
+exports.name = 'file';
+/**
+ * File service for handling file storage and retrieval.
+ *
+ * This service provides functionality for storing, retrieving, and managing files.
+ * It handles file storage on disk and maintains file metadata in the database.
+ * Files are organized by format and tag in the upload directory.
+ */
+class FileService {
+    /**
+     * @hidden
+     */
+    constructor() {
+        /**
+         * @hidden
+         */
+        this.directory = null;
+    }
+    /**
+     * @hidden
+     *
+     * Sets the upload directory for file storage
+     * @param {string} directory - Directory path for file storage
+     * @throws {Error} If directory is invalid or not writable
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * fileService.setUploadDirectory('/path/to/uploads');
+     * ```
+     */
+    setUploadDirectory(directory) {
+        if (!fs_1.default.existsSync(directory)) {
+            fs_1.default.mkdirSync(directory, { recursive: true });
+        }
+        this.directory = directory;
+    }
+    /**
+     * @hidden
+     *
+     * Creates stored file details with unique filename
+     * @param {string} fileType - MIME type of the file
+     * @param {string} tag - Tag for file organization
+     * @returns {StoredFileDetail} Storage details including filename and path
+     * @throws {Error} If upload directory is not set
+     *
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * const details = fileService.createStoredDetail('image/jpeg', 'profile');
+     * // Returns: { fileName: '1234567890.jpeg', fullPath: '/uploads/jpeg/profile/1234567890.jpeg', fileFormat: 'jpeg' }
+     * ```
+     */
+    createStoredDetail(fileType, tag) {
+        const typeParts = fileType.split('/');
+        const fileFormat = typeParts[1] || typeParts[0] || 'unknown';
+        const time = new Date().getTime();
+        const fileName = `${time}.${fileFormat}`;
+        if (!FileService.instance.directory) {
+            throw new Error('Upload directory has not been set');
+        }
+        const fullPath = path_1.default.join(FileService.instance.directory, fileFormat, tag, fileName);
+        return { fileName, fullPath, fileFormat };
+    }
+    /**
+     * @hidden
+     *
+     * Stores a file, removes the temporary file, and saves metadata to database
+     * @param {StoreFileOptions} options - File storage options
+     * @returns {Promise<IFile>} Promise resolving to stored file document
+     * @throws {Error} If upload directory is not set or storage fails
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * const file = await fileService.storeFile({
+     *   file: {
+     *     path: '/tmp/upload.jpg',
+     *     type: 'image/jpeg',
+     *     name: 'profile.jpg',
+     *     size: 1024
+     *   },
+     *   ownerId: 'user123',
+     *   tag: 'profile',
+     *   removeFileAfterStore: true
+     * });
+     * ```
+     */
+    storeFile({ file, ownerId, tag, removeFileAfterStore = true }) {
+        if (!FileService.instance.directory) {
+            throw new Error('Upload directory has not been set');
+        }
+        let storedFile;
+        return new Promise(async (done, reject) => {
+            storedFile = FileService.instance.createStoredDetail(file.type, tag);
+            fs_1.default.copyFile(file.path, storedFile.fullPath, (err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    done(null);
+                }
+                // remove temp file
+                if (removeFileAfterStore) {
+                    fs_1.default.unlinkSync(file.path);
+                }
+            });
+        })
+            .then(() => {
+            // Get collection model for access to relative collection
+            const CollectionModel = DataProvider.getCollection('cms', 'file');
+            if (!CollectionModel) {
+                throw new Error('Collection model not found');
+            }
+            const data = {
+                owner: ownerId,
+                fileName: storedFile.fileName,
+                originalName: file.name,
+                format: storedFile.fileFormat,
+                tag,
+                size: file.size,
+            };
+            // Create new document
+            const doc = new CollectionModel(data);
+            return doc.save().then(savedDoc => {
+                trigger_operator_1.default.call('insert-one', 'cms', 'file', {
+                    query: null,
+                    queryResult: savedDoc,
+                });
+                return savedDoc;
+            });
+        })
+            .catch(err => {
+            // remove stored file
+            fs_1.default.unlinkSync(storedFile.fullPath);
+            throw err;
+        });
+    }
+    /**
+     * @hidden
+     *
+     * Removes a file from the disk
+     * @param {string} path - File path to remove
+     * @returns {Promise<void>} Promise resolving when file is removed
+     * @throws {Error} If file removal fails
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * await fileService.removeFromDisc('/uploads/jpeg/profile/1234567890.jpeg');
+     * ```
+     */
+    removeFromDisc(path) {
+        return new Promise((done, reject) => {
+            fs_1.default.unlink(path, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    done();
+            });
+        });
+    }
+    /**
+     * Removes a file from both database and disk
+     *
+     * @param {string} fileId - File ID to remove
+     * @returns {Promise<void>} Promise resolving when file is removed
+     * @throws {Error} If file is not found or removal fails
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * try {
+     *   await fileService.removeFile('file123');
+     *   console.log('File removed successfully');
+     * } catch (error) {
+     *   console.error('Failed to remove file:', error);
+     * }
+     * ```
+     */
+    removeFile(fileId) {
+        if (!FileService.instance.directory) {
+            throw new Error('Upload directory has not been set');
+        }
+        return new Promise(async (done, reject) => {
+            const CollectionModel = DataProvider.getCollection('cms', 'file');
+            if (!CollectionModel) {
+                return reject(new Error('Collection model not found'));
+            }
+            const fileDoc = await CollectionModel.findOne({ _id: fileId }).exec();
+            if (!fileDoc) {
+                return reject(new Error('File not found'));
+            }
+            await CollectionModel.deleteOne({ _id: fileId })
+                .exec()
+                .then(() => {
+                // create file path
+                const filePath = path_1.default.join(FileService.instance.directory, fileDoc.format, fileDoc.tag, fileDoc.fileName);
+                // Remove file from disc
+                return FileService.instance.removeFromDisc(filePath).catch(async (err) => {
+                    // Recreate fileDoc if removing file operation has error
+                    await new CollectionModel(fileDoc).save();
+                    throw err;
+                });
+            })
+                .then(() => {
+                trigger_operator_1.default.call('remove-one', 'cms', 'file', {
+                    query: { _id: fileId },
+                    queryResult: null,
+                });
+            })
+                .then(done)
+                .catch(reject);
+        });
+    }
+    /**
+     * Retrieves a file document from the database
+     *
+     * @param {string} fileId - File ID to retrieve
+     * @returns {Promise<IFile>} Promise resolving to file document
+     * @throws {Error} If collection model is not found or file is not found
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * const fileDoc = await fileService.getFile('file123');
+     * console.log('File details:', fileDoc);
+     * ```
+     */
+    getFile(fileId) {
+        const CollectionModel = DataProvider.getCollection('cms', 'file');
+        if (!CollectionModel) {
+            throw new Error('Collection model not found');
+        }
+        return CollectionModel.findOne({ _id: fileId })
+            .exec()
+            .then(doc => {
+            if (!doc) {
+                throw new Error('File not found');
+            }
+            return doc;
+        });
+    }
+    /**
+     * Retrieves the public URL link for a file
+     *
+     * @param {string} fileId - File ID to get link for
+     * @returns {Promise<string>} Promise resolving to file URL
+     * @throws {Error} If static path root is not defined or file is not found
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * const link = await fileService.getFileLink('file123');
+     * // Returns: '/static/jpeg/profile/1234567890.jpeg'
+     * ```
+     */
+    async getFileLink(fileId) {
+        const fileDoc = await FileService.instance.getFile(fileId);
+        if (!config_1.config.staticPath?.actualPath) {
+            throw new Error('Static path root is not defined');
+        }
+        const link = config_1.config.staticPath.actualPath + `/${fileDoc.format}/${fileDoc.tag}/` + fileDoc.fileName;
+        return link;
+    }
+    /**
+     * Gets the full filesystem path for a file
+     *
+     * @param {string} fileId - File ID to get path for
+     * @returns {Promise<string>} Promise resolving to full file path
+     * @throws {Error} If upload directory is not set or file is not found
+     * @example
+     * ```typescript
+     * import { fileService } from '@modular-rest/server';
+     *
+     * const path = await fileService.getFilePath('file123');
+     * // Returns: '/uploads/jpeg/profile/1234567890.jpeg'
+     * ```
+     */
+    async getFilePath(fileId) {
+        const { fileName, format, tag } = await FileService.instance.getFile(fileId);
+        if (!FileService.instance.directory) {
+            throw new Error('Upload directory has not been set');
+        }
+        return path_1.default.join(FileService.instance.directory, format, tag, fileName);
+    }
+}
+/**
+ * Main file service instance
+ * @constant {FileService}
+ */
+exports.main = new FileService();

package/dist/services/functions/router.d.ts

@@ -0,0 +1,4 @@
+import Router from 'koa-router';
+declare const functionRouter: Router<any, {}>;
+declare const name = "function";
+export { name, functionRouter as main };

package/dist/services/functions/router.js

@@ -0,0 +1,67 @@
+"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 };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.name = void 0;
+const koa_router_1 = __importDefault(require("koa-router"));
+const service = __importStar(require("./service"));
+const middleware = __importStar(require("../../middlewares"));
+const validator_1 = require("../../class/validator");
+const reply_1 = require("../../class/reply");
+const functionRouter = new koa_router_1.default();
+exports.main = functionRouter;
+const name = 'function';
+exports.name = name;
+functionRouter.use('/', middleware.auth, async (ctx, next) => {
+    const body = ctx.request.body;
+    const bodyValidated = (0, validator_1.validateObject)(body, 'name args');
+    // fields validation
+    if (!bodyValidated.isValid) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: bodyValidated.requires })));
+    }
+    await next();
+});
+functionRouter.post('/run', middleware.auth, async (ctx) => {
+    const { name, args } = ctx.request.body;
+    try {
+        const result = await service.runFunction(name, args, ctx.state.user);
+        ctx.body = JSON.stringify((0, reply_1.create)('s', { data: result }));
+    }
+    catch (e) {
+        ctx.throw(400, JSON.stringify((0, reply_1.create)('e', { error: e.message })));
+    }
+});

package/dist/services/functions/service.d.ts

@@ -0,0 +1,132 @@
+import { AccessType } from '../../class/security';
+import { User } from '../../class/user';
+/**
+ * Service name constant
+ * @constant {string}
+ */
+export declare const name = "functions";
+/**
+ * Interface for defined functions.
+ *
+ * @interface DefinedFunction
+ * @inline
+ * @example
+ * ```typescript
+ * const myFunction: DefinedFunction = {
+ *   name: 'calculateTotal',
+ *   permissionTypes: ['user_access'],
+ *   callback: (args) => args.items.reduce((sum, item) => sum + item.price, 0)
+ * };
+ * ```
+ */
+export interface DefinedFunction {
+    /**
+     * Unique name of the function
+     * @type {string}
+     */
+    name: string;
+    /**
+     * List of permission types required to run the function
+     * @type {AccessType[]}
+     */
+    permissionTypes: AccessType[];
+    /**
+     * The actual function implementation
+     * @type {(args: any) => any}
+     */
+    callback: (args: any) => any;
+}
+/**
+ * To define a function you need to create a `functions.[js|ts]` in each module of your app and return am array called `functions`, and then define all your functions with calling the `defineFunction` method.
+ *
+ * The `defineFunction` method serves as a core utility for creating custom functions dynamically. This method allows you to specify various parameters, including the name of the function, the permissions required for access, and the corresponding logic that should be executed when the function is invoked.
+ *
+ * @summary
+ * Define a server function to be called by clients.
+ *
+ * @param {DefinedFunction} options - The function definition options. See {@link DefinedFunction} for detailed parameter descriptions.
+ * @expandType DefinedFunction
+ *
+ * @returns {Object} The defined function object which system will use to generate a router for the function, generall the client library will use the router to call the function.
+ * @throws {Error} If function name already exists, permission types are missing, or callback is invalid
+ *
+ * @example
+ * Here is an example illustrating how to use the `defineFunction` method effectively:
+ * ```typescript
+ * // /modules/myModule/functions.ts
+ *
+ * import { defineFunction } from "@modular-rest/server";
+ *
+ * const getServerTime = defineFunction({
+ *   name: "getServerTime",
+ *   permissionTypes: ["anonymous_access"],
+ *   callback: (params) => {
+ *     // return your data only
+ *     return `
+ *       Welcome, ${params.username}!
+ *       The current server time is ${new Date().toLocaleString()}.
+ *     `;
+ *
+ *     // error handling,
+ *     // client gets error code 400, and the message
+ *     // throw new Error('An error occurred');
+ *   },
+ * });
+ *
+ * module.exports.functions = [getServerTime];
+ * ```
+ * In this example, we define a function named `getServerTime` that requires the `user` permission type to access. When the function is called, it will return a message containing the current server time and the username of the user who invoked the function.
+ *
+ * ---
+ *
+ * By utilizing the `defineFunction` method, developers are empowered to create custom functionality effortlessly within the Modular REST framework, enhancing both the versatility and security of their applications.
+ */
+export declare function defineFunction(options: DefinedFunction): DefinedFunction;
+/**
+ * Runs a function by name with arguments and user context
+ *
+ * @param {string} name - Name of the function to run
+ * @param {any} args - Arguments to pass to the function
+ * @param {User} user - User attempting to run the function
+ * @returns {Promise<any>} Promise resolving to function result
+ * @throws {Error} If function not found or user lacks required permissions
+ *
+ * @private
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await runFunction('calculateTotal', {
+ *     items: [
+ *       { price: 10 },
+ *       { price: 20 }
+ *     ]
+ *   }, currentUser);
+ *   console.log('Total:', result); // 30
+ * } catch (error) {
+ *   console.error('Function execution failed:', error);
+ * }
+ * ```
+ */
+export declare function runFunction(name: string, args: any, user: User): Promise<any>;
+/**
+ * Adds a function to the registry, this method is used for internal use only,
+ * it will add all defined functions to the registry.
+ *
+ * @param {DefinedFunction} func - Function to add
+ * @throws {Error} If function name already exists
+ *
+ * @private
+ *
+ * @example
+ * ```typescript
+ * const myFunction = defineFunction({
+ *   name: 'myFunction',
+ *   permissionTypes: ['user_access'],
+ *   callback: (args) => args.value * 2
+ * });
+ *
+ * addFunction(myFunction);
+ * ```
+ */
+export declare function addFunction(func: DefinedFunction): void;