Community写作与编辑github.com

mwpryer/kilncast

🔥 轻量级的 Schema 类型化 Firestore SDK 封装

kilncast 是什么?

kilncast 是一个轻量级的 Firestore 类型安全封装层,它利用 Standard Schema 验证器(如 Zod、Valibot、ArkType)来定义文档结构,从而实现强类型推断。它不引入运行时验证,而是将 Schema 严格用于 TypeScript 类型推断,底层仍然是标准的 Firestore API。 该工具支持三种入口:无平台依赖的核心模块(kilncast)、Firebase Admin SDK(kilncast/admin)和 Web 端 Firebase 模块(kilncast/web)。通过提供类型安全的集合引用、查询构建器、事务、批量写入、实时快照等操作,它显著提升了开发体验,同时保留了通过 `.ref` 属性降级到原始 SDK 的灵活性。 kilncast 遵循一系列核心规则:ID 只能通过路径访问,缺失文档返回 null,且自动处理 Date、Uint8Array 等类型的边界转换。它自定义了 serverTimestamp、increment 等哨兵值,并确保查询的 where 和 orderBy 路径在编译时进行类型检查。整体上,它没有添加额外的运行时开销或错误处理,Firestore 的原始语义和错误信息都会保留。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add mwpryer/kilncast

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

kilncast 是做什么的?

轻量级的类型化 Firestore 封装。它负责类型推断和类型强转,但不进行验证:schema 仅用于类型推断,不会在运行时执行,因此不存在运行时验证。底层仍然是原生的 Firestore;每个处理句柄都暴露 .ref 以便降级到原始 SDK。

设置

# 服务端
npm install kilncast firebase-admin
# Web 端
npm install kilncast firebase

三个入口:

  • kilncast:无平台依赖。包含 Schema 定义、哨兵值、类型、KilncastError。不导入 Firebase,适用于共享模块和前端打包。
  • kilncast/admin:基于 firebase-admin 的 createDatabase(getFirestore()),以及类型化的引用辅助函数。重新导出了无平台依赖的核心模块。
  • kilncast/web:基于模块化 firebase SDK 的相同封装。

快速开始

import { collection, increment } from "kilncast";
// 或者 "kilncast/web"
import { createDatabase } from "kilncast/admin";
import { getFirestore } from "firebase-admin/firestore";
import { z } from "zod";

// 无绑定关系的基础定义,在仅引入 "kilncast" 的共享模块中定义一次即可
const posts = collection(
  "posts",
  z.object({ title: z.string(), likes: z.number(), createdAt: z.date() }),
);

const db = createDatabase(getFirestore());

await db
  .collection(posts)
  .set("hello", { title: "Hello", likes: 0, createdAt: new Date() });
// Doc | null, Doc = T & { id }
const post = await db.collection(posts).get("hello");
await db.collection(posts).update("hello", { likes: increment(1) });
const popular = await db
  .collection(posts)
  .where("likes", ">=", 10)
  .orderBy("likes", "desc")
  .limit(10)
  .get();

Schema 可以是任何 Standard Schema 验证器(Zod、Valibot、ArkType)。它描述了一个文档的字段,不包含 id。

核心规则

  1. ID 只存在于路径中。 永远不要在一个 Schema 中声明 id 字段(编译时会报错)。读取时会将 id 合并到返回对象中;写入时则排除 id。add(data) 会返回自动生成的 id。
  2. 读取缺失文档返回 null。 get() 返回 Doc<S> | null;没有 .exists 快照需要检查(可以使用 .doc(id).exists() 来获取布尔值)。
  3. 值在边界处进行类型强转。 写入 Date 类型,读取时得到 Date 类型(内部以 Timestamp 存储);写入 Uint8Array 类型,读取时得到 Uint8Array 类型(内部以 SDK 字节类型存储)。这种转换在 map 和数组深层也能生效。
  4. 哨兵值是 kilncast 自带的。 从 kilncast 中导入 serverTimestamp、increment、arrayUnion、arrayRemove、deleteField,永远不要从 SDK 的 FieldValue 中导入。每个哨兵值都有类型约束,只能用于合适的字段(increment 用于数字类型,deleteField 仅用于可选字段)。
  5. 查询是 Schema 类型安全的。 where / orderBy 接受带类型的点分隔路径,用于访问嵌套的 map(例如 "customer.address.city");拼写错误的字段名或错误的值类型会在编译时报错。如果要针对 id 进行查询,请使用 kilncast 中的 documentId()。
  6. 点分隔路径键仅在 update 中有效。 update("o1", { "totals.items": increment(1) }) 只会修改一个嵌套字段。在合并模式下的 set 操作中,点分隔键会被视为字面量字段名,因此请改用嵌套对象。
  7. 事务和批量写入不需要 await。 事务中的读取操作是异步的;写入操作返回 void,并将结果缓冲直到提交。批量操作是只写的(不支持 get 或 add),并在调用 .commit() 时原子性地应用。
  8. 没有运行时验证。 如果一个文档已经偏离了它的 Schema,返回时仍然会按照 Schema 的类型来推断。如果担心数据漂移问题,请自己手动对结果进行 Schema 验证。
  9. SDK 语义优先。 kilncast 从不封装 Firestore、网络或权限错误;KilncastError 仅涵盖 kilncast 自身的失败情况。任何 kilncast 未封装的功能都可以通过 .ref 访问。

常见操作

const col = db.collection(posts);

// 读取
// Doc | null
await col.get("hello");
// boolean
await col.doc("hello").exists();

// 写入,也可以使用 col.doc("hello") 进行
await col.set("hello", { title: "Hi", likes: 0, createdAt: new Date() });
await col.set("hello", { likes: 1 }, { merge: true });
await col.update("hello", { likes: increment(1) });
// 返回新 id
const id = await col.add({ title: "New", likes: 0, createdAt: new Date() });
await col.delete(id);

// 查询,不可变构建器,.get() 别名 .list()
await col.where("likes", ">=", 10).orderBy("likes", "desc").limit(5).get();
await col.count();
// 无匹配时返回 0
await col.sum("likes");
// 无匹配时返回 null
await col.average("likes");
// 返回取消订阅函数
const unsub = col.onSnapshot((docs) => {});

// 子集合,相同的定义可在任意层级复用
db.collection(posts).doc("hello").collection(comments);

// 集合组,包含所有同名集合
await db.collectionGroup(comments).orderBy("createdAt").get();

// 事务,读取异步,写入同步
await db.runTransaction(async (tx) => {
  const post = await tx.collection(posts).get("hello");
  if (post) tx.collection(posts).update("hello", { likes: post.likes + 1 });
});

// 批量操作,只写,提交时原子执行
const batch = db.batch();
batch.collection(posts).update("hello", { likes: increment(1) });
await batch.commit();

完整参考

详见 REFERENCE.md 了解查询与游标、哨兵值与嵌套更新、实时更新、事务与批处理的详细说明,以及原始字段与全精度时间戳、字节值、中立值类型、.ref 逃生舱和注意事项。

相关技能