Community라이팅 & 에디팅github.com

mwpryer/kilncast

🔥 Firestore SDK 위에 얇은 스키마 타입 래퍼

kilncast란 무엇인가요?

kilncast는 Firestore SDK 위에 얇은 타입 래퍼를 제공합니다. 스키마는 타입 추론에만 사용되며 런타임 검증을 수행하지 않습니다. 서버(firebase-admin)와 웹(firebase) 환경을 모두 지원하며, Zod, Valibot, ArkType 등 Standard Schema 호환 라이브러리를 사용해 문서 스키마를 정의할 수 있습니다. 내부적으로는 순수 Firestore이므로 모든 핸들에서 `.ref`를 통해 원시 SDK에 접근할 수 있습니다. 문서 읽기 시 `null`을 반환하고, 경계에서 Date와 Timestamp, Uint8Array와 bytes 간 자동 변환을 수행합니다. 트랜잭션과 배치 쓰기, 실시간 스냅샷, 컬렉션 그룹 쿼리 등 Firestore의 핵심 기능을 타입 안전하게 활용할 수 있습니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add mwpryer/kilncast

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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: 모듈식 firebase SDK 위에 동일한 기능을 제공합니다.

빠른 시작

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를 제외한 한 문서의 필드를 설명합니다.

핵심 규칙

  1. Id는 경로 전용입니다. 스키마에 id 필드를 선언하지 마십시오(컴파일 오류). 읽기는 id를 평면적으로 병합하고, 쓰기는 이를 제외합니다. add(data)는 생성된 id를 반환합니다.
  2. 존재하지 않는 읽기는 null입니다. get()은 Doc<S> | null을 반환합니다. 확인할 .exists 스냅샷이 없습니다(부울 값에는 .doc(id).exists()를 사용하십시오).
  3. 값은 경계에서 강제 변환됩니다. Date를 쓰고 Date를 읽습니다(Timestamp로 저장됨). Uint8Array를 쓰고 Uint8Array를 읽습니다(SDK bytes로 저장됨). 맵과 배열 깊숙이 적용됩니다.
  4. 센티널은 kilncast 자체의 것입니다. serverTimestamp, increment, arrayUnion, arrayRemove, deleteField를 SDK의 FieldValue가 아닌 kilncast에서 임포트하십시오. 각각은 적합한 필드에 대해 타입이 제한됩니다(increment는 숫자에, deleteField는 선택적 필드에만).
  5. 쿼리는 스키마에 따라 타입이 지정됩니다. where / orderBy는 중첩 맵 안의 점으로 구분된 경로("customer.address.city")를 사용합니다. 잘못 입력된 필드나 잘못된 값 타입은 컴파일 오류입니다. kilncast의 documentId()로 id를 대상으로 지정하십시오.
  6. 점으로 구분된 키는 update에서만 작동합니다. update("o1", { "totals.items": increment(1) })는 하나의 중첩 필드에만 영향을 줍니다. 병합 set에서는 점으로 구분된 키가 리터럴 필드 이름이므로 대신 객체를 중첩하십시오.
  7. 트랜잭션 및 배치 쓰기는 await를 사용하지 않습니다. 트랜잭션 내 읽기는 비동기이지만 쓰기는 void를 반환하고 커밋될 때까지 버퍼링됩니다. 배치는 쓰기 전용이며(get, add 없음) .commit()에서 원자적으로 적용됩니다.
  8. 런타임 검증이 없습니다. 스키마에서 벗어난 문서는 유효한 것으로 타입이 지정되어 반환됩니다. 차이가 중요한 경우 결과에 직접 스키마를 실행하십시오.
  9. 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를 참조하십시오.

관련 스킬