CommunitySchreiben & Editierengithub.com

mwpryer/kilncast

🔥 Dünner, schema-typisierter Wrapper über Firestore-SDKs

Was ist kilncast?

Kilncast ist ein schlanker, typisierter Wrapper um die Firestore-SDKs von Firebase, der Entwicklern eine typsichere Schnittstelle bietet, ohne die Laufzeitvalidierung zu erzwingen. Das Schema dient ausschließlich der Typinferenz und wird nie ausgeführt – es gibt also keine Runtime-Validierung. Darunter liegt reines Firestore; jedes Handle stellt ein `.ref` zur Verfügung, um auf das rohe SDK zurückzugreifen. Die Bibliothek unterstützt drei Einstiegspunkte: ein neutrales Kernmodul (`kilncast`), das weder Firebase noch eine Plattform importiert, sowie `kilncast/admin` für das Admin-SDK und `kilncast/web` für das modulare Web-SDK. Entwickler können mit jedem Standard-Schema-Validator (Zod, Valibot, ArkType) ihre Dokument-Schemata definieren und erhalten vollständige TypeScript-Typfähigkeit in Lese-, Schreib- und Query-Operationen. Kilncast automatisiert die Koerzierung an den Grenzen: Timestamps werden zu `Date`, Bytes zu `Uint8Array`. Es stellt eigene Sentinels (`serverTimestamp`, `increment`, `arrayUnion`, `arrayRemove`, `deleteField`) bereit, die typbeschränkt sind. Queries sind ebenfalls typsicher: `where`/`orderBy` akzeptieren verschachtelte Punktnotation (`"customer.address.city"`) und führen bei falschen Feldnamen oder Wertetypen zu Kompilierungsfehlern. Transaktionen und Batches sind integriert, wobei Batches ausschließlich beschreibend sind und erst mit `.commit()` atomar angewendet werden. Kilncast verpackt Firestore-, Netzwerk- oder Berechtigungsfehler nie; der Fehlertyp `KilncastError` deckt nur eigene Fehler ab. Alles, was kilncast nicht abdeckt, ist über das `.ref`-Escape-Hatch erreichbar.

Funktioniert mit~Claude Code~Codex CLI✓Cursor
npx skills add mwpryer/kilncast

Installed? Explore more Schreiben & Editieren skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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()) über firebase-admin, plus typisierte Ref-Helfer. Exportiert den gesamten neutralen Kern.
  • kilncast/web: dasselbe über das modulare firebase-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

  1. IDs sind pfadbasiert. Deklarieren Sie niemals ein id-Feld in einem Schema (Kompilierungsfehler). Lesevorgänge nehmen id flach auf; Schreibvorgänge schließen es aus. add(data) gibt die generierte ID zurück.
  2. Fehlende Lesevorgänge sind null. get() gibt Doc<S> | null zurück; es gibt keinen .exists-Snapshot (verwenden Sie .doc(id).exists() für einen Boolean).
  3. Werte werden an der Grenze konvertiert. Schreiben Sie ein Date, lesen Sie ein Date (gespeichert als Timestamp); schreiben Sie ein Uint8Array, lesen Sie ein Uint8Array (gespeichert als SDK-Bytes). Tief durch Maps und Arrays.
  4. Sentinels sind kilncast-eigene. Importieren Sie serverTimestamp, increment, arrayUnion, arrayRemove, deleteField aus kilncast, niemals FieldValue aus einem SDK. Jeder ist typbeschränkt auf die Felder, zu denen er passt (increment auf Zahlen, deleteField nur auf optionale Felder).
  5. Queries sind auf das Schema typisiert. where / orderBy akzeptieren typisierte Punktnotation in verschachtelte Maps ("customer.address.city"); ein falsch geschriebenes Feld oder falscher Wertetyp führt zu einem Kompilierungsfehler. Adressieren Sie die ID mit documentId() aus kilncast.
  6. Punktierte Pfade funktionieren nur in update. update("o1", { "totals.items": increment(1) }) berührt ein verschachteltes Feld. In einem set mit Merge ist ein Punkt-Pfad ein literalischer Feldname, also verschachteln Sie stattdessen ein Objekt.
  7. Transaktions- und Batch-Schreibvorgänge benötigen kein await. Lesevorgänge in einer Transaktion sind asynchron; Schreibvorgänge geben void zurück und puffern bis zum Commit. Batches sind schreibgeschützt (kein get, kein add) und werden atomar mit .commit() angewendet.
  8. 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.
  9. SDK-Semantik gewinnt. kilncast umschließt niemals Firestore-, Netzwerk- oder Berechtigungsfehler; KilncastError deckt nur kilncast-eigene Fehler ab. Alles, was kilncast nicht umschließt, ist über .ref erreichbar.

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.

Verwandte Skills