# @danthegoodman/quick-convex 中文文档

规范地址：https://npmcn.com/package/%40danthegoodman/quick-convex/

版本：0\.2\.14
npm 元数据更新时间：2026-09-18T00:38:18.600Z
中文译文更新时间：2026-11-11T11:07:53.676Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40danthegoodman/quick-convex
原文对照：https://npmcn.com/package/%40danthegoodman/quick-convex/?lang=original
项目主页：https://github.com/danthegoodman1/quick-convex#readme
源码仓库：https://github.com/danthegoodman1/quick-convex

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：553 kB，85 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.43\.0
- 首次发布：2026-02-08T15:14:12.020Z
- 最新版本发布：2026-09-18T00:38:18.428Z
- 近 30 天下载量：9484（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Convex的快速对流组件.

## 安装

```sh
npm install @danthegoodman/quick-convex
```

也可以使用：`pnpm add @danthegoodman/quick-convex`、`yarn add @danthegoodman/quick-convex`、`bun add @danthegoodman/quick-convex`

## README

# QuiCK 凸起轴

A 类 [奎凯](https://www.foundationdb.org/files/QuiCK.pdf)\- 将队列执行作为Convex组件.

## 安装

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import quickConvex from "@danthegoodman/quick-convex/convex.config.js";

const app = defineApp();
app.use(quickConvex, { name: "quickVesting" });
app.use(quickConvex, { name: "quickFifo" });

export default app;
```

## 用对流测试

注册每个快速组件实例 `convex-test` 使用来自 `@danthegoodman/quick-convex/test`。使用您配置的相同组件名称 内 `convex.config.ts`。 。 。 .

```ts
import { convexTest } from "convex-test";
import schema from "./schema.js";
import quickTest from "@danthegoodman/quick-convex/test";

const modules = import.meta.glob("./**/*.*s");

export function initConvexTest() {
  const t = convexTest(schema, modules);

  quickTest.register(t, "quickVesting");
  quickTest.register(t, "quickFifo");

  return t;
}
```

一旦排出排出排出队列,且组件被闲置,Quick就应该清空了 下级 `convex-test` 没有额外的快速减速步骤.

如果你的测试故意留下 推迟预定的未来工作 预定工作在测试结束时仍将存在。 撕裂的修复只覆盖了 Stale 在组件否则闲置后进行内部快速重新安排.

## 快速类 API

使用类 API 来排队工作 :

```ts
import { Quick } from "@danthegoodman/quick-convex";
import { components, api } from "./_generated/api";

const quickVesting = new Quick(components.quickVesting, {
  defaultOrderBy: "vesting",
  managerSlots: 10,
  workersPerManager: 25,
  retryByDefault: true,
  defaultRetryBehavior: {
    maxAttempts: 5,
    initialBackoffMs: 250,
    base: 2,
  },
});

const quickFifo = new Quick(components.quickFifo, {
  defaultOrderBy: "fifo",
});
```

### 工人职能合同

工人必须接受这种论点:

```ts
{
  payload: TPayload;
  queueId: string;
}
```

这既适用于行动工人,也适用于突变工人.

### 行动工作者

```ts
export const enqueueEmail = mutation({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return await quickVesting.enqueueAction(ctx, {
      queueId: args.userId,
      priority: 12,
      fn: api.jobs.sendEmailWorker,
      args: { userId: args.userId },
      runAfter: 5_000,
    });
  },
});
```

### Enqueue 突变工人

```ts
export const enqueueMutationWorker = mutation({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return await quickVesting.enqueueMutation(ctx, {
      queueId: args.userId,
      fn: api.jobs.processUserMutationWorker,
      args: { userId: args.userId },
    });
  },
});
```

### 批次队列( 多功能)

`enqueueBatchAction` 财务报告和审定财务报表 `enqueueBatchMutation` 接受批次中每个单项函数的 refs和dedupe 处理创建.

```ts
export const enqueueBatch = mutation({
  args: { queueId: v.string() },
  handler: async (ctx, args) => {
    return await quickFifo.enqueueBatchAction(ctx, [
      {
        queueId: args.queueId,
        fn: api.jobs.workerA,
        args: { value: 1 },
      },
      {
        queueId: args.queueId,
        fn: api.jobs.workerA,
        args: { value: 2 },
      },
      {
        queueId: args.queueId,
        fn: api.jobs.workerB,
        args: { value: 3 },
      },
    ]);
  },
});
```

### 在补全调用中重试

`onComplete` 永远是一个变异的手柄,为动作工人和变异工人运行. 快速持续完成状态`phase: "onComplete"`),在坠机后恢复在那里,因此完成处理者被安全地重试了2次.

```ts
import { vOnCompleteArgs } from "@danthegoodman/quick-convex";

export const onEmailComplete = mutation({
  args: vOnCompleteArgs(v.object({ userId: v.string() })),
  handler: async (_ctx, args) => {
    // args: { workId, context, status, result }
    return null;
  },
});

