Community寫作與編輯github.com

mwpryer/kilncast

🔥 輕量型別包裝層,用於 Firestore SDK,提供型別推論但無執行時期驗證。

kilncast 是什麼?

kilncast 是一個輕量、型別安全的包裝層,建構於 Firestore (firebase-admin 與模組化 firebase SDK) 之上。它利用 Zod、Valibot 或 ArkType 等標準 Schema 驗證器來定義文件結構,但**不會在執行時期執行 Schema**——僅用於 TypeScript 型別推論,提供開發時期型別安全,而不增加運行時期效能開銷。支援伺服器端 (firebase-admin)、網頁端 (firebase) 以及純型別核心模組,可在共用模組中安全使用而不引入 Firebase。核心規則強調 ID 僅為路徑、讀取回傳 `Doc | null`、界線型別強制轉換 (例如 Timestamp ↔ Date)、自訂哨兵值 (serverTimestamp、increment 等)、型別安全查詢、交易與批次寫入,以及透過 `.ref` 屬性直接存取原始 SDK。特別適合需要型別安全但希望保持 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
# 網頁端
npm install kilncast firebase

三個進入點:

  • kilncast:中性核心。Schema 定義、哨兵值、型別、KilncastError。不匯入任何 Firebase,適合在共用模組與前端套件中使用。
  • kilncast/admin:createDatabase(getFirestore()) 包裝 firebase-admin,並提供型別化的 ref 輔助函式。重新匯出整個中性核心。
  • 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 可以是任何標準 Schema 驗證器 (Zod、Valibot、ArkType)。它描述一個文件的所有欄位,但不包含 id。

核心規則

  1. ID 僅存在於路徑中。 永遠不要在 Schema 中宣告 id 欄位 (編譯錯誤)。讀取時會將 id 扁平合併;寫入時會排除它。add(data) 回傳產生的 id。
  2. 讀取不到的資料為 null。 get() 回傳 Doc<S> | null;沒有 .exists 快照可檢查 (請使用 .doc(id).exists() 取得布林值)。
  3. 邊界值會進行型別強制轉換。 寫入 Date,讀取 Date (儲存為 Timestamp);寫入 Uint8Array,讀取 Uint8Array (儲存為 SDK 位元組)。適用於深層地圖與陣列。
  4. 哨兵值是 kilncast 自己的。 從 kilncast 匯入 serverTimestamp、increment、arrayUnion、arrayRemove、deleteField,永遠不要從 SDK 匯入 FieldValue。每個哨兵值都受型別約束,僅適用於符合的欄位 (increment 用於數值,deleteField 僅用於可選欄位)。
  5. 查詢的型別會對應 Schema。 where / orderBy 接受型別化的點分隔路徑,用於巢狀地圖 (例如 "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 逃脫機制以及注意事項。

相關技能