@ciscode/database-kit 1.0.0

package/dist/services/database.service.js

@@ -0,0 +1,205 @@
+"use strict";
+// src/services/database.service.ts
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var DatabaseService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseService = void 0;
+const common_1 = require("@nestjs/common");
+const mongo_adapter_1 = require("../adapters/mongo.adapter");
+const postgres_adapter_1 = require("../adapters/postgres.adapter");
+/**
+ * Main database service that provides a unified interface
+ * for database operations across MongoDB and PostgreSQL.
+ *
+ * This service acts as a facade over the underlying adapters,
+ * providing a clean API for creating repositories and managing connections.
+ *
+ * @example
+ * ```typescript
+ * // In a NestJS service
+ * @Injectable()
+ * export class UserService {
+ *   private readonly usersRepo: Repository<User>;
+ *
+ *   constructor(@InjectDatabase() private readonly db: DatabaseService) {
+ *     this.usersRepo = db.createMongoRepository({ model: UserModel });
+ *   }
+ * }
+ * ```
+ */
+let DatabaseService = DatabaseService_1 = class DatabaseService {
+    constructor(config) {
+        this.logger = new common_1.Logger(DatabaseService_1.name);
+        this.config = config;
+        this.logger.log(`DatabaseService initialized with type: ${config.type}`);
+    }
+    /**
+     * Lifecycle hook called when the module is being destroyed.
+     * Gracefully closes all database connections.
+     */
+    async onModuleDestroy() {
+        this.logger.log('Cleaning up database connections...');
+        await this.disconnect();
+    }
+    /**
+     * Returns the current database type.
+     */
+    get type() {
+        return this.config.type;
+    }
+    /**
+     * Checks if the database is connected.
+     */
+    isConnected() {
+        var _a, _b, _c, _d;
+        switch (this.config.type) {
+            case 'mongo':
+                return (_b = (_a = this.mongoAdapter) === null || _a === void 0 ? void 0 : _a.isConnected()) !== null && _b !== void 0 ? _b : false;
+            case 'postgres':
+                return (_d = (_c = this.postgresAdapter) === null || _c === void 0 ? void 0 : _c.isConnected()) !== null && _d !== void 0 ? _d : false;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Initializes the underlying driver connection.
+     * Must be awaited before using repositories.
+     */
+    async connect() {
+        switch (this.config.type) {
+            case 'mongo': {
+                if (!this.mongoAdapter) {
+                    this.mongoAdapter = new mongo_adapter_1.MongoAdapter(this.config);
+                }
+                await this.mongoAdapter.connect();
+                this.logger.log('MongoDB connection established');
+                break;
+            }
+            case 'postgres': {
+                if (!this.postgresAdapter) {
+                    this.postgresAdapter = new postgres_adapter_1.PostgresAdapter(this.config);
+                }
+                this.postgresAdapter.connect();
+                this.logger.log('PostgreSQL connection pool established');
+                break;
+            }
+            default: {
+                // TypeScript exhaustiveness check - this should never happen
+                const exhaustiveCheck = this.config;
+                throw new Error(`Unsupported database type: ${exhaustiveCheck.type}`);
+            }
+        }
+    }
+    /**
+     * Gracefully disconnects from the database.
+     */
+    async disconnect() {
+        try {
+            if (this.mongoAdapter) {
+                await this.mongoAdapter.disconnect();
+                this.mongoAdapter = undefined;
+            }
+            if (this.postgresAdapter) {
+                await this.postgresAdapter.disconnect();
+                this.postgresAdapter = undefined;
+            }
+            this.logger.log('All database connections closed');
+        }
+        catch (error) {
+            this.logger.error('Error during database disconnect', error);
+            throw error;
+        }
+    }
+    /**
+     * Creates a MongoDB repository using a Mongoose model.
+     *
+     * @param options - Options containing the Mongoose model
+     * @returns Repository instance with CRUD methods
+     * @throws Error if database type is not 'mongo'
+     *
+     * @example
+     * ```typescript
+     * const usersRepo = db.createMongoRepository<User>({ model: UserModel });
+     * const user = await usersRepo.create({ name: 'John' });
+     * ```
+     */
+    createMongoRepository(options) {
+        if (this.config.type !== 'mongo') {
+            throw new Error(`Database type is "${this.config.type}". createMongoRepository can only be used when type === "mongo".`);
+        }
+        if (!this.mongoAdapter) {
+            this.mongoAdapter = new mongo_adapter_1.MongoAdapter(this.config);
+        }
+        return this.mongoAdapter.createRepository(options);
+    }
+    /**
+     * Creates a PostgreSQL repository using a table configuration.
+     *
+     * @param cfg - Configuration for the entity/table
+     * @returns Repository instance with CRUD methods
+     * @throws Error if database type is not 'postgres'
+     *
+     * @example
+     * ```typescript
+     * const ordersRepo = db.createPostgresRepository<Order>({
+     *   table: 'orders',
+     *   primaryKey: 'id',
+     *   columns: ['id', 'user_id', 'total', 'created_at'],
+     * });
+     * ```
+     */
+    createPostgresRepository(cfg) {
+        if (this.config.type !== 'postgres') {
+            throw new Error(`Database type is "${this.config.type}". createPostgresRepository can only be used when type === "postgres".`);
+        }
+        if (!this.postgresAdapter) {
+            this.postgresAdapter = new postgres_adapter_1.PostgresAdapter(this.config);
+            this.postgresAdapter.connect();
+        }
+        return this.postgresAdapter.createRepository(cfg);
+    }
+    /**
+     * Returns the underlying MongoDB adapter.
+     * Useful for advanced operations not covered by the repository interface.
+     *
+     * @throws Error if database type is not 'mongo'
+     */
+    getMongoAdapter() {
+        if (this.config.type !== 'mongo') {
+            throw new Error('getMongoAdapter() is only available for MongoDB connections');
+        }
+        if (!this.mongoAdapter) {
+            this.mongoAdapter = new mongo_adapter_1.MongoAdapter(this.config);
+        }
+        return this.mongoAdapter;
+    }
+    /**
+     * Returns the underlying PostgreSQL adapter.
+     * Useful for advanced operations not covered by the repository interface.
+     *
+     * @throws Error if database type is not 'postgres'
+     */
+    getPostgresAdapter() {
+        if (this.config.type !== 'postgres') {
+            throw new Error('getPostgresAdapter() is only available for PostgreSQL connections');
+        }
+        if (!this.postgresAdapter) {
+            this.postgresAdapter = new postgres_adapter_1.PostgresAdapter(this.config);
+        }
+        return this.postgresAdapter;
+    }
+};
+exports.DatabaseService = DatabaseService;
+exports.DatabaseService = DatabaseService = DatabaseService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], DatabaseService);
+//# sourceMappingURL=database.service.js.map

