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