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())sobrefirebase-admin, mais helpers de ref tipados. Re-exporta todo o core neutro.kilncast/web: o mesmo sobre o SDK modularfirebase.
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
- IDs são apenas caminhos. Nunca declare um campo
idem um esquema (erro de compilação). Leitura mesclaidde forma plana; escrita o exclui.add(data)retorna o id gerado. - Leituras ausentes retornam
null.get()retornaDoc<S> | null; não há snapshot.existspara verificar (use.doc(id).exists()para um booleano). - Valores coagidos na fronteira. Escreva um
Date, leia umDate(armazenado comoTimestamp); escreva umUint8Array, leia umUint8Array(armazenado como bytes do SDK). Profundo através de mapas e arrays. - Sentinelas são próprias do
kilncast. ImporteserverTimestamp,increment,arrayUnion,arrayRemove,deleteFielddokilncast, nuncaFieldValuede um SDK. Cada um é restrito por tipo aos campos que se encaixa (incrementem números,deleteFieldapenas em campos opcionais). - Consultas são tipadas com o esquema.
where/orderByaceitam 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 comdocumentId()dokilncast. - Chaves com caminho pontilhado funcionam apenas em
update.update("o1", { "totals.items": increment(1) })altera um campo aninhado. Em umsetcom merge, uma chave pontilhada é um nome de campo literal, então aninhe um objeto. - Escritas em transações e batches não usam
await. Leituras em uma transação são assíncronas; escritas retornamvoide são armazenadas em buffer até o commit. Batches são apenas para escrita (não háget, nemadd) e são aplicados atomicamente em.commit(). - 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.
- A semântica do SDK prevalece. O
kilncastnunca envolve erros de Firestore, rede ou permissão;KilncastErrorcobre apenas falhas do própriokilncast. Qualquer coisa que okilncastnã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.