Package Exports

@kommix/mongoose-activity

Readme

@kommix/mongoose-activity

Production-grade activity logging for Mongoose 📝 → CRUD, deletions, custom events, feeds.

A modern, production-ready Mongoose plugin that takes care of activity logging so you don't have to. Create, update, delete — everything gets tracked automatically. No more DIY audit tables! ✨

🔍 Why Not Other Plugins?

Most existing mongoose activity/audit plugins fall short for production use:

📊 Feature Comparison

Capability	Other Plugins	@kommix/mongoose-activity
Auto CRUD Hooks	❌ Often manual logging¹	✅ Full lifecycle hooks + custom events
Deletion Tracking	❌ Rarely explicit; soft-delete only²	✅ Hard deletes + field capture pre-delete
Bulk Operations	❌ `deleteMany`/`updateMany` gaps³	✅ Bulk threshold & optimization
Retention/TTL	❌ Generally missing	✅ Auto-cleanup via `retentionDays`
Performance	❌ Sync-only, no batching	✅ Async logging, event system
TypeScript	❌ Mixed JS/TS support	✅ TypeScript-first
Maintenance	❌ Many stale (2016-2020)⁴	✅ Active development

🔍 Specific Gaps We Found:

mongoose-activitylog: Manual builder pattern, no auto-hooks, last release May 2020¹
mongoose-user-history-plugin: Missing bulk ops, TTL, performance tuning³
mf-mongoose-audittrail: Audit fields only, no central Activity collection²
mongoose-activitylogs: Basic append-style, last published August 2016⁴
@hilarion/mongoose-activity-logger: Unmaintained since October 2019⁴

^{¹mongoose-activitylog ²mf-mongoose-audittrail ³mongoose-user-history-plugin ⁴Many plugins last updated between 2016–2020 (see npm/GitHub links)}

🎯 What Makes This Different?

🔄 Production-Ready Design - Built for enterprise workloads with async logging, TTL cleanup, and smart indexing
🗑️ Complete Deletion Coverage - Only plugin with full deleteOne/deleteMany/findOneAndDelete tracking + field capture
⚡ Performance Optimized - Bulk operation thresholds, async logging, configurable batching
🚀 Modern Stack - TypeScript-first, zero dependencies, Node 18+ support
🔧 Battle-Tested - 91.93% test coverage, comprehensive performance benchmarks

💡 Built because we got tired of half-maintained plugins. Now you don't have to.

📚 Documentation

📖 API Reference - Complete API documentation
🎯 Advanced Examples - Complex use cases and patterns
📊 Benchmarks & Performance - Performance metrics and optimization tips
⚡ Performance Tests - Load testing and performance analysis
🗺️ Roadmap - Future features and improvements
💡 Sample Examples - 7 runnable examples covering all features

🚀 Installation

npm install @kommix/mongoose-activity

⚡ Quick Start

💫 5-Second Demo

// One-liner setup
userSchema.plugin(activityPlugin, { trackedFields: ['name', 'email'] });

await User.create({ name: "Jane" }); // → activity logged automatically!

That's it! Activities now show up automatically. You focus on features, we handle the logs.

What you get:

{
  "type": "users_created",
  "entity": { "type": "users", "id": "652a..." },
  "changes": { "name": "Jane", "email": "jane@example.com" },
  "userId": "auto-detected",
  "timestamp": "2025-09-27T12:34:56Z"
}

1. Plugin Setup - Auto-Track Document Changes

import mongoose from 'mongoose';
import { activityPlugin } from '@kommix/mongoose-activity';

// Your existing schema
const userSchema = new mongoose.Schema({
  name: String,
  email: String,
  status: String
});

// Add the plugin - specify which fields to track
userSchema.plugin(activityPlugin, {
  trackedFields: ['name', 'email', 'status'], // Fields to track
  collectionName: 'users' // Entity type for activities
});

const User = mongoose.model('User', userSchema);

// Now every save/update/delete automatically logs activities!
const user = await User.create({
  name: 'John Doe',
  email: 'john@example.com'
});
// ✅ Automatically logs: { type: 'users_created', entity: { type: 'users', id: user._id }, ... }

