kilncast 是做什麼的?
Firestore 的輕量型別包裝層。它進行型別推論與強制轉換,但不進行驗證:Schema 僅用於型別推論,永遠不會被執行,因此沒有執行時期驗證。底層仍是純粹的 Firestore;每個控制代碼都提供 .ref 屬性,讓您可以降級使用原始 SDK。
設定
# 伺服器端
npm install kilncast firebase-admin
# 網頁端
npm install kilncast firebase
三個進入點:
kilncast:中性核心。Schema 定義、哨兵值、型別、KilncastError。不匯入任何 Firebase,適合在共用模組與前端套件中使用。kilncast/admin:createDatabase(getFirestore())包裝firebase-admin,並提供型別化的 ref 輔助函式。重新匯出整個中性核心。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 可以是任何標準 Schema 驗證器 (Zod、Valibot、ArkType)。它描述一個文件的所有欄位,但不包含 id。
核心規則
- ID 僅存在於路徑中。 永遠不要在 Schema 中宣告
id欄位 (編譯錯誤)。讀取時會將id扁平合併;寫入時會排除它。add(data)回傳產生的 id。 - 讀取不到的資料為
null。get()回傳Doc<S> | null;沒有.exists快照可檢查 (請使用.doc(id).exists()取得布林值)。 - 邊界值會進行型別強制轉換。 寫入
Date,讀取Date(儲存為Timestamp);寫入Uint8Array,讀取Uint8Array(儲存為 SDK 位元組)。適用於深層地圖與陣列。 - 哨兵值是
kilncast自己的。 從kilncast匯入serverTimestamp、increment、arrayUnion、arrayRemove、deleteField,永遠不要從 SDK 匯入FieldValue。每個哨兵值都受型別約束,僅適用於符合的欄位 (increment用於數值,deleteField僅用於可選欄位)。 - 查詢的型別會對應 Schema。
where/orderBy接受型別化的點分隔路徑,用於巢狀地圖 (例如"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 逃脫機制以及注意事項。