Add job result storage functionality

Author: noxify

.changeset/clean-brooms-cut.md

@@ -0,0 +1,42 @@
+---
+"@vorsteh-queue/core": minor
+"@vorsteh-queue/adapter-drizzle": minor
+"@vorsteh-queue/adapter-prisma": minor
+---
+
+Add job result storage functionality
+
+Job handlers can now return values that are automatically stored in the database and made available through events and job records.
+
+**New Features:**
+
+- Added optional `result` field to job records for storing handler return values
+- Enhanced `BaseJob` interface with generic result type parameter
+- Updated all adapters (Drizzle, Prisma, Memory) to support result storage
+- Results are accessible in `job:completed` events and job queries
+
+**Database Changes:**
+
+- Added `result` JSONB column to queue_jobs table in both Drizzle and Prisma schemas
+- Column is optional and backward compatible with existing jobs
+
+**API Changes:**
+
+- `JobHandler<TPayload, TResult>` now supports result type parameter
+- `updateJobStatus()` method accepts optional result parameter
+- Job completion events include result data
+
+**Examples:**
+
+```typescript
+// Handler with typed result
+queue.register<EmailPayload, EmailResult>("send-email", async (job) => {
+  await sendEmail(job.payload)
+  return { messageId: "msg_123", sent: true } // Stored in job.result
+})
+
+// Access results in events
+queue.on("job:completed", (job) => {
+  console.log("Result:", job.result) // { messageId: "msg_123", sent: true }
+})
+```

README.md

