@faapi/task-bullmq 0.0.0-canary.0 → 6.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 faapi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
 # @faapi/task-bullmq
 
-Placeholder package for Trusted Publisher setup. Real content published via CI from https://github.com/faapi/faapi.
+faapi 任务子系统的 **BullMQ 驱动**（Redis 持久化队列）。
+
+基于 Redis 的任务队列——任务不丢（持久化）、多实例天然防重跑（worker 领取制）、支持延迟任务与指数退避重试。适合已有 Redis 基础设施或需要高吞吐的项目。
+
+## 安装
+
+```bash
+pnpm add @faapi/task-bullmq bullmq
+```
+
+## 使用
+
+任务定义不变（主包文件约定 `src/tasks/<name>/task.ts`），只切驱动：
+
+```ts
+// faapi.config.ts
+import type { FaapiConfig } from '@faapi/faapi';
+
+export default {
+  task: {
+    driver: 'bullmq',
+    bullmq: { connection: { host: '127.0.0.1', port: 6379 } },
+    // 可选：同 Redis 下多应用隔离
+    // bullmq: { connection: {...}, prefix: 'myapp' },
+  },
+} satisfies FaapiConfig;
+```
+
+```ts
+// handler 里用法完全不变
+export function POST(body, tasks) {
+  return tasks.enqueue('send-email', { to: body.email });
+}
+```
+
+## 语义映射
+
+| faapi 驱动接口 | BullMQ |
+| --- | --- |
+| `enqueue(name, payload, { retries, delayMs })` | `queue.add(name, payload, { attempts: retries + 1, backoff: exponential 500ms, delay })` |
+| `startWorker(name, { concurrency, process })` | `new Worker(name, handler, { connection, concurrency, prefix })` |
+| `stop(timeoutMs)` | workers.close() + queues.close()（race 超时） |
+| `stopWorkers()` | 仅关 Worker（dev 热替换重注册用），Queue 连接保持 |
+| 失败重试 | BullMQ 侧执行（attempts = retries + 1，指数退避 500ms 起） |
+
+注意：BullMQ 不提供执行中任务的取消信号——`run` 的 `taskCtx.signal` 永不 abort，长任务请自行做超时控制。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { TaskDriver } from '@faapi/faapi';
+import { ConnectionOptions } from 'bullmq';
+
+/**
+ * BullMQ 驱动选项
+ */
+interface BullMQDriverOptions {
+    /** Redis 连接配置（透传给 Queue / Worker 的 connection） */
+    connection: ConnectionOptions;
+    /** 队列名前缀（默认 `faapi`——同一 Redis 下多个 faapi 应用隔离用） */
+    prefix?: string;
+}
+/**
+ * faapi 任务队列 BullMQ 驱动（Redis 持久化队列）
+ *
+ * 与 faapi 主包 `config.task.driver: 'bullmq'` 配合使用：
+ *
+ * ```ts
+ * // faapi.config.ts
+ * export default {
+ *   task: {
+ *     driver: 'bullmq',
+ *     bullmq: { connection: { host: '127.0.0.1', port: 6379 } },
+ *   },
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 语义映射（详见包根 README）：
+ * - `enqueue` → `queue.add(name, payload, { delay, attempts, backoff })`（每任务一个 Queue）
+ * - `startWorker` → `new Worker(name, handler, { connection, concurrency })`
+ * - `stop` → workers.close() + queues.close()（等 in-flight；超时由 BullMQ 处置）
+ * - 重试 → BullMQ 侧执行（attempts = retries + 1，指数退避 500ms 起）
+ */
+declare function createBullMQDriver(options: BullMQDriverOptions): TaskDriver;
+
+export { type BullMQDriverOptions, createBullMQDriver };

package/dist/index.js