package/dist/services/database.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.service.js","sourceRoot":"","sources":["../../src/services/database.service.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,63 @@
+import { LogLevel } from '@nestjs/common';
+/**
+ * Centralized logging service for DatabaseKit.
+ * Provides structured logging with context support.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class MyService {
+ *   constructor(private readonly logger: LoggerService) {}
+ *
+ *   doSomething() {
+ *     this.logger.log('Operation started', 'MyService');
+ *   }
+ * }
+ * ```
+ */
+export declare class LoggerService {
+    private readonly logger;
+    /**
+     * Logs a message at the 'log' level.
+     *
+     * @param message - The message to log
+     * @param context - Optional context (usually the class/method name)
+     */
+    log(message: string, context?: string): void;
+    /**
+     * Logs a message at the 'error' level.
+     *
+     * @param message - The error message
+     * @param trace - Optional stack trace
+     * @param context - Optional context (usually the class/method name)
+     */
+    error(message: string, trace?: string, context?: string): void;
+    /**
+     * Logs a message at the 'warn' level.
+     *
+     * @param message - The warning message
+     * @param context - Optional context (usually the class/method name)
+     */
+    warn(message: string, context?: string): void;
+    /**
+     * Logs a message at the 'debug' level.
+     *
+     * @param message - The debug message
+     * @param context - Optional context (usually the class/method name)
+     */
+    debug(message: string, context?: string): void;
+    /**
+     * Logs a message at the 'verbose' level.
+     *
+     * @param message - The verbose message
+     * @param context - Optional context (usually the class/method name)
+     */
+    verbose(message: string, context?: string): void;
+    /**
+     * Sets the log levels to display.
+     *
+     * @param levels - Array of log levels to enable
+     */
+    setLogLevels(levels: LogLevel[]): void;
+}
+//# sourceMappingURL=logger.service.d.ts.map

