@classytic/mongokit 1.0.1 → 2.0.0

package/src/pagination/utils/limits.js

@@ -0,0 +1,82 @@
+/**
+ * @typedef {Object} PaginationConfig
+ * @property {number} defaultLimit - Default limit value
+ * @property {number} maxLimit - Maximum allowed limit
+ * @property {number} maxPage - Maximum allowed page number
+ */
+
+/**
+ * Validates and sanitizes limit value
+ * Parses strings to numbers and prevents NaN bugs
+ *
+ * @param {number|string} limit - Requested limit
+ * @param {PaginationConfig} config - Pagination configuration
+ * @returns {number} Sanitized limit between 1 and maxLimit
+ */
+export function validateLimit(limit, config) {
+  const parsed = Number(limit);
+
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    return config.defaultLimit || 10;
+  }
+
+  return Math.min(Math.floor(parsed), config.maxLimit);
+}
+
+/**
+ * Validates and sanitizes page number
+ * Parses strings to numbers and prevents NaN bugs
+ *
+ * @param {number|string} page - Requested page (1-indexed)
+ * @param {PaginationConfig} config - Pagination configuration
+ * @returns {number} Sanitized page number >= 1
+ * @throws {Error} If page exceeds maxPage
+ */
+export function validatePage(page, config) {
+  const parsed = Number(page);
+
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    return 1;
+  }
+
+  const sanitized = Math.floor(parsed);
+
+  if (sanitized > config.maxPage) {
+    throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage}`);
+  }
+
+  return sanitized;
+}
+
+/**
+ * Checks if page number should trigger deep pagination warning
+ *
+ * @param {number} page - Current page number
+ * @param {number} threshold - Warning threshold
+ * @returns {boolean} True if warning should be shown
+ */
+export function shouldWarnDeepPagination(page, threshold) {
+  return page > threshold;
+}
+
+/**
+ * Calculates number of documents to skip for offset pagination
+ *
+ * @param {number} page - Page number (1-indexed)
+ * @param {number} limit - Documents per page
+ * @returns {number} Number of documents to skip
+ */
+export function calculateSkip(page, limit) {
+  return (page - 1) * limit;
+}
+
+/**
+ * Calculates total number of pages
+ *
+ * @param {number} total - Total document count
+ * @param {number} limit - Documents per page
+ * @returns {number} Total number of pages
+ */
+export function calculateTotalPages(total, limit) {
+  return Math.ceil(total / limit);
+}

package/src/pagination/utils/sort.js

@@ -0,0 +1,101 @@
+/**
+ * Normalizes sort object to ensure stable key order
+ * Primary fields first, _id last (not alphabetical)
+ *
+ * @param {Record<string, 1|-1>} sort - Sort specification
+ * @returns {Record<string, 1|-1>} Normalized sort with stable key order
+ */
+export function normalizeSort(sort) {
+  /** @type {Record<string, 1|-1>} */
+  const normalized = {};
+
+  Object.keys(sort).forEach(key => {
+    if (key !== '_id') normalized[key] = sort[key];
+  });
+
+  if (sort._id !== undefined) {
+    normalized._id = sort._id;
+  }
+
+  return normalized;
+}
+
+/**
+ * Validates and normalizes sort for keyset pagination
+ * Auto-adds _id tie-breaker if needed
+ * Ensures _id direction matches primary field
+ *
+ * @param {Record<string, 1|-1>} sort - Sort specification
+ * @returns {Record<string, 1|-1>} Validated and normalized sort
+ * @throws {Error} If sort is invalid for keyset pagination
+ */
+export function validateKeysetSort(sort) {
+  const keys = Object.keys(sort);
+
+  if (keys.length === 1 && keys[0] !== '_id') {
+    const field = keys[0];
+    const direction = sort[field];
+    return normalizeSort({ [field]: direction, _id: direction });
+  }
+
+  if (keys.length === 1 && keys[0] === '_id') {
+    return normalizeSort(sort);
+  }
+
+  if (keys.length === 2) {
+    if (!keys.includes('_id')) {
+      throw new Error('Keyset pagination requires _id as tie-breaker');
+    }
+
+    const primaryField = keys.find(k => k !== '_id');
+    const primaryDirection = sort[primaryField];
+    const idDirection = sort._id;
+
+    if (primaryDirection !== idDirection) {
+      throw new Error('_id direction must match primary field direction');
+    }
+
+    return normalizeSort(sort);
+  }
+
+  throw new Error('Keyset pagination only supports single field + _id');
+}
+
+/**
+ * Inverts sort directions (1 becomes -1, -1 becomes 1)
+ *
+ * @param {Record<string, 1|-1>} sort - Sort specification
+ * @returns {Record<string, 1|-1>} Inverted sort
+ */
+export function invertSort(sort) {
+  /** @type {Record<string, 1|-1>} */
+  const inverted = {};
+
+  Object.keys(sort).forEach(key => {
+    inverted[key] = sort[key] === 1 ? -1 : 1;
+  });
+
+  return inverted;
+}
+
+/**
+ * Extracts primary sort field (first non-_id field)
+ *
+ * @param {Record<string, 1|-1>} sort - Sort specification
+ * @returns {string} Primary field name
+ */
+export function getPrimaryField(sort) {
+  const keys = Object.keys(sort);
+  return keys.find(k => k !== '_id') || '_id';
+}
+
+/**
+ * Gets sort direction for a specific field
+ *
+ * @param {Record<string, 1|-1>} sort - Sort specification
+ * @param {string} field - Field name
+ * @returns {1|-1|undefined} Sort direction
+ */
+export function getDirection(sort, field) {
+  return sort[field];
+}

package/src/plugins/aggregate-helpers.plugin.js

@@ -1,71 +1,71 @@
-/**
- * Aggregate Helpers Plugin
- * Adds common aggregation helper methods
- */
-
-export const aggregateHelpersPlugin = () => ({
-  name: 'aggregate-helpers',
-
-  apply(repo) {
-    if (!repo.registerMethod) {
-      throw new Error('aggregateHelpersPlugin requires methodRegistryPlugin');
-    }
-
-    /**
-     * Group by field
-     */
-    repo.registerMethod('groupBy', async function (field, options = {}) {
-      const pipeline = [
-        { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-        { $sort: { count: -1 } }
-      ];
-
-      if (options.limit) {
-        pipeline.push({ $limit: options.limit });
-      }
-
-      return this.aggregate(pipeline, options);
-    });
-
-    // Helper: Generic aggregation operation
-    const aggregateOperation = async function (field, operator, resultKey, query = {}, options = {}) {
-      const pipeline = [
-        { $match: query },
-        { $group: { _id: null, [resultKey]: { [operator]: `$${field}` } } }
-      ];
-
-      const result = await this.aggregate(pipeline, options);
-      return result[0]?.[resultKey] || 0;
-    };
-
-    /**
-     * Sum field values
-     */
-    repo.registerMethod('sum', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$sum', 'total', query, options);
-    });
-
-    /**
-     * Average field values
-     */
-    repo.registerMethod('average', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$avg', 'avg', query, options);
-    });
-
-    /**
-     * Get minimum value
-     */
-    repo.registerMethod('min', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$min', 'min', query, options);
-    });
-
-    /**
-     * Get maximum value
-     */
-    repo.registerMethod('max', async function (field, query = {}, options = {}) {
-      return aggregateOperation.call(this, field, '$max', 'max', query, options);
-    });
-  }
-});
-
-export default aggregateHelpersPlugin;
+/**
+ * Aggregate Helpers Plugin
+ * Adds common aggregation helper methods
+ */
+
+export const aggregateHelpersPlugin = () => ({
+  name: 'aggregate-helpers',
+
+  apply(repo) {
+    if (!repo.registerMethod) {
+      throw new Error('aggregateHelpersPlugin requires methodRegistryPlugin');
+    }
+
+    /**
+     * Group by field
+     */
+    repo.registerMethod('groupBy', async function (field, options = {}) {
+      const pipeline = [
+        { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+        { $sort: { count: -1 } }
+      ];
+
+      if (options.limit) {
+        pipeline.push(/** @type {any} */({ $limit: options.limit }));
+      }
+
+      return this.aggregate(pipeline, options);
+    });
+
+    // Helper: Generic aggregation operation
+    const aggregateOperation = async function (field, operator, resultKey, query = {}, options = {}) {
+      const pipeline = [
+        { $match: query },
+        { $group: { _id: null, [resultKey]: { [operator]: `$${field}` } } }
+      ];
+
+      const result = await this.aggregate(pipeline, options);
+      return result[0]?.[resultKey] || 0;
+    };
+
+    /**
+     * Sum field values
+     */
+    repo.registerMethod('sum', async function (field, query = {}, options = {}) {
+      return aggregateOperation.call(this, field, '$sum', 'total', query, options);
+    });
+
+    /**
+     * Average field values
+     */
+    repo.registerMethod('average', async function (field, query = {}, options = {}) {
+      return aggregateOperation.call(this, field, '$avg', 'avg', query, options);
+    });
+
+    /**
+     * Get minimum value
+     */
+    repo.registerMethod('min', async function (field, query = {}, options = {}) {
+      return aggregateOperation.call(this, field, '$min', 'min', query, options);
+    });
+
+    /**
+     * Get maximum value
+     */
+    repo.registerMethod('max', async function (field, query = {}, options = {}) {
+      return aggregateOperation.call(this, field, '$max', 'max', query, options);
+    });
+  }
+});
+
+export default aggregateHelpersPlugin;

package/src/plugins/audit-log.plugin.js

@@ -1,60 +1,60 @@
-export const auditLogPlugin = (logger) => ({
-  name: 'auditLog',
-
-  apply(repo) {
-    repo.on('after:create', ({ context, result }) => {
-      logger?.info?.('Document created', {
-        model: context.model || repo.model,
-        id: result._id,
-        userId: context.user?._id || context.user?.id,
-        organizationId: context.organizationId,
-      });
-    });
-
-    repo.on('after:update', ({ context, result }) => {
-      logger?.info?.('Document updated', {
-        model: context.model || repo.model,
-        id: context.id || result._id,
-        userId: context.user?._id || context.user?.id,
-        organizationId: context.organizationId,
-      });
-    });
-
-    repo.on('after:delete', ({ context, result }) => {
-      logger?.info?.('Document deleted', {
-        model: context.model || repo.model,
-        id: context.id,
-        userId: context.user?._id || context.user?.id,
-        organizationId: context.organizationId,
-      });
-    });
-
-    repo.on('error:create', ({ context, error }) => {
-      logger?.error?.('Create failed', {
-        model: context.model || repo.model,
-        error: error.message,
-        userId: context.user?._id || context.user?.id,
-      });
-    });
-
-    repo.on('error:update', ({ context, error }) => {
-      logger?.error?.('Update failed', {
-        model: context.model || repo.model,
-        id: context.id,
-        error: error.message,
-        userId: context.user?._id || context.user?.id,
-      });
-    });
-
-    repo.on('error:delete', ({ context, error }) => {
-      logger?.error?.('Delete failed', {
-        model: context.model || repo.model,
-        id: context.id,
-        error: error.message,
-        userId: context.user?._id || context.user?.id,
-      });
-    });
-  },
-});
-
-export default auditLogPlugin;
+export const auditLogPlugin = (logger) => ({
+  name: 'auditLog',
+
+  apply(repo) {
+    repo.on('after:create', ({ context, result }) => {
+      logger?.info?.('Document created', {
+        model: context.model || repo.model,
+        id: result._id,
+        userId: context.user?._id || context.user?.id,
+        organizationId: context.organizationId,
+      });
+    });
+
+    repo.on('after:update', ({ context, result }) => {
+      logger?.info?.('Document updated', {
+        model: context.model || repo.model,
+        id: context.id || result._id,
+        userId: context.user?._id || context.user?.id,
+        organizationId: context.organizationId,
+      });
+    });
+
+    repo.on('after:delete', ({ context, result }) => {
+      logger?.info?.('Document deleted', {
+        model: context.model || repo.model,
+        id: context.id,
+        userId: context.user?._id || context.user?.id,
+        organizationId: context.organizationId,
+      });
+    });
+
+    repo.on('error:create', ({ context, error }) => {
+      logger?.error?.('Create failed', {
+        model: context.model || repo.model,
+        error: error.message,
+        userId: context.user?._id || context.user?.id,
+      });
+    });
+
+    repo.on('error:update', ({ context, error }) => {
+      logger?.error?.('Update failed', {
+        model: context.model || repo.model,
+        id: context.id,
+        error: error.message,
+        userId: context.user?._id || context.user?.id,
+      });
+    });
+
+    repo.on('error:delete', ({ context, error }) => {
+      logger?.error?.('Delete failed', {
+        model: context.model || repo.model,
+        id: context.id,
+        error: error.message,
+        userId: context.user?._id || context.user?.id,
+      });
+    });
+  },
+});
+
+export default auditLogPlugin;

package/src/plugins/batch-operations.plugin.js

@@ -1,66 +1,66 @@
-/**
- * Batch Operations Plugin
- * Adds bulk update/delete operations with proper event emission
- */
-
-export const batchOperationsPlugin = () => ({
-  name: 'batch-operations',
-
-  apply(repo) {
-    if (!repo.registerMethod) {
-      throw new Error('batchOperationsPlugin requires methodRegistryPlugin');
-    }
-
-    /**
-     * Update multiple documents
-     * @param {Object} query - MongoDB query to match documents
-     * @param {Object} data - Update data
-     * @param {Object} options - Additional options (session, context)
-     * @returns {Promise<Object>} MongoDB update result
-     */
-    repo.registerMethod('updateMany', async function (query, data, options = {}) {
-      const context = await this._buildContext('updateMany', { query, data, options });
-
-      try {
-        this.emit('before:updateMany', context);
-
-        const result = await this.Model.updateMany(query, data, {
-          runValidators: true,
-          session: options.session,
-        }).exec();
-
-        this.emit('after:updateMany', { context, result });
-        return result;
-      } catch (error) {
-        this.emit('error:updateMany', { context, error });
-        throw this._handleError(error);
-      }
-    });
-
-    /**
-     * Delete multiple documents
-     * @param {Object} query - MongoDB query to match documents
-     * @param {Object} options - Additional options (session, context)
-     * @returns {Promise<Object>} MongoDB delete result
-     */
-    repo.registerMethod('deleteMany', async function (query, options = {}) {
-      const context = await this._buildContext('deleteMany', { query, options });
-
-      try {
-        this.emit('before:deleteMany', context);
-
-        const result = await this.Model.deleteMany(query, {
-          session: options.session,
-        }).exec();
-
-        this.emit('after:deleteMany', { context, result });
-        return result;
-      } catch (error) {
-        this.emit('error:deleteMany', { context, error });
-        throw this._handleError(error);
-      }
-    });
-  }
-});
-
-export default batchOperationsPlugin;
+/**
+ * Batch Operations Plugin
+ * Adds bulk update/delete operations with proper event emission
+ */
+
+export const batchOperationsPlugin = () => ({
+  name: 'batch-operations',
+
+  apply(repo) {
+    if (!repo.registerMethod) {
+      throw new Error('batchOperationsPlugin requires methodRegistryPlugin');
+    }
+
+    /**
+     * Update multiple documents
+     * @param {Object} query - MongoDB query to match documents
+     * @param {Object} data - Update data
+     * @param {Object} options - Additional options (session, context)
+     * @returns {Promise<Object>} MongoDB update result
+     */
+    repo.registerMethod('updateMany', async function (query, data, options = {}) {
+      const context = await this._buildContext('updateMany', { query, data, options });
+
+      try {
+        this.emit('before:updateMany', context);
+
+        const result = await this.Model.updateMany(query, data, {
+          runValidators: true,
+          session: options.session,
+        }).exec();
+
+        this.emit('after:updateMany', { context, result });
+        return result;
+      } catch (error) {
+        this.emit('error:updateMany', { context, error });
+        throw this._handleError(error);
+      }
+    });
+
+    /**
+     * Delete multiple documents
+     * @param {Object} query - MongoDB query to match documents
+     * @param {Object} options - Additional options (session, context)
+     * @returns {Promise<Object>} MongoDB delete result
+     */
+    repo.registerMethod('deleteMany', async function (query, options = {}) {
+      const context = await this._buildContext('deleteMany', { query, options });
+
+      try {
+        this.emit('before:deleteMany', context);
+
+        const result = await this.Model.deleteMany(query, {
+          session: options.session,
+        }).exec();
+
+        this.emit('after:deleteMany', { context, result });
+        return result;
+      } catch (error) {
+        this.emit('error:deleteMany', { context, error });
+        throw this._handleError(error);
+      }
+    });
+  }
+});
+
+export default batchOperationsPlugin;

package/src/plugins/field-filter.plugin.js

@@ -1,27 +1,27 @@
-import { getFieldsForUser } from '../utils/field-selection.js';
-
-export const fieldFilterPlugin = (fieldPreset) => ({
-  name: 'fieldFilter',
-
-  apply(repo) {
-    const applyFieldFiltering = (context) => {
-      if (!fieldPreset) return;
-
-      const user = context.context?.user || context.user;
-      const fields = getFieldsForUser(user, fieldPreset);
-      const presetSelect = fields.join(' ');
-
-      if (context.select) {
-        context.select = `${presetSelect} ${context.select}`;
-      } else {
-        context.select = presetSelect;
-      }
-    };
-
-    repo.on('before:getAll', applyFieldFiltering);
-    repo.on('before:getById', applyFieldFiltering);
-    repo.on('before:getByQuery', applyFieldFiltering);
-  },
-});
-
-export default fieldFilterPlugin;
+import { getFieldsForUser } from '../utils/field-selection.js';
+
+export const fieldFilterPlugin = (fieldPreset) => ({
+  name: 'fieldFilter',
+
+  apply(repo) {
+    const applyFieldFiltering = (context) => {
+      if (!fieldPreset) return;
+
+      const user = context.context?.user || context.user;
+      const fields = getFieldsForUser(user, fieldPreset);
+      const presetSelect = fields.join(' ');
+
+      if (context.select) {
+        context.select = `${presetSelect} ${context.select}`;
+      } else {
+        context.select = presetSelect;
+      }
+    };
+
+    repo.on('before:getAll', applyFieldFiltering);
+    repo.on('before:getById', applyFieldFiltering);
+    repo.on('before:getByQuery', applyFieldFiltering);
+  },
+});
+
+export default fieldFilterPlugin;

package/src/plugins/index.js

@@ -1,19 +1,19 @@
-// Core plugins
-export { fieldFilterPlugin } from './field-filter.plugin.js';
-export { timestampPlugin } from './timestamp.plugin.js';
-export { auditLogPlugin } from './audit-log.plugin.js';
-export { softDeletePlugin } from './soft-delete.plugin.js';
-export { methodRegistryPlugin } from './method-registry.plugin.js';
-export {
-  validationChainPlugin,
-  blockIf,
-  requireField,
-  autoInject,
-  immutableField,
-  uniqueField,
-} from './validation-chain.plugin.js';
-export { mongoOperationsPlugin } from './mongo-operations.plugin.js';
-export { batchOperationsPlugin } from './batch-operations.plugin.js';
-export { aggregateHelpersPlugin } from './aggregate-helpers.plugin.js';
-export { subdocumentPlugin } from './subdocument.plugin.js';
-
+// Core plugins
+export { fieldFilterPlugin } from './field-filter.plugin.js';
+export { timestampPlugin } from './timestamp.plugin.js';
+export { auditLogPlugin } from './audit-log.plugin.js';
+export { softDeletePlugin } from './soft-delete.plugin.js';
+export { methodRegistryPlugin } from './method-registry.plugin.js';
+export {
+  validationChainPlugin,
+  blockIf,
+  requireField,
+  autoInject,
+  immutableField,
+  uniqueField,
+} from './validation-chain.plugin.js';
+export { mongoOperationsPlugin } from './mongo-operations.plugin.js';
+export { batchOperationsPlugin } from './batch-operations.plugin.js';
+export { aggregateHelpersPlugin } from './aggregate-helpers.plugin.js';
+export { subdocumentPlugin } from './subdocument.plugin.js';
+