@objectstack/service-queue 4.0.4 → 4.1.0

package/CHANGELOG.md

@@ -1,177 +0,0 @@
-# @objectstack/service-queue
-
-## 4.0.4
-
-### Patch Changes
-
-- Updated dependencies [326b66b]
-  - @objectstack/spec@4.0.4
-  - @objectstack/core@4.0.4
-
-## 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"
-  ]
-}