CommunityEscrita e Ediçãogithub.com

mwpryer/kilncast

🔥 Um wrapper fino e tipado sobre os SDKs do Firestore

O que é kilncast?

Kilncast é uma biblioteca TypeScript que fornece uma camada fina e tipada sobre os SDKs do Firestore (firebase-admin e firebase modular), focando em inferência de tipos e coerção em vez de validação em tempo de execução. Ideal para desenvolvedores que querem segurança de tipos ao interagir com o Firestore sem o overhead de validações extras, ela suporta esquemas definidos com validadores compatíveis com Standard Schema (Zod, Valibot, ArkType). O kilncast oferece três entrypoints: um core neutro sem Firebase, e adaptadores específicos para admin e web. Ele inclui operações completas de leitura, escrita, consultas, transações e batches, além de enviar sentinels próprios (como `increment`, `serverTimestamp`) e gerenciar IDs como caminhos, nunca como campos. O projeto mantém a semântica do SDK subjacente, expondo `.ref` para acesso direto quando necessário, e é útil para projetos que exigem tipagem forte para Firestore com mínimo de abstração.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add mwpryer/kilncast

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que kilncast faz?

Wrapper fino e tipado sobre o Firestore. Tipa e coage, não valida: o esquema é usado apenas para inferência de tipos e nunca é executado, portanto não há validação em tempo de execução. Por baixo, é Firestore puro; cada handle expõe .ref para acesso direto ao SDK bruto.

Configuração

# servidor
npm install kilncast firebase-admin
# web
npm install kilncast firebase

Três pontos de entrada:

  • kilncast: neutro. Definição de esquemas, sentinelas, tipos, KilncastError. Não importa Firebase, seguro em módulos compartilhados e bundles frontend.
  • kilncast/admin: createDatabase(getFirestore()) sobre firebase-admin, mais helpers de ref tipados. Re-exporta todo o core neutro.
  • kilncast/web: o mesmo sobre o SDK modular firebase.

Início rápido

import { collection, increment } from "kilncast";
// ou "kilncast/web"
import { createDatabase } from "kilncast/admin";
import { getFirestore } from "firebase-admin/firestore";
import { z } from "zod";

// Definição simples e desacoplada, defina uma vez em um módulo compartilhado importando apenas "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();

O esquema é qualquer validador Standard Schema (Zod, Valibot, ArkType). Ele descreve os campos de um documento, excluindo o id.

Regras principais

  1. IDs são apenas caminhos. Nunca declare um campo id em um esquema (erro de compilação). Leitura mescla id de forma plana; escrita o exclui. add(data) retorna o id gerado.
  2. Leituras ausentes retornam null. get() retorna Doc<S> | null; não há snapshot .exists para verificar (use .doc(id).exists() para um booleano).
  3. Valores coagidos na fronteira. Escreva um Date, leia um Date (armazenado como Timestamp); escreva um Uint8Array, leia um Uint8Array (armazenado como bytes do SDK). Profundo através de mapas e arrays.
  4. Sentinelas são próprias do kilncast. Importe serverTimestamp, increment, arrayUnion, arrayRemove, deleteField do kilncast, nunca FieldValue de um SDK. Cada um é restrito por tipo aos campos que se encaixa (increment em números, deleteField apenas em campos opcionais).
  5. Consultas são tipadas com o esquema. where / orderBy aceitam caminhos pontilhados tipados em mapas aninhados ("customer.address.city"); um campo com erro de digitação ou tipo de valor errado é um erro de compilação. Aponte para o id com documentId() do kilncast.
  6. Chaves com caminho pontilhado funcionam apenas em update. update("o1", { "totals.items": increment(1) }) altera um campo aninhado. Em um set com merge, uma chave pontilhada é um nome de campo literal, então aninhe um objeto.
  7. Escritas em transações e batches não usam await. Leituras em uma transação são assíncronas; escritas retornam void e são armazenadas em buffer até o commit. Batches são apenas para escrita (não há get, nem add) e são aplicados atomicamente em .commit().
  8. Sem validação em tempo de execução. Um documento que se desvia do esquema retorna tipado como válido. Onde o desvio importa, execute o esquema no resultado manualmente.
  9. A semântica do SDK prevalece. O kilncast nunca envolve erros de Firestore, rede ou permissão; KilncastError cobre apenas falhas do próprio kilncast. Qualquer coisa que o kilncast não envolve é acessível via .ref.

Operações comuns

const col = db.collection(posts);

// Leituras
// Doc | null
await col.get("hello");
// boolean
await col.doc("hello").exists();

// Escritas, também em 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) });
// retorna o novo id
const id = await col.add({ title: "New", likes: 0, createdAt: new Date() });
await col.delete(id);

// Consultas, builder imutável, .get() alias .list()
await col.where("likes", ">=", 10).orderBy("likes", "desc").limit(5).get();
await col.count();
// 0 sobre correspondência vazia
await col.sum("likes");
// null sobre correspondência vazia
await col.average("likes");
// retorna função para cancelar inscrição
const unsub = col.onSnapshot((docs) => {});

// Subcoleção, mesma definição reutilizável em qualquer profundidade
db.collection(posts).doc("hello").collection(comments);

// Grupo de coleções, toda coleção com esse nome
await db.collectionGroup(comments).orderBy("createdAt").get();

// Transação, leituras assíncronas, escritas síncronas
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, apenas escrita, atômico no commit
const batch = db.batch();
batch.collection(posts).update("hello", { likes: increment(1) });
await batch.commit();

Referência completa

Consulte REFERENCE.md para consultas e cursores, sentinelas e atualizações aninhadas, atualizações ao vivo, transações e batches em detalhes, campos brutos e timestamps de precisão total, bytes, tipos de valor neutros, a escotilha de escape .ref e pegadinhas.

Habilidades Relacionadas