# @chronark/zod-bird 中文文档

规范地址：https://npmcn.com/package/%40chronark/zod-bird/

版本：1\.0\.0
npm 元数据更新时间：2025-11-03T17:10:39.053Z
中文译文更新时间：2026-11-09T15:15:42.974Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chronark/zod-bird
原文对照：https://npmcn.com/package/%40chronark/zod-bird/?lang=original

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

- 包体积（解压后）：59.8 kB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^4\.0\.0
- 首次发布：2023-05-21T07:59:58.137Z
- 最新版本发布：2025-11-03T17:10:38.854Z
- 近 30 天下载量：188725（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 0 个）

## 中文简介

# @chronark/zod-bird (英语)

##### 使用 Zod 完全打入小鸟管

## 安装

```sh
npm install @chronark/zod-bird
```

也可以使用：`pnpm add @chronark/zod-bird`、`yarn add @chronark/zod-bird`、`bun add @chronark/zod-bird`

## README

# @chronark/zod-bird (英语)

##### 使用 Zod 完全打入小鸟管

  

-   类型安全
-   处理为您构建 url 参数
-   数据易于转换
-   在缓存指令中为下个js所建
-   以重试逻辑构建, 用于限制速率的请求

```ts
import { Tinybird } from "@chronark/zod-bird";
import { z } from "zod";

const tb = new Tinybird({ token: "token" });

export const getEvents = tb.buildPipe({
  pipe: "get_events__v1",
  parameters: z.object({
    tenantId: z.string(),
  }),
  data: z.object({
    event: z.string(),
    time: z.number().transform((t) => new Date(t)),
  }),
});


const res = await getEvents({ tenantId: "chronark" })

// res.data = {event: string, time: Date}[]
// if no rows found, res.data will be an empty array
```

## 安装

```
npm i @chronark/zod-bird
```

## 输入数据

```ts
// lib/tinybird.ts
import { Tinybird } from "./client";
import { z } from "zod";

const tb = new Tinybird({ token: process.env.TINYBIRD_TOKEN! });

export const publishEvent = tb.buildIngestEndpoint({
  datasource: "events__v1",
  event: z.object({
    id: z.string(),
    tenantId: z.string(),
    channelId: z.string(),
    time: z.number().int(),
    event: z.string(),
    content: z.string().optional().default(""),
    metadata: z.string().optional().default(""),
  }),
});
```

```ts
// somewhere.ts
import { publishEvent } from "./lib/tinybird";

await publishEvent({
  id: "1",
  tenantId: "1",
  channelId: "1",
  time: Date.now(),
  event: "test",
  content: "test",
  metadata: JSON.stringify({ test: "test" }),
});
```

或多事件成批地,使用单向天鸟求取.

```ts
// somewhere.ts
import { publishEvent } from "./lib/tinybird";

await publishEvent([
  {
    id: "1",
    tenantId: "1",
    channelId: "1",
    time: Date.now(),
    event: "test",
    content: "test",
    metadata: JSON.stringify({ test: "test" }),
  },
  {
    id: "2",
    tenantId: "2",
    channelId: "2",
    time: Date.now(),
    event: "test2",
    content: "test2",
    metadata: JSON.stringify({ test2: "test2" }),
  },
]);
```

## 查询终点

```ts
// lib/tinybird.ts
import { Tinybird } from "./client";
import { z } from "zod";

const tb = new Tinybird({ token: process.env.TINYBIRD_TOKEN! });

export const getChannelActivity = tb.buildPipe({
  pipe: "get_channel_activity__v1",
  parameters: z.object({
    tenantId: z.string(),
    channelId: z.string().optional(),
    start: z.number(),
    end: z.number().optional(),
    granularity: z.enum(["1m", "1h", "1d", "1w", "1M"]),
  }),
  data: z.object({
    time: z.string().transform((t) => new Date(t).getTime()),
    count: z
      .number()
      .nullable()
      .optional()
      .transform((v) => (typeof v === "number" ? v : 0)),
  }),
});
```

```ts
// somewhere.ts
import { getChannelActivity } from "./lib/tinybird";


const res = await getChannelActivity({
   tenantId: "1",
   channelId: "1",
   start: 123,
   end: 1234,
   granularity: "1h"
})

```

`res` 是来自小鸟端点的响应,但现在已完全输入,数据已经按照定义的图解解析 `data`。 。 。 .

## 处理错误

对于 `429` (超过限额)和 `500` 错误, `zod-bird` 自动重试( e)[源代码](https://github.com/chronark/zod-bird/blob/52944e5aebcfb547f9ccaf1e3fca03b158953e8f/src/client.ts#L45-L60)) (中文(简体) ).

其它错误都会丢出 `Exception`因此,你应该抓住它 通过尝试捕获:

```typescript
try {
    const res = await getEvents({ tenantId: "chronark" })
    return res.data
} catch (e) {
    console.error(e)
    return e.messsage
}
```

## 高级

### 缓存

你可以在每个管子上添加缓存指令.

#### 禁用缓存( 用于默认缓存万事的 Next.js )

```ts
tb.buildPipe({
  pipe: "some_pipe__v1",
  parameters: z.object({
   hello: z.string()
  }),
  data: z.object({
    response: z.string()
  }),
   opts: {
      cache: "no-store" // <-------- Add this
   };
});

```

#### 缓存15分钟

```ts

tb.buildPipe({
  pipe: "some_pipe__v1",
  parameters: z.object({
   hello: z.string()
  }),
  data: z.object({
    response: z.string()
  }),
   opts: {
      next: {
        revalidate: 900 ;// <-------- Add this
      }
    };
});
```

## 常见问题

### @chronark/zod-bird 是什么？

@chronark/zod-bird \(英语\) 使用 Zod 完全打入小鸟管

### 如何安装 @chronark/zod-bird？

在项目目录运行 npm install @chronark/zod-bird，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @chronark/zod-bird 支持 TypeScript 吗？

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

### @chronark/zod-bird 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @chronark/zod-bird 可以商用吗？

@chronark/zod-bird 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chronark/zod-bird 的下载量有多少？

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

### @chronark/zod-bird 还在维护吗？

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