{"_id":"@alirezaaminzadeh/nest-bpmn-engine","name":"@alirezaaminzadeh/nest-bpmn-engine","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alirezaaminzadeh/nest-bpmn-engine","version":"1.0.0","description":"Production-ready BPMN 2.0 Process Execution Engine for NestJS with comprehensive workflow orchestration capabilities","author":{"name":"Alireza Aminzadeh","email":"alireza.aminzadeh@hotmail.com"},"private":false,"license":"MIT","keywords":["nestjs","bpmn","bpmn2","workflow","process-engine","orchestration","typescript","business-process","automation"],"repository":{"type":"git","url":"git+https://github.com/syeedalireza/nest-bpmn-engine.git"},"homepage":"https://github.com/syeedalireza/nest-bpmn-engine#readme","bugs":{"url":"https://github.com/syeedalireza/nest-bpmn-engine/issues"},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"prebuild":"rimraf dist","build":"nest build","format":"prettier --write \"src/**/*.ts\" \"test/**/*.ts\"","start":"nest start","start:dev":"nest start --watch","start:debug":"nest start --debug --watch","start:prod":"node dist/main","lint":"eslint \"{src,apps,libs,test}/**/*.ts\" --fix","lint:check":"eslint \"{src,apps,libs,test}/**/*.ts\"","test":"jest","test:watch":"jest --watch","test:cov":"jest --coverage","test:debug":"node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand","test:e2e":"jest --config ./test/jest-e2e.json","prepare":"husky install"},"dependencies":{"@nestjs/bull":"^11.0.4","@nestjs/common":"^11.1.12","@nestjs/config":"^4.0.2","@nestjs/core":"^11.1.12","@nestjs/event-emitter":"^3.0.1","@nestjs/platform-express":"^11.0.1","@nestjs/swagger":"^11.2.5","@nestjs/terminus":"^11.0.0","@nestjs/throttler":"^6.5.0","@nestjs/typeorm":"^11.0.0","axios":"^1.13.4","bpmn-engine":"^25.0.1","bull":"^4.16.5","class-transformer":"^0.5.1","class-validator":"^0.14.3","compression":"^1.8.1","helmet":"^8.1.0","ioredis":"^5.9.2","pg":"^8.18.0","prom-client":"^15.1.3","redis":"^5.10.0","reflect-metadata":"^0.2.2","rxjs":"^7.8.2","typeorm":"^0.3.28","winston":"^3.19.0","winston-daily-rotate-file":"^5.0.0"},"devDependencies":{"@eslint/eslintrc":"^3.2.0","@eslint/js":"^9.18.0","@nestjs/cli":"^11.0.0","@nestjs/schematics":"^11.0.0","@nestjs/testing":"^11.1.12","@types/bull":"^3.15.9","@types/compression":"^1.8.1","@types/express":"^5.0.6","@types/jest":"^30.0.0","@types/node":"^22.19.7","@types/supertest":"^6.0.2","eslint":"^9.18.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.5","globals":"^16.0.0","husky":"^9.1.7","jest":"^30.0.0","lint-staged":"^16.2.7","prettier":"^3.4.2","rimraf":"^6.1.2","source-map-support":"^0.5.21","supertest":"^7.2.2","ts-jest":"^29.4.6","ts-loader":"^9.5.2","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","typescript":"^5.7.3","typescript-eslint":"^8.20.0"},"jest":{"moduleFileExtensions":["js","json","ts"],"rootDir":"src","testRegex":".*\\.spec\\.ts$","transform":{"^.+\\.(t|j)s$":"ts-jest"},"collectCoverageFrom":["**/*.(t|j)s"],"coverageDirectory":"../coverage","testEnvironment":"node"},"_id":"@alirezaaminzadeh/nest-bpmn-engine@1.0.0","gitHead":"c01e22bfe4b09c2bc34c05767502a78a78d0effb","_nodeVersion":"22.12.0","_npmVersion":"11.4.0","dist":{"integrity":"sha512-ysKP45cNZBh+PhZap1WRPU5hSxbVuIJ9dUMxezADifsHdikZ1/5elnXUdYWAVr/WlzNHcjMJBkdaK1IAaWzuBg==","shasum":"6c7e5695f987f993db34fc3ef6c5201e281cb6ac","tarball":"https://registry.npmjs.org/@alirezaaminzadeh/nest-bpmn-engine/-/nest-bpmn-engine-1.0.0.tgz","fileCount":143,"unpackedSize":536014,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCAppS3V7M2jBrk+1R3NL9JN13PS2K0Q97Sv71YX9Fb4AIhAKi7N/+/Drta8iyE9TBkbrcl82fG4SwfhGiDjffXR77A"}]},"_npmUser":{"name":"syeedalireza","email":"syeedalireza@yahoo.com"},"directories":{},"maintainers":[{"name":"syeedalireza","email":"syeedalireza@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nest-bpmn-engine_1.0.0_1769851974981_0.3552735406835006"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-31T09:32:54.901Z","1.0.0":"2026-01-31T09:32:55.147Z","modified":"2026-01-31T09:32:55.315Z"},"maintainers":[{"name":"syeedalireza","email":"syeedalireza@yahoo.com"}],"description":"Production-ready BPMN 2.0 Process Execution Engine for NestJS with comprehensive workflow orchestration capabilities","homepage":"https://github.com/syeedalireza/nest-bpmn-engine#readme","keywords":["nestjs","bpmn","bpmn2","workflow","process-engine","orchestration","typescript","business-process","automation"],"repository":{"type":"git","url":"git+https://github.com/syeedalireza/nest-bpmn-engine.git"},"author":{"name":"Alireza Aminzadeh","email":"alireza.aminzadeh@hotmail.com"},"bugs":{"url":"https://github.com/syeedalireza/nest-bpmn-engine/issues"},"license":"MIT","readme":"# BPMN Process Engine for NestJS\r\n\r\n[![npm version](https://img.shields.io/npm/v/@alirezaaminzadeh/nest-bpmn-engine.svg)](https://www.npmjs.com/package/@alirezaaminzadeh/nest-bpmn-engine)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)\r\n[![NestJS](https://img.shields.io/badge/NestJS-10.x-red.svg)](https://nestjs.com/)\r\n\r\nProduction-ready BPMN 2.0 Process Execution Engine for NestJS with comprehensive workflow orchestration capabilities. Built with TypeScript, PostgreSQL, Redis, and modern software engineering practices.\r\n\r\n## ✨ Features\r\n\r\n### Core BPMN 2.0 Support\r\n- ✅ **Events**: Start, End, Intermediate Events\r\n- ✅ **Tasks**: User Tasks, Service Tasks, Script Tasks\r\n- ✅ **Gateways**: Exclusive, Parallel, Inclusive Gateways\r\n- ✅ **Flows**: Sequence Flows, Message Flows\r\n- ✅ **Advanced**: Sub-processes, Call Activities\r\n\r\n### Process Management\r\n- 🚀 Deploy and version BPMN process definitions\r\n- ▶️ Start process instances with variables\r\n- ⏸️ Suspend and resume running processes\r\n- ⏹️ Terminate processes with reason tracking\r\n- 🔍 Query and filter process instances\r\n- 📊 Process execution history and audit trail\r\n\r\n### Task Management\r\n- 📋 Create and manage user tasks\r\n- 👤 Claim and assign tasks to users/groups\r\n- ✅ Complete tasks with output variables\r\n- 🔄 Delegate tasks to other users\r\n- ⏰ Task priorities and due dates\r\n- 🔍 Advanced task filtering and queries\r\n\r\n### Integration & Extensibility\r\n- 🔗 REST API service task execution\r\n- 📡 Webhook notifications for process events\r\n- 🔌 Custom JavaScript expressions\r\n- 🌐 External task workers pattern\r\n- 🎯 Event-driven architecture\r\n\r\n### Enterprise Features\r\n- 📈 Prometheus metrics and monitoring\r\n- 📝 Winston logging with daily rotation\r\n- ❤️ Health checks and readiness probes\r\n- 🔒 Security with Helmet.js\r\n- ⚡ Rate limiting and throttling\r\n- 🐳 Full Docker support\r\n- 📚 Auto-generated Swagger documentation\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install @alirezaaminzadeh/nest-bpmn-engine\r\n```\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Setup with Docker (Recommended)\r\n\r\nClone and start with Docker Compose:\r\n\r\n```bash\r\n# Create .env file\r\ncp .env.example .env\r\n\r\n# Edit .env and set your passwords\r\n# DB_PASSWORD=your_secure_password\r\n# REDIS_PASSWORD=your_redis_password\r\n\r\n# Start all services\r\ndocker-compose up -d\r\n```\r\n\r\nThe API will be available at `http://localhost` (port 80).\r\n\r\n### 2. Manual Setup\r\n\r\n```bash\r\n# Install dependencies\r\nnpm install\r\n\r\n# Setup database (PostgreSQL required)\r\n# Create database: bpmn_engine\r\n\r\n# Start development server\r\nnpm run start:dev\r\n```\r\n\r\n## 📖 Usage\r\n\r\n### Deploy a Process Definition\r\n\r\n```typescript\r\nimport { DeploymentService } from '@alirezaaminzadeh/nest-bpmn-engine';\r\n\r\nconst bpmnXml = `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\r\n<definitions xmlns=\"http://www.omg.org/spec/BPMN/20100524/MODEL\">\r\n  <process id=\"approval-process\" name=\"Approval Process\" isExecutable=\"true\">\r\n    <startEvent id=\"start\"/>\r\n    <userTask id=\"review\" name=\"Review Request\"/>\r\n    <endEvent id=\"end\"/>\r\n  </process>\r\n</definitions>`;\r\n\r\nconst deployment = await deploymentService.deployProcess({\r\n  bpmnXml,\r\n  category: 'approvals',\r\n  deployedBy: 'admin',\r\n});\r\n```\r\n\r\n### Start a Process Instance\r\n\r\n```typescript\r\nimport { ProcessService } from '@alirezaaminzadeh/nest-bpmn-engine';\r\n\r\nconst instance = await processService.startProcess('approval-process', {\r\n  businessKey: 'REQ-2024-001',\r\n  variables: {\r\n    requestId: '12345',\r\n    amount: 1000,\r\n    requestor: 'john.doe',\r\n  },\r\n  startedBy: 'system',\r\n});\r\n```\r\n\r\n### Manage Tasks\r\n\r\n```typescript\r\nimport { TaskService } from '@alirezaaminzadeh/nest-bpmn-engine';\r\n\r\n// List tasks assigned to me\r\nconst tasks = await taskService.getAllTasks('john.doe', TaskState.ACTIVE);\r\n\r\n// Claim a task\r\nawait taskService.claimTask(taskId, { assignee: 'john.doe' });\r\n\r\n// Complete a task\r\nawait taskService.completeTask(taskId, {\r\n  variables: { approved: true, comments: 'Approved' },\r\n});\r\n```\r\n\r\n## 🏗️ Architecture\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────────┐\r\n│                     Client Applications                       │\r\n└────────────────────────────┬────────────────────────────────┘\r\n                             │\r\n                ┌────────────▼────────────┐\r\n                │   NestJS REST API       │\r\n                │   (Swagger Docs)        │\r\n                └────────────┬────────────┘\r\n                             │\r\n        ┌────────────────────┼────────────────────┐\r\n        │                    │                    │\r\n┌───────▼────────┐  ┌────────▼────────┐  ┌───────▼────────┐\r\n│  BPMN Engine   │  │  Process Mgmt   │  │   Task Mgmt    │\r\n│   Executor     │  │    Service      │  │    Service     │\r\n└───────┬────────┘  └────────┬────────┘  └───────┬────────┘\r\n        │                    │                    │\r\n        └────────────────────┼────────────────────┘\r\n                             │\r\n        ┌────────────────────┼────────────────────┐\r\n        │                    │                    │\r\n┌───────▼────────┐  ┌────────▼────────┐  ┌───────▼────────┐\r\n│   PostgreSQL   │  │      Redis      │  │   Bull Queue   │\r\n│  (Process DB)  │  │   (Cache/Jobs)  │  │  (Async Tasks) │\r\n└────────────────┘  └─────────────────┘  └────────────────┘\r\n```\r\n\r\n## 📡 API Endpoints\r\n\r\n### Deployments\r\n- `POST /api/v1/deployments` - Deploy process definition\r\n- `GET /api/v1/deployments` - List all deployments\r\n- `GET /api/v1/deployments/:id` - Get deployment details\r\n- `DELETE /api/v1/deployments/:id` - Delete deployment\r\n\r\n### Processes\r\n- `POST /api/v1/processes/:key/start` - Start process instance\r\n- `GET /api/v1/processes/instances` - List instances\r\n- `GET /api/v1/processes/instances/:id` - Get instance details\r\n- `POST /api/v1/processes/instances/:id/suspend` - Suspend instance\r\n- `POST /api/v1/processes/instances/:id/resume` - Resume instance\r\n- `DELETE /api/v1/processes/instances/:id` - Terminate instance\r\n\r\n### Tasks\r\n- `GET /api/v1/tasks` - List tasks (with filters)\r\n- `GET /api/v1/tasks/:id` - Get task details\r\n- `POST /api/v1/tasks/:id/claim` - Claim task\r\n- `POST /api/v1/tasks/:id/complete` - Complete task\r\n- `POST /api/v1/tasks/:id/delegate` - Delegate task\r\n\r\n### Monitoring\r\n- `GET /api/v1/health` - Health check\r\n- `GET /api/v1/metrics` - Prometheus metrics\r\n\r\nFull API documentation available at `/api/docs` when running the server.\r\n\r\n## 🧪 Testing\r\n\r\n```bash\r\n# Unit tests\r\nnpm run test\r\n\r\n# E2E tests\r\nnpm run test:e2e\r\n\r\n# Test coverage\r\nnpm run test:cov\r\n```\r\n\r\n## 🔧 Configuration\r\n\r\nEnvironment variables (see `.env.example`):\r\n\r\n```env\r\n# Application\r\nNODE_ENV=development\r\nPORT=3000\r\nAPI_PREFIX=api/v1\r\n\r\n# Database\r\nDATABASE_HOST=postgres\r\nDATABASE_PORT=5432\r\nDATABASE_NAME=bpmn_engine\r\nDATABASE_USER=bpmn_user\r\nDATABASE_PASSWORD=your_password\r\n\r\n# Redis\r\nREDIS_HOST=redis\r\nREDIS_PORT=6379\r\nREDIS_PASSWORD=your_redis_password\r\n\r\n# Security\r\nJWT_SECRET=your_secret\r\nRATE_LIMIT_TTL=60\r\nRATE_LIMIT_MAX=100\r\n\r\n# Logging\r\nLOG_LEVEL=info\r\nLOG_DIR=logs\r\n```\r\n\r\n## 🐳 Docker Support\r\n\r\n### Development\r\n```bash\r\ndocker-compose up -d\r\n```\r\n\r\n### Production\r\n```bash\r\ndocker build -f docker/Dockerfile -t bpmn-engine:latest .\r\ndocker run -p 3000:3000 bpmn-engine:latest\r\n```\r\n\r\n## 📊 Monitoring\r\n\r\n### Prometheus Metrics\r\n\r\nAccess metrics at `http://localhost:3000/api/v1/metrics`\r\n\r\nAvailable metrics:\r\n- `bpmn_process_started_total` - Total processes started\r\n- `bpmn_process_completed_total` - Total processes completed\r\n- `bpmn_process_failed_total` - Total processes failed\r\n- `bpmn_active_processes` - Currently active processes\r\n- `bpmn_task_created_total` - Total tasks created\r\n- `bpmn_task_completed_total` - Total tasks completed\r\n- `bpmn_process_duration_seconds` - Process execution duration\r\n\r\n### Logs\r\n\r\nLogs are stored in the `logs/` directory:\r\n- `application-YYYY-MM-DD.log` - All logs\r\n- `error-YYYY-MM-DD.log` - Error logs only\r\n\r\n## 🔒 Security\r\n\r\n- ✅ Input validation with class-validator\r\n- ✅ SQL injection prevention (parameterized queries)\r\n- ✅ XSS protection\r\n- ✅ Rate limiting (100 req/min per IP)\r\n- ✅ Helmet.js security headers\r\n- ✅ CORS configuration\r\n- ✅ Environment-based secrets\r\n- ✅ Non-root Docker user\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Please follow these steps:\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## 👤 Author\r\n\r\n**Alireza Aminzadeh**\r\n\r\n- Email: alireza.aminzadeh@hotmail.com\r\n- GitHub: [@syeedalireza](https://github.com/syeedalireza)\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- Built with [NestJS](https://nestjs.com/)\r\n- BPMN engine powered by [bpmn-engine](https://github.com/paed01/bpmn-engine)\r\n- Inspired by enterprise workflow orchestration needs\r\n\r\n## 📈 Roadmap\r\n\r\n- [ ] BPMN 2.0 Timer Events\r\n- [ ] Message and Signal Events\r\n- [ ] Multi-instance activities\r\n- [ ] DMN (Decision Model and Notation) support\r\n- [ ] Process migration tools\r\n- [ ] Advanced analytics dashboard\r\n- [ ] GraphQL API support\r\n\r\n## 💬 Support\r\n\r\nFor issues, questions, or contributions:\r\n- 🐛 [Report a bug](https://github.com/syeedalireza/nest-bpmn-engine/issues)\r\n- 💡 [Request a feature](https://github.com/syeedalireza/nest-bpmn-engine/issues)\r\n- 📧 Email: alireza.aminzadeh@hotmail.com\r\n\r\n---\r\n\r\nMade with ❤️ by [Alireza Aminzadeh](https://github.com/syeedalireza)\r\n","readmeFilename":"README.md","_rev":"1-0e4ee5a9d185481c81b4695dc3c05d6b"}