@igniter-js/jobs 0.1.0

package/README.md

@@ -0,0 +1,410 @@
+# @igniter-js/jobs
+
+Type-safe background job processing for TypeScript applications with Redis queues.
+
+## Features
+
+- 🔷 **Full Type Safety** - End-to-end TypeScript inference from job definition to dispatch
+- 🚀 **Builder API** - Fluent, chainable API for defining jobs and queues
+- ⚡ **BullMQ Powered** - Production-ready job processing with Redis
+- 🎯 **Scopes & Actors** - Multi-tenant support with scope and actor tracking
+- 📊 **Real-time Events** - Subscribe to job lifecycle events
+- 🔄 **Cron Jobs** - Built-in scheduled job support
+- 🔍 **Search & Discovery** - Find jobs and queues with powerful filters
+- 📈 **Telemetry Ready** - Optional OpenTelemetry integration
+
+## Installation
+
+```bash
+npm install @igniter-js/jobs bullmq ioredis zod
+```
+
+## Quick Start
+
+### 1. Define Your Queues
+
+```typescript
+import { IgniterQueue } from '@igniter-js/jobs'
+import { z } from 'zod'
+
+const emailQueue = IgniterQueue.create('email')
+  .addJob('sendWelcome', {
+    schema: z.object({
+      email: z.string().email(),
+      name: z.string(),
+    }),
+    handler: async ({ data, log }) => {
+      await log('info', `Sending welcome email to ${data.email}`)
+      await sendEmail(data.email, 'Welcome!', `Hello ${data.name}!`)
+    },
+    options: {
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 1000 },
+    },
+  })
+  .addJob('sendPasswordReset', {
+    schema: z.object({
+      email: z.string().email(),
+      token: z.string(),
+    }),
+    handler: async ({ data }) => {
+      await sendEmail(data.email, 'Password Reset', `Your token: ${data.token}`)
+    },
+  })
+  .addCron('dailyDigest', {
+    pattern: '0 8 * * *', // 8 AM daily
+    handler: async () => {
+      await generateAndSendDailyDigest()
+    },
+  })
+  .build()
+```
+
+### 2. Create Jobs Instance
+
+```typescript
+import { IgniterJobs } from '@igniter-js/jobs'
+import { BullMQAdapter } from '@igniter-js/jobs/adapters'
+import Redis from 'ioredis'
+
+const connection = new Redis()
+
+const jobs = IgniterJobs.create<AppContext>()
+  .withAdapter(
+    BullMQAdapter.create({
+      connection,
+      defaultJobOptions: {
+        removeOnComplete: { count: 100 },
+        removeOnFail: { count: 500 },
+      },
+    })
+  )
+  .withContext(() => ({
+    db: prisma,
+    logger: winston,
+  }))
+  .addQueue(emailQueue)
+  .addQueue(notificationQueue)
+  .addScope('organization', {
+    resolver: (id) => prisma.organization.findUnique({ where: { id } }),
+  })
+  .addActor('user', {
+    resolver: (id) => prisma.user.findUnique({ where: { id } }),
+  })
+  .build()
+```
+
+### 3. Dispatch Jobs
+
+```typescript
+// Simple dispatch with type-safe payload
+await jobs.email.sendWelcome.dispatch({
+  email: 'user@example.com',
+  name: 'John',
+})
+
+// Dispatch with options
+await jobs.email.sendPasswordReset.dispatch(
+  { email: 'user@example.com', token: 'abc123' },
+  {
+    delay: 5000,
+    priority: 10,
+    scope: { type: 'organization', id: 'org-123' },
+    actor: { type: 'user', id: 'user-456' },
+  }
+)
+
+// Schedule for future time
+await jobs.email.sendWelcome.schedule({
+  data: { email: 'user@example.com', name: 'Jane' },
+  at: new Date('2025-01-01T00:00:00Z'),
+})
+```
+
+### 4. Start Workers
+
+```typescript
+const worker = await jobs.worker
+  .forQueues(['email', 'notifications'])
+  .withConcurrency(10)
+  .withLimiter({ max: 100, duration: 60000 })
+  .onIdle(() => console.log('Worker idle'))
+  .start()
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await worker.close()
+  await jobs.shutdown()
+})
+```
+
+## Job Management
+
+### Get Job Info
+
+```typescript
+const job = await jobs.job.get('email', 'job-id')
+console.log(job?.state) // 'completed' | 'failed' | 'waiting' | etc.
+```
+
+### Retry Failed Jobs
+
+```typescript
+// Single job
+await jobs.job.retry('email', 'job-id')
+
+// All failed jobs in queue
+await jobs.queue.retryAll('email')
+```
+
+### Job State
+
+```typescript
+const state = await jobs.job.state('email', 'job-id')
+const progress = await jobs.job.progress('email', 'job-id')
+const logs = await jobs.job.logs('email', 'job-id')
+```
+
+### Promote Delayed Jobs
+
+```typescript
+// Move delayed job to waiting
+await jobs.job.promote('email', 'job-id')
+```
+
+## Queue Management
+
+### Queue Info
+
+```typescript
+const queue = await jobs.queue.retrieve('email')
+console.log(queue.isPaused)
+console.log(queue.jobCounts) // { waiting: 5, active: 2, completed: 100, ... }
+```
+
+### Pause/Resume
+
+```typescript
+await jobs.queue.pause('email')
+await jobs.queue.resume('email')
+```
+
+### Clean Queue
+
+```typescript
+// Remove completed jobs older than 24 hours
+await jobs.queue.clean('email', {
+  status: 'completed',
+  olderThan: 24 * 60 * 60 * 1000,
+})
+
+// Drain waiting/delayed jobs
+await jobs.queue.drain('email')
+
+// Obliterate entire queue
+await jobs.queue.obliterate('email', { force: true })
+```
+
+## Events
+
+### Subscribe to Events
+
+```typescript
+// All events from email queue
+const unsubscribe = await jobs.subscribe('email:*', async (event) => {
+  console.log(event.type, event.data)
+})
+
+// Specific job type events
+await jobs.subscribe('email:sendWelcome:completed', async (event) => {
+  console.log('Welcome email sent:', event.data.jobId)
+})
+
+// Global events
+await jobs.subscribe('*:*:failed', async (event) => {
+  await alertOps('Job failed:', event.data)
+})
+
+// Cleanup
+await unsubscribe()
+```
+
+### Event Types
+
+- `enqueued` - Job added to queue
+- `started` - Job processing started
+- `progress` - Job progress updated
+- `completed` - Job completed successfully
+- `failed` - Job failed
+- `retrying` - Job being retried
+
+## Search
+
+### Find Jobs
+
+```typescript
+const results = await jobs.search.jobs({
+  status: ['failed', 'waiting'],
+  queue: 'email',
+  jobName: 'sendWelcome',
+  scopeId: 'org-123',
+  dateRange: {
+    from: new Date('2025-01-01'),
+    to: new Date('2025-01-31'),
+  },
+  orderBy: 'createdAt:desc',
+  limit: 50,
+})
+```
+
+### Find Queues
+
+```typescript
+const queues = await jobs.search.queues({
+  name: 'email',
+  isPaused: false,
+})
+```
+
+## Scopes & Actors
+
+Scopes and actors enable multi-tenant job processing with tracking.
+
+### Define Scopes
+
+```typescript
+const jobs = IgniterJobs.create()
+  .addScope('organization', {
+    resolver: async (id) => {
+      return prisma.organization.findUnique({ where: { id } })
+    },
+  })
+  .addScope('workspace', {
+    resolver: async (id) => {
+      return prisma.workspace.findUnique({ where: { id } })
+    },
+  })
+  .build()
+```
+
+### Define Actors
+
+```typescript
+const jobs = IgniterJobs.create()
+  .addActor('user', {
+    resolver: async (id) => {
+      return prisma.user.findUnique({ where: { id } })
+    },
+  })
+  .addActor('system', {
+    resolver: async (id) => ({ id, type: 'system' }),
+  })
+  .build()
+```
+
+### Use in Jobs
+
+```typescript
+await jobs.email.sendWelcome.dispatch(
+  { email: 'user@example.com', name: 'John' },
+  {
+    scope: { type: 'organization', id: 'org-123' },
+    actor: { type: 'user', id: 'user-456' },
+  }
+)
+
+// Search by scope/actor
+const orgJobs = await jobs.search.jobs({
+  scopeId: 'org-123',
+  actorId: 'user-456',
+})
+```
+
+## Telemetry
+
+```typescript
+import { TelemetryAdapter } from '@igniter-js/telemetry'
+
+const jobs = IgniterJobs.create()
+  .withTelemetry(
+    TelemetryAdapter.create({
+      serviceName: 'my-service',
+    })
+  )
+  .build()
+```
+
+## Testing
+
+Use the MemoryAdapter for testing:
+
+```typescript
+import { MemoryAdapter } from '@igniter-js/jobs/adapters'
+
+const adapter = MemoryAdapter.create()
+
+const jobs = IgniterJobs.create()
+  .withAdapter(adapter)
+  .addQueue(emailQueue)
+  .build()
+
+// Test job dispatch
+await jobs.email.sendWelcome.dispatch({ email: 'test@example.com', name: 'Test' })
+
+// Verify job was created
+const searchResults = await jobs.search.jobs({ queue: 'email' })
+expect(searchResults.length).toBe(1)
+```
+
+## API Reference
+
+### IgniterQueue
+
+| Method | Description |
+|--------|-------------|
+| `create(name, options?)` | Create queue builder |
+| `addJob(name, config)` | Add job definition |
+| `addCron(name, config)` | Add cron job |
+| `build()` | Build queue configuration |
+
+### IgniterJobs
+
+| Method | Description |
+|--------|-------------|
+| `create<Context>()` | Create jobs builder |
+| `withAdapter(adapter)` | Set adapter |
+| `withContext(factory)` | Set context factory |
+| `addQueue(queue)` | Add queue |
+| `addScope(name, config)` | Add scope definition |
+| `addActor(name, config)` | Add actor definition |
+| `withTelemetry(adapter)` | Enable telemetry |
+| `withDefaults(options)` | Set default job options |
+| `build()` | Build jobs instance |
+
+### Jobs Runtime
+
+| Property/Method | Description |
+|----------------|-------------|
+| `[queueName].[jobName].dispatch(data, options?)` | Dispatch job |
+| `[queueName].[jobName].schedule(params)` | Schedule job |
+| `job.get(queue, id)` | Get job info |
+| `job.state(queue, id)` | Get job state |
+| `job.retry(queue, id)` | Retry job |
+| `job.remove(queue, id)` | Remove job |
+| `job.promote(queue, id)` | Promote delayed job |
+| `queue.retrieve(name)` | Get queue info |
+| `queue.pause(name)` | Pause queue |
+| `queue.resume(name)` | Resume queue |
+| `queue.drain(name)` | Drain queue |
+| `queue.clean(name, options)` | Clean queue |
+| `queue.obliterate(name, options?)` | Delete queue |
+| `queue.retryAll(name)` | Retry all failed |
+| `subscribe(pattern, handler)` | Subscribe to events |
+| `search.jobs(filter)` | Search jobs |
+| `search.queues(filter)` | Search queues |
+| `worker` | Worker builder |
+| `shutdown()` | Shutdown |
+
+## License
+
+MIT