Was macht kilncast?
Dünner, typisierter Wrapper über Firestore. Er typt und konvertiert, er validiert nicht: Das Schema dient nur der Typinferenz und wird nie ausgeführt, daher gibt es keine Laufzeitvalidierung. Darunter liegt reines Firestore; jedes Handle stellt .ref zur Verfügung, um auf das rohe SDK zurückzugreifen.
Einrichtung
# Server
npm install kilncast firebase-admin
# Web
npm install kilncast firebase
Drei Einstiegspunkte:
kilncast: neutral. Schema-Definition, Sentinels, Typen,KilncastError. Importiert kein Firebase, sicher in gemeinsamen Modulen und Frontend-Bundles.kilncast/admin:createDatabase(getFirestore())überfirebase-admin, plus typisierte Ref-Helfer. Exportiert den gesamten neutralen Kern.kilncast/web: dasselbe über das modularefirebase-SDK.
Schnellstart
import { collection, increment } from "kilncast";
// oder "kilncast/web"
import { createDatabase } from "kilncast/admin";
import { getFirestore } from "firebase-admin/firestore";
import { z } from "zod";
// Einfache, ungebundene Definition, einmal in einem gemeinsamen Modul, das nur "kilncast" importiert
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: "Hallo", 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();
Das Schema ist jeder Standard Schema -Validator (Zod, Valibot, ArkType). Es beschreibt die Felder eines Dokuments, ohne die ID.
Kernregeln
- IDs sind pfadbasiert. Deklarieren Sie niemals ein
id-Feld in einem Schema (Kompilierungsfehler). Lesevorgänge nehmenidflach auf; Schreibvorgänge schließen es aus.add(data)gibt die generierte ID zurück. - Fehlende Lesevorgänge sind
null.get()gibtDoc<S> | nullzurück; es gibt keinen.exists-Snapshot (verwenden Sie.doc(id).exists()für einen Boolean). - Werte werden an der Grenze konvertiert. Schreiben Sie ein
Date, lesen Sie einDate(gespeichert alsTimestamp); schreiben Sie einUint8Array, lesen Sie einUint8Array(gespeichert als SDK-Bytes). Tief durch Maps und Arrays. - Sentinels sind
kilncast-eigene. Importieren SieserverTimestamp,increment,arrayUnion,arrayRemove,deleteFieldauskilncast, niemalsFieldValueaus einem SDK. Jeder ist typbeschränkt auf die Felder, zu denen er passt (incrementauf Zahlen,deleteFieldnur auf optionale Felder). - Queries sind auf das Schema typisiert.
where/orderByakzeptieren typisierte Punktnotation in verschachtelte Maps ("customer.address.city"); ein falsch geschriebenes Feld oder falscher Wertetyp führt zu einem Kompilierungsfehler. Adressieren Sie die ID mitdocumentId()auskilncast. - Punktierte Pfade funktionieren nur in
update.update("o1", { "totals.items": increment(1) })berührt ein verschachteltes Feld. In einemsetmit Merge ist ein Punkt-Pfad ein literalischer Feldname, also verschachteln Sie stattdessen ein Objekt. - Transaktions- und Batch-Schreibvorgänge benötigen kein
await. Lesevorgänge in einer Transaktion sind asynchron; Schreibvorgänge gebenvoidzurück und puffern bis zum Commit. Batches sind schreibgeschützt (keinget, keinadd) und werden atomar mit.commit()angewendet. - Keine Laufzeitvalidierung. Ein Dokument, das von seinem Schema abweicht, kommt als gültig typisiert zurück. Wenn die Abweichung relevant ist, führen Sie das Schema selbst auf dem Ergebnis aus.
- SDK-Semantik gewinnt.
kilncastumschließt niemals Firestore-, Netzwerk- oder Berechtigungsfehler;KilncastErrordeckt nurkilncast-eigene Fehler ab. Alles, waskilncastnicht umschließt, ist über.referreichbar.
Häufige Operationen
const col = db.collection(posts);
// Lesevorgänge
// Doc | null
await col.get("hello");
// boolean
await col.doc("hello").exists();
// Schreibvorgänge, auch auf 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) });
// gibt die neue ID zurück
const id = await col.add({ title: "New", likes: 0, createdAt: new Date() });
await col.delete(id);
// Queries, unveränderlicher Builder, .get() alias .list()
await col.where("likes", ">=", 10).orderBy("likes", "desc").limit(5).get();
await col.count();
// 0 bei leerem Treffer
await col.sum("likes");
// null bei leerem Treffer
await col.average("likes");
// gibt unsubscribe-Funktion zurück
const unsub = col.onSnapshot((docs) => {});
// Subkollektion, dieselbe Definition auf jeder Tiefe wiederverwendbar
db.collection(posts).doc("hello").collection(comments);
// Sammlungsgruppe, jede Sammlung mit diesem Namen
await db.collectionGroup(comments).orderBy("createdAt").get();
// Transaktion, Lesevorgänge asynchron, Schreibvorgänge synchron
await db.runTransaction(async (tx) => {
const post = await tx.collection(posts).get("hello");
if (post) tx.collection(posts).update("hello", { likes: post.likes + 1 });
});
// Batch, schreibgeschützt, atomar bei commit
const batch = db.batch();
batch.collection(posts).update("hello", { likes: increment(1) });
await batch.commit();
Vollständige Referenz
Siehe REFERENCE.md für Queries und Cursor, Sentinels und verschachtelte Updates, Live-Updates, Transaktionen und Batches im Detail, rohe Felder und vollpräzise Timestamps, Bytes, neutrale Wertetypen, den .ref-Escape-Mechanismus und Stolperfallen.