@modular-rest/server 1.11.13 → 1.12.0

package/dist/middlewares.js

@@ -0,0 +1,106 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auth = auth;
+const validator_1 = require("./class/validator");
+const userManager = __importStar(require("./services/user_manager/service"));
+/**
+ * Authentication middleware that secures routes by validating user tokens and managing access control.
+ *
+ * This middleware performs several key functions:
+ * 1. Validates that the incoming request contains an authorization token in the header
+ * 2. Verifies the token is valid by checking against the user management service
+ * 3. Retrieves the associated user object if the token is valid
+ * 4. Attaches the authenticated {@link User} object on ctx.state.user for use in subsequent middleware/routes
+ * 5. Throws appropriate HTTP errors (401, 412) if authentication fails
+ *
+ * The middleware integrates with the permission system to enable role-based access control.
+ * The attached user object provides methods like hasPermission() to check specific permissions.
+ *
+ * Common usage patterns:
+ * - Protecting sensitive API endpoints
+ * - Implementing role-based access control
+ * - Getting the current authenticated user
+ * - Validating user permissions before allowing actions
+ *
+ * @throws {Error} 401 - If no authorization header is present
+ * @throws {Error} 412 - If token validation fails
+ * @param ctx - Koa Context object containing request/response data
+ * @param next - Function to invoke next middleware
+ *
+ * @example
+ * ```typescript
+ * // Inside the router.ts file
+ * import { auth } from '@modular-rest/server';
+ * import { Router } from 'koa-router';
+ *
+ * const name = 'flowers';
+ *
+ * const flowerRouter = new Router();
+ *
+ * flowerRouter.get('/list', auth, (ctx) => {
+ *  // Get the authenticated user
+ *  const user = ctx.state.user;
+ *
+ *  // Then you can check the user's role and permission
+ *  if(user.hasPermission('get_flower')) {
+ *    ctx.body = 'This is a list of flowers: Rose, Lily, Tulip';
+ *  } else {
+ *    ctx.status = 403;
+ *    ctx.body = 'You are not authorized to access this resource';
+ *  }
+ * });
+ *
+ * module.exports.name = name;
+ * module.exports.main = flowerRouter;
+ * ```
+ */
+async function auth(ctx, next) {
+    const headers = ctx.header;
+    const headersValidated = (0, validator_1.validator)(headers, 'authorization');
+    if (!headersValidated.isValid)
+        ctx.throw(401, 'authentication is required');
+    const token = headers.authorization;
+    await userManager.main
+        .getUserByToken(token)
+        .then(async (user) => {
+        ctx.state.user = user;
+        await next();
+    })
+        .catch(err => {
+        console.log(err);
+        ctx.throw(err.status || 412, err.message);
+    });
+}

package/dist/play-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/play-test.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const application_1 = require("./application");
+const app = (0, application_1.createRest)({
+    adminUser: {
+        email: 'admin@example.com',
+        password: 'password',
+    },
+});

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

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

package/dist/services/data_provider/router.js

