@dangao/bun-server 1.0.0 → 1.0.3

package/src/queue/queue-module.ts

@@ -0,0 +1,64 @@
+import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+
+import { QueueService } from './service';
+import {
+  QUEUE_OPTIONS_TOKEN,
+  QUEUE_SERVICE_TOKEN,
+  MemoryQueueStore,
+  type QueueModuleOptions,
+  type QueueStore,
+} from './types';
+
+@Module({
+  providers: [],
+})
+export class QueueModule {
+  /**
+   * 创建队列模块
+   * @param options - 模块配置
+   */
+  public static forRoot(
+    options: QueueModuleOptions = {},
+  ): typeof QueueModule {
+    const providers: ModuleProvider[] = [];
+
+    // 如果没有提供 store，使用默认的内存存储
+    const store: QueueStore = options.store ?? new MemoryQueueStore();
+
+    const service = new QueueService({
+      store,
+      defaultQueue: options.defaultQueue,
+      enableWorker: options.enableWorker,
+      concurrency: options.concurrency,
+    });
+
+    providers.push(
+      {
+        provide: QUEUE_SERVICE_TOKEN,
+        useValue: service,
+      },
+      {
+        provide: QUEUE_OPTIONS_TOKEN,
+        useValue: options,
+      },
+      QueueService,
+    );
+
+    // 动态更新模块元数据
+    const existingMetadata =
+      Reflect.getMetadata(MODULE_METADATA_KEY, QueueModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      providers: [...(existingMetadata.providers || []), ...providers],
+      exports: [
+        ...(existingMetadata.exports || []),
+        QUEUE_SERVICE_TOKEN,
+        QUEUE_OPTIONS_TOKEN,
+        QueueService,
+      ],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, QueueModule);
+
+    return QueueModule;
+  }
+}

package/src/queue/service.ts