export const enqueueEmail = mutation({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return await quickVesting.enqueueAction(ctx, {
      queueId: args.userId,
      fn: api.jobs.sendEmailWorker,
      args: { userId: args.userId },
      onComplete: {
        fn: api.jobs.onEmailComplete,
        context: { userId: args.userId },
      },
    });
  },
});
```

`vOnCompleteArgs()` 不使用上下文验证符 `context: any`。 。 。 .

### 重试配置

-   设置类默认值 `new Quick(component, { retryByDefault, defaultRetryBehavior })`。 。 。 .
-   每个项目覆盖 `retry`数字 :
-   `retry: false` 禁用该项的重试 .
-   `retry: true` 使用类/默认重试行为.
-   `retry: { maxAttempts, initialBackoffMs, base }` 设定每个项目的行为.

### 运行时间管理槽

`managerSlots` 控制管理器的动作可以同时要求队列指针. 准备吧 `0` 暂停新工作而不排队占位符项目。 已经 经营工人继续工作,直到他们结束.

```ts
export const pauseQuick = mutation({
  args: {},
  handler: async (ctx) => {
    await ctx.runMutation(components.quickVesting.config.update, {
      managerSlots: 0,
    });
  },
});

export const resumeQuick = mutation({
  args: {},
  handler: async (ctx) => {
    await ctx.runMutation(components.quickVesting.config.update, {
      managerSlots: 10,
    });
    await ctx.runMutation(components.quickVesting.config.kick, {});
  },
});
```

如果使用类 API,则可用的控件与 `quick.setManagerSlots(ctx, slots)` 财务报告和审定财务报表 `quick.kick(ctx)`。 。 。 .

### 授予模式的优先级

-   `priority` 可选于 `enqueueAction`, (中文(简体) ), `enqueueMutation`,并批发项目.
-   失踪 `priority` 默认为 `0`。 。 。 .
-   支持的值为整数 `0..15`。 。 。 .
-   人数较多是更优先的事项.
-   优先权仅影响 `"vesting"` 模式.

## 队列行为

-   支助 `"vesting"` 财务报告和审定财务报表 `"fifo"` 命令模式.
-   FIFO物品由 Convex 输入时间戳来订购,所以同时排队 遵守交易承诺命令。 由旧的快版本排出排队的项目 升级后在时间戳上标出的项目.
-   使用指针扫描和租赁,同时进行处理.
-   `managerSlots` 控制最大同时运行的管理器( 默认) `10`) (中文(简体) ).
-   `managerSlots: 0` 暂停新管理者索赔, 直至提出值并踢出扫描仪 .
-   `workersPerManager` 控制每个管理器减压的项目数 `queueId` 通过( 默认) `10`) (中文(简体) ).
-   包括克龙式回收和指针式垃圾收集.

### 选择命令模式

-   使用 `"vesting"` 当吞吐量是优先。 已准备好的项目一旦到期即可运行,因此被延迟/再审的项目不会在同一队列中阻挡较新的已准备好的工作.
-   单位 `"vesting"` 模式,已准备好的项目由 `priority` 首先,然后通过 `vestingTime` 在优先级别之内.
-   跨队列优先级是最佳的,而不是严格的,因为队列排程仍然是以指针为基础的.
-   使用 `"fifo"` 当严格的每 -`queueId` 需要订购。 执行命令域的主语义。 单位 `"fifo"` 模式,延迟/重试的头项会拖住其余部分 `queueId` 直到它再次准备好.

在实践中,FIFO队列常常是一个更清洁和更能发挥作用的替代品,而不是创建许多 `maxParallelism: 1` 工作池(每个订购域一个). 使用快速 FIFO, 使用 `queueId` 作为域名密钥(例如用户名、账户名、或汇总名),以及每个域名(`queueId` ) 保持命令,而不同的域仍然可以并行处理.

## 比较 Convex 工作池

快取自康维克斯·沃克普斯和"克克克"的论文. 工作池是出色的,生产证明的,这个组成部分基于许多相同的想法.

### 工作场所的优势

-   略轻重量跑时模型.
-   正式由Convex团队维护.
-   在许多常见的设置中操作简单.
-   生产 - 规模证明在Convex.

### 工作池边缘情况

-   在一些突起的扩大模式中(例如: `0` 对许多列入清单的项目来说,争论可能围绕所称的工作发生.
-   今天, Workpools 不在“ 完成” 超时失败上重试 .

### 快速优势

-   多个订购模式,特别是严格的每个域FIFO通过 `queueId`。 。 。 .
-   FIFO 比通过许多程序模拟订单容易得多 `maxParallelism: 1` 劳动池.
-   从闲置到重载的更快更低.
-   Oncomplete 超时失败被重审了最多两次.
-   QuiCK模型在苹果公司得到规模验证(但此执行不在此列!)

### 考虑权衡

-   当负载低或未分期摊还时,快则每单位工作会更重一点(每个工作周围会有更多的队列-管理动作/动作).

## 示例

见 `example/convex/example.ts` 用于端到端使用 `Quick`。 。 。 .

## 常见问题

### @danthegoodman/quick-convex 是什么？

Convex的快速对流组件\.

### 如何安装 @danthegoodman/quick-convex？

在项目目录运行 npm install @danthegoodman/quick-convex，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.43\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @danthegoodman/quick-convex 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @danthegoodman/quick-convex 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @danthegoodman/quick-convex 可以商用吗？

@danthegoodman/quick-convex 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @danthegoodman/quick-convex 的下载量有多少？

根据 npm 官方下载统计，@danthegoodman/quick-convex 在 2026/10/12 – 2026/11/10 这 30 天内被下载 9,484 次，日均约 316 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @danthegoodman/quick-convex 还在维护吗？

最新版本 0\.2\.14 发布于 2026/09/18（1 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。