@@ -0,0 +1,187 @@
+"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 security_1 = require("../../class/security");
+const koa_router_1 = __importDefault(require("koa-router"));
+const validator_1 = require("../../class/validator");
+const reply_1 = require("../../class/reply");
+const nested_property_1 = __importDefault(require("nested-property"));
+const service = __importStar(require("./service"));
+const middleware = __importStar(require("../../middlewares"));
+const name = 'data-provider';
+exports.name = name;
+const dataProvider = new koa_router_1.default();
+exports.main = dataProvider;
+dataProvider.use('/', middleware.auth, async (ctx, next) => {
+    const body = ctx.request.body;
+    const bodyValidated = (0, validator_1.validateObject)(body, 'database collection');
+    // fields validation
+    if (!bodyValidated.isValid) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: bodyValidated.requires })));
+    }
+    // type caster
+    if (body.types && body.hasOwnProperty(body.bodyKey || '.')) {
+        const bodyKey = body.bodyKey;
+        for (const key in body.types) {
+            if (body.types.hasOwnProperty(key) && typeof body.types[key] == 'object') {
+                const typeDetail = body.types[key];
+                try {
+                    const value = nested_property_1.default.get(body[bodyKey], typeDetail.path);
+                    const newProperty = service.TypeCasters[typeDetail.type](value);
+                    nested_property_1.default.set(body[bodyKey], typeDetail.path, newProperty);
+                    console.log('newProperty', newProperty, JSON.stringify(body[bodyKey]));
+                }
+                catch (e) {
+                    console.log('type caster error', e);
+                }
+            }
+        }
+    }
+    await next();
+});
+dataProvider.post('/find', async (ctx) => {
+    const body = ctx.request.body;
+    const bodyValidate = (0, validator_1.validateObject)(body, 'database collection query');
+    // fields validation
+    if (!bodyValidate.isValid) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: bodyValidate.requires })));
+    }
+    // access validation
+    const hasAccess = service.checkAccess(body.database, body.collection, security_1.AccessTypes.read, body.query, ctx.state.user);
+    if (!hasAccess) {
+        console.log(body);
+        console.log(ctx.state.user.permission);
+        ctx.throw(403, 'access denied');
+    }
+    // collection validation
+    const collection = service.getCollection(body.database, body.collection);
+    if (collection == null) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: 'wrong database or collection' })));
+    }
+    // operate on db
+    let queryRequest = collection.find(body.query, body.projection);
+    if (body.options) {
+        queryRequest = service.performAdditionalOptionsToQueryObject(queryRequest, body.options);
+    }
+    if (body.populates) {
+        try {
+            queryRequest = service.performPopulateToQueryObject(queryRequest, body.populates);
+        }
+        catch (err) {
+            ctx.status = 412;
+            ctx.body = err;
+        }
+    }
+    await queryRequest
+        .exec()
+        .then(async (docs) => {
+        ctx.body = { data: docs };
+    })
+        .catch(err => {
+        ctx.status = err.status || 500;
+        ctx.body = err.message;
+    });
+});
+dataProvider.post('/find-one', async (ctx) => {
+    const body = ctx.request.body;
+    const bodyValidate = (0, validator_1.validateObject)(body, 'database collection query');
+    // fields validation
+    if (!bodyValidate.isValid) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: bodyValidate.requires })));
+    }
+    // access validation
+    const hasAccess = service.checkAccess(body.database, body.collection, security_1.AccessTypes.read, body.query, ctx.state.user);
+    if (!hasAccess)
+        ctx.throw(403, 'access denied');
+    // collection validation
+    const collection = service.getCollection(body.database, body.collection);
+    if (collection == null) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: 'wrong database or collection' })));
+    }
+    // operate on db
+    let queryRequest = collection.findOne(body.query, body.projection, body.options);
+    if (body.options) {
+        queryRequest = service.performAdditionalOptionsToQueryObject(queryRequest, body.options);
+    }
+    if (body.populates) {
+        try {
+            queryRequest = service.performPopulateToQueryObject(queryRequest, body.populates);
+        }
+        catch (err) {
+            ctx.status = 412;
+            ctx.body = err;
+        }
+    }
+    // operate on db
+    await queryRequest
+        .exec()
+        .then(async (doc) => {
+        ctx.body = { data: doc };
+    })
+        .catch(err => {
+        ctx.status = err.status || 500;
+        ctx.body = err.message;
+    });
+});
+dataProvider.post('/count', async (ctx) => {
+    const body = ctx.request.body;
+    const bodyValidate = (0, validator_1.validateObject)(body, 'database collection query');
+    // fields validation
+    if (!bodyValidate.isValid) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: bodyValidate.requires })));
+    }
+    // access validation
+    const hasAccess = service.checkAccess(body.database, body.collection, security_1.AccessTypes.read, body.query, ctx.state.user);
+    if (!hasAccess)
+        ctx.throw(403, 'access denied');
+    // collection validation
+    const collection = service.getCollection(body.database, body.collection);
+    if (collection == null) {
+        ctx.throw(412, JSON.stringify((0, reply_1.create)('e', { error: 'wrong database or collection' })));
+    }
+    await collection
+        .countDocuments(body.query)
+        .then(count => {
+        ctx.body = { data: count };
+    })
+        .catch(err => {
+        ctx.status = err.status || 500;
+        ctx.body = err.message;
+    });
+});

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