@@ -0,0 +1,85 @@
+// src/index.ts
+import { Queue, Worker } from "bullmq";
+function createBullMQDriver(options) {
+  if (!options?.connection) {
+    throw new Error("[faapi] @faapi/task-bullmq requires `bullmq.connection` in config.task");
+  }
+  const prefix = options.prefix ?? "faapi";
+  let stopped = false;
+  const queues = /* @__PURE__ */ new Map();
+  const workers = /* @__PURE__ */ new Map();
+  function getQueue(name) {
+    let q = queues.get(name);
+    if (!q) {
+      q = new Queue(name, { connection: options.connection, prefix });
+      queues.set(name, q);
+    }
+    return q;
+  }
+  const attemptCounts = /* @__PURE__ */ new Map();
+  return {
+    async enqueue(name, payload, opts) {
+      if (stopped) {
+        throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+      }
+      const queue = getQueue(name);
+      const job = await queue.add(name, payload, {
+        // BullMQ attempts 含首次执行，retries 是额外重试次数
+        attempts: (opts?.retries ?? 0) + 1,
+        backoff: { type: "exponential", delay: 500 },
+        ...opts?.delayMs ? { delay: opts.delayMs } : {}
+      });
+      return job.id ?? crypto.randomUUID();
+    },
+    async startWorker(name, workerOpts) {
+      const process = workerOpts.process;
+      const existing = workers.get(name);
+      if (existing) {
+        await existing.close();
+      }
+      const worker = new Worker(
+        name,
+        async (job) => {
+          const attempt = (attemptCounts.get(job.id ?? "") ?? 0) + 1;
+          attemptCounts.set(job.id ?? "", attempt);
+          return await process({
+            id: job.id ?? "",
+            name,
+            payload: job.data,
+            attempt,
+            signal: new AbortController().signal
+            // BullMQ 不提供执行中任务的取消信号
+          });
+        },
+        { connection: options.connection, concurrency: workerOpts.concurrency, prefix }
+      );
+      worker.on("error", (err) => {
+        console.error(`[faapi] bullmq worker error for task "${name}":`, err);
+      });
+      workers.set(name, worker);
+    },
+    async stop(timeoutMs = 1e4) {
+      stopped = true;
+      const closes = [
+        ...Array.from(workers.values()).map((w) => w.close()),
+        ...Array.from(queues.values()).map((q) => q.close())
+      ];
+      workers.clear();
+      const timeout = new Promise((resolve) => {
+        const timer = setTimeout(resolve, timeoutMs);
+        timer.unref?.();
+      });
+      await Promise.race([Promise.all(closes), timeout]);
+      attemptCounts.clear();
+    },
+    async stopWorkers() {
+      const closes = Array.from(workers.values()).map((w) => w.close());
+      workers.clear();
+      await Promise.all(closes);
+    }
+  };
+}
+export {
+  createBullMQDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { TaskDriver, TaskDriverProcess } from '@faapi/faapi';\nimport { Queue, Worker, type ConnectionOptions, type Job } from 'bullmq';\n\n/**\n * BullMQ 驱动选项\n */\nexport interface BullMQDriverOptions {\n  /** Redis 连接配置（透传给 Queue / Worker 的 connection） */\n  connection: ConnectionOptions;\n  /** 队列名前缀（默认 `faapi`——同一 Redis 下多个 faapi 应用隔离用） */\n  prefix?: string;\n}\n\n/**\n * faapi 任务队列 BullMQ 驱动（Redis 持久化队列）\n *\n * 与 faapi 主包 `config.task.driver: 'bullmq'` 配合使用：\n *\n * ```ts\n * // faapi.config.ts\n * export default {\n *   task: {\n *     driver: 'bullmq',\n *     bullmq: { connection: { host: '127.0.0.1', port: 6379 } },\n *   },\n * } satisfies FaapiConfig;\n * ```\n *\n * 语义映射（详见包根 README）：\n * - `enqueue` → `queue.add(name, payload, { delay, attempts, backoff })`（每任务一个 Queue）\n * - `startWorker` → `new Worker(name, handler, { connection, concurrency })`\n * - `stop` → workers.close() + queues.close()（等 in-flight；超时由 BullMQ 处置）\n * - 重试 → BullMQ 侧执行（attempts = retries + 1，指数退避 500ms 起）\n */\nexport function createBullMQDriver(options: BullMQDriverOptions): TaskDriver {\n  if (!options?.connection) {\n    throw new Error('[faapi] @faapi/task-bullmq requires `bullmq.connection` in config.task');\n  }\n  const prefix = options.prefix ?? 'faapi';\n\n  let stopped = false;\n  /** 每任务一个 Queue（按名缓存） */\n  const queues = new Map<string, Queue>();\n  /** 已创建的 Worker（stopWorkers / stop 时关闭） */\n  const workers = new Map<string, Worker>();\n\n  function getQueue(name: string): Queue {\n    let q = queues.get(name);\n    if (!q) {\n      q = new Queue(name, { connection: options.connection, prefix });\n      queues.set(name, q);\n    }\n    return q;\n  }\n\n  /** 驱动侧 attempt 计数（兼容不同 BullMQ 版本的 attemptsMade/attemptsStarted 字段差异） */\n  const attemptCounts = new Map<string, number>();\n\n  return {\n    async enqueue(name, payload, opts) {\n      if (stopped) {\n        throw new Error('[faapi] Task queue is stopped and no longer accepts jobs');\n      }\n      const queue = getQueue(name);\n      const job = await queue.add(name, payload, {\n        // BullMQ attempts 含首次执行，retries 是额外重试次数\n        attempts: (opts?.retries ?? 0) + 1,\n        backoff: { type: 'exponential', delay: 500 },\n        ...(opts?.delayMs ? { delay: opts.delayMs } : {}),\n      });\n      return job.id ?? crypto.randomUUID();\n    },\n\n    async startWorker(name, workerOpts) {\n      const process: TaskDriverProcess = workerOpts.process;\n      // 二次注册（reload 场景）先关旧 Worker\n      const existing = workers.get(name);\n      if (existing) {\n        await existing.close();\n      }\n      const worker = new Worker(\n        name,\n        async (job: Job) => {\n          const attempt = (attemptCounts.get(job.id ?? '') ?? 0) + 1;\n          attemptCounts.set(job.id ?? '', attempt);\n          return await process({\n            id: job.id ?? '',\n            name,\n            payload: job.data,\n            attempt,\n            signal: new AbortController().signal, // BullMQ 不提供执行中任务的取消信号\n          });\n        },\n        { connection: options.connection, concurrency: workerOpts.concurrency, prefix },\n      );\n      // 处理器内部异常已由语义层包装记录；这里兜底防止 unhandled error 事件崩进程\n      worker.on('error', (err) => {\n        console.error(`[faapi] bullmq worker error for task \"${name}\":`, err);\n      });\n      workers.set(name, worker);\n    },\n\n    async stop(timeoutMs = 10_000) {\n      stopped = true;\n      const closes = [\n        ...Array.from(workers.values()).map((w) => w.close()),\n        ...Array.from(queues.values()).map((q) => q.close()),\n      ];\n      workers.clear();\n      const timeout = new Promise<void>((resolve) => {\n        const timer = setTimeout(resolve, timeoutMs);\n        timer.unref?.();\n      });\n      await Promise.race([Promise.all(closes), timeout]);\n      attemptCounts.clear();\n    },\n\n    async stopWorkers() {\n      const closes = Array.from(workers.values()).map((w) => w.close());\n      workers.clear();\n      await Promise.all(closes);\n    },\n  };\n}\n"],"mappings":";AACA,SAAS,OAAO,cAAgD;AAiCzD,SAAS,mBAAmB,SAA0C;AAC3E,MAAI,CAAC,SAAS,YAAY;AACxB,UAAM,IAAI,MAAM,wEAAwE;AAAA,EAC1F;AACA,QAAM,SAAS,QAAQ,UAAU;AAEjC,MAAI,UAAU;AAEd,QAAM,SAAS,oBAAI,IAAmB;AAEtC,QAAM,UAAU,oBAAI,IAAoB;AAExC,WAAS,SAAS,MAAqB;AACrC,QAAI,IAAI,OAAO,IAAI,IAAI;AACvB,QAAI,CAAC,GAAG;AACN,UAAI,IAAI,MAAM,MAAM,EAAE,YAAY,QAAQ,YAAY,OAAO,CAAC;AAC9D,aAAO,IAAI,MAAM,CAAC;AAAA,IACpB;AACA,WAAO;AAAA,EACT;AAGA,QAAM,gBAAgB,oBAAI,IAAoB;AAE9C,SAAO;AAAA,IACL,MAAM,QAAQ,MAAM,SAAS,MAAM;AACjC,UAAI,SAAS;AACX,cAAM,IAAI,MAAM,0DAA0D;AAAA,MAC5E;AACA,YAAM,QAAQ,SAAS,IAAI;AAC3B,YAAM,MAAM,MAAM,MAAM,IAAI,MAAM,SAAS;AAAA;AAAA,QAEzC,WAAW,MAAM,WAAW,KAAK;AAAA,QACjC,SAAS,EAAE,MAAM,eAAe,OAAO,IAAI;AAAA,QAC3C,GAAI,MAAM,UAAU,EAAE,OAAO,KAAK,QAAQ,IAAI,CAAC;AAAA,MACjD,CAAC;AACD,aAAO,IAAI,MAAM,OAAO,WAAW;AAAA,IACrC;AAAA,IAEA,MAAM,YAAY,MAAM,YAAY;AAClC,YAAM,UAA6B,WAAW;AAE9C,YAAM,WAAW,QAAQ,IAAI,IAAI;AACjC,UAAI,UAAU;AACZ,cAAM,SAAS,MAAM;AAAA,MACvB;AACA,YAAM,SAAS,IAAI;AAAA,QACjB;AAAA,QACA,OAAO,QAAa;AAClB,gBAAM,WAAW,cAAc,IAAI,IAAI,MAAM,EAAE,KAAK,KAAK;AACzD,wBAAc,IAAI,IAAI,MAAM,IAAI,OAAO;AACvC,iBAAO,MAAM,QAAQ;AAAA,YACnB,IAAI,IAAI,MAAM;AAAA,YACd;AAAA,YACA,SAAS,IAAI;AAAA,YACb;AAAA,YACA,QAAQ,IAAI,gBAAgB,EAAE;AAAA;AAAA,UAChC,CAAC;AAAA,QACH;AAAA,QACA,EAAE,YAAY,QAAQ,YAAY,aAAa,WAAW,aAAa,OAAO;AAAA,MAChF;AAEA,aAAO,GAAG,SAAS,CAAC,QAAQ;AAC1B,gBAAQ,MAAM,yCAAyC,IAAI,MAAM,GAAG;AAAA,MACtE,CAAC;AACD,cAAQ,IAAI,MAAM,MAAM;AAAA,IAC1B;AAAA,IAEA,MAAM,KAAK,YAAY,KAAQ;AAC7B,gBAAU;AACV,YAAM,SAAS;AAAA,QACb,GAAG,MAAM,KAAK,QAAQ,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;AAAA,QACpD,GAAG,MAAM,KAAK,OAAO,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;AAAA,MACrD;AACA,cAAQ,MAAM;AACd,YAAM,UAAU,IAAI,QAAc,CAAC,YAAY;AAC7C,cAAM,QAAQ,WAAW,SAAS,SAAS;AAC3C,cAAM,QAAQ;AAAA,MAChB,CAAC;AACD,YAAM,QAAQ,KAAK,CAAC,QAAQ,IAAI,MAAM,GAAG,OAAO,CAAC;AACjD,oBAAc,MAAM;AAAA,IACtB;AAAA,IAEA,MAAM,cAAc;AAClB,YAAM,SAAS,MAAM,KAAK,QAAQ,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;AAChE,cAAQ,MAAM;AACd,YAAM,QAAQ,IAAI,MAAM;AAAA,IAC1B;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,11 +1,60 @@
 {
   "name": "@faapi/task-bullmq",
-  "version": "0.0.0-canary.0",
-  "description": "Placeholder for Trusted Publisher setup. Real content published via CI from https://github.com/faapi/faapi.",
+  "version": "6.3.0",
+  "description": "BullMQ task queue driver for faapi — persistent queue on Redis",
   "type": "module",
-  "main": "./index.js",
-  "files": [],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "bullmq": "^5.58.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11",
+    "@faapi/faapi": "6.3.0"
+  },
+  "peerDependencies": {
+    "bullmq": "^5.0.0",
+    "@faapi/faapi": "^6.3.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faapi/faapi.git",
+    "directory": "packages/task-bullmq"
+  },
+  "bugs": {
+    "url": "https://github.com/faapi/faapi/issues"
+  },
+  "keywords": [
+    "faapi",
+    "task-queue",
+    "bullmq",
+    "redis",
+    "driver"
+  ],
+  "sideEffects": false,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json"
   }
-}
+}