@classytic/mongokit 1.0.1 → 2.0.0

package/src/plugins/soft-delete.plugin.js

@@ -1,46 +1,46 @@
-export const softDeletePlugin = (options = {}) => ({
-  name: 'softDelete',
-
-  apply(repo) {
-    const deletedField = options.deletedField || 'deletedAt';
-    const deletedByField = options.deletedByField || 'deletedBy';
-
-    repo.on('before:delete', async (context) => {
-      if (options.soft !== false) {
-        const updateData = {
-          [deletedField]: new Date(),
-        };
-
-        if (context.user) {
-          updateData[deletedByField] = context.user._id || context.user.id;
-        }
-
-        await repo.Model.findByIdAndUpdate(context.id, updateData, { session: context.session });
-
-        context.softDeleted = true;
-      }
-    });
-
-    repo.on('before:getAll', (context) => {
-      if (!context.includeDeleted && options.soft !== false) {
-        const queryParams = context.queryParams || {};
-        queryParams.filters = {
-          ...(queryParams.filters || {}),
-          [deletedField]: { $exists: false },
-        };
-        context.queryParams = queryParams;
-      }
-    });
-
-    repo.on('before:getById', (context) => {
-      if (!context.includeDeleted && options.soft !== false) {
-        context.query = {
-          ...(context.query || {}),
-          [deletedField]: { $exists: false },
-        };
-      }
-    });
-  },
-});
-
-export default softDeletePlugin;
+export const softDeletePlugin = (options = {}) => ({
+  name: 'softDelete',
+
+  apply(repo) {
+    const deletedField = options.deletedField || 'deletedAt';
+    const deletedByField = options.deletedByField || 'deletedBy';
+
+    repo.on('before:delete', async (context) => {
+      if (options.soft !== false) {
+        const updateData = {
+          [deletedField]: new Date(),
+        };
+
+        if (context.user) {
+          updateData[deletedByField] = context.user._id || context.user.id;
+        }
+
+        await repo.Model.findByIdAndUpdate(context.id, updateData, { session: context.session });
+
+        context.softDeleted = true;
+      }
+    });
+
+    repo.on('before:getAll', (context) => {
+      if (!context.includeDeleted && options.soft !== false) {
+        const queryParams = context.queryParams || {};
+        queryParams.filters = {
+          ...(queryParams.filters || {}),
+          [deletedField]: { $exists: false },
+        };
+        context.queryParams = queryParams;
+      }
+    });
+
+    repo.on('before:getById', (context) => {
+      if (!context.includeDeleted && options.soft !== false) {
+        context.query = {
+          ...(context.query || {}),
+          [deletedField]: { $exists: false },
+        };
+      }
+    });
+  },
+});
+
+export default softDeletePlugin;

package/src/plugins/subdocument.plugin.js