@@ -0,0 +1,131 @@
+import mongoose, { Model, PopulateOptions, Query } from 'mongoose';
+import TypeCasters from './typeCasters';
+import { CollectionDefinition } from '../../class/collection_definition';
+import { User } from '../../class/user';
+/**
+ * Service name constant
+ * @constant {string}
+ */
+export declare const name = "dataProvider";
+/**
+ * MongoDB connection options
+ * @interface MongoOption
+ * @property {string} [dbPrefix] - Prefix for database names
+ * @property {string} mongoBaseAddress - MongoDB connection URL
+ */
+export interface MongoOption {
+    dbPrefix?: string;
+    mongoBaseAddress: string;
+}
+/**
+ * Collection definition options
+ * @interface CollectionDefinitionOption
+ * @property {CollectionDefinition[]} list - List of collection definitions
+ * @property {MongoOption} mongoOption - MongoDB connection options
+ */
+interface CollectionDefinitionListOption {
+    list: CollectionDefinition[];
+    mongoOption: MongoOption;
+}
+/**
+ * Adds collection definitions and connects to their respective databases
+ * @function addCollectionDefinitionByList
+ * @param {CollectionDefinitionListOption} options - Collection definition options
+ * @returns {Promise<void>} A promise that resolves when all collections are set up
+ * @example
+ * ```typescript
+ * await addCollectionDefinitionByList({
+ *   list: [
+ *     new CollectionDefinition({
+ *       database: 'myapp',
+ *       collection: 'users',
+ *       schema: userSchema,
+ *       permissions: [new Permission({ type: 'user_access', read: true })]
+ *     })
+ *   ],
+ *   mongoOption: {
+ *     mongoBaseAddress: 'mongodb://localhost:27017',
+ *     dbPrefix: 'myapp_'
+ *   }
+ * });
+ * ```
+ */
+export declare function addCollectionDefinitionByList({ list, mongoOption, }: CollectionDefinitionListOption): Promise<void>;
+/**
+ * Gets a Mongoose model for a specific collection
+ * @function getCollection
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @returns {Model<T>} Mongoose model for the collection
+ * @throws {Error} If the collection doesn't exist
+ * @example
+ * ```typescript
+ * const userModel = getCollection('myapp', 'users');
+ * const users = await userModel.find();
+ * ```
+ */
+export declare function getCollection<T>(db: string, collection: string): Model<T>;
+/**
+ * Checks if a user has access to perform an operation on a collection
+ * @function checkAccess
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @param {string} operationType - Type of operation (read/write)
+ * @param {Record<string, any>} queryOrDoc - Query or document being accessed
+ * @param {User} user - User performing the operation
+ * @returns {boolean} Whether the user has access
+ * @example
+ * ```typescript
+ * const hasAccess = checkAccess('myapp', 'users', 'read', {}, currentUser);
+ * if (hasAccess) {
+ *   const users = await getCollection('myapp', 'users').find();
+ * }
+ * ```
+ */
+export declare function checkAccess(db: string, collection: string, operationType: string, queryOrDoc: Record<string, any>, user: User): boolean;
+/**
+ * Converts a string ID to a MongoDB ObjectId
+ * @function getAsID
+ * @param {string} strId - String ID to convert
+ * @returns {mongoose.Types.ObjectId | undefined} MongoDB ObjectId or undefined if invalid
+ * @example
+ * ```typescript
+ * const id = getAsID('507f1f77bcf86cd799439011');
+ * if (id) {
+ *   const doc = await collection.findById(id);
+ * }
+ * ```
+ */
+export declare function getAsID(strId: string): mongoose.Types.ObjectId | undefined;
+/**
+ * Applies populate options to a Mongoose query
+ * @function performPopulateToQueryObject
+ * @param {Query<T, any>} queryObj - Mongoose query object
+ * @param {PopulateOptions[]} [popArr=[]] - Array of populate options
+ * @returns {Query<T, any>} Query with populate options applied
+ * @example
+ * ```typescript
+ * const query = collection.find();
+ * const populatedQuery = performPopulateToQueryObject(query, [
+ *   { path: 'author', select: 'name email' }
+ * ]);
+ * ```
+ */
+export declare function performPopulateToQueryObject<T = any>(queryObj: Query<T, any>, popArr?: PopulateOptions[]): Query<T, any>;
+/**
+ * Applies additional options to a Mongoose query
+ * @function performAdditionalOptionsToQueryObject
+ * @param {Query<T, any>} queryObj - Mongoose query object
+ * @param {Record<string, any>} options - Additional query options
+ * @returns {Query<T, any>} Query with additional options applied
+ * @example
+ * ```typescript
+ * const query = collection.find();
+ * const queryWithOptions = performAdditionalOptionsToQueryObject(query, {
+ *   sort: { createdAt: -1 },
+ *   limit: 10
+ * });
+ * ```
+ */
+export declare function performAdditionalOptionsToQueryObject<T = any>(queryObj: Query<T, any>, options: Record<string, any>): Query<T, any>;
+export { TypeCasters };

package/dist/services/data_provider/service.js

