kilncast은(는) 무엇을 하나요?
Firestore 위의 얇은 타입 래퍼입니다. 타입을 지정하고 강제 변환하며, 검증하지는 않습니다: 스키마는 타입 추론에만 사용되며 절대 실행되지 않으므로 런타임 검증이 없습니다. 내부적으로는 순수 Firestore이며, 모든 핸들은 .ref를 노출하여 원시 SDK에 접근할 수 있습니다.
설정
# 서버
npm install kilncast firebase-admin
# 웹
npm install kilncast firebase
세 가지 진입점:
kilncast: 중립. 스키마 정의, 센티널, 타입,KilncastError. Firebase를 임포트하지 않으며, 공유 모듈 및 프론트엔드 번들에서 안전합니다.kilncast/admin:firebase-admin위의createDatabase(getFirestore())와 타입화된 ref 헬퍼를 제공합니다. 중립 코어 전체를 다시 내보냅니다.kilncast/web: 모듈식firebaseSDK 위에 동일한 기능을 제공합니다.
빠른 시작
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();
스키마는 모든 Standard Schema 검증기(Zod, Valibot, ArkType)입니다. id를 제외한 한 문서의 필드를 설명합니다.
핵심 규칙
- Id는 경로 전용입니다. 스키마에
id필드를 선언하지 마십시오(컴파일 오류). 읽기는id를 평면적으로 병합하고, 쓰기는 이를 제외합니다.add(data)는 생성된 id를 반환합니다. - 존재하지 않는 읽기는
null입니다.get()은Doc<S> | null을 반환합니다. 확인할.exists스냅샷이 없습니다(부울 값에는.doc(id).exists()를 사용하십시오). - 값은 경계에서 강제 변환됩니다.
Date를 쓰고Date를 읽습니다(Timestamp로 저장됨).Uint8Array를 쓰고Uint8Array를 읽습니다(SDK bytes로 저장됨). 맵과 배열 깊숙이 적용됩니다. - 센티널은
kilncast자체의 것입니다.serverTimestamp,increment,arrayUnion,arrayRemove,deleteField를 SDK의FieldValue가 아닌kilncast에서 임포트하십시오. 각각은 적합한 필드에 대해 타입이 제한됩니다(increment는 숫자에,deleteField는 선택적 필드에만). - 쿼리는 스키마에 따라 타입이 지정됩니다.
where/orderBy는 중첩 맵 안의 점으로 구분된 경로("customer.address.city")를 사용합니다. 잘못 입력된 필드나 잘못된 값 타입은 컴파일 오류입니다.kilncast의documentId()로 id를 대상으로 지정하십시오. - 점으로 구분된 키는
update에서만 작동합니다.update("o1", { "totals.items": increment(1) })는 하나의 중첩 필드에만 영향을 줍니다. 병합set에서는 점으로 구분된 키가 리터럴 필드 이름이므로 대신 객체를 중첩하십시오. - 트랜잭션 및 배치 쓰기는
await를 사용하지 않습니다. 트랜잭션 내 읽기는 비동기이지만 쓰기는void를 반환하고 커밋될 때까지 버퍼링됩니다. 배치는 쓰기 전용이며(get,add없음).commit()에서 원자적으로 적용됩니다. - 런타임 검증이 없습니다. 스키마에서 벗어난 문서는 유효한 것으로 타입이 지정되어 반환됩니다. 차이가 중요한 경우 결과에 직접 스키마를 실행하십시오.
- 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();
전체 참조
쿼리 및 커서, 센티널 및 중첩 업데이트, 실시간 업데이트, 트랜잭션 및 배치 세부 정보, 원시 필드 및 전체 정밀도 타임스탬프, 바이트, 중립 값 형식, .ref 탈출구 및 주의 사항에 대해서는 REFERENCE.md를 참조하십시오.