@faapi/task-pgboss 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,50 @@
 # @faapi/task-pgboss
 
-Placeholder package for Trusted Publisher setup. Real content published via CI from https://github.com/faapi/faapi.
+faapi 任务子系统的 **pg-boss 驱动**（PostgreSQL 持久化队列）。
+
+基于 PostgreSQL 的任务队列——任务不丢（持久化）、多实例天然防重跑（worker 领取制）、cron 重复投递由 pg-boss 消费语义兜底。复用业务方已有的 Postgres，不引入 Redis。
+
+## 安装
+
+```bash
+pnpm add @faapi/task-pgboss pgboss
+```
+
+## 使用
+
+任务定义不变（主包文件约定 `src/tasks/<name>/task.ts`），只切驱动：
+
+```ts
+// faapi.config.ts
+import type { FaapiConfig } from '@faapi/faapi';
+
+export default {
+  task: {
+    driver: 'pgboss',
+    pgboss: { connectionString: 'postgres://localhost:5432/app' }, // 透传给 new PgBoss(...)
+  },
+} satisfies FaapiConfig;
+```
+
+```ts
+// handler 里用法完全不变
+export function POST(body, tasks) {
+  return tasks.enqueue('send-email', { to: body.email });
+}
+```
+
+## 语义映射
+
+| faapi 驱动接口 | pg-boss |
+| --- | --- |
+| `enqueue(name, payload, { retries, delayMs })` | `boss.send(name, payload, { retryLimit, retryDelay: 1, retryBackoff: true, startAfter })` |
+| `startWorker(name, { concurrency, process })` | `boss.work(name, { batchSize: concurrency }, handler)` |
+| `stop(timeoutMs)` | 停 work + `boss.stop({ close: true, timeout })` |
+| `stopWorkers()` | `offWork()`（不断开连接，dev 热替换重注册用） |
+| 失败重试 | pg-boss 侧执行（retryLimit + retryBackoff 指数退避） |
+
+注意：pg-boss 不提供执行中任务的取消信号——`run` 的 `taskCtx.signal` 永不 abort，长任务请自行做超时控制。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { TaskDriver } from '@faapi/faapi';
+import PgBoss from 'pg-boss';
+
+/**
+ * pg-boss 驱动选项（透传给 PgBoss 构造函数）
+ *
+ * 常用：`connectionString`；其余见 pg-boss 文档（ConstructorOptions）。
+ */
+type PgBossDriverOptions = PgBoss.ConstructorOptions;
+/**
+ * faapi 任务队列 pg-boss 驱动（PostgreSQL 持久化队列）
+ *
+ * 与 faapi 主包 `config.task.driver: 'pgboss'` 配合使用：
+ *
+ * ```ts
+ * // faapi.config.ts
+ * export default {
+ *   task: {
+ *     driver: 'pgboss',
+ *     pgboss: { connectionString: 'postgres://localhost:5432/app' },
+ *   },
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 语义映射（详见包根 README）：
+ * - `enqueue` → `boss.send(name, payload, { retryLimit, retryDelay, retryBackoff, startAfter })`
+ * - `startWorker` → `boss.work(name, { batchSize: concurrency, includeMetadata: true }, handler)`
+ * - `stop` → `offWork` + `boss.stop({ close: true, graceful: true, timeout })`
+ * - 重试 → pg-boss 侧执行（retryLimit + retryBackoff 指数退避）
+ */
+declare function createPgBossDriver(options?: PgBossDriverOptions): TaskDriver;
+
+export { type PgBossDriverOptions, createPgBossDriver };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import PgBoss from "pg-boss";
+function createPgBossDriver(options = {}) {
+  let boss = null;
+  let stopped = false;
+  const workerIds = /* @__PURE__ */ new Map();
+  async function ensureBoss() {
+    if (!boss) {
+      boss = new PgBoss(options);
+      await boss.start();
+    }
+    return boss;
+  }
+  return {
+    async enqueue(name, payload, opts) {
+      if (stopped) {
+        throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+      }
+      const b = await ensureBoss();
+      const sendOptions = {
+        retryLimit: opts?.retries ?? 0,
+        retryDelay: 1,
+        // 秒；配合 retryBackoff 指数退避
+        retryBackoff: true,
+        ...opts?.delayMs ? { startAfter: new Date(Date.now() + opts.delayMs) } : {}
+      };
+      const id = await b.send(name, payload, sendOptions);
+      if (!id) {
+        throw new Error(`[faapi] pg-boss send failed for task "${name}"`);
+      }
+      return id;
+    },
+    async startWorker(name, workerOpts) {
+      const b = await ensureBoss();
+      const process = workerOpts.process;
+      const existing = workerIds.get(name);
+      if (existing) {
+        await b.offWork(existing);
+      }
+      const workerId = await b.work(
+        name,
+        { batchSize: workerOpts.concurrency, includeMetadata: true },
+        async (jobs) => {
+          for (const job of jobs) {
+            const attempt = job.retryCount + 1;
+            await process({
+              id: job.id,
+              name,
+              payload: job.data,
+              attempt,
+              signal: new AbortController().signal
+              // pg-boss 不提供执行中任务的取消信号
+            });
+          }
+        }
+      );
+      workerIds.set(name, workerId);
+    },
+    async stop(timeoutMs = 1e4) {
+      stopped = true;
+      const b = boss;
+      if (b) {
+        for (const workerId of workerIds.values()) {
+          await b.offWork(workerId).catch(() => {
+          });
+        }
+        workerIds.clear();
+        await b.stop({ close: true, graceful: true, timeout: Math.floor(timeoutMs / 1e3) });
+        boss = null;
+      }
+    },
+    async stopWorkers() {
+      const b = boss;
+      if (b) {
+        for (const workerId of workerIds.values()) {
+          await b.offWork(workerId).catch(() => {
+          });
+        }
+      }
+      workerIds.clear();
+    }
+  };
+}
+export {
+  createPgBossDriver
+};
+//# 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 PgBoss from 'pg-boss';\n\n/**\n * pg-boss 驱动选项（透传给 PgBoss 构造函数）\n *\n * 常用：`connectionString`；其余见 pg-boss 文档（ConstructorOptions）。\n */\nexport type PgBossDriverOptions = PgBoss.ConstructorOptions;\n\n/**\n * faapi 任务队列 pg-boss 驱动（PostgreSQL 持久化队列）\n *\n * 与 faapi 主包 `config.task.driver: 'pgboss'` 配合使用：\n *\n * ```ts\n * // faapi.config.ts\n * export default {\n *   task: {\n *     driver: 'pgboss',\n *     pgboss: { connectionString: 'postgres://localhost:5432/app' },\n *   },\n * } satisfies FaapiConfig;\n * ```\n *\n * 语义映射（详见包根 README）：\n * - `enqueue` → `boss.send(name, payload, { retryLimit, retryDelay, retryBackoff, startAfter })`\n * - `startWorker` → `boss.work(name, { batchSize: concurrency, includeMetadata: true }, handler)`\n * - `stop` → `offWork` + `boss.stop({ close: true, graceful: true, timeout })`\n * - 重试 → pg-boss 侧执行（retryLimit + retryBackoff 指数退避）\n */\nexport function createPgBossDriver(options: PgBossDriverOptions = {}): TaskDriver {\n  let boss: PgBoss | null = null;\n  let stopped = false;\n  /** 已创建的 pg-boss worker id（stopWorkers 时 offWork） */\n  const workerIds = new Map<string, string>();\n\n  async function ensureBoss(): Promise<PgBoss> {\n    if (!boss) {\n      boss = new PgBoss(options);\n      // pg-boss 惰性连接：start 后才连库；驱动在首次 enqueue/startWorker 前建立\n      await boss.start();\n    }\n    return boss;\n  }\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 b = await ensureBoss();\n      const sendOptions: PgBoss.SendOptions = {\n        retryLimit: opts?.retries ?? 0,\n        retryDelay: 1, // 秒；配合 retryBackoff 指数退避\n        retryBackoff: true,\n        ...(opts?.delayMs ? { startAfter: new Date(Date.now() + opts.delayMs) } : {}),\n      };\n      // pg-boss data 形参为 object——基础类型 payload（cron 空任务等）按 JSON 语义透传\n      const id = await b.send(name, payload as object, sendOptions);\n      if (!id) {\n        throw new Error(`[faapi] pg-boss send failed for task \"${name}\"`);\n      }\n      return id;\n    },\n\n    async startWorker(name, workerOpts) {\n      const b = await ensureBoss();\n      const process: TaskDriverProcess = workerOpts.process;\n      // 二次注册（reload 场景）先 offWork 旧 worker\n      const existing = workerIds.get(name);\n      if (existing) {\n        await b.offWork(existing);\n      }\n      const workerId = await b.work<unknown>(\n        name,\n        { batchSize: workerOpts.concurrency, includeMetadata: true },\n        async (jobs) => {\n          for (const job of jobs) {\n            // retryCount 从 0 起（首次执行为 0）→ faapi attempt 从 1 起\n            const attempt = job.retryCount + 1;\n            await process({\n              id: job.id,\n              name,\n              payload: job.data,\n              attempt,\n              signal: new AbortController().signal, // pg-boss 不提供执行中任务的取消信号\n            });\n          }\n          // handler 正常返回 = 本批全部完成；抛错 = 整批失败由 pg-boss 按 retryLimit 重试\n        },\n      );\n      workerIds.set(name, workerId);\n    },\n\n    async stop(timeoutMs = 10_000) {\n      stopped = true;\n      const b = boss;\n      if (b) {\n        for (const workerId of workerIds.values()) {\n          await b.offWork(workerId).catch(() => {});\n        }\n        workerIds.clear();\n        // graceful: 等 in-flight 任务完成；timeout 秒后强制处置\n        await b.stop({ close: true, graceful: true, timeout: Math.floor(timeoutMs / 1000) });\n        boss = null;\n      }\n    },\n\n    async stopWorkers() {\n      const b = boss;\n      if (b) {\n        for (const workerId of workerIds.values()) {\n          await b.offWork(workerId).catch(() => {});\n        }\n      }\n      workerIds.clear();\n    },\n  };\n}\n"],"mappings":";AACA,OAAO,YAAY;AA8BZ,SAAS,mBAAmB,UAA+B,CAAC,GAAe;AAChF,MAAI,OAAsB;AAC1B,MAAI,UAAU;AAEd,QAAM,YAAY,oBAAI,IAAoB;AAE1C,iBAAe,aAA8B;AAC3C,QAAI,CAAC,MAAM;AACT,aAAO,IAAI,OAAO,OAAO;AAEzB,YAAM,KAAK,MAAM;AAAA,IACnB;AACA,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,MAAM,QAAQ,MAAM,SAAS,MAAM;AACjC,UAAI,SAAS;AACX,cAAM,IAAI,MAAM,0DAA0D;AAAA,MAC5E;AACA,YAAM,IAAI,MAAM,WAAW;AAC3B,YAAM,cAAkC;AAAA,QACtC,YAAY,MAAM,WAAW;AAAA,QAC7B,YAAY;AAAA;AAAA,QACZ,cAAc;AAAA,QACd,GAAI,MAAM,UAAU,EAAE,YAAY,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,OAAO,EAAE,IAAI,CAAC;AAAA,MAC7E;AAEA,YAAM,KAAK,MAAM,EAAE,KAAK,MAAM,SAAmB,WAAW;AAC5D,UAAI,CAAC,IAAI;AACP,cAAM,IAAI,MAAM,yCAAyC,IAAI,GAAG;AAAA,MAClE;AACA,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,YAAY,MAAM,YAAY;AAClC,YAAM,IAAI,MAAM,WAAW;AAC3B,YAAM,UAA6B,WAAW;AAE9C,YAAM,WAAW,UAAU,IAAI,IAAI;AACnC,UAAI,UAAU;AACZ,cAAM,EAAE,QAAQ,QAAQ;AAAA,MAC1B;AACA,YAAM,WAAW,MAAM,EAAE;AAAA,QACvB;AAAA,QACA,EAAE,WAAW,WAAW,aAAa,iBAAiB,KAAK;AAAA,QAC3D,OAAO,SAAS;AACd,qBAAW,OAAO,MAAM;AAEtB,kBAAM,UAAU,IAAI,aAAa;AACjC,kBAAM,QAAQ;AAAA,cACZ,IAAI,IAAI;AAAA,cACR;AAAA,cACA,SAAS,IAAI;AAAA,cACb;AAAA,cACA,QAAQ,IAAI,gBAAgB,EAAE;AAAA;AAAA,YAChC,CAAC;AAAA,UACH;AAAA,QAEF;AAAA,MACF;AACA,gBAAU,IAAI,MAAM,QAAQ;AAAA,IAC9B;AAAA,IAEA,MAAM,KAAK,YAAY,KAAQ;AAC7B,gBAAU;AACV,YAAM,IAAI;AACV,UAAI,GAAG;AACL,mBAAW,YAAY,UAAU,OAAO,GAAG;AACzC,gBAAM,EAAE,QAAQ,QAAQ,EAAE,MAAM,MAAM;AAAA,UAAC,CAAC;AAAA,QAC1C;AACA,kBAAU,MAAM;AAEhB,cAAM,EAAE,KAAK,EAAE,OAAO,MAAM,UAAU,MAAM,SAAS,KAAK,MAAM,YAAY,GAAI,EAAE,CAAC;AACnF,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IAEA,MAAM,cAAc;AAClB,YAAM,IAAI;AACV,UAAI,GAAG;AACL,mBAAW,YAAY,UAAU,OAAO,GAAG;AACzC,gBAAM,EAAE,QAAQ,QAAQ,EAAE,MAAM,MAAM;AAAA,UAAC,CAAC;AAAA,QAC1C;AAAA,MACF;AACA,gBAAU,MAAM;AAAA,IAClB;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,11 +1,60 @@
 {
   "name": "@faapi/task-pgboss",
-  "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": "pg-boss task queue driver for faapi — persistent queue on PostgreSQL",
   "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",
+    "pg-boss": "^10.1.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11",
+    "@faapi/faapi": "6.3.0"
+  },
+  "peerDependencies": {
+    "pg-boss": "^10.0.0",
+    "@faapi/faapi": "^6.3.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faapi/faapi.git",
+    "directory": "packages/task-pgboss"
+  },
+  "bugs": {
+    "url": "https://github.com/faapi/faapi/issues"
+  },
+  "keywords": [
+    "faapi",
+    "task-queue",
+    "pg-boss",
+    "postgres",
+    "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"
   }
-}
+}