@@ -1,66 +1,66 @@
-/**
- * Subdocument Plugin
- * Adds subdocument array operations
- */
-
-import createError from 'http-errors';
-
-export const subdocumentPlugin = () => ({
-  name: 'subdocument',
-
-  apply(repo) {
-    if (!repo.registerMethod) {
-      throw new Error('subdocumentPlugin requires methodRegistryPlugin');
-    }
-
-    /**
-     * Add subdocument to array
-     */
-    repo.registerMethod('addSubdocument', async function (parentId, arrayPath, subData, options = {}) {
-      return this.update(parentId, { $push: { [arrayPath]: subData } }, options);
-    });
-
-    /**
-     * Get subdocument from array
-     */
-    repo.registerMethod('getSubdocument', async function (parentId, arrayPath, subId, options = {}) {
-      return this._executeQuery(async (Model) => {
-        const parent = await Model.findById(parentId).session(options.session).exec();
-        if (!parent) throw createError(404, 'Parent not found');
-
-        const sub = parent[arrayPath].id(subId);
-        if (!sub) throw createError(404, 'Subdocument not found');
-
-        return options.lean ? sub.toObject() : sub;
-      });
-    });
-
-    /**
-     * Update subdocument in array
-     */
-    repo.registerMethod('updateSubdocument', async function (parentId, arrayPath, subId, updateData, options = {}) {
-      return this._executeQuery(async (Model) => {
-        const query = { _id: parentId, [`${arrayPath}._id`]: subId };
-        const update = { $set: { [`${arrayPath}.$`]: { ...updateData, _id: subId } } };
-
-        const result = await Model.findOneAndUpdate(query, update, {
-          new: true,
-          runValidators: true,
-          session: options.session,
-        }).exec();
-
-        if (!result) throw createError(404, 'Parent or subdocument not found');
-        return result;
-      });
-    });
-
-    /**
-     * Delete subdocument from array
-     */
-    repo.registerMethod('deleteSubdocument', async function (parentId, arrayPath, subId, options = {}) {
-      return this.update(parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
-    });
-  }
-});
-
-export default subdocumentPlugin;
+/**
+ * Subdocument Plugin
+ * Adds subdocument array operations
+ */
+
+import { createError } from '../utils/error.js';
+
+export const subdocumentPlugin = () => ({
+  name: 'subdocument',
+
+  apply(repo) {
+    if (!repo.registerMethod) {
+      throw new Error('subdocumentPlugin requires methodRegistryPlugin');
+    }
+
+    /**
+     * Add subdocument to array
+     */
+    repo.registerMethod('addSubdocument', async function (parentId, arrayPath, subData, options = {}) {
+      return this.update(parentId, { $push: { [arrayPath]: subData } }, options);
+    });
+
+    /**
+     * Get subdocument from array
+     */
+    repo.registerMethod('getSubdocument', async function (parentId, arrayPath, subId, options = {}) {
+      return this._executeQuery(async (Model) => {
+        const parent = await Model.findById(parentId).session(options.session).exec();
+        if (!parent) throw createError(404, 'Parent not found');
+
+        const sub = parent[arrayPath].id(subId);
+        if (!sub) throw createError(404, 'Subdocument not found');
+
+        return options.lean ? sub.toObject() : sub;
+      });
+    });
+
+    /**
+     * Update subdocument in array
+     */
+    repo.registerMethod('updateSubdocument', async function (parentId, arrayPath, subId, updateData, options = {}) {
+      return this._executeQuery(async (Model) => {
+        const query = { _id: parentId, [`${arrayPath}._id`]: subId };
+        const update = { $set: { [`${arrayPath}.$`]: { ...updateData, _id: subId } } };
+
+        const result = await Model.findOneAndUpdate(query, update, {
+          new: true,
+          runValidators: true,
+          session: options.session,
+        }).exec();
+
+        if (!result) throw createError(404, 'Parent or subdocument not found');
+        return result;
+      });
+    });
+
+    /**
+     * Delete subdocument from array
+     */
+    repo.registerMethod('deleteSubdocument', async function (parentId, arrayPath, subId, options = {}) {
+      return this.update(parentId, { $pull: { [arrayPath]: { _id: subId } } }, options);
+    });
+  }
+});
+
+export default subdocumentPlugin;

package/src/plugins/timestamp.plugin.js

@@ -1,19 +1,19 @@
-export const timestampPlugin = () => ({
-  name: 'timestamp',
-
-  apply(repo) {
-    repo.on('before:create', (context) => {
-      if (!context.data) return;
-      const now = new Date();
-      if (!context.data.createdAt) context.data.createdAt = now;
-      if (!context.data.updatedAt) context.data.updatedAt = now;
-    });
-
-    repo.on('before:update', (context) => {
-      if (!context.data) return;
-      context.data.updatedAt = new Date();
-    });
-  },
-});
-
-export default timestampPlugin;
+export const timestampPlugin = () => ({
+  name: 'timestamp',
+
+  apply(repo) {
+    repo.on('before:create', (context) => {
+      if (!context.data) return;
+      const now = new Date();
+      if (!context.data.createdAt) context.data.createdAt = now;
+      if (!context.data.updatedAt) context.data.updatedAt = now;
+    });
+
+    repo.on('before:update', (context) => {
+      if (!context.data) return;
+      context.data.updatedAt = new Date();
+    });
+  },
+});
+
+export default timestampPlugin;

package/src/plugins/validation-chain.plugin.js

@@ -1,145 +1,145 @@
-import createError from 'http-errors';
-
-export const validationChainPlugin = (validators = [], options = {}) => {
-  const { stopOnFirstError = true } = options;
-
-  validators.forEach((v, idx) => {
-    if (!v.name || typeof v.name !== 'string') {
-      throw new Error(`Validator at index ${idx} missing 'name' (string)`);
-    }
-    if (typeof v.validate !== 'function') {
-      throw new Error(`Validator '${v.name}' missing 'validate' function`);
-    }
-  });
-
-  const validatorsByOperation = { create: [], update: [], delete: [], createMany: [] };
-  const allOperationsValidators = [];
-
-  validators.forEach(v => {
-    if (!v.operations || v.operations.length === 0) {
-      allOperationsValidators.push(v);
-    } else {
-      v.operations.forEach(op => {
-        if (validatorsByOperation[op]) {
-          validatorsByOperation[op].push(v);
-        }
-      });
-    }
-  });
-
-  return {
-    name: 'validation-chain',
-
-    apply(repo) {
-      const getValidatorsForOperation = (operation) => {
-        const specific = validatorsByOperation[operation] || [];
-        return [...allOperationsValidators, ...specific];
-      };
-
-      const runValidators = async (operation, context) => {
-        const validators = getValidatorsForOperation(operation);
-        const errors = [];
-
-        for (const validator of validators) {
-          try {
-            await validator.validate(context, repo);
-          } catch (error) {
-            if (stopOnFirstError) {
-              throw error;
-            }
-            errors.push({
-              validator: validator.name,
-              error: error.message || String(error)
-            });
-          }
-        }
-
-        if (errors.length > 0) {
-          const error = createError(
-            400,
-            `Validation failed: ${errors.map(e => `[${e.validator}] ${e.error}`).join('; ')}`
-          );
-          error.validationErrors = errors;
-          throw error;
-        }
-      };
-
-      repo.on('before:create', async (context) => await runValidators('create', context));
-      repo.on('before:createMany', async (context) => await runValidators('createMany', context));
-      repo.on('before:update', async (context) => await runValidators('update', context));
-      repo.on('before:delete', async (context) => await runValidators('delete', context));
-    }
-  };
-};
-
-/**
- * Block operation if condition is true
- * @param {string} name - Validator name
- * @param {string[]} operations - Operations to block on
- * @param {Function} condition - Condition function (context) => boolean
- * @param {string} errorMessage - Error message to throw
- * @example blockIf('block-library', ['delete'], ctx => ctx.data.managed, 'Cannot delete managed records')
- */
-export const blockIf = (name, operations, condition, errorMessage) => ({
-  name,
-  operations,
-  validate: (context) => {
-    if (condition(context)) {
-      throw createError(403, errorMessage);
-    }
-  }
-});
-
-export const requireField = (field, operations = ['create']) => ({
-  name: `require-${field}`,
-  operations,
-  validate: (context) => {
-    if (!context.data || context.data[field] === undefined || context.data[field] === null) {
-      throw createError(400, `Field '${field}' is required`);
-    }
-  }
-});
-
-export const autoInject = (field, getter, operations = ['create']) => ({
-  name: `auto-inject-${field}`,
-  operations,
-  validate: (context) => {
-    if (context.data && !(field in context.data)) {
-      const value = getter(context);
-      if (value !== null && value !== undefined) {
-        context.data[field] = value;
-      }
-    }
-  }
-});
-
-export const immutableField = (field) => ({
-  name: `immutable-${field}`,
-  operations: ['update'],
-  validate: (context) => {
-    if (context.data && field in context.data) {
-      throw createError(400, `Field '${field}' cannot be modified`);
-    }
-  }
-});
-
-export const uniqueField = (field, errorMessage) => ({
-  name: `unique-${field}`,
-  operations: ['create', 'update'],
-  validate: async (context, repo) => {
-    if (!context.data || !context.data[field]) return;
-
-    const query = { [field]: context.data[field] };
-    const existing = await repo.getByQuery(query, {
-      select: '_id',
-      lean: true,
-      throwOnNotFound: false
-    });
-
-    if (existing && existing._id.toString() !== context.id?.toString()) {
-      throw createError(409, errorMessage || `${field} already exists`);
-    }
-  }
-});
-
-export default validationChainPlugin;
+import { createError } from '../utils/error.js';
+
+export const validationChainPlugin = (validators = [], options = {}) => {
+  const { stopOnFirstError = true } = options;
+
+  validators.forEach((v, idx) => {
+    if (!v.name || typeof v.name !== 'string') {
+      throw new Error(`Validator at index ${idx} missing 'name' (string)`);
+    }
+    if (typeof v.validate !== 'function') {
+      throw new Error(`Validator '${v.name}' missing 'validate' function`);
+    }
+  });
+
+  const validatorsByOperation = { create: [], update: [], delete: [], createMany: [] };
+  const allOperationsValidators = [];
+
+  validators.forEach(v => {
+    if (!v.operations || v.operations.length === 0) {
+      allOperationsValidators.push(v);
+    } else {
+      v.operations.forEach(op => {
+        if (validatorsByOperation[op]) {
+          validatorsByOperation[op].push(v);
+        }
+      });
+    }
+  });
+
+  return {
+    name: 'validation-chain',
+
+    apply(repo) {
+      const getValidatorsForOperation = (operation) => {
+        const specific = validatorsByOperation[operation] || [];
+        return [...allOperationsValidators, ...specific];
+      };
+
+      const runValidators = async (operation, context) => {
+        const validators = getValidatorsForOperation(operation);
+        const errors = [];
+
+        for (const validator of validators) {
+          try {
+            await validator.validate(context, repo);
+          } catch (error) {
+            if (stopOnFirstError) {
+              throw error;
+            }
+            errors.push({
+              validator: validator.name,
+              error: error.message || String(error)
+            });
+          }
+        }
+
+        if (errors.length > 0) {
+          const error = /** @type {Error & {status: number, validationErrors: any[]}} */ (createError(
+            400,
+            `Validation failed: ${errors.map(e => `[${e.validator}] ${e.error}`).join('; ')}`
+          ));
+          error.validationErrors = errors;
+          throw error;
+        }
+      };
+
+      repo.on('before:create', async (context) => await runValidators('create', context));
+      repo.on('before:createMany', async (context) => await runValidators('createMany', context));
+      repo.on('before:update', async (context) => await runValidators('update', context));
+      repo.on('before:delete', async (context) => await runValidators('delete', context));
+    }
+  };
+};
+
+/**
+ * Block operation if condition is true
+ * @param {string} name - Validator name
+ * @param {string[]} operations - Operations to block on
+ * @param {Function} condition - Condition function (context) => boolean
+ * @param {string} errorMessage - Error message to throw
+ * @example blockIf('block-library', ['delete'], ctx => ctx.data.managed, 'Cannot delete managed records')
+ */
+export const blockIf = (name, operations, condition, errorMessage) => ({
+  name,
+  operations,
+  validate: (context) => {
+    if (condition(context)) {
+      throw createError(403, errorMessage);
+    }
+  }
+});
+
+export const requireField = (field, operations = ['create']) => ({
+  name: `require-${field}`,
+  operations,
+  validate: (context) => {
+    if (!context.data || context.data[field] === undefined || context.data[field] === null) {
+      throw createError(400, `Field '${field}' is required`);
+    }
+  }
+});
+
+export const autoInject = (field, getter, operations = ['create']) => ({
+  name: `auto-inject-${field}`,
+  operations,
+  validate: (context) => {
+    if (context.data && !(field in context.data)) {
+      const value = getter(context);
+      if (value !== null && value !== undefined) {
+        context.data[field] = value;
+      }
+    }
+  }
+});
+
+export const immutableField = (field) => ({
+  name: `immutable-${field}`,
+  operations: ['update'],
+  validate: (context) => {
+    if (context.data && field in context.data) {
+      throw createError(400, `Field '${field}' cannot be modified`);
+    }
+  }
+});
+
+export const uniqueField = (field, errorMessage) => ({
+  name: `unique-${field}`,
+  operations: ['create', 'update'],
+  validate: async (context, repo) => {
+    if (!context.data || !context.data[field]) return;
+
+    const query = { [field]: context.data[field] };
+    const existing = await repo.getByQuery(query, {
+      select: '_id',
+      lean: true,
+      throwOnNotFound: false
+    });
+
+    if (existing && existing._id.toString() !== context.id?.toString()) {
+      throw createError(409, errorMessage || `${field} already exists`);
+    }
+  }
+});
+
+export default validationChainPlugin;

package/src/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Type definitions for MongoKit
+ * Used for type checking and auto-completion
+ */
+
+import { Model, Document, PopulateOptions, ClientSession, Types } from 'mongoose';
+
+// Re-export mongoose ObjectId
+export type ObjectId = Types.ObjectId;
+
+// Pagination configuration
+export interface PaginationConfig {
+  defaultLimit?: number;
+  maxLimit?: number;
+  maxPage?: number;
+  deepPageThreshold?: number;
+  cursorVersion?: number;
+  useEstimatedCount?: boolean;
+}
+
+// Pagination options
+export interface OffsetPaginationOptions {
+  filters?: Record<string, any>;
+  sort?: Record<string, 1 | -1>;
+  page?: number;
+  limit?: number;
+  select?: string | string[];
+  populate?: string | string[] | PopulateOptions | PopulateOptions[];
+  lean?: boolean;
+  session?: ClientSession;
+}
+
+export interface KeysetPaginationOptions {
+  filters?: Record<string, any>;
+  sort: Record<string, 1 | -1>;
+  after?: string;
+  limit?: number;
+  select?: string | string[] | Record<string, any>;
+  populate?: string | string[] | PopulateOptions | PopulateOptions[];
+  lean?: boolean;
+  session?: ClientSession;
+}
+
+export interface AggregatePaginationOptions {
+  pipeline?: any[];
+  page?: number;
+  limit?: number;
+  session?: ClientSession;
+}
+
+// Pagination result types
+export interface OffsetPaginationResult<T = any> {
+  method: 'offset';
+  docs: T[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+  warning?: string;
+}
+
+export interface KeysetPaginationResult<T = any> {
+  method: 'keyset';
+  docs: T[];
+  limit: number;
+  hasMore: boolean;
+  next: string | null;
+}
+
+export interface AggregatePaginationResult<T = any> {
+  method: 'aggregate';
+  docs: T[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+  warning?: string;
+}
+
+export type PaginationResult<T = any> =
+  | OffsetPaginationResult<T>
+  | KeysetPaginationResult<T>
+  | AggregatePaginationResult<T>;

package/src/utils/error.js

@@ -0,0 +1,12 @@
+/**
+ * Creates an error with HTTP status code
+ *
+ * @param {number} status - HTTP status code
+ * @param {string} message - Error message
+ * @returns {Error & {status: number}} Error with status property
+ */
+export function createError(status, message) {
+  const error = /** @type {Error & {status: number}} */ (new Error(message));
+  error.status = status;
+  return error;
+}