package/dist/services/logger.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.service.d.ts","sourceRoot":"","sources":["../../src/services/logger.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,qBACa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAEpD;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI5C;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI9D;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI7C;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAI9C;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAIhD;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI;CAGzC"}

package/dist/services/logger.service.js

@@ -0,0 +1,93 @@
+"use strict";
+// src/services/logger.service.ts
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggerService = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Centralized logging service for DatabaseKit.
+ * Provides structured logging with context support.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class MyService {
+ *   constructor(private readonly logger: LoggerService) {}
+ *
+ *   doSomething() {
+ *     this.logger.log('Operation started', 'MyService');
+ *   }
+ * }
+ * ```
+ */
+let LoggerService = class LoggerService {
+    constructor() {
+        this.logger = new common_1.Logger('DatabaseKit');
+    }
+    /**
+     * Logs a message at the 'log' level.
+     *
+     * @param message - The message to log
+     * @param context - Optional context (usually the class/method name)
+     */
+    log(message, context) {
+        this.logger.log(message, context);
+    }
+    /**
+     * Logs a message at the 'error' level.
+     *
+     * @param message - The error message
+     * @param trace - Optional stack trace
+     * @param context - Optional context (usually the class/method name)
+     */
+    error(message, trace, context) {
+        this.logger.error(message, trace, context);
+    }
+    /**
+     * Logs a message at the 'warn' level.
+     *
+     * @param message - The warning message
+     * @param context - Optional context (usually the class/method name)
+     */
+    warn(message, context) {
+        this.logger.warn(message, context);
+    }
+    /**
+     * Logs a message at the 'debug' level.
+     *
+     * @param message - The debug message
+     * @param context - Optional context (usually the class/method name)
+     */
+    debug(message, context) {
+        var _a, _b;
+        (_b = (_a = this.logger).debug) === null || _b === void 0 ? void 0 : _b.call(_a, message, context);
+    }
+    /**
+     * Logs a message at the 'verbose' level.
+     *
+     * @param message - The verbose message
+     * @param context - Optional context (usually the class/method name)
+     */
+    verbose(message, context) {
+        var _a, _b;
+        (_b = (_a = this.logger).verbose) === null || _b === void 0 ? void 0 : _b.call(_a, message, context);
+    }
+    /**
+     * Sets the log levels to display.
+     *
+     * @param levels - Array of log levels to enable
+     */
+    setLogLevels(levels) {
+        common_1.Logger.overrideLogger(levels);
+    }
+};
+exports.LoggerService = LoggerService;
+exports.LoggerService = LoggerService = __decorate([
+    (0, common_1.Injectable)()
+], LoggerService);
+//# sourceMappingURL=logger.service.js.map

package/dist/services/logger.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.service.js","sourceRoot":"","sources":["../../src/services/logger.service.ts"],"names":[],"mappings":";AAAA,iCAAiC;;;;;;;;;AAEjC,2CAA8D;AAE9D;;;;;;;;;;;;;;;GAeG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAa;IAAnB;QACc,WAAM,GAAG,IAAI,eAAM,CAAC,aAAa,CAAC,CAAC;IA6DxD,CAAC;IA3DG;;;;;OAKG;IACH,GAAG,CAAC,OAAe,EAAE,OAAgB;QACjC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAe,EAAE,KAAc,EAAE,OAAgB;QACnD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe,EAAE,OAAgB;QAClC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,OAAgB;;QACnC,MAAA,MAAA,IAAI,CAAC,MAAM,EAAC,KAAK,mDAAG,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAe,EAAE,OAAgB;;QACrC,MAAA,MAAA,IAAI,CAAC,MAAM,EAAC,OAAO,mDAAG,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,MAAkB;QAC3B,eAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;CACJ,CAAA;AA9DY,sCAAa;wBAAb,aAAa;IADzB,IAAA,mBAAU,GAAE;GACA,aAAa,CA8DzB"}

package/dist/utils/pagination.utils.d.ts

@@ -0,0 +1,57 @@
+import { PageOptions, PageResult } from '../contracts/database.contracts';
+/**
+ * Utility functions for pagination operations.
+ */
+/**
+ * Normalizes pagination options with defaults and constraints.
+ *
+ * @param options - The input pagination options
+ * @returns Normalized options with validated values
+ */
+export declare function normalizePaginationOptions<T = Record<string, unknown>>(options?: PageOptions<T>): Required<PageOptions<T>>;
+/**
+ * Calculates pagination metadata from total count.
+ *
+ * @param total - Total number of items
+ * @param page - Current page number
+ * @param limit - Items per page
+ * @returns Pagination metadata
+ */
+export declare function calculatePagination(total: number, page: number, limit: number): {
+    pages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+};
+/**
+ * Creates a page result object.
+ *
+ * @param data - Array of items for the current page
+ * @param page - Current page number
+ * @param limit - Items per page
+ * @param total - Total number of items
+ * @returns Complete page result
+ */
+export declare function createPageResult<T>(data: T[], page: number, limit: number, total: number): PageResult<T>;
+/**
+ * Parses a sort string into an object.
+ * Supports formats like "-createdAt,name" or "+updatedAt,-title"
+ *
+ * @param sortString - Comma-separated sort fields with optional +/- prefix
+ * @returns Object with field names as keys and 'asc' | 'desc' as values
+ *
+ * @example
+ * ```typescript
+ * parseSortString('-createdAt,name');
+ * // Returns: { createdAt: 'desc', name: 'asc' }
+ * ```
+ */
+export declare function parseSortString(sortString: string): Record<string, 'asc' | 'desc'>;
+/**
+ * Calculates the offset for a given page and limit.
+ *
+ * @param page - Page number (1-indexed)
+ * @param limit - Items per page
+ * @returns Offset value for database query
+ */
+export declare function calculateOffset(page: number, limit: number): number;
+//# sourceMappingURL=pagination.utils.d.ts.map

package/dist/utils/pagination.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.utils.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,UAAU,EAA0B,MAAM,iCAAiC,CAAC;AAElG;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,OAAO,GAAE,WAAW,CAAC,CAAC,CAAM,GAC3B,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAmB1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAMvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,UAAU,CAAC,CAAC,CAAC,CAUf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,CAkBhC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/utils/pagination.utils.js

@@ -0,0 +1,113 @@
+"use strict";
+// src/utils/pagination.utils.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePaginationOptions = normalizePaginationOptions;
+exports.calculatePagination = calculatePagination;
+exports.createPageResult = createPageResult;
+exports.parseSortString = parseSortString;
+exports.calculateOffset = calculateOffset;
+const database_contracts_1 = require("../contracts/database.contracts");
+/**
+ * Utility functions for pagination operations.
+ */
+/**
+ * Normalizes pagination options with defaults and constraints.
+ *
+ * @param options - The input pagination options
+ * @returns Normalized options with validated values
+ */
+function normalizePaginationOptions(options = {}) {
+    var _a, _b, _c, _d;
+    const { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } = database_contracts_1.DATABASE_KIT_CONSTANTS;
+    let page = (_a = options.page) !== null && _a !== void 0 ? _a : 1;
+    let limit = (_b = options.limit) !== null && _b !== void 0 ? _b : DEFAULT_PAGE_SIZE;
+    // Ensure page is at least 1
+    if (page < 1)
+        page = 1;
+    // Ensure limit is within bounds
+    if (limit < 1)
+        limit = 1;
+    if (limit > MAX_PAGE_SIZE)
+        limit = MAX_PAGE_SIZE;
+    return {
+        filter: (_c = options.filter) !== null && _c !== void 0 ? _c : {},
+        page,
+        limit,
+        sort: (_d = options.sort) !== null && _d !== void 0 ? _d : {},
+    };
+}
+/**
+ * Calculates pagination metadata from total count.
+ *
+ * @param total - Total number of items
+ * @param page - Current page number
+ * @param limit - Items per page
+ * @returns Pagination metadata
+ */
+function calculatePagination(total, page, limit) {
+    const pages = Math.max(1, Math.ceil(total / limit));
+    const hasNext = page < pages;
+    const hasPrev = page > 1;
+    return { pages, hasNext, hasPrev };
+}
+/**
+ * Creates a page result object.
+ *
+ * @param data - Array of items for the current page
+ * @param page - Current page number
+ * @param limit - Items per page
+ * @param total - Total number of items
+ * @returns Complete page result
+ */
+function createPageResult(data, page, limit, total) {
+    const pages = Math.max(1, Math.ceil(total / limit));
+    return {
+        data,
+        page,
+        limit,
+        total,
+        pages,
+    };
+}
+/**
+ * Parses a sort string into an object.
+ * Supports formats like "-createdAt,name" or "+updatedAt,-title"
+ *
+ * @param sortString - Comma-separated sort fields with optional +/- prefix
+ * @returns Object with field names as keys and 'asc' | 'desc' as values
+ *
+ * @example
+ * ```typescript
+ * parseSortString('-createdAt,name');
+ * // Returns: { createdAt: 'desc', name: 'asc' }
+ * ```
+ */
+function parseSortString(sortString) {
+    const result = {};
+    if (!sortString)
+        return result;
+    const fields = sortString.split(',').map((f) => f.trim()).filter(Boolean);
+    for (const field of fields) {
+        if (field.startsWith('-')) {
+            result[field.slice(1)] = 'desc';
+        }
+        else if (field.startsWith('+')) {
+            result[field.slice(1)] = 'asc';
+        }
+        else {
+            result[field] = 'asc';
+        }
+    }
+    return result;
+}
+/**
+ * Calculates the offset for a given page and limit.
+ *
+ * @param page - Page number (1-indexed)
+ * @param limit - Items per page
+ * @returns Offset value for database query
+ */
+function calculateOffset(page, limit) {
+    return Math.max(0, (page - 1) * limit);
+}
+//# sourceMappingURL=pagination.utils.js.map

package/dist/utils/pagination.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.utils.js","sourceRoot":"","sources":["../../src/utils/pagination.utils.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation.utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Utility functions for validation operations.
+ */
+/**
+ * Validates that a value is a valid MongoDB ObjectId string.
+ *
+ * @param id - The string to validate
+ * @returns True if valid ObjectId format
+ */
+export declare function isValidMongoId(id: string): boolean;
+/**
+ * Validates that a value is a valid UUID (v4).
+ *
+ * @param id - The string to validate
+ * @returns True if valid UUID format
+ */
+export declare function isValidUuid(id: string): boolean;
+/**
+ * Validates that a value is a positive integer.
+ *
+ * @param value - The value to validate
+ * @returns True if positive integer
+ */
+export declare function isPositiveInteger(value: unknown): boolean;
+/**
+ * Sanitizes a filter object by removing undefined and null values.
+ *
+ * @param filter - The filter object to sanitize
+ * @returns Sanitized filter object
+ */
+export declare function sanitizeFilter<T extends Record<string, unknown>>(filter: T): Partial<T>;
+/**
+ * Validates that all required fields are present in an object.
+ *
+ * @param obj - The object to validate
+ * @param requiredFields - Array of required field names
+ * @returns Object with isValid boolean and missing fields array
+ */
+export declare function validateRequiredFields(obj: Record<string, unknown>, requiredFields: string[]): {
+    isValid: boolean;
+    missing: string[];
+};
+/**
+ * Extracts only allowed fields from an object.
+ * Useful for preventing mass assignment vulnerabilities.
+ *
+ * @param obj - The source object
+ * @param allowedFields - Array of allowed field names
+ * @returns New object with only allowed fields
+ */
+export declare function pickFields<T extends Record<string, unknown>>(obj: T, allowedFields: string[]): Partial<T>;
+/**
+ * Omits specified fields from an object.
+ *
+ * @param obj - The source object
+ * @param fieldsToOmit - Array of field names to omit
+ * @returns New object without the omitted fields
+ */
+export declare function omitFields<T extends Record<string, unknown>>(obj: T, fieldsToOmit: string[]): Partial<T>;
+//# sourceMappingURL=validation.utils.d.ts.map

package/dist/utils/validation.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.utils.d.ts","sourceRoot":"","sources":["../../src/utils/validation.utils.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASzD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,MAAM,EAAE,CAAC,GACR,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,cAAc,EAAE,MAAM,EAAE,GACvB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAazC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,GAAG,EAAE,CAAC,EACN,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,GAAG,EAAE,CAAC,EACN,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,CAAC,CAAC,CAQZ"}