Merge pull request #10 from noxify/store-result

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 }
+})
+```

.changeset/timeout-and-poll-interval.md

@@ -0,0 +1,58 @@
+---
+"@vorsteh-queue/core": minor
+"@vorsteh-queue/adapter-drizzle": minor
+"@vorsteh-queue/adapter-prisma": minor
+---
+
+Add configurable job timeouts and rename `processingInterval` to `pollInterval`.
+
+**New Features:**
+
+- **Configurable job timeouts**: Set `timeout: number` for specific timeout or `timeout: false` to disable timeout completely
+- **Job-specific timeout override**: Individual jobs can override queue default timeout settings
+- **Timeout field storage**: Job timeout configuration is now stored in job records for proper handling
+
+**Breaking Changes:**
+
+- **Renamed `processingInterval` to `pollInterval`**: More accurately describes the interval between queue polling cycles
+- **Database schema changes**: Added `timeout` column to queue_jobs table (JSONB field, nullable)
+
+**Migration Guide:**
+
+```typescript
+// Before
+const queue = new Queue(adapter, {
+  name: "my-queue",
+  processingInterval: 1000, // OLD
+})
+
+// After
+const queue = new Queue(adapter, {
+  name: "my-queue",
+  pollInterval: 1000, // NEW
+})
+
+// New timeout features
+await queue.add("long-job", payload, { timeout: false }) // Disable timeout
+await queue.add("quick-job", payload, { timeout: 5000 }) // 5 second timeout
+```
+
+**Database Migration Required:**
+
+- **Drizzle users**: Run migrations to add `timeout` column
+- **Prisma users**: Run `prisma db push` or `prisma migrate` to apply schema changes
+
+**Examples:**
+
+```typescript
+// Disable timeout for long-running data processing
+await queue.add("process-large-dataset", data, { timeout: false })
+
+// Set specific timeout for API calls
+await queue.add("external-api-call", params, { timeout: 30000 })
+
+// Use default timeout (30 seconds) - no change needed
+await queue.add("normal-job", payload)
+```
+
+This release improves queue configuration clarity and provides flexible timeout control for different job types.

.github/workflows/ci.yml

@@ -100,12 +100,12 @@ jobs:
         run: pnpm test:core
 
       - name: Test Drizzle PostgreSQL (PGlite)
-        run: pnpm test:drizzle-postgres
+        run: pnpm test:drizzle
 
       - name: Test Prisma (Testcontainers - Postgres)
         run: |
           pnpm -F adapter-prisma prisma:generate
-          pnpm test:prisma-postgres
+          pnpm test:prisma
         env:
           # Ensure Docker is available for Testcontainers
           TESTCONTAINERS_RYUK_DISABLED: true

.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Deploy production docs
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - "changeset-release/main"
+
+jobs:
+  deploy-production:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./.github/setup
+
+      - name: Install Vercel CLI
+        run: npm install --global vercel@latest
+      - name: Deploy to Vercel
+        run: vercel --prod --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}

README.md

@@ -25,11 +25,6 @@
 │   ├── adapter-drizzle/     # Drizzle ORM adapter (PostgreSQL)
 │   └── adapter-prisma/      # Prisma ORM adapter (PostgreSQL)
 ├── examples/                # Standalone usage examples
-│   ├── drizzle-pg/         # Drizzle + node-postgres
-│   ├── drizzle-postgres/   # Drizzle + postgres.js
-│   ├── progress-tracking/  # Real-time progress updates
-│   ├── event-system/       # Comprehensive event monitoring
-│   └── pm2-workers/        # Production deployment with PM2
 └── tooling/                # Shared development tools
 ```
 
@@ -84,21 +79,22 @@ const queue = new Queue(new PostgresPrismaQueueAdapter(prisma), { name: "my-queu
 // Register job handlers
 queue.register<EmailPayload, EmailResult>("send-email", async (job) => {
   console.log(`Sending email to ${job.payload.to}`)
-  
+
   // Send email logic here
   await sendEmail(job.payload)
-  
-  return { 
-    messageId: "msg_123", 
-    sent: true 
+
+  // Return result - will be stored in job.result field
+  return {
+    messageId: "msg_123",
+    sent: true,
   }
 })
 
 // Add jobs
-await queue.add("send-email", { 
-  to: "[email protected]", 
-  subject: "Welcome!", 
-  body: "Welcome to our service!" 
+await queue.add("send-email", {
+  to: "[email protected]",
+  subject: "Welcome!",
+  body: "Welcome to our service!",
 })
 await queue.add(
   "send-email",
@@ -115,14 +111,7 @@ queue.start()
 
 ## Examples
 
-Check out the [examples directory](./examples/) for complete, runnable examples:
-
-- **[drizzle-pg](./examples/drizzle-pg/)** - Basic example using Drizzle ORM with node-postgres (pg)
-- **[drizzle-pglite](./examples/drizzle-pglite/)** - Zero-setup example using Drizzle ORM with PGlite (embedded PostgreSQL)
-- **[drizzle-postgres](./examples/drizzle-postgres/)** - Advanced example using Drizzle ORM with postgres.js and recurring jobs
-- **[event-system](./examples/event-system/)** - Comprehensive event monitoring and statistics using Drizzle ORM with postgres.js
-- **[pm2-workers](./examples/pm2-workers/)** - Manage multiple Vorsteh Queues with PM2 using Drizzle ORM with postgres.js
-- **[progress-tracking](./examples/progress-tracking/)** - Real-time job progress tracking using Drizzle ORM with postgres.js
+Check out the [examples directory](./examples/) for complete, runnable examples.
 
 > **Note**: All examples demonstrate the UTC-first timezone approach and automatic job cleanup features.
 
@@ -196,6 +185,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 +267,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,7 +24,9 @@ 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)
+  timeout      Json?     @db.JsonB
   cron         String?   @db.VarChar(255)
   repeatEvery  Int?      @map("repeat_every")
   repeatLimit  Int?      @map("repeat_limit")

examples/prisma-client/prisma/schema.prisma

@@ -31,7 +31,9 @@ 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)
+  timeout      Json?     @db.JsonB
   cron         String?   @db.VarChar(255)
   repeatEvery  Int?      @map("repeat_every")
   repeatLimit  Int?      @map("repeat_limit")