@objectstack/service-queue 4.0.3 → 4.0.5

package/README.md

@@ -0,0 +1,453 @@
+# @objectstack/service-queue
+
+Queue Service for ObjectStack — implements `IQueueService` with in-memory and BullMQ adapters.
+
+## Features
+
+- **Multiple Adapters**: In-memory (development) and BullMQ/Redis (production)
+- **Job Queues**: Organize work into named queues with priorities
+- **Worker Pools**: Process jobs concurrently with configurable workers
+- **Retry Logic**: Automatic retry with exponential backoff
+- **Job Scheduling**: Delay job execution or schedule for future
+- **Progress Tracking**: Track job progress and completion
+- **Job Events**: Listen to job lifecycle events (active, completed, failed)
+- **Rate Limiting**: Control job processing rate
+
+## Installation
+
+```bash
+pnpm add @objectstack/service-queue
+```
+
+For BullMQ adapter (production):
+```bash
+pnpm add bullmq ioredis
+```
+
+## Basic Usage
+
+```typescript
+import { defineStack } from '@objectstack/spec';
+import { ServiceQueue } from '@objectstack/service-queue';
+
+const stack = defineStack({
+  services: [
+    ServiceQueue.configure({
+      adapter: 'memory', // or 'bullmq'
+      defaultQueue: 'default',
+    }),
+  ],
+});
+```
+
+## Configuration
+
+### In-Memory Adapter (Development)
+
+```typescript
+ServiceQueue.configure({
+  adapter: 'memory',
+  concurrency: 5, // Max concurrent jobs
+});
+```
+
+### BullMQ Adapter (Production)
+
+```typescript
+ServiceQueue.configure({
+  adapter: 'bullmq',
+  redis: {
+    host: 'localhost',
+    port: 6379,
+    password: process.env.REDIS_PASSWORD,
+  },
+  queues: {
+    default: { concurrency: 10 },
+    email: { concurrency: 5, rateLimit: { max: 100, duration: 60000 } },
+    reports: { concurrency: 2 },
+  },
+});
+```
+
+## Service API
+
+```typescript
+// Get queue service
+const queue = kernel.getService<IQueueService>('queue');
+```
+
+### Adding Jobs
+
+```typescript
+// Add a simple job
+await queue.add('email', 'send_welcome', {
+  to: 'user@example.com',
+  template: 'welcome',
+});
+
+// Add job with options
+await queue.add('reports', 'generate_monthly', {
+  month: '2024-01',
+  format: 'pdf',
+}, {
+  priority: 1, // Higher number = higher priority
+  attempts: 3, // Retry up to 3 times
+  backoff: {
+    type: 'exponential',
+    delay: 1000,
+  },
+});
+
+// Add delayed job (runs in 1 hour)
+await queue.add('notifications', 'reminder', {
+  userId: '123',
+  message: 'Don't forget!',
+}, {
+  delay: 3600000, // 1 hour in milliseconds
+});
+
+// Schedule job for specific time
+await queue.add('cleanup', 'old_files', {}, {
+  timestamp: new Date('2024-12-31T23:59:59Z').getTime(),
+});
+```
+
+### Processing Jobs
+
+```typescript
+// Register a job processor
+queue.process('email', async (job) => {
+  console.log('Processing email job:', job.data);
+
+  // Access job data
+  const { to, template } = job.data;
+
+  // Update progress
+  await job.updateProgress(25);
+
+  // Send email
+  await sendEmail(to, template);
+
+  await job.updateProgress(100);
+
+  // Return result
+  return { sent: true, messageId: 'msg_123' };
+});
+
+// Process with concurrency
+queue.process('reports', 5, async (job) => {
+  // Up to 5 reports generated concurrently
+  return await generateReport(job.data);
+});
+
+// Process with named handler
+queue.process('default', 'calculate_metrics', async (job) => {
+  return await calculateMetrics(job.data);
+});
+```
+
+### Job Management
+
+```typescript
+// Get job by ID
+const job = await queue.getJob('email', 'job_abc123');
+
+// Get job status
+const status = await job.getState();
+// 'waiting' | 'active' | 'completed' | 'failed' | 'delayed'
+
+// Remove job
+await queue.removeJob('email', 'job_abc123');
+
+// Retry failed job
+await queue.retryJob('email', 'job_abc123');
+
+// Get job result
+const result = await job.returnvalue;
+```
+
+### Queue Operations
+
+```typescript
+// Pause queue (stop processing new jobs)
+await queue.pause('email');
+
+// Resume queue
+await queue.resume('email');
+
+// Clear all jobs in queue
+await queue.clear('email');
+
+// Get queue statistics
+const stats = await queue.getStats('email');
+// {
+//   waiting: 45,
+//   active: 5,
+//   completed: 1250,
+//   failed: 12,
+//   delayed: 3
+// }
+```
+
+## Advanced Features
+
+### Job Events
+
+```typescript
+// Listen to job lifecycle events
+queue.on('email', 'completed', async (job, result) => {
+  console.log(`Email sent: ${result.messageId}`);
+});
+
+queue.on('email', 'failed', async (job, error) => {
+  console.error(`Email failed: ${error.message}`);
+  // Send alert to admin
+});
+
+queue.on('email', 'progress', async (job, progress) => {
+  console.log(`Email progress: ${progress}%`);
+});
+
+queue.on('email', 'active', async (job) => {
+  console.log(`Email job started: ${job.id}`);
+});
+```
+
+### Bulk Operations
+
+```typescript
+// Add multiple jobs at once
+await queue.addBulk('email', [
+  { name: 'send_welcome', data: { to: 'user1@example.com' } },
+  { name: 'send_welcome', data: { to: 'user2@example.com' } },
+  { name: 'send_welcome', data: { to: 'user3@example.com' } },
+]);
+
+// Get multiple jobs
+const jobs = await queue.getJobs('email', ['waiting', 'active']);
+```
+
+### Job Patterns
+
+#### Worker Pattern
+
+```typescript
+// Dedicated worker process
+queue.process('heavy_processing', async (job) => {
+  // CPU-intensive work
+  const result = await processLargeDataset(job.data);
+  return result;
+});
+```
+
+#### Fan-Out Pattern
+
+```typescript
+// Split work across multiple jobs
+await queue.add('orchestrator', 'process_batch', { batchId: '123' });
+
+queue.process('orchestrator', async (job) => {
+  const items = await loadBatchItems(job.data.batchId);
+
+  // Create sub-jobs for each item
+  for (const item of items) {
+    await queue.add('worker', 'process_item', { item });
+  }
+});
+
+queue.process('worker', async (job) => {
+  return await processItem(job.data.item);
+});
+```
+
+#### Priority Queues
+
+```typescript
+// High priority
+await queue.add('tasks', 'urgent', data, { priority: 10 });
+
+// Normal priority
+await queue.add('tasks', 'normal', data, { priority: 5 });
+
+// Low priority
+await queue.add('tasks', 'background', data, { priority: 1 });
+```
+
+### Rate Limiting
+
+```typescript
+// Limit queue to 100 jobs per minute
+ServiceQueue.configure({
+  adapter: 'bullmq',
+  queues: {
+    api_calls: {
+      concurrency: 5,
+      rateLimit: {
+        max: 100,
+        duration: 60000, // 1 minute
+      },
+    },
+  },
+});
+```
+
+### Repeatable Jobs
+
+```typescript
+// Add cron-based repeatable job
+await queue.addRepeatable('cleanup', 'old_sessions', {}, {
+  cron: '0 2 * * *', // Daily at 2 AM
+});
+
+// Add interval-based repeatable job
+await queue.addRepeatable('sync', 'data', {}, {
+  every: 300000, // Every 5 minutes
+});
+
+// Remove repeatable job
+await queue.removeRepeatable('cleanup', 'old_sessions');
+```
+
+## Common Use Cases
+
+### Email Queue
+
+```typescript
+queue.process('email', async (job) => {
+  const { to, subject, body, template } = job.data;
+
+  try {
+    const result = await emailProvider.send({
+      to,
+      subject,
+      html: renderTemplate(template, job.data),
+    });
+
+    return { messageId: result.id, sentAt: new Date() };
+  } catch (error) {
+    // Throw error to trigger retry
+    throw new Error(`Failed to send email: ${error.message}`);
+  }
+});
+
+// Add email job
+await queue.add('email', 'welcome', {
+  to: 'newuser@example.com',
+  template: 'welcome',
+  name: 'John Doe',
+}, {
+  attempts: 3,
+  backoff: { type: 'exponential', delay: 5000 },
+});
+```
+
+### Report Generation
+
+```typescript
+queue.process('reports', async (job) => {
+  const { reportType, userId, dateRange } = job.data;
+
+  await job.updateProgress(10);
+
+  // Fetch data
+  const data = await fetchReportData(reportType, dateRange);
+
+  await job.updateProgress(50);
+
+  // Generate report
+  const report = await generatePDF(data);
+
+  await job.updateProgress(90);
+
+  // Upload to storage
+  const url = await uploadReport(report);
+
+  await job.updateProgress(100);
+
+  // Notify user
+  await notifyUser(userId, { reportUrl: url });
+
+  return { url, size: report.length };
+});
+```
+
+### Webhook Processing
+
+```typescript
+queue.process('webhooks', async (job) => {
+  const { url, payload, headers } = job.data;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Webhook failed: ${response.status}`);
+  }
+
+  return { status: response.status, responseTime: Date.now() - job.timestamp };
+});
+```
+
+## REST API Endpoints
+
+```
+POST   /api/v1/queues/:queue/jobs           # Add job
+GET    /api/v1/queues/:queue/jobs/:id       # Get job
+DELETE /api/v1/queues/:queue/jobs/:id       # Remove job
+POST   /api/v1/queues/:queue/jobs/:id/retry # Retry failed job
+GET    /api/v1/queues/:queue/stats          # Get queue stats
+POST   /api/v1/queues/:queue/pause          # Pause queue
+POST   /api/v1/queues/:queue/resume         # Resume queue
+DELETE /api/v1/queues/:queue                # Clear queue
+```
+
+## Best Practices
+
+1. **Idempotent Jobs**: Design jobs to be safely retried
+2. **Error Handling**: Always handle errors and throw to trigger retry
+3. **Progress Updates**: Update progress for long-running jobs
+4. **Resource Limits**: Set appropriate concurrency limits
+5. **Job Data**: Keep job data small (< 1MB)
+6. **Monitoring**: Track queue metrics and job failure rates
+7. **Cleanup**: Remove completed jobs periodically
+
+## Performance Considerations
+
+- **Concurrency**: Tune based on system resources and external API limits
+- **Rate Limiting**: Prevent overwhelming external services
+- **Job Size**: Keep job payloads small for faster serialization
+- **Redis Connection**: Use connection pooling for BullMQ
+- **Queue Organization**: Use separate queues for different job types
+
+## Contract Implementation
+
+Implements `IQueueService` from `@objectstack/spec/contracts`:
+
+```typescript
+interface IQueueService {
+  add(queue: string, name: string, data: any, options?: JobOptions): Promise<Job>;
+  addBulk(queue: string, jobs: JobDefinition[]): Promise<Job[]>;
+  process(queue: string, handler: JobHandler): void;
+  getJob(queue: string, jobId: string): Promise<Job | null>;
+  removeJob(queue: string, jobId: string): Promise<void>;
+  retryJob(queue: string, jobId: string): Promise<void>;
+  getStats(queue: string): Promise<QueueStats>;
+  pause(queue: string): Promise<void>;
+  resume(queue: string): Promise<void>;
+  clear(queue: string): Promise<void>;
+  on(queue: string, event: JobEvent, handler: EventHandler): void;
+}
+```
+
+## License
+
+Apache-2.0
+
+## See Also
+
+- [BullMQ Documentation](https://docs.bullmq.io/)
+- [@objectstack/spec/contracts](../../spec/src/contracts/)
+- [Queue Patterns Guide](/content/docs/guides/queues/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-queue",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "license": "Apache-2.0",
   "description": "Queue Service for ObjectStack — implements IQueueService with in-memory and BullMQ adapters",
   "type": "module",
@@ -14,13 +14,38 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "4.0.3",
-    "@objectstack/spec": "4.0.3"
+    "@objectstack/core": "4.0.5",
+    "@objectstack/spec": "4.0.5"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "@types/node": "^25.6.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "keywords": [
+    "objectstack",
+    "service",
+    "queue",
+    "jobs",
+    "background"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/services/service-queue"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/service-queue@4.0.3 build /home/runner/work/framework/framework/packages/services/service-queue
-> tsup --config ../../../tsup.config.ts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-ESM dist/index.js     2.78 KB
-ESM dist/index.js.map 8.33 KB
-ESM ⚡️ Build success in 49ms
-CJS dist/index.cjs     3.89 KB
-CJS dist/index.cjs.map 8.90 KB
-CJS ⚡️ Build success in 59ms
-DTS Build start
-DTS ⚡️ Build success in 6379ms
-DTS dist/index.d.ts  3.63 KB
-DTS dist/index.d.cts 3.63 KB

package/CHANGELOG.md

@@ -1,169 +0,0 @@
-# @objectstack/service-queue
-
-## 4.0.3
-
-### Patch Changes
-
-- @objectstack/spec@4.0.3
-- @objectstack/core@4.0.3
-
-## 4.0.2
-
-### Patch Changes
-
-- Updated dependencies [5f659e9]
-  - @objectstack/spec@4.0.2
-  - @objectstack/core@4.0.2
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies [f08ffc3]
-- Updated dependencies [e0b0a78]
-  - @objectstack/spec@4.0.0
-  - @objectstack/core@4.0.0
-
-## 3.3.1
-
-### Patch Changes
-
-- @objectstack/spec@3.3.1
-- @objectstack/core@3.3.1
-
-## 3.3.0
-
-### Patch Changes
-
-- @objectstack/spec@3.3.0
-- @objectstack/core@3.3.0
-
-## 3.2.9
-
-### Patch Changes
-
-- @objectstack/spec@3.2.9
-- @objectstack/core@3.2.9
-
-## 3.2.8
-
-### Patch Changes
-
-- @objectstack/spec@3.2.8
-- @objectstack/core@3.2.8
-
-## 3.2.7
-
-### Patch Changes
-
-- @objectstack/spec@3.2.7
-- @objectstack/core@3.2.7
-
-## 3.2.6
-
-### Patch Changes
-
-- @objectstack/spec@3.2.6
-- @objectstack/core@3.2.6
-
-## 3.2.5
-
-### Patch Changes
-
-- @objectstack/spec@3.2.5
-- @objectstack/core@3.2.5
-
-## 3.2.4
-
-### Patch Changes
-
-- @objectstack/spec@3.2.4
-- @objectstack/core@3.2.4
-
-## 3.2.3
-
-### Patch Changes
-
-- @objectstack/spec@3.2.3
-- @objectstack/core@3.2.3
-
-## 3.2.2
-
-### Patch Changes
-
-- Updated dependencies [46defbb]
-  - @objectstack/spec@3.2.2
-  - @objectstack/core@3.2.2
-
-## 3.2.1
-
-### Patch Changes
-
-- Updated dependencies [850b546]
-  - @objectstack/spec@3.2.1
-  - @objectstack/core@3.2.1
-
-## 3.2.0
-
-### Patch Changes
-
-- Updated dependencies [5901c29]
-  - @objectstack/spec@3.2.0
-  - @objectstack/core@3.2.0
-
-## 3.1.1
-
-### Patch Changes
-
-- Updated dependencies [953d667]
-  - @objectstack/spec@3.1.1
-  - @objectstack/core@3.1.1
-
-## 3.1.0
-
-### Patch Changes
-
-- Updated dependencies [0088830]
-  - @objectstack/spec@3.1.0
-  - @objectstack/core@3.1.0
-
-## 3.0.11
-
-### Patch Changes
-
-- Updated dependencies [92d9d99]
-  - @objectstack/spec@3.0.11
-  - @objectstack/core@3.0.11
-
-## 3.0.10
-
-### Patch Changes
-
-- Updated dependencies [d1e5d31]
-  - @objectstack/spec@3.0.10
-  - @objectstack/core@3.0.10
-
-## 3.0.9
-
-### Patch Changes
-
-- Updated dependencies [15e0df6]
-  - @objectstack/spec@3.0.9
-  - @objectstack/core@3.0.9
-
-## 3.0.8
-
-### Patch Changes
-
-- Updated dependencies [5a968a2]
-  - @objectstack/spec@3.0.8
-  - @objectstack/core@3.0.8
-
-## 3.0.7
-
-### Patch Changes
-
-- Updated dependencies [0119bd7]
-- Updated dependencies [5426bdf]
-  - @objectstack/spec@3.0.7
-  - @objectstack/core@3.0.7

package/src/bullmq-queue-adapter.ts

@@ -1,58 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { IQueueService, QueuePublishOptions, QueueHandler } from '@objectstack/spec/contracts';
-
-/**
- * Configuration for the BullMQ queue adapter.
- */
-export interface BullMQQueueAdapterOptions {
-  /** Redis connection URL (e.g. 'redis://localhost:6379') */
-  redisUrl: string;
-  /** Default job options */
-  defaultJobOptions?: {
-    /** Number of retry attempts */
-    attempts?: number;
-    /** Backoff strategy */
-    backoff?: { type: 'fixed' | 'exponential'; delay: number };
-  };
-}
-
-/**
- * BullMQ queue adapter skeleton implementing IQueueService.
- *
- * This is a placeholder for future BullMQ integration.
- * Concrete implementation will use the `bullmq` package.
- *
- * @example
- * ```ts
- * const queue = new BullMQQueueAdapter({ redisUrl: 'redis://localhost:6379' });
- * await queue.publish('orders', { orderId: 123 });
- * ```
- */
-export class BullMQQueueAdapter implements IQueueService {
-  private readonly redisUrl: string;
-
-  constructor(options: BullMQQueueAdapterOptions) {
-    this.redisUrl = options.redisUrl;
-  }
-
-  async publish<T = unknown>(_queue: string, _data: T, _options?: QueuePublishOptions): Promise<string> {
-    throw new Error(`BullMQQueueAdapter not yet implemented (url: ${this.redisUrl})`);
-  }
-
-  async subscribe<T = unknown>(_queue: string, _handler: QueueHandler<T>): Promise<void> {
-    throw new Error('BullMQQueueAdapter not yet implemented');
-  }
-
-  async unsubscribe(_queue: string): Promise<void> {
-    throw new Error('BullMQQueueAdapter not yet implemented');
-  }
-
-  async getQueueSize(_queue: string): Promise<number> {
-    throw new Error('BullMQQueueAdapter not yet implemented');
-  }
-
-  async purge(_queue: string): Promise<void> {
-    throw new Error('BullMQQueueAdapter not yet implemented');
-  }
-}

package/src/index.ts

@@ -1,8 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-export { QueueServicePlugin } from './queue-service-plugin.js';
-export type { QueueServicePluginOptions } from './queue-service-plugin.js';
-export { MemoryQueueAdapter } from './memory-queue-adapter.js';
-export type { MemoryQueueAdapterOptions } from './memory-queue-adapter.js';
-export { BullMQQueueAdapter } from './bullmq-queue-adapter.js';
-export type { BullMQQueueAdapterOptions } from './bullmq-queue-adapter.js';

package/src/memory-queue-adapter.test.ts

@@ -1,87 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect } from 'vitest';
-import { MemoryQueueAdapter } from './memory-queue-adapter';
-import type { IQueueService, QueueMessage } from '@objectstack/spec/contracts';
-
-describe('MemoryQueueAdapter', () => {
-  it('should implement IQueueService contract', () => {
-    const queue: IQueueService = new MemoryQueueAdapter();
-    expect(typeof queue.publish).toBe('function');
-    expect(typeof queue.subscribe).toBe('function');
-    expect(typeof queue.unsubscribe).toBe('function');
-    expect(typeof queue.getQueueSize).toBe('function');
-    expect(typeof queue.purge).toBe('function');
-  });
-
-  it('should publish and deliver to subscriber', async () => {
-    const queue = new MemoryQueueAdapter();
-    const received: QueueMessage[] = [];
-
-    await queue.subscribe('orders', async (msg) => {
-      received.push(msg);
-    });
-
-    const id = await queue.publish('orders', { orderId: 123 });
-    expect(id).toBe('msg-1');
-    expect(received).toHaveLength(1);
-    expect(received[0].data).toEqual({ orderId: 123 });
-    expect(received[0].attempts).toBe(1);
-  });
-
-  it('should support multiple subscribers', async () => {
-    const queue = new MemoryQueueAdapter();
-    const log1: unknown[] = [];
-    const log2: unknown[] = [];
-
-    await queue.subscribe('events', async (msg) => { log1.push(msg.data); });
-    await queue.subscribe('events', async (msg) => { log2.push(msg.data); });
-
-    await queue.publish('events', 'hello');
-    expect(log1).toEqual(['hello']);
-    expect(log2).toEqual(['hello']);
-  });
-
-  it('should unsubscribe from a queue', async () => {
-    const queue = new MemoryQueueAdapter();
-    const received: unknown[] = [];
-
-    await queue.subscribe('q1', async (msg) => { received.push(msg.data); });
-    await queue.unsubscribe('q1');
-    await queue.publish('q1', 'data');
-    expect(received).toHaveLength(0);
-  });
-
-  it('should retain dead letters when no subscribers', async () => {
-    const queue = new MemoryQueueAdapter();
-    const id = await queue.publish('orphan', { lost: true });
-    expect(id).toBe('msg-1');
-  });
-
-  it('should return queue size of 0 for in-memory queue', async () => {
-    const queue = new MemoryQueueAdapter();
-    expect(await queue.getQueueSize('test')).toBe(0);
-  });
-
-  it('should purge a queue by removing handlers', async () => {
-    const queue = new MemoryQueueAdapter();
-    const received: unknown[] = [];
-
-    await queue.subscribe('q1', async (msg) => { received.push(msg.data); });
-    await queue.purge('q1');
-    await queue.publish('q1', 'data');
-    expect(received).toHaveLength(0);
-  });
-
-  it('should increment message counter across publishes', async () => {
-    const queue = new MemoryQueueAdapter();
-    const ids: string[] = [];
-
-    await queue.subscribe('q', async () => {});
-    ids.push(await queue.publish('q', 'a'));
-    ids.push(await queue.publish('q', 'b'));
-    ids.push(await queue.publish('q', 'c'));
-
-    expect(ids).toEqual(['msg-1', 'msg-2', 'msg-3']);
-  });
-});

package/src/memory-queue-adapter.ts

@@ -1,82 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { IQueueService, QueuePublishOptions, QueueMessage, QueueHandler } from '@objectstack/spec/contracts';
-
-/**
- * Configuration options for MemoryQueueAdapter.
- */
-export interface MemoryQueueAdapterOptions {
-  /** Maximum number of messages retained per queue (0 = unlimited) */
-  maxQueueSize?: number;
-}
-
-/**
- * In-memory queue adapter implementing IQueueService.
- *
- * Provides synchronous in-process pub/sub delivery.
- * Suitable for single-process environments, development, and testing.
- */
-export class MemoryQueueAdapter implements IQueueService {
-  private readonly handlers = new Map<string, QueueHandler[]>();
-  private readonly deadLetters: QueueMessage[] = [];
-  private msgCounter = 0;
-  private readonly maxQueueSize: number;
-
-  constructor(options: MemoryQueueAdapterOptions = {}) {
-    this.maxQueueSize = options.maxQueueSize ?? 0;
-  }
-
-  async publish<T = unknown>(queue: string, data: T, options?: QueuePublishOptions): Promise<string> {
-    const id = `msg-${++this.msgCounter}`;
-    const msg: QueueMessage<T> = {
-      id,
-      data,
-      attempts: 0,
-      timestamp: Date.now(),
-    };
-
-    const fns = this.handlers.get(queue) ?? [];
-    if (fns.length === 0) {
-      // No subscribers — retain as dead letter if within limits
-      if (this.maxQueueSize === 0 || this.deadLetters.length < this.maxQueueSize) {
-        this.deadLetters.push(msg);
-      }
-      return id;
-    }
-
-    const maxRetries = options?.retries ?? 0;
-    for (const handler of fns) {
-      let attempt = 0;
-      let success = false;
-      while (!success && attempt <= maxRetries) {
-        try {
-          msg.attempts = attempt + 1;
-          await handler(msg as QueueMessage);
-          success = true;
-        } catch {
-          attempt++;
-        }
-      }
-    }
-
-    return id;
-  }
-
-  async subscribe<T = unknown>(queue: string, handler: QueueHandler<T>): Promise<void> {
-    const existing = this.handlers.get(queue) ?? [];
-    this.handlers.set(queue, [...existing, handler as QueueHandler]);
-  }
-
-  async unsubscribe(queue: string): Promise<void> {
-    this.handlers.delete(queue);
-  }
-
-  async getQueueSize(_queue: string): Promise<number> {
-    // In-memory: no persistent queue depth tracking
-    return 0;
-  }
-
-  async purge(queue: string): Promise<void> {
-    this.handlers.delete(queue);
-  }
-}

package/src/queue-service-plugin.ts

@@ -1,62 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import { MemoryQueueAdapter } from './memory-queue-adapter.js';
-import type { MemoryQueueAdapterOptions } from './memory-queue-adapter.js';
-
-/**
- * Configuration options for the QueueServicePlugin.
- */
-export interface QueueServicePluginOptions {
-  /** Queue adapter type (default: 'memory') */
-  adapter?: 'memory' | 'bullmq';
-  /** Options for the memory queue adapter */
-  memory?: MemoryQueueAdapterOptions;
-  /** Redis connection URL (used when adapter is 'bullmq') */
-  redisUrl?: string;
-}
-
-/**
- * QueueServicePlugin — Production IQueueService implementation.
- *
- * Registers a queue service with the kernel during the init phase.
- * Supports in-memory and BullMQ adapters.
- *
- * @example
- * ```ts
- * import { ObjectKernel } from '@objectstack/core';
- * import { QueueServicePlugin } from '@objectstack/service-queue';
- *
- * const kernel = new ObjectKernel();
- * kernel.use(new QueueServicePlugin({ adapter: 'memory' }));
- * await kernel.bootstrap();
- *
- * const queue = kernel.getService('queue');
- * await queue.publish('orders', { orderId: 123 });
- * ```
- */
-export class QueueServicePlugin implements Plugin {
-  name = 'com.objectstack.service.queue';
-  version = '1.0.0';
-  type = 'standard';
-
-  private readonly options: QueueServicePluginOptions;
-
-  constructor(options: QueueServicePluginOptions = {}) {
-    this.options = { adapter: 'memory', ...options };
-  }
-
-  async init(ctx: PluginContext): Promise<void> {
-    const adapter = this.options.adapter;
-    if (adapter === 'bullmq') {
-      throw new Error(
-        'BullMQ queue adapter is not yet implemented. ' +
-        'Use adapter: "memory" or provide a custom IQueueService via ctx.registerService("queue", impl).'
-      );
-    }
-
-    const queue = new MemoryQueueAdapter(this.options.memory);
-    ctx.registerService('queue', queue);
-    ctx.logger.info('QueueServicePlugin: registered memory queue adapter');
-  }
-}

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
-}