easy-mongo-orm

Easy Mongo ORM

A powerful and elegant MongoDB/Mongoose toolkit that makes database operations a breeze with built-in caching, search, pagination, performance monitoring, soft delete, versioning, data export/import, schema validation, and migration utilities.

Features

• 🚀 Easy to Use: Simple and intuitive API
• 🔍 Advanced Search: Text, Geospatial, and Fuzzy search built-in
• 📄 Smart Pagination: Both regular and aggregation pagination support
• 💾 Caching: Built-in caching system for better performance
• 📊 Performance Monitoring: Track operation times and query performance
• 🔒 Rate Limiting: Protect your database from overload
• 🔄 Transactions: Easy-to-use transaction support
• 🔗 Population: Simple document population with depth control
• 🏗️ Query Builder: Fluent query building interface
• 📦 Bulk Operations: Efficient bulk create, update, and delete
• 🗑️ Soft Delete: Mark documents as deleted without removing them
• 📜 Versioning & Audit Trail: Track document changes over time
• 📤 Data Export/Import: Export and import data in JSON and CSV formats
• ✅ Schema Validation: Enhanced validation beyond Mongoose's built-in validation
• 🔄 Data Migration: Tools for schema migrations and data transformations

Installation

npm install easy-mongo-orm mongoose

Quick Start

const { EasyMongo } = require('easy-mongo-orm');

// Initialize with your model configuration
const userDb = new EasyMongo({
  connection: {
    uri: 'mongodb://localhost:27017/mydb'
  },
  model: {
    name: 'User',
    schema: {
      name: { type: String, required: true },
      email: { type: String, required: true, unique: true },
      age: Number,
      tags: [String]
    },
    options: {
      timestamps: true
    }
  },
  features: {
    enableCache: true,
    enablePerformanceMonitoring: true
  }
});

// Connect to database
await userDb.connect();

// CRUD Operations
const user = await userDb.create({
  name: 'John Doe',
  email: '[e-mail]',
  age: 30,
  tags: ['developer']
});

// Search Operations
const results = await userDb.search({
  text: 'John',
  fields: ['name']
});

// Pagination
const { data, pagination } = await userDb.paginate(
  { age: { $gt: 25 } },
  { page: 1, limit: 10 }
);

// Performance Stats
const stats = userDb.getPerformanceStats();

Advanced Features

Text Search

const results = await userDb.search({
  text: 'developer',
  fields: ['tags', 'bio']
});

Geospatial Search

const nearbyUsers = await userDb.searchNearby({
  coordinates: [-73.935242, 40.730610],
  maxDistance: 1000 // meters
});

Fuzzy Search

const results = await userDb.fuzzySearch({
  field: 'name',
  query: 'jhon' // will match "John"
});

Query Builder

const users = await userDb
  .query()
  .where({ age: { $gt: 25 } })
  .select('name email')
  .sort('-createdAt')
  .limit(10)
  .execute();

Large Dataset Handling

const stream = userDb
  .largeDataset()
  .where({ status: 'active' })
  .stream();

for await (const doc of stream) {
  // Process each document
}

Transactions

await userDb.withTransaction(async (session) => {
  const user = await userDb.create({
    name: 'Alice',
    email: '[e-mail]'
  }, { session });
  
  await userDb.create({
    name: 'Bob',
    email: '[e-mail]'
  }, { session });
});

Caching

// First call hits database
const user1 = await userDb.findOne({ email: '[e-mail]' });

// Second call uses cache
const user2 = await userDb.findOne({ email: '[e-mail]' });

// Clear specific cache
await userDb.clearCache('email:[e-mail]');

// Clear all cache
await userDb.clearAllCache();

Performance Monitoring

const stats = userDb.getPerformanceStats();
console.log(stats);
// {
//   operations: {
//     create: { count: 10, totalTime: 150, averageTime: 15 },
//     find: { count: 20, totalTime: 180, averageTime: 9 }
//   },
//   totalQueries: 30,
//   averageQueryTime: 11,
//   errors: 0
// }

Soft Delete

// Enable soft delete in features
const userDb = new EasyMongo({
  // ... other config
  features: {
    enableSoftDelete: true,
    softDelete: {
      deletedField: 'isDeleted',  // default
      deletedAtField: 'deletedAt' // default
    }
  }
});

// Soft delete a document
await userDb.softDeleteById('60d21b4667d0d8992e610c85');

// Soft delete multiple documents
await userDb.softDelete({ status: 'inactive' });

// Restore a soft-deleted document
await userDb.restoreById('60d21b4667d0d8992e610c85');

// Restore multiple soft-deleted documents
await userDb.restore({ status: 'inactive' });

// Find including soft-deleted documents
const allUsers = await userDb.findWithDeleted({});

// Find only soft-deleted documents
const deletedUsers = await userDb.findOnlyDeleted({});

Document Versioning & Audit Trail

// Enable versioning in features
const userDb = new EasyMongo({
  // ... other config
  features: {
    enableVersioning: true,
    versioning: {
      historyCollectionName: 'UserHistory' // default is modelName + 'History'
    }
  }
});

