# @corbits/cron 中文文档

规范地址：https://npmcn.com/package/%40corbits/cron/

版本：0\.2\.2
npm 元数据更新时间：2026-10-20T02:20:47.934Z
中文译文更新时间：2026-11-10T19:35:49.369Z
软件包许可：LGPL-2\.1-only

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

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

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

- 包体积（解压后）：87.9 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- peer 依赖：hono ^4\.13\.8，@intx/db ^0\.5\.0，postgres ^3\.4\.9，drizzle-orm ^0\.45\.3，@intx/hub-api ^0\.5\.0
- 首次发布：2026-09-25T05:11:09.916Z
- 最新版本发布：2026-10-20T02:20:47.761Z
- 近 30 天下载量：3263（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

互换中枢的日程安排:赠款分配的日程路线外加一个将到期行转换为运行触发邮件的计时器

## 安装

```sh
npm install @corbits/cron
```

也可以使用：`pnpm add @corbits/cron`、`yarn add @corbits/cron`、`bun add @corbits/cron`

## README

# @ c轨道/ cron

在协调世界时5个战地克龙时间表上唤醒交流剂的轨道中心模块,作为 `@intx/hub-api` 中心(Interchange的多租户控制平面)上的路由,并存储在它的Postgres. 一个计时器邮件会按其代理的当前运行,代理的工作流程定义的运行实例来发送每个到期的调度.

调度支持创建、列表、暂停、恢复和删除。 没有编辑:删除再创建。 一个表达式必须能够起火(没有2月30日),最多256个字符和64个逗号条款.

## 为什么?

1.  **计划跟随代理,而不是运行.** 一个调度按其定义名称命名一个代理,所以它能活下来重新部署. 它等待代理机没有当前运行,当代理机被删除时会永远停止.
2.  **就像任何枢纽路线一样.** `createCronRoutes` 返回 a `Hono<TenantEnv>` 子应用程序。 每条路线都穿过枢纽 `requireGrant`,检查呼叫主(用户或代理账户)持有赠款(资源许可).
3.  **安全带几个枢纽复制品.** 计票人申请到期行数 `FOR UPDATE SKIP LOCKED`,所以没有时间表 点火两次。 移民是一能的,在每个靴子上都有一个咨询锁.

## 安装

```bash
bun add @corbits/cron @intx/authz @intx/db @intx/hub-api drizzle-orm hono postgres
```

运行于节点QQ24.

## 快速启动

```ts
import { nextCronFireAfter } from "@corbits/cron";

console.log(nextCronFireAfter("0 9 * * *", new Date()));
```

打印下09: 00 UTC, 下一次显示该表达点火的时间表 .

## 合适的话