@@ -88,6 +88,7 @@ queue.register<EmailPayload, EmailResult>("send-email", async (job) => {
   // Send email logic here
   await sendEmail(job.payload)
 
+  // Return result - will be stored in job.result field
   return { 
     messageId: "msg_123", 
     sent: true 
@@ -196,6 +197,49 @@ await queue.add("business-task", payload, {
 4. **Simple and predictable** - no runtime timezone complexity
 5. **Server timezone independent** - works consistently across environments
 
+## Job Results
+
+Job handlers can return results that are automatically stored and made available:
+
+```typescript
+interface ProcessResult {
+  processed: number
+  errors: string[]
+  duration: number
+}
+
+queue.register<{ items: string[] }, ProcessResult>("process-data", async (job) => {
+  const startTime = Date.now()
+  const errors: string[] = []
+  let processed = 0
+
+  for (const item of job.payload.items) {
+    try {
+      await processItem(item)
+      processed++
+    } catch (error) {
+      errors.push(`Failed to process ${item}: ${error.message}`)
+    }
+  }
+
+  // Return result - automatically stored in job.result field
+  return {
+    processed,
+    errors,
+    duration: Date.now() - startTime
+  }
+})
+
+// Access results in events
+queue.on("job:completed", (job) => {
+  const result = job.result as ProcessResult
+  console.log(`Processed ${result.processed} items in ${result.duration}ms`)
+  if (result.errors.length > 0) {
+    console.warn(`Errors: ${result.errors.join(", ")}`)
+  }
+})
+```
+
 ## Progress Tracking
 
 ```typescript
@@ -235,6 +279,7 @@ queue.on("job:processing", (job) => {
 
 queue.on("job:completed", (job) => {
   console.log(`🎉 Job ${job.name} completed successfully`)
+  console.log(`📊 Result:`, job.result) // Access job result
 })
 
 queue.on("job:failed", (job) => {

examples/README.md

@@ -5,22 +5,87 @@ Standalone examples demonstrating different configurations of vorsteh-queue.
 ## Available Examples
 
 ### [drizzle-pg](./drizzle-pg/)
+
 Basic usage with Drizzle ORM and node-postgres driver.
+
 - Simple job processing
 - Priority handling
 - Delayed jobs
 
+### [drizzle-pglite](./drizzle-pglite/)
+
+Zero-setup example using Drizzle ORM with PGlite (embedded PostgreSQL).
+
+- No external database required
+- Multiple job types with results
+- Progress tracking
+- Event system
+
 ### [drizzle-postgres](./drizzle-postgres/)
+
 Advanced usage with Drizzle ORM and postgres.js driver.
+
 - Multiple job types
 - Recurring jobs
 - Event handling
 - Queue monitoring
 
+### [event-system](./event-system/)
+
+Comprehensive event monitoring and statistics.
+
+- Job lifecycle events
+- Real-time statistics
+- Performance monitoring
+- Error tracking
+
+### [pm2-workers](./pm2-workers/)
+
+Production deployment with PM2 process manager.
+
+- Multiple worker processes
+- Process management
+- Scaling configuration
+- Production monitoring
+
+### [prisma-client](./prisma-client/)
+
+Prisma ORM with PostgreSQL using driver adapters.
+
+- Type-safe database operations
+- Modern Prisma client w/o rust engine
+- Job management
+
+### [prisma-client-js](./prisma-client-js/)
+
+Prisma ORM with traditional prisma-client-js provider.
+
+- Legacy Prisma setup
+- PostgreSQL integration
+- Job management
+
+### [progress-tracking](./progress-tracking/)
+
+Real-time job progress tracking demonstration.
+
+- Progress updates
+- Long-running jobs
+- Progress monitoring
+- Status reporting
+
+### [result-storage](./result-storage/)
+
+Job result storage and retrieval with progress tracking.
+
+- Job return values
+- Result persistence
+- Progress tracking
+- Error handling
+
 ## Quick Start
 
 1. Choose an example directory
 2. Follow the README instructions in that directory
 3. Ensure PostgreSQL is running locally or update the DATABASE_URL
 
-Each example is self-contained and can be used as a starting point for your own implementation.
+Each example is self-contained and can be used as a starting point for your own implementation.

examples/prisma-client-js/prisma/schema.prisma

@@ -24,6 +24,7 @@ model QueueJob {
   completedAt  DateTime? @map("completed_at") @db.Timestamptz(6)
   failedAt     DateTime? @map("failed_at") @db.Timestamptz(6)
   error        Json?     @db.JsonB
+  result       Json?     @db.JsonB
   progress     Int?      @default(0)
   cron         String?   @db.VarChar(255)
   repeatEvery  Int?      @map("repeat_every")

examples/prisma-client/prisma/schema.prisma

@@ -31,6 +31,7 @@ model QueueJob {
   completedAt  DateTime? @map("completed_at") @db.Timestamptz(6)
   failedAt     DateTime? @map("failed_at") @db.Timestamptz(6)
   error        Json?     @db.JsonB
+  result       Json?     @db.JsonB
   progress     Int?      @default(0)
   cron         String?   @db.VarChar(255)
   repeatEvery  Int?      @map("repeat_every")

examples/result-storage/README.md

@@ -0,0 +1,58 @@
+# Result Storage Example
+
+This example demonstrates how to use job results in Vorsteh Queue. Job handlers can return values that are automatically stored in the database and made available through events and job records.
+
+## Features Demonstrated
+
+- **Result Storage**: Job handlers return results that are automatically stored
+- **Type Safety**: Full TypeScript support for job payloads and results
+- **Progress Tracking**: Real-time progress updates during job processing
+- **Error Handling**: Proper error collection and reporting in results
+- **Event Access**: Accessing results through job completion events
+
+## Running the Example
+
+```bash
+pnpm install
+pnpm start
+```
+
+## Key Concepts
+
+### Job Handler Results
+
+```typescript
+interface ProcessDataResult {
+  processed: number
+  failed: number
+  duration: number
+  errors: string[]
+}
+
+queue.register<ProcessDataPayload, ProcessDataResult>("process-data", async (job) => {
+  // Process data...
+  
+  // Return result - automatically stored in job.result field
+  return {
+    processed: 45,
+    failed: 5,
+    duration: 1250,
+    errors: ["Failed to process item-23"]
+  }
+})
+```
+
+### Accessing Results
+
+Results are available in job completion events:
+
+```typescript
+queue.on("job:completed", (job) => {
+  console.log("Job result:", job.result)
+  // Result is typed according to your handler's return type
+})
+```
+
+### Database Storage
+
+Results are stored as JSON in the database `result` field and can be queried later for analytics, debugging, or reporting purposes.

examples/result-storage/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "result-storage-example",
+  "version": "1.0.0",
+  "description": "demonstrating job result storage and retrieval with progress tracking using Drizzle ORM with PGlite (embedded PostgreSQL)",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "db:push": "drizzle-kit push"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.3.5",
+    "@vorsteh-queue/adapter-drizzle": "workspace:*",
+    "@vorsteh-queue/core": "workspace:*",
+    "drizzle-orm": "^0.44.3"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.4",
+    "tsx": "4.20.3",
+    "typescript": "^5.8.3"
+  }
+}

examples/result-storage/src/database.ts

@@ -0,0 +1,10 @@
+import { PGlite } from "@electric-sql/pglite"
+import { drizzle } from "drizzle-orm/pglite"
+
+import * as schema from "./schema"
+
+// Shared embedded database connection
+const client = new PGlite()
+
+export const db = drizzle(client, { schema })
+export { client }