{"_id":"@dot-ready/redis-service-template","_rev":"3-d6ba339b1dfbc0e01b71e2515dd9d017","name":"@dot-ready/redis-service-template","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@dot-ready/redis-service-template","version":"1.0.0","keywords":["redis","microservice","background-processing","queue","worker","template","fault-tolerant"],"author":{"name":"DOTReady Team"},"license":"MIT","_id":"@dot-ready/redis-service-template@1.0.0","maintainers":[{"name":"lucasgazetta","email":"lucas@readyfordot.com"}],"homepage":"https://github.com/DOT-Ready/redis-service-template#readme","bugs":{"url":"https://github.com/DOT-Ready/redis-service-template/issues"},"dist":{"shasum":"9892a67fe25b41b4301bfa840a33c462bf4ba661","tarball":"https://registry.npmjs.org/@dot-ready/redis-service-template/-/redis-service-template-1.0.0.tgz","fileCount":18,"integrity":"sha512-S6ObXCg5j6Ea9mhLq8DwAIGocbGGKuLWVJLpxgTlu7k4fl5M+/QTICbcSAwwW75QS5rVYMS76ELBAVs0bmhSiQ==","signatures":[{"sig":"MEQCIAaC2xMUM8qFukdhTNzC6QQZOdYESTwVMR7ybk4HmmDPAiA0PFTIHMwIeTwk3gcSbT/R0eqESSajsRtIxV7EdR/2AA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":198579},"main":"index.js","engines":{"node":">=18.0.0"},"gitHead":"c66a79ffc456666193edfdb26a9ba3de9e503038","scripts":{"lint":"eslint src/","test":"jest --coverage","lint:fix":"eslint src/ --fix","test:watch":"jest --watch"},"_npmUser":{"name":"lucasgazetta","email":"lucas@readyfordot.com"},"repository":{"url":"git+https://github.com/DOT-Ready/redis-service-template.git","type":"git"},"_npmVersion":"10.9.2","description":"Production-grade framework for building fault-tolerant Redis-based background processing services with zero message loss and complete accountability","directories":{},"_nodeVersion":"22.14.0","dependencies":{"cors":"^2.8.5","uuid":"^9.0.1","dotenv":"^16.3.1","nanoid":"^3.3.7","express":"^4.18.2","ioredis":"^5.3.2","winston":"^3.11.0","winston-daily-rotate-file":"^4.7.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.54.0","supertest":"^6.3.3","redis-mock":"^0.56.3","@types/jest":"^29.5.5"},"peerDependencies":{"mysql2":"^3.6.5"},"peerDependenciesMeta":{"mysql2":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/redis-service-template_1.0.0_1774993057890_0.3288940934233415","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@dot-ready/redis-service-template","version":"1.0.1","keywords":["redis","microservice","background-processing","queue","worker","template","fault-tolerant"],"author":{"name":"DOTReady Team"},"license":"MIT","_id":"@dot-ready/redis-service-template@1.0.1","maintainers":[{"name":"lucasgazetta","email":"lucas@readyfordot.com"}],"homepage":"https://github.com/DOT-Ready/redis-service-template#readme","bugs":{"url":"https://github.com/DOT-Ready/redis-service-template/issues"},"dist":{"shasum":"3330cc192f1723977dae893661d1e2d4ca2056ef","tarball":"https://registry.npmjs.org/@dot-ready/redis-service-template/-/redis-service-template-1.0.1.tgz","fileCount":18,"integrity":"sha512-mIivjJ4VDSsqrnKh5buc+rNbHQKMSI4mNHNW9gZu/BGm7tkr+1E9XVZ0zOZpp2+QDVswtROUdbXe39V5Fj+xiA==","signatures":[{"sig":"MEUCIQCmgiCFzz92jAq2OSbCzFR9SqboZw+68lZZPBKD6O+1xAIgU03aeF/ICkJQfzEf4/f1A+z7JDNsq7A1eRMIIxEeLy0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":198763},"main":"index.js","engines":{"node":">=18.0.0"},"gitHead":"c66a79ffc456666193edfdb26a9ba3de9e503038","scripts":{"lint":"eslint src/","test":"jest --coverage","lint:fix":"eslint src/ --fix","test:watch":"jest --watch"},"_npmUser":{"name":"lucasgazetta","email":"lucas@readyfordot.com"},"repository":{"url":"git+https://github.com/DOT-Ready/redis-service-template.git","type":"git"},"_npmVersion":"10.9.2","description":"Production-grade framework for building fault-tolerant Redis-based background processing services with zero message loss and complete accountability","directories":{},"_nodeVersion":"22.14.0","dependencies":{"cors":"^2.8.5","uuid":"^9.0.1","dotenv":"^16.3.1","nanoid":"^3.3.7","express":"^4.18.2","ioredis":"^5.3.2","winston":"^3.11.0","winston-daily-rotate-file":"^4.7.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.54.0","supertest":"^6.3.3","redis-mock":"^0.56.3","@types/jest":"^29.5.5"},"peerDependencies":{"mysql2":"^3.6.5"},"peerDependenciesMeta":{"mysql2":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/redis-service-template_1.0.1_1774993137161_0.41284592034000256","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@dot-ready/redis-service-template","version":"1.0.2","description":"Production-grade framework for building fault-tolerant Redis-based background processing services with zero message loss and complete accountability","main":"index.js","scripts":{"test":"jest --coverage","test:watch":"jest --watch","lint":"eslint src/","lint:fix":"eslint src/ --fix"},"keywords":["redis","microservice","background-processing","queue","worker","template","fault-tolerant"],"author":{"name":"DOTReady Team"},"license":"MIT","dependencies":{"cors":"^2.8.5","dotenv":"^16.3.1","express":"^4.18.2","ioredis":"^5.3.2","nanoid":"^3.3.7","uuid":"^9.0.1","winston":"^3.11.0","winston-daily-rotate-file":"^4.7.1"},"devDependencies":{"@types/jest":"^29.5.5","eslint":"^8.54.0","jest":"^29.7.0","redis-mock":"^0.56.3","supertest":"^6.3.3"},"engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/DOT-Ready/redis-service-template.git"},"bugs":{"url":"https://github.com/DOT-Ready/redis-service-template/issues"},"homepage":"https://github.com/DOT-Ready/redis-service-template#readme","publishConfig":{"access":"public"},"_id":"@dot-ready/redis-service-template@1.0.2","gitHead":"59d53fae36c10c142d7d55d99ca1bb3038bc0fcb","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-E1lgmenR7inRCNoW2FA4v0v1qHY7sqiZIpOq+e5h2XF1xYviR21i9jcslZ9dyfYzpPm4RCwesy6QK8620XsiAw==","shasum":"22817947b0fa0aaec5e3b1612228375b09e4eefb","tarball":"https://registry.npmjs.org/@dot-ready/redis-service-template/-/redis-service-template-1.0.2.tgz","fileCount":17,"unpackedSize":188122,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFtevxytv3jM8JtxBKyQhIUtqP/2WsZxsJo9uepLoKlUAiEA6sYHVpuzpWe5lAbqTbO858oj/B2yp1ukKdiM0010aUE="}]},"_npmUser":{"name":"lucasgazetta","email":"lucas@readyfordot.com"},"directories":{},"maintainers":[{"name":"lucasgazetta","email":"lucas@readyfordot.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/redis-service-template_1.0.2_1774993323248_0.34363303895236297"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-31T21:37:37.837Z","modified":"2026-03-31T21:42:03.496Z","1.0.0":"2026-03-31T21:37:38.054Z","1.0.1":"2026-03-31T21:38:57.310Z","1.0.2":"2026-03-31T21:42:03.389Z"},"bugs":{"url":"https://github.com/DOT-Ready/redis-service-template/issues"},"author":{"name":"DOTReady Team"},"license":"MIT","homepage":"https://github.com/DOT-Ready/redis-service-template#readme","keywords":["redis","microservice","background-processing","queue","worker","template","fault-tolerant"],"repository":{"type":"git","url":"git+https://github.com/DOT-Ready/redis-service-template.git"},"description":"Production-grade framework for building fault-tolerant Redis-based background processing services with zero message loss and complete accountability","maintainers":[{"name":"lucasgazetta","email":"lucas@readyfordot.com"}],"readme":"# @dot-ready/redis-service-template\n\nProduction-grade framework for building fault-tolerant Redis-based background processing services with zero message loss and complete accountability.\n\n## Features\n\n- **Zero Message Loss** - Triple persistence (Redis, Memory, Disk)\n- **Automatic Recovery** - Handles Redis failures, crashes, and network issues\n- **Complete Accountability** - Track every message from receipt to completion\n- **Worker Pool Management** - Concurrent processing with configurable workers\n- **Smart Retry Logic** - Exponential backoff with dead letter queue\n- **Health Monitoring** - Built-in health checks and auto-recovery\n- **Comprehensive Logging** - Multi-output logging with audit trails\n- **HTTP API** - Built-in health, stats, metrics, and control endpoints\n\n## Installation\n\n```bash\nnpm install @dot-ready/redis-service-template\n```\n\nAdd to your `.npmrc`:\n```\n@dot-ready:registry=https://npm.pkg.github.com\n```\n\n## Quick Start\n\nCreate a new service by extending `BaseRedisService`:\n\n```javascript\nrequire('dotenv').config();\nconst { BaseRedisService } = require('@dot-ready/redis-service-template');\n\nclass MyService extends BaseRedisService {\n  constructor() {\n    super({\n      serviceName: 'my-service',\n      queueName: 'my-service:queue',\n      port: 3001,\n      redis: {\n        host: process.env.REDIS_HOST || 'localhost',\n        port: parseInt(process.env.REDIS_PORT) || 6379,\n      },\n      workers: { maxWorkers: 10 },\n      fallback: { directory: './fallback-models' },\n      logging: { level: 'info', outputs: ['console', 'file'] },\n    });\n  }\n\n  validateServiceModel(model) {\n    if (!model.payload) throw new Error('payload is required');\n  }\n\n  async processModel(model) {\n    // Your business logic here\n    return { success: true };\n  }\n}\n\nconst service = new MyService();\nservice.start();\n```\n\n## Exports\n\n```javascript\nconst {\n  // Core - extend these to build services\n  BaseRedisService,          // Queue-driven service base class\n  BaseEventListenerService,  // Redis keyspace event listener base class\n\n  // Core components (auto-initialized by BaseRedisService)\n  ModelTracker,              // In-memory model tracking with audit trail\n  FallbackManager,           // Disk persistence fallback\n  WorkerPoolManager,         // Concurrent processing pool\n  HealthMonitor,             // Component health monitoring\n  ProgressTracker,           // Cross-instance coordination\n\n  // Services (usable standalone or via BaseRedisService)\n  RedisManager,              // Enhanced ioredis wrapper\n  Logger,                    // Winston-based structured logging\n  ConfigManager,             // Hierarchical configuration\n  ExpressServer,             // HTTP API for monitoring/control\n  MySQLService,              // MySQL connection pool (optional)\n\n  // Utilities\n  UidGenerator,              // Traceable UID generation\n} = require('@dot-ready/redis-service-template');\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│           Express HTTP API                  │\n│     /health /stats /metrics /pause /resume  │\n└──────────────────┬──────────────────────────┘\n                   │\n┌──────────────────┴──────────────────────────┐\n│           BaseRedisService                  │\n│         (Main BRPOP Processing Loop)        │\n└──────────────────┬──────────────────────────┘\n                   │\n        ┌──────────┼──────────┬───────────────┐\n        │          │          │               │\n┌───────▼──────┐ ┌─▼──────┐ ┌▼──────────┐ ┌─▼────────┐\n│ModelTracker  │ │Worker  │ │Fallback   │ │Health    │\n│(In-Memory)   │ │Pool    │ │Manager    │ │Monitor   │\n└──────────────┘ └────────┘ │(Disk)     │ └──────────┘\n                             └───────────┘\n```\n\n## What You Implement\n\nWhen extending `BaseRedisService`, you only need to implement two methods:\n\n| Method | Purpose |\n|---|---|\n| `validateServiceModel(model)` | Validate the model's payload before processing |\n| `processModel(model)` | Your actual business logic |\n\nEverything else (queue consumption, retry logic, disk persistence, health monitoring, logging, HTTP API) is handled by the framework.\n\n## Built-in HTTP Endpoints\n\nEvery service automatically gets:\n\n| Endpoint | Method | Description |\n|---|---|---|\n| `/health` | GET | Health status (200 if healthy, 503 if not) |\n| `/stats` | GET | Processing statistics |\n| `/metrics` | GET | Prometheus-format metrics |\n| `/models` | GET | Model tracker stats |\n| `/models/:uid` | GET | Detailed model audit report |\n| `/workers` | GET | Worker pool status |\n| `/fallback` | GET | Disk fallback stats |\n| `/config` | GET | Sanitized configuration |\n| `/dead-letter` | GET | Dead letter queue count |\n| `/completed` | GET | Paginated completed models |\n| `/pause` | POST | Pause processing |\n| `/resume` | POST | Resume processing |\n\n## Configuration\n\nConfiguration is loaded in this priority order:\n1. Constructor config (highest)\n2. Environment variables\n3. `config/default.json` in your project root\n4. Package defaults (lowest)\n\n### Key Environment Variables\n\n```bash\nSERVICE_NAME=my-service\nQUEUE_NAME=my-service:queue\nPORT=3001\n\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_DB=0\n\nMAX_CONCURRENT_JOBS=10\nMAX_RETRIES=3\nRETRY_DELAY=1000\nMAX_RETRY_DELAY=60000\n\nFALLBACK_DIR=./fallback-models\nLOG_LEVEL=info\nHEALTH_CHECK_INTERVAL=30000\n```\n\n## Model Structure\n\nEvery message follows this structure:\n\n```javascript\n{\n  uid: \"unique-identifier\",\n  service_type: \"service-name\",\n  queue_name: \"queue:name\",\n  created_at: \"2024-01-01T00:00:00Z\",\n  retry_count: 0,\n  max_retries: 3,\n  status: \"pending\",\n  priority: \"normal\",\n  payload: {\n    // Service-specific data\n  },\n  wildcard: {},\n  errors: [],\n  checkpoints: []\n}\n```\n\n## Testing\n\n```bash\nnpm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}