R2D1 / 文档

TypeScript

TypeScript 包通过一个集合 API 连接 R2 文档存储和 D1 索引。选择运行时适配器，并提供 schema 与 document codec。

安装

Node.js 适配器需要 Node.js 22 或更高版本。Cloudflare Workers 使用 Workers 子路径。

npm install @nexcraft-dev/r2d1

Node.js

使用 Node.js 的 R2 和 D1 适配器。以下代码假定 r2Config、d1Config、schema 和 codec 已配置。

import { R2D1 } from "@nexcraft-dev/r2d1";
import { NodeR2DocumentStore, NodeD1IndexStore } from "@nexcraft-dev/r2d1/node";

const users = await new R2D1(
  new NodeR2DocumentStore(r2Config),
  new NodeD1IndexStore(d1Config),
).collection(schema, codec);

await users.put({ id: "user-1", country: "NZ", score: 4.5 });
const page = await users
  .query().where("country").eq("NZ")
  .sortBy("score", "DESC").limit(20).fetch();

Cloudflare Workers

将 R2 bucket 绑定为 DOCUMENTS，将 D1 database 绑定为 INDEXES，然后传给 Workers 适配器。

import { R2D1 } from "@nexcraft-dev/r2d1";
import {
  WorkersR2DocumentStore,
  WorkersD1IndexStore,
} from "@nexcraft-dev/r2d1/workers";

const users = await new R2D1(
  new WorkersR2DocumentStore(env.DOCUMENTS),
  new WorkersD1IndexStore(env.INDEXES),
).collection(schema, codec);

Java 数据兼容性

R2 key、D1 table、index 和 cursor 格式遵循 Java 契约。文档字节格式由应用决定：Java 没有默认格式。请使用能读写相同字节的 TypeScript codec。jsonCodec 是可选项，且不支持 bigint。TypeScript 的 long 字段使用 bigint。

完整示例

仓库提供完整的 Node.js、Workers 和共享 codec 示例。