@@ -0,0 +1,252 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeCasters = exports.name = void 0;
+exports.addCollectionDefinitionByList = addCollectionDefinitionByList;
+exports.getCollection = getCollection;
+exports.checkAccess = checkAccess;
+exports.getAsID = getAsID;
+exports.performPopulateToQueryObject = performPopulateToQueryObject;
+exports.performAdditionalOptionsToQueryObject = performAdditionalOptionsToQueryObject;
+const mongoose_1 = __importDefault(require("mongoose"));
+const security_1 = require("../../class/security");
+const trigger_operator_1 = __importDefault(require("../../class/trigger_operator"));
+const typeCasters_1 = __importDefault(require("./typeCasters"));
+exports.TypeCasters = typeCasters_1.default;
+/**
+ * Service name constant
+ * @constant {string}
+ */
+exports.name = 'dataProvider';
+// Set mongoose options
+mongoose_1.default.set('useCreateIndex', true);
+// Database connections and collections storage
+const connections = {};
+const collections = {};
+const permissionDefinitions = {};
+/**
+ * Connects to a database and sets up collections based on collection definitions
+ * @function connectToDatabaseByCollectionDefinitionList
+ * @param {string} dbName - Name of the database to connect to
+ * @param {CollectionDefinition[]} [collectionDefinitionList=[]] - List of collection definitions
+ * @param {MongoOption} mongoOption - MongoDB connection options
+ * @returns {Promise<void>} A promise that resolves when the connection is established
+ * @throws {Error} If triggers are not properly configured
+ * @private
+ */
+function connectToDatabaseByCollectionDefinitionList(dbName, collectionDefinitionList = [], mongoOption) {
+    return new Promise((done, reject) => {
+        // Create db connection
+        const fullDbName = (mongoOption.dbPrefix || '') + dbName;
+        const connectionString = mongoOption.mongoBaseAddress;
+        console.info(`- Connecting to database: ${fullDbName}`);
+        const connection = mongoose_1.default.createConnection(connectionString, {
+            useUnifiedTopology: true,
+            useNewUrlParser: true,
+            dbName: fullDbName,
+        });
+        // Store connection
+        connections[dbName] = connection;
+        // add db models from schemas
+        collectionDefinitionList.forEach(collectionDefinition => {
+            const collection = collectionDefinition.collection;
+            const schema = collectionDefinition.schema;
+            if (collections[dbName] == undefined)
+                collections[dbName] = {};
+            if (permissionDefinitions[dbName] == undefined)
+                permissionDefinitions[dbName] = {};
+            // create model from schema
+            // and store in on global collection object
+            const model = connection.model(collection, schema);
+            collections[dbName][collection] = model;
+            // define Access Definition from component permissions
+            // and store it on global access definition object
+            permissionDefinitions[dbName][collection] = new security_1.AccessDefinition({
+                database: dbName,
+                collection: collection,
+                permissionList: collectionDefinition.permissions,
+            });
+            // add trigger
+            if (collectionDefinition.triggers != undefined) {
+                if (!Array.isArray(collectionDefinition.triggers)) {
+                    throw new Error('Triggers must be an array');
+                }
+                collectionDefinition.triggers.forEach(trigger => {
+                    trigger_operator_1.default.addTrigger({
+                        ...trigger,
+                        database: collectionDefinition.database,
+                        collection: collectionDefinition.collection,
+                    });
+                });
+            }
+        });
+        connection.on('connected', () => {
+            console.info(`- ${fullDbName} database has been connected`);
+            done();
+        });
+    });
+}
+/**
+ * Adds collection definitions and connects to their respective databases
+ * @function addCollectionDefinitionByList
+ * @param {CollectionDefinitionListOption} options - Collection definition options
+ * @returns {Promise<void>} A promise that resolves when all collections are set up
+ * @example
+ * ```typescript
+ * await addCollectionDefinitionByList({
+ *   list: [
+ *     new CollectionDefinition({
+ *       database: 'myapp',
+ *       collection: 'users',
+ *       schema: userSchema,
+ *       permissions: [new Permission({ type: 'user_access', read: true })]
+ *     })
+ *   ],
+ *   mongoOption: {
+ *     mongoBaseAddress: 'mongodb://localhost:27017',
+ *     dbPrefix: 'myapp_'
+ *   }
+ * });
+ * ```
+ */
+async function addCollectionDefinitionByList({ list, mongoOption, }) {
+    // Group collection definitions by database
+    const dbGroups = {};
+    list.forEach(collectionDefinition => {
+        if (!dbGroups[collectionDefinition.database]) {
+            dbGroups[collectionDefinition.database] = [];
+        }
+        dbGroups[collectionDefinition.database].push(collectionDefinition);
+    });
+    // Connect to each database
+    const connectionPromises = Object.entries(dbGroups).map(([dbName, collectionDefinitionList]) => connectToDatabaseByCollectionDefinitionList(dbName, collectionDefinitionList, mongoOption));
+    await Promise.all(connectionPromises);
+}
+/**
+ * Gets a Mongoose model for a specific collection
+ * @function getCollection
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @returns {Model<T>} Mongoose model for the collection
+ * @throws {Error} If the collection doesn't exist
+ * @example
+ * ```typescript
+ * const userModel = getCollection('myapp', 'users');
+ * const users = await userModel.find();
+ * ```
+ */
+function getCollection(db, collection) {
+    if (!collections[db] || !collections[db][collection]) {
+        throw new Error(`Collection ${collection} not found in database ${db}`);
+    }
+    return collections[db][collection];
+}
+/**
+ * Gets the permission list for a specific operation on a collection
+ * @function _getPermissionList
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @param {string} operationType - Type of operation (read/write)
+ * @returns {any[]} List of permissions
+ * @private
+ */
+function _getPermissionList(db, collection, operationType) {
+    if (!permissionDefinitions[db] || !permissionDefinitions[db][collection]) {
+        return [];
+    }
+    return permissionDefinitions[db][collection].permissionList;
+}
+/**
+ * Checks if a user has access to perform an operation on a collection
+ * @function checkAccess
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @param {string} operationType - Type of operation (read/write)
+ * @param {Record<string, any>} queryOrDoc - Query or document being accessed
+ * @param {User} user - User performing the operation
+ * @returns {boolean} Whether the user has access
+ * @example
+ * ```typescript
+ * const hasAccess = checkAccess('myapp', 'users', 'read', {}, currentUser);
+ * if (hasAccess) {
+ *   const users = await getCollection('myapp', 'users').find();
+ * }
+ * ```
+ */
+function checkAccess(db, collection, operationType, queryOrDoc, user) {
+    const permissionList = _getPermissionList(db, collection, operationType);
+    return permissionList.some(permission => {
+        if (permission.type === 'god_access')
+            return true;
+        if (permission.type === 'anonymous_access' && user.type === 'anonymous')
+            return true;
+        if (permission.type === 'user_access' && user.type === 'user')
+            return true;
+        return false;
+    });
+}
+/**
+ * Converts a string ID to a MongoDB ObjectId
+ * @function getAsID
+ * @param {string} strId - String ID to convert
+ * @returns {mongoose.Types.ObjectId | undefined} MongoDB ObjectId or undefined if invalid
+ * @example
+ * ```typescript
+ * const id = getAsID('507f1f77bcf86cd799439011');
+ * if (id) {
+ *   const doc = await collection.findById(id);
+ * }
+ * ```
+ */
+function getAsID(strId) {
+    try {
+        return mongoose_1.default.Types.ObjectId(strId);
+    }
+    catch (e) {
+        return undefined;
+    }
+}
+/**
+ * Applies populate options to a Mongoose query
+ * @function performPopulateToQueryObject
+ * @param {Query<T, any>} queryObj - Mongoose query object
+ * @param {PopulateOptions[]} [popArr=[]] - Array of populate options
+ * @returns {Query<T, any>} Query with populate options applied
+ * @example
+ * ```typescript
+ * const query = collection.find();
+ * const populatedQuery = performPopulateToQueryObject(query, [
+ *   { path: 'author', select: 'name email' }
+ * ]);
+ * ```
+ */
+function performPopulateToQueryObject(queryObj, popArr = []) {
+    popArr.forEach(pop => {
+        queryObj.populate(pop);
+    });
+    return queryObj;
+}
+/**
+ * Applies additional options to a Mongoose query
+ * @function performAdditionalOptionsToQueryObject
+ * @param {Query<T, any>} queryObj - Mongoose query object
+ * @param {Record<string, any>} options - Additional query options
+ * @returns {Query<T, any>} Query with additional options applied
+ * @example
+ * ```typescript
+ * const query = collection.find();
+ * const queryWithOptions = performAdditionalOptionsToQueryObject(query, {
+ *   sort: { createdAt: -1 },
+ *   limit: 10
+ * });
+ * ```
+ */
+function performAdditionalOptionsToQueryObject(queryObj, options) {
+    Object.entries(options).forEach(([key, value]) => {
+        // @ts-ignore
+        queryObj[key](value);
+    });
+    return queryObj;
+}