// Create, update, and delete operations automatically track changes

// Get document history
const history = await userDb.getDocumentHistory('60d21b4667d0d8992e610c85');
// Returns array of versions with changes

// Get specific version
const v2 = await userDb.getDocumentVersion('60d21b4667d0d8992e610c85', 2);

// Revert to a previous version
await userDb.revertToVersion('60d21b4667d0d8992e610c85', 2, {
  user: '[e-mail]' // optional user info for audit trail
});

Data Export/Import

// Enable data export in features
const userDb = new EasyMongo({
  // ... other config
  features: {
    enableDataExport: true
  }
});

// Export to JSON
await userDb.exportToJson(
  { status: 'active' }, // filter
  './exports/active-users.json', // file path
  { 
    projection: { password: 0 }, // exclude fields
    sort: { createdAt: -1 }
  }
);

// Export to CSV
await userDb.exportToCsv(
  { status: 'active' },
  './exports/active-users.csv',
  { 
    fields: ['name', 'email', 'createdAt'] // specify fields to export
  }
);

// Export large dataset with streaming
await userDb.exportLargeDatasetToJson(
  { status: 'active' },
  './exports/all-active-users.json',
  { batchSize: 1000 }
);

// Import from JSON
await userDb.importFromJson(
  './imports/users.json',
  {
    replace: false, // don't clear collection before import
    upsert: true,   // update existing documents
    idField: '_id'  // field to use for matching existing documents
  }
);

// Import from CSV
await userDb.importFromCsv(
  './imports/users.csv',
  {
    fieldTypes: {
      age: 'number',
      isActive: 'boolean',
      joinDate: 'date'
    }
  }
);

Enhanced Schema Validation

// Enable schema validation in features
const userDb = new EasyMongo({
  // ... other config
  features: {
    enableSchemaValidator: true
  }
});

// Get common validation schemas
const Joi = require('joi');
const commonSchemas = SchemaValidator.createCommonSchemas();

// Define a validation schema
userDb.defineValidationSchema(Joi.object({
  name: Joi.string().required(),
  email: commonSchemas.email.required(),
  password: commonSchemas.password,
  age: Joi.number().min(18).max(100),
  role: Joi.string().valid('user', 'admin', 'editor')
}));

// Validate data
try {
  const validatedData = userDb.validate({
    name: 'John Doe',
    email: 'invalid-email',
    age: 15
  });
} catch (error) {
  console.log(error.details);
  // [
  //   { field: 'email', message: 'must be a valid email', type: 'string.email' },
  //   { field: 'age', message: 'must be at least 18', type: 'number.min' }
  // ]
}

// Async validation
const validatedData = await userDb.validateAsync(data);

Data Migration

// Enable migration in features
const userDb = new EasyMongo({
  // ... other config
  features: {
    enableMigration: true
  }
});

// Register a migration
userDb.registerMigration({
  name: 'add-status-field',
  version: 1,
  description: 'Add status field to all users',
  up: async () => {
    // Create a migration helper
    const helper = userDb.migrationManager.createMigrationHelper(userDb.Model);
    
    // Add a field to all documents
    await helper.addField('status', 'active');
  },
  down: async () => {
    const helper = userDb.migrationManager.createMigrationHelper(userDb.Model);
    await helper.removeField('status');
  }
});

// Register another migration
userDb.registerMigration({
  name: 'rename-bio-to-description',
  version: 2,
  description: 'Rename bio field to description',
  up: async () => {
    const helper = userDb.migrationManager.createMigrationHelper(userDb.Model);
    await helper.renameField('bio', 'description');
  },
  down: async () => {
    const helper = userDb.migrationManager.createMigrationHelper(userDb.Model);
    await helper.renameField('description', 'bio');
  }
});

// Apply all pending migrations
const result = await userDb.applyMigrations();
console.log(`Applied ${result.applied} migrations`);

// Get migration status
const status = await userDb.getMigrationStatus();
console.log(`Applied migrations: ${status.applied.length}`);
console.log(`Pending migrations: ${status.pending.length}`);

// Rollback the last migration
await userDb.rollbackLastMigration();

Configuration Options

Connection Options

{
  uri: 'mongodb://localhost:27017/mydb',
  options: {
    useNewUrlParser: true,
    useUnifiedTopology: true
    // ... other mongoose connection options
  }
}

Feature Options

{
  // Core features
  enableCache: true,
  cacheTTL: 3600, // seconds
  enablePerformanceMonitoring: true,
  enableRateLimit: true,
  rateLimit: {
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100 // requests per windowMs
  },
  
  // New features
  enableSoftDelete: true,
  softDelete: {
    deletedField: 'isDeleted',
    deletedAtField: 'deletedAt'
  },
  
  enableVersioning: true,
  versioning: {
    historyCollectionName: 'CustomHistoryCollection'
  },
  
  enableDataExport: true,
  dataExport: {
    // export options
  },
  
  enableSchemaValidator: true,
  schemaValidator: {
    // validation options
  },
  
  enableMigration: true,
  migration: {
    // migration options
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Md.Tousif