@@ -0,0 +1,302 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type {
+  QueueStore,
+  QueueModuleOptions,
+  Job,
+  JobData,
+  JobHandler,
+  JobOptions,
+  CronOptions,
+} from './types';
+import { QUEUE_OPTIONS_TOKEN } from './types';
+
+/**
+ * 队列服务
+ */
+@Injectable()
+export class QueueService {
+  private store: QueueStore;
+  private defaultQueue: string;
+  private enableWorker: boolean;
+  private concurrency: number;
+  private workers: Map<string, Set<Promise<void>>> = new Map();
+  private cronJobs: Map<string, { handler: JobHandler; options: CronOptions }> =
+    new Map();
+  private cronTimers: Map<string, ReturnType<typeof setInterval>> = new Map();
+
+  public constructor(@Inject(QUEUE_OPTIONS_TOKEN) options: QueueModuleOptions) {
+    this.store = options.store!;
+    this.defaultQueue = options.defaultQueue ?? 'default';
+    this.enableWorker = options.enableWorker ?? true;
+    this.concurrency = options.concurrency ?? 1;
+
+    if (this.enableWorker) {
+      this.startWorker(this.defaultQueue);
+    }
+  }
+
+  /**
+   * 添加任务
+   * @param jobName - 任务名称
+   * @param data - 任务数据
+   * @param options - 任务选项
+   * @param queueName - 队列名称（可选，默认使用 defaultQueue）
+   * @returns 任务 ID
+   */
+  public async add<T = JobData>(
+    jobName: string,
+    data: T,
+    options?: JobOptions,
+    queueName?: string,
+  ): Promise<string> {
+    const queue = queueName ?? this.defaultQueue;
+    const jobId = await this.store.add(queue, {
+      name: jobName,
+      data,
+      options,
+    });
+
+    // 如果启用了工作进程，确保队列有工作进程在运行
+    if (this.enableWorker && !this.workers.has(queue)) {
+      this.startWorker(queue);
+    }
+
+    return jobId;
+  }
+
+  /**
+   * 获取任务
+   * @param jobId - 任务 ID
+   * @param queueName - 队列名称（可选）
+   * @returns 任务，如果不存在则返回 undefined
+   */
+  public async get<T = JobData>(
+    jobId: string,
+    queueName?: string,
+  ): Promise<Job<T> | undefined> {
+    const queue = queueName ?? this.defaultQueue;
+    return this.store.get<T>(queue, jobId);
+  }
+
+  /**
+   * 删除任务
+   * @param jobId - 任务 ID
+   * @param queueName - 队列名称（可选）
+   * @returns 是否删除成功
+   */
+  public async delete(jobId: string, queueName?: string): Promise<boolean> {
+    const queue = queueName ?? this.defaultQueue;
+    return this.store.delete(queue, jobId);
+  }
+
+  /**
+   * 清空队列
+   * @param queueName - 队列名称（可选）
+   * @returns 是否清空成功
+   */
+  public async clear(queueName?: string): Promise<boolean> {
+    const queue = queueName ?? this.defaultQueue;
+    return this.store.clear(queue);
+  }
+
+  /**
+   * 获取队列中的任务数量
+   * @param queueName - 队列名称（可选）
+   * @returns 任务数量
+   */
+  public async count(queueName?: string): Promise<number> {
+    const queue = queueName ?? this.defaultQueue;
+    return this.store.count(queue);
+  }
+
+  /**
+   * 注册任务处理器
+   * @param jobName - 任务名称
+   * @param handler - 任务处理器
+   * @param queueName - 队列名称（可选）
+   */
+  public async registerHandler<T = JobData>(
+    jobName: string,
+    handler: JobHandler<T>,
+    queueName?: string,
+  ): Promise<void> {
+    const queue = queueName ?? this.defaultQueue;
+    const key = `${queue}:${jobName}`;
+
+    // 存储处理器（实际实现中可能需要更复杂的注册机制）
+    // 这里简化处理，假设处理器可以通过任务名称找到
+    // 实际使用时，可能需要一个处理器注册表
+    (this as unknown as { handlers: Map<string, JobHandler<JobData>> }).handlers =
+      (this as unknown as { handlers: Map<string, JobHandler<JobData>> }).handlers ??
+      new Map();
+    (
+      this as unknown as { handlers: Map<string, JobHandler<JobData>> }
+    ).handlers.set(key, handler as JobHandler<JobData>);
+  }
+
+  /**
+   * 注册定时任务（Cron）
+   * @param jobName - 任务名称
+   * @param handler - 任务处理器
+   * @param options - Cron 配置
+   * @param queueName - 队列名称（可选）
+   */
+  public async registerCron<T = JobData>(
+    jobName: string,
+    handler: JobHandler<T>,
+    options: CronOptions,
+    queueName?: string,
+  ): Promise<void> {
+    const queue = queueName ?? this.defaultQueue;
+    const key = `${queue}:${jobName}`;
+
+    this.cronJobs.set(key, { handler: handler as JobHandler<JobData>, options });
+
+    // 如果设置了立即执行，先执行一次
+    if (options.runOnInit) {
+      await this.add(jobName, {} as T, undefined, queue);
+    }
+
+    // 解析 Cron 表达式并设置定时器
+    // 注意：这里简化实现，实际应该使用 cron 解析库
+    const interval = this.parseCronInterval(options.pattern);
+    if (interval > 0) {
+      const timer = setInterval(async () => {
+        await this.add(jobName, {} as T, undefined, queue);
+      }, interval);
+      this.cronTimers.set(key, timer);
+    }
+  }
+
+  /**
+   * 启动工作进程
+   * @param queueName - 队列名称
+   */
+  private startWorker(queueName: string): void {
+    if (this.workers.has(queueName)) {
+      return;
+    }
+
+    const workerSet = new Set<Promise<void>>();
+    this.workers.set(queueName, workerSet);
+
+    // 启动并发工作进程
+    for (let i = 0; i < this.concurrency; i++) {
+      const worker = this.processQueue(queueName);
+      workerSet.add(worker);
+    }
+  }
+
+  /**
+   * 处理队列
+   * @param queueName - 队列名称
+   */
+  private async processQueue(queueName: string): Promise<void> {
+    while (true) {
+      try {
+        const job = await this.store.getNext(queueName);
+        if (!job) {
+          // 没有任务，等待一段时间后重试
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+          continue;
+        }
+
+        // 更新任务状态为 active
+        await this.store.updateStatus(queueName, job.id, 'active');
+
+        try {
+          // 获取处理器
+          const handler = this.getHandler(job.name, queueName);
+          if (handler) {
+            await handler(job as Job<JobData>);
+            await this.store.updateStatus(queueName, job.id, 'completed');
+          } else {
+            // 没有找到处理器，标记为失败
+            await this.store.updateStatus(queueName, job.id, 'failed');
+          }
+        } catch (error) {
+          // 处理任务失败
+          await this.store.updateStatus(queueName, job.id, 'failed');
+          // 可以在这里添加重试逻辑
+          console.error(`Job ${job.id} failed:`, error);
+        }
+      } catch (error) {
+        console.error(`Error processing queue ${queueName}:`, error);
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+  }
+
+  /**
+   * 获取处理器
+   * @param jobName - 任务名称
+   * @param queueName - 队列名称
+   * @returns 处理器，如果不存在则返回 undefined
+   */
+  private getHandler(
+    jobName: string,
+    queueName: string,
+  ): JobHandler<JobData> | undefined {
+    const key = `${queueName}:${jobName}`;
+    return (
+      this as unknown as { handlers: Map<string, JobHandler<JobData>> }
+    ).handlers?.get(key);
+  }
+
+  /**
+   * 解析 Cron 表达式为间隔时间（毫秒）
+   * 注意：这是简化实现，实际应该使用专业的 cron 解析库
+   * @param pattern - Cron 表达式
+   * @returns 间隔时间（毫秒），如果无法解析则返回 -1
+   */
+  private parseCronInterval(pattern: string): number {
+    // 简化实现：只支持简单的格式
+    // 实际应该使用 cron-parser 等库
+    const parts = pattern.trim().split(/\s+/);
+    if (parts.length !== 5) {
+      return -1;
+    }
+
+    const [minute, hour, day, month, weekday] = parts;
+
+    // 如果所有字段都是 *，表示每分钟执行
+    if (
+      minute === '*' &&
+      hour === '*' &&
+      day === '*' &&
+      month === '*' &&
+      weekday === '*'
+    ) {
+      return 60000; // 1 分钟
+    }
+
+    // 如果分钟是数字，其他都是 *，表示每 N 分钟执行
+    if (
+      /^\d+$/.test(minute) &&
+      hour === '*' &&
+      day === '*' &&
+      month === '*' &&
+      weekday === '*'
+    ) {
+      return parseInt(minute, 10) * 60000;
+    }
+
+    // 默认返回 -1，表示需要更复杂的解析
+    // 实际实现中应该使用 cron-parser
+    return -1;
+  }
+
+  /**
+   * 销毁服务，清理资源
+   */
+  public destroy(): void {
+    // 清理所有定时器
+    for (const timer of this.cronTimers.values()) {
+      clearInterval(timer);
+    }
+    this.cronTimers.clear();
+    this.cronJobs.clear();
+    this.workers.clear();
+  }
+}

package/src/queue/types.ts

@@ -0,0 +1,341 @@
+/**
+ * 任务数据
+ */
+export interface JobData {
+  [key: string]: unknown;
+}
+
+/**
+ * 任务选项
+ */
+export interface JobOptions {
+  /**
+   * 任务延迟（毫秒）
+   */
+  delay?: number;
+
+  /**
+   * 任务优先级（数字越大优先级越高）
+   */
+  priority?: number;
+
+  /**
+   * 任务重试次数
+   */
+  attempts?: number;
+
+  /**
+   * 任务重试延迟（毫秒）
+   */
+  backoff?: {
+    type: 'fixed' | 'exponential';
+    delay: number;
+  };
+
+  /**
+   * 任务超时时间（毫秒）
+   */
+  timeout?: number;
+
+  /**
+   * 任务 ID（如果不提供则自动生成）
+   */
+  jobId?: string;
+
+  /**
+   * 是否移除任务（如果已完成）
+   */
+  removeOnComplete?: boolean | number;
+
+  /**
+   * 是否移除任务（如果失败）
+   */
+  removeOnFail?: boolean | number;
+}
+
+/**
+ * 任务
+ */
+export interface Job<T = JobData> {
+  /**
+   * 任务 ID
+   */
+  id: string;
+
+  /**
+   * 任务名称
+   */
+  name: string;
+
+  /**
+   * 任务数据
+   */
+  data: T;
+
+  /**
+   * 任务选项
+   */
+  options?: JobOptions;
+
+  /**
+   * 任务状态
+   */
+  status: 'waiting' | 'active' | 'completed' | 'failed' | 'delayed';
+
+  /**
+   * 创建时间
+   */
+  createdAt: number;
+
+  /**
+   * 更新时间
+   */
+  updatedAt: number;
+}
+
+/**
+ * 任务处理器
+ */
+export type JobHandler<T = JobData> = (job: Job<T>) => Promise<void> | void;
+
+/**
+ * 队列存储接口
+ */
+export interface QueueStore {
+  /**
+   * 添加任务
+   * @param queueName - 队列名称
+   * @param job - 任务
+   * @returns 任务 ID
+   */
+  add<T = JobData>(
+    queueName: string,
+    job: Omit<Job<T>, 'id' | 'status' | 'createdAt' | 'updatedAt'>,
+  ): Promise<string>;
+
+  /**
+   * 获取任务
+   * @param queueName - 队列名称
+   * @param jobId - 任务 ID
+   * @returns 任务，如果不存在则返回 undefined
+   */
+  get<T = JobData>(queueName: string, jobId: string): Promise<Job<T> | undefined>;
+
+  /**
+   * 获取下一个待处理的任务
+   * @param queueName - 队列名称
+   * @returns 任务，如果没有则返回 undefined
+   */
+  getNext<T = JobData>(queueName: string): Promise<Job<T> | undefined>;
+
+  /**
+   * 更新任务状态
+   * @param queueName - 队列名称
+   * @param jobId - 任务 ID
+   * @param status - 新状态
+   * @returns 是否更新成功
+   */
+  updateStatus(
+    queueName: string,
+    jobId: string,
+    status: Job['status'],
+  ): Promise<boolean>;
+
+  /**
+   * 删除任务
+   * @param queueName - 队列名称
+   * @param jobId - 任务 ID
+   * @returns 是否删除成功
+   */
+  delete(queueName: string, jobId: string): Promise<boolean>;
+
+  /**
+   * 清空队列
+   * @param queueName - 队列名称
+   * @returns 是否清空成功
+   */
+  clear(queueName: string): Promise<boolean>;
+
+  /**
+   * 获取队列中的任务数量
+   * @param queueName - 队列名称
+   * @returns 任务数量
+   */
+  count(queueName: string): Promise<number>;
+}
+
+/**
+ * 内存队列存储实现
+ */
+export class MemoryQueueStore implements QueueStore {
+  private queues: Map<string, Map<string, Job>> = new Map();
+  private jobCounter = 0;
+
+  public async add<T = JobData>(
+    queueName: string,
+    job: Omit<Job<T>, 'id' | 'status' | 'createdAt' | 'updatedAt'>,
+  ): Promise<string> {
+    const queue = this.getQueue(queueName);
+    const jobId = job.options?.jobId ?? `job_${++this.jobCounter}_${Date.now()}`;
+    const now = Date.now();
+
+    const fullJob: Job<T> = {
+      id: jobId,
+      name: job.name,
+      data: job.data,
+      options: job.options,
+      status: job.options?.delay ? 'delayed' : 'waiting',
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    queue.set(jobId, fullJob as Job<JobData>);
+    return jobId;
+  }
+
+  public async get<T = JobData>(
+    queueName: string,
+    jobId: string,
+  ): Promise<Job<T> | undefined> {
+    const queue = this.getQueue(queueName);
+    return queue.get(jobId) as Job<T> | undefined;
+  }
+
+  public async getNext<T = JobData>(
+    queueName: string,
+  ): Promise<Job<T> | undefined> {
+    const queue = this.getQueue(queueName);
+    const now = Date.now();
+
+    // 查找下一个待处理的任务（优先处理 delayed 且已到期的任务，然后处理 waiting 的任务）
+    let nextJob: Job<T> | undefined;
+    let highestPriority = -Infinity;
+
+    for (const job of queue.values()) {
+      // 检查 delayed 任务是否到期
+      if (job.status === 'delayed' && job.options?.delay) {
+        const delayEndTime = job.createdAt + job.options.delay;
+        if (now >= delayEndTime) {
+          if (
+            (job.options.priority ?? 0) > highestPriority ||
+            !nextJob
+          ) {
+            nextJob = job as Job<T>;
+            highestPriority = job.options?.priority ?? 0;
+          }
+        }
+      } else if (job.status === 'waiting') {
+        if (
+          (job.options?.priority ?? 0) > highestPriority ||
+          !nextJob
+        ) {
+          nextJob = job as Job<T>;
+          highestPriority = job.options?.priority ?? 0;
+        }
+      }
+    }
+
+    return nextJob;
+  }
+
+  public async updateStatus(
+    queueName: string,
+    jobId: string,
+    status: Job['status'],
+  ): Promise<boolean> {
+    const queue = this.getQueue(queueName);
+    const job = queue.get(jobId);
+    if (!job) {
+      return false;
+    }
+
+    job.status = status;
+    job.updatedAt = Date.now();
+    return true;
+  }
+
+  public async delete(queueName: string, jobId: string): Promise<boolean> {
+    const queue = this.getQueue(queueName);
+    return queue.delete(jobId);
+  }
+
+  public async clear(queueName: string): Promise<boolean> {
+    const queue = this.getQueue(queueName);
+    queue.clear();
+    return true;
+  }
+
+  public async count(queueName: string): Promise<number> {
+    const queue = this.getQueue(queueName);
+    return queue.size;
+  }
+
+  private getQueue(queueName: string): Map<string, Job<JobData>> {
+    if (!this.queues.has(queueName)) {
+      this.queues.set(queueName, new Map());
+    }
+    return this.queues.get(queueName)!;
+  }
+}
+
+/**
+ * Cron 表达式配置
+ */
+export interface CronOptions {
+  /**
+   * Cron 表达式（支持标准 5 字段格式：分 时 日 月 周）
+   * 例如：'0 0 * * *' 表示每天午夜执行
+   */
+  pattern: string;
+
+  /**
+   * 时区
+   * @default 'UTC'
+   */
+  timezone?: string;
+
+  /**
+   * 是否立即执行一次
+   * @default false
+   */
+  runOnInit?: boolean;
+}
+
+/**
+ * QueueModule 配置选项
+ */
+export interface QueueModuleOptions {
+  /**
+   * 队列存储实现
+   * @default MemoryQueueStore
+   */
+  store?: QueueStore;
+
+  /**
+   * 默认队列名称
+   * @default 'default'
+   */
+  defaultQueue?: string;
+
+  /**
+   * 是否启用工作进程
+   * @default true
+   */
+  enableWorker?: boolean;
+
+  /**
+   * 工作进程并发数
+   * @default 1
+   */
+  concurrency?: number;
+}
+
+/**
+ * QueueService Token
+ */
+export const QUEUE_SERVICE_TOKEN = Symbol('@dangao/bun-server:queue:service');
+
+/**
+ * QueueModule Options Token
+ */
+export const QUEUE_OPTIONS_TOKEN = Symbol('@dangao/bun-server:queue:options');