[互换](https://github.com/faremeter/interchange) 由AI代理作为主要负责人,拥有自己的身份,权限和证书. 其中心拥有租户、校长、赠款和工作流程运行.

-   **运行于 :** 作为其Hono应用软件上的路线, 其过程中的滴答和其Postgres中的桌子.
-   **插入到 :** [`@intx/hub-api`](https://github.com/faremeter/interchange/tree/main/packages/hub-api) 路线和赠款,以及 [`@intx/db`](https://github.com/faremeter/interchange/tree/main/packages/db) (数量) `DBConfig`页:1 `tenant` 表格作为 FK 目标,及其工作流程定义和运行).
-   **与 :** [`@corbits/webhooks`](https://github.com/corbitsdev/webhooks)以及其他轨道中心模块, [`@corbits/mailbox`](https://github.com/corbitsdev/corbits-mailbox) 财务报告和审定财务报表 [`@corbits/artifacts`](https://github.com/corbitsdev/corbits-artifacts)。 。 。 .

## 参考文献

### `createCronRoutes(deps)`

| `deps` | 类型 | 主机提供的东西 |
| --- | --- | --- |
| `db` | `CronDb` | 枢纽的细雨柄. |
| `requireGrant` | `RequireGrant` | 从 `@intx/hub-api`是因为 `createRequireGrant`。 。 。 . |

### 路线

路径相对于主机上载子应用程序的位置.

| 方法 | 路径 | 赠款 | 目的 |
| --- | --- | --- | --- |
| 获取 | `/` | `cron-schedule:*` `read` | `{ schedules: [...] }` 给打电话的房客. |
| 邮政 | `/` | `cron-schedule:*` `create` | 从 `{ expression, definitionName, subject, body }`. 201 (中文(简体) ) `{ schedule }`; 400 (英语) `invalid_body`, (中文(简体) ), `invalid_expression` 或者说 `unknown_definition`。 。 。 . |
| 邮政 | `/:id/pause` | `cron-schedule:<id>` `manage` | 停止启动它. `{ schedule }` 与 `enabled: false`; 404 (简体中文) `not_found`。 。 。 . |
| 邮政 | `/:id/resume` | `cron-schedule:<id>` `manage` | 从接下来的比赛中再次开火. `{ schedule }` 与 `enabled: true`; 404 (简体中文) `not_found`。 。 。 . |
| 迪莱特 | `/:id` | `cron-schedule:<id>` `manage` | 删除一个时间表. `{ ok: true }`; 404 (简体中文) `not_found` 当它不在打电话者的房客. |

### `createCronTicker(opts)`

回返 `{ start(), stop() }`。 。 。 .

每分钟交货最多一次。 每个勾选符先承诺 `lastFiredAt` 在每行要求,然后打电话 `deliver` 在锁外 一个死在中段的进程,或者 `deliver` 投出,投出那分钟的火 而不是重复它; 时刻表再次起火 在它的下一个匹配分钟。 停止并等待回调 在他们的改变承诺后运行.

| `opts` | 类型 | 目的 |
| --- | --- | --- |
| `db` | `CronDb` | 枢纽的细雨柄. |
| `deliver` | `DeliverCronMail` | 发送一个到期时间表的邮件. `createRunTriggerCronDeliver(deliverer)` 建造它. |
| `intervalMs` | `number` (可选) | 民调期. 默认为60000. |
| `onTickError` | `(error) => void` (可选) | 发送前失败了 。 接下来的滴答重试. |
| `onDeliveryError` | `(error, schedule) => void` (可选) | 一次送货失败. |
| `onScheduleWaiting` | `(schedule) => void` (可选) | 日程安排开始等待它的代理下一个运行. |
| `onScheduleStopped` | `(schedule) => void` (可选) | 时间表停止 : `reason` 实值 `agent_deleted`,或 `invalid_expression` 对于一行永远不能开火. |

送货人扔出一个带错误 `RUN_GRANTS_NOT_ROUTABLE` 或者说 `RUN_MAIL_NOT_ROUTABLE` (与 `isUnroutableRunTrigger`当一个跑的地址死了。 如果运行的侧车已经放出,计时器会标记运行失败,所以调度会等待代理的下一场运行.

### `runCronMigrations(dbConfig, { schema })`

从 `@corbits/cron/migrations`参数与 `@intx/db`是因为 `runMigrations`。 。 。 . `schema` 持有主机 `tenant` 表格,必须先存在。 计时表总是住在 `cron` 计划 每只靴子上都叫这个.

### 其他出口

| 导出 | 使用 |
| --- | --- |
| `isValidCronExpression(expression)` | 语法,范围与上限检查. `POST /` 也要求可能发生火灾. |
| `nextCronFireAfter(expression, after)` | 在协调世界时之后的下一分钟 `after`。 。 。 . |
| `isUnroutableRunTrigger(error)`, (中文(简体) ), `RUN_GRANTS_NOT_ROUTABLE`, (中文(简体) ), `RUN_MAIL_NOT_ROUTABLE` | 死亡地址错误与送货人合同如下. |
| `CronRoutesDeps`, (中文(简体) ), `CreateCronTickerOpts`, (中文(简体) ), `CronTicker`, (中文(简体) ), `CronDb`, (中文(简体) ), `DeliverCronMail`, (中文(简体) ), `RunTriggerDeliverer`, (中文(简体) ), `UnroutableRunTrigger` | 以上各类. |

## 使用互换

运行每个枢纽靴子上的迁移 并构建路线:

```ts
import { timeWindowEvaluator } from "@intx/authz";
import { createDB, createGrantStore, runMigrations } from "@intx/db";
import { createRequireGrant } from "@intx/hub-api";
import { createCronRoutes } from "@corbits/cron";
import { runCronMigrations } from "@corbits/cron/migrations";

const dbConfig = {
  host: "localhost",
  port: 5432,
  user: "postgres",
  password: "postgres",
  database: "interchange",
};
await runMigrations(dbConfig, { schema: "public" });
await runCronMigrations(dbConfig, { schema: "public" });
const { db } = createDB(dbConfig);

export const cronRoutes = createCronRoutes({
  db,
  requireGrant: createRequireGrant({
    grantStore: createGrantStore(db),
    conditionRegistry: { time_window: timeWindowEvaluator },
  }),
});
```

挂载 `cronRoutes` 时间 `/cron` 下级 `/api/tenants/:tenantId`在枢纽的认证 和租户中间的软件。 给每本金 `cron-schedule:*` 与 `read` 财务报告和审定财务报表 `create` 以列表和创建,以及 `manage` 联 合 国 `cron-schedule:*` 或一个 `cron-schedule:<id>`删除. `POST /cron` 与 `{ "expression": "0 9 * * *", "definitionName": "daily-report", "subject": "Run", "body": "go" }` 然后邮寄 `daily-report` 每天协调世界时9: 00 代理.

每个中枢进程启动一个勾选器 `createCronTicker({ db, deliver: createRunTriggerCronDeliver(deliverer) })`时 `deliverer` 是枢纽的跑动触发器 `@corbits/webhooks`' `createRunTriggerDeliverer`调用 `ticker.stop()` 关闭。 在起火时 滴答邮件 `<run id>@<tenant domain>` 对于代理当前运行,所以代理工作流程需要一个 `mail` 触发。 复制品安全地共享桌子.

## 从0.1升级

-   `mountCron(app, opts)` 改为: `app.route(path, createCronRoutes({ db, requireGrant }))`。路线不再在 `/api/tenants/:tenantId/cron`但无论宿主上哪儿都行.
-   `requireTenantMember` 不见了 每个路线检查a `cron-schedule` 所以校长在申请之前需要这些补助 或者他们得到403.
-   `applyCronMigrations(url, { tenantSchema })` 现在 `runCronMigrations(dbConfig, { schema })`从 `@corbits/cron/migrations`。通过旧的 `tenantSchema` 值为 `schema`。 。 。 .
-   `cronScheduleTable`, (中文(简体) ), `CRON_FIELD_RANGES`, (中文(简体) ), `cronExpressionCanFire`, (中文(简体) ), `isValidTimeZone`, (中文(简体) ), `zonedParts`, (中文(简体) ), `MAX_LOOKAHEAD_MINUTES`, (中文(简体) ), `resolveLiveDeployment`, (中文(简体) ), `definitionExists`, (中文(简体) ), `failStaleAnchorRun` 类型 `CronField`, (中文(简体) ), `ZonedParts`, (中文(简体) ), `LiveDeployment`, (中文(简体) ), `MountCronOpts`, (中文(简体) ), `RequireTenantMember` 不再出口.
-   `@intx/db`, (中文(简体) ), `@intx/hub-api`, (中文(简体) ), `drizzle-orm`, (中文(简体) ), `hono` 财务报告和审定财务报表 `postgres` 现在已经是同龄人了.
-   `createCronTicker`是因为 `intervalMs` 是可选的,默认为1分钟.
-   现有数据库升级到第一个启动时没有手动步骤。 每0.1.0时刻表保持状态并持续开火.

## 许可证

LGPL-2.1-仅限. 见 [自由主义](https://github.com/corbitsdev/corbits-cron/blob/main/LICENSE)。 。 。 .

## 常见问题

### @corbits/cron 是什么？

互换中枢的日程安排:赠款分配的日程路线外加一个将到期行转换为运行触发邮件的计时器

### 如何安装 @corbits/cron？

在项目目录运行 npm install @corbits/cron，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：hono（^4\.13\.8）、@intx/db（^0\.5\.0）、postgres（^3\.4\.9）、drizzle-orm（^0\.45\.3）、@intx/hub-api（^0\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @corbits/cron 支持 TypeScript 吗？

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

### @corbits/cron 支持 ESM 还是 CommonJS？

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

### @corbits/cron 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @corbits/cron 可以商用吗？

@corbits/cron 使用 LGPL-2\.1-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @corbits/cron 的下载量有多少？

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

### @corbits/cron 还在维护吗？

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