user.name = 'Jane Doe';
await user.save();
// ✅ Automatically logs: { type: 'document_updated', changes: { name: { from: 'John Doe', to: 'Jane Doe' } }, ... }

await User.deleteOne({ _id: user._id });
// ✅ Automatically logs: { type: 'users_deleted', meta: { deletedFields: { name: 'Jane Doe', email: 'john@example.com' } }, ... }

2. Manual Logging - Custom Business Events

import { logActivity } from '@kommix/mongoose-activity';

// Log custom business events
await logActivity({
  userId: customerId,
  entity: { type: 'order', id: orderId },
  type: 'order_shipped',
  meta: {
    trackingNumber: 'ABC123',
    carrier: 'FedEx',
    estimatedDelivery: '2024-01-15'
  }
});

3. Query Activity Feeds

import { getActivityFeed, getEntityActivity } from '@kommix/mongoose-activity';

// Get user's activity feed
const feed = await getActivityFeed(userId, {
  limit: 20,
  entityType: 'order' // Optional filters
});

// Get complete history for a specific entity
const orderHistory = await getEntityActivity('order', orderId);

4. Express/Koa Middleware - Auto-Capture Context

import { activityContextMiddleware } from '@kommix/mongoose-activity';

// Basic usage (works with any framework)
app.use(activityContextMiddleware({
  extractUserId: (req) => req.user?.id,
  extractRequestId: (req) => req.headers?.['x-request-id']
}));

// Now all activities automatically include request context — magic! ✨

🎯 Enhanced TypeScript Support

import { Request, Response } from 'express';
import { Context } from 'koa';

// Express with full type safety and IntelliSense
app.use(activityContextMiddleware<Request, Response>({
  extractUserId: (req) => req.user?.id,  // Full autocomplete
  extractRequestId: (req) => req.headers['x-request-id'],
}));

// Koa with type safety
app.use(koaActivityContextMiddleware<Context>({
  extractUserId: (ctx) => ctx.state.user?.id,
  extractIp: (ctx) => ctx.ip,
}));

// Custom framework integration
interface MyCustomRequest {
  authenticatedUser: { userId: string };
  customHeaders: Record<string, string>;
}

app.use(activityContextMiddleware<MyCustomRequest>({
  extractUserId: (req) => req.authenticatedUser.userId,
  extractRequestId: (req) => req.customHeaders.requestId,
}));

✨ Key Features

🗑️ Deletion Tracking

userSchema.plugin(activityPlugin, {
  trackDeletions: true,          // Enable deletion tracking
  deletionFields: ['name', 'email'], // Fields to capture before deletion
  bulkDeleteThreshold: 100       // Auto-optimize for bulk operations
});

🔄 Event System

import { activityEvents } from '@kommix/mongoose-activity';

// React to activities in real-time — hook into your business logic
activityEvents.on('activity:logged', (activity) => {
  if (activity.type === 'order_shipped') {
    notificationService.send(activity.userId, 'Your order has shipped!');
  }
});

⚙️ Global Configuration

import { activityConfig } from '@kommix/mongoose-activity';

activityConfig.configure({
  asyncLogging: true,     // Fire-and-forget for performance
  retentionDays: 90,      // Auto-cleanup with TTL
  throwOnError: false     // Silent error handling
});

🧩 Compatibility

Node.js: 18+ (matches engines field in package.json)
MongoDB: 4.0+ (for TTL and indexes)
Mongoose: 6.0+ or 7.0+ or 8.0+
TypeScript: 4.0+ (full type support with enhanced middleware IntelliSense)
Frameworks: Express, Koa, or any compatible middleware framework

🧪 Development

# Install dependencies
npm install

# Run tests (91.93% coverage)
npm test

# Build (CJS + ESM)
npm run build

# Development mode
npm run dev

🤝 Contributing

We'd love your help to make this even better! PRs, issues, and feature ideas are always welcome 🚀

Before submitting:

Run npm run lint and npm run format
Add tests for new features
Update documentation if needed

👐 Looking to build something cool? Reach out — we're friendly and love crazy ideas!

📄 License

MIT © Kommix

📦 npm · 💻 GitHub · 📖 Full Documentation