기본 제공 함수

웹사이트 서버 코드에서 import 없이 사용하는 Cake20 Runtime 기능입니다.

Runtime 전역 기능

app: 현재 웹사이트 ID, 이름, 도메인, 전체 URL, Runtime, timezone과 DB 정보를 제공합니다.
db: 웹사이트별 모델 타입이 자동 반영되는 전용 Prisma Client입니다.
fetchGet과 fetchPost: UI·서버·테스트에서 같은 방식으로 HTTP를 요청합니다.
now, toDate, textDate와 startOfToday: 공통 날짜 생성·변환·표시를 제공합니다.
auth: 로그인, 로그아웃, 현재 사용자와 권한 검사를 제공합니다.
mail: 웹사이트 SMTP 설정으로 이메일을 보냅니다.
payment: Toss, Stripe와 PayPal 결제·환불·웹훅 검증을 제공합니다.
storage: files 또는 Object Storage의 파일을 읽고 저장하고 삭제합니다.
excel.open, excel.download와 excel.save: 단일 시트의 행 데이터를 XLSX로 읽고 내려받거나 저장합니다.
job.<파일>과 job.$get: 비동기 작업을 등록하고 상태를 조회합니다.
z: API 입력 검증과 *.db.ts 모델 선언에 사용하는 Zod 기반 schema builder입니다.
defineApi, defineHook과 defineTask: handler의 타입을 명확하게 선언합니다.

서버 전용 기능은 server/api, server/routes, server/hooks, server/tasks와 서버에서 호출되는 shared 함수에서 사용합니다.

XLSX 바로 다운로드하기

excel.download(name, rows)는 XLSX 다운로드 Response를 바로 반환합니다.
파일을 storage에 저장하지 않으므로 다운로드 파일이 누적되지 않습니다.
즉시 처리하는 API와 route의 다운로드는 excel.download를 우선 사용합니다.
name은 경로가 아닌 .xlsx 파일명이어야 합니다.
비동기 job처럼 요청이 이미 끝난 작업은 excel.save로 결과를 보관하고 정리 정책을 둡니다.

export default async () => {
  const rows = [
    ["ID", "이름", "가입일"],
    [1, "카페", new Date()],
    [2, "사용자", new Date()]
  ];
  return excel.download("users.xlsx", rows);
};

XLSX 영구 저장하기

행은 문자열, 숫자, boolean, Date와 빈 셀만 지원합니다.
Workbook, 스타일, 수식과 다중 시트 편집은 지원하지 않습니다.
excel.save(path, rows)는 storage에 저장하고 path, byte size와 가능한 경우 공개 URL을 반환합니다.
나중에 다시 열거나 공유해야 하는 파일에만 excel.save를 사용합니다.
저장 경로는 반드시 .xlsx로 끝나야 하며 웹사이트 파일 용량 제한을 적용합니다.
files에 저장한 XLSX는 공개될 수 있으므로 비밀번호나 비공개 자료를 넣지 않습니다.

export default async () => {
  const rows = [
    ["ID", "이름", "가입일"],
    [1, "카페", new Date()],
    [2, "사용자", new Date()]
  ];
  return excel.save("exports/users.xlsx", rows);
};

XLSX 읽기

excel.open(path)는 storage에서 파일을 읽어 첫 번째 시트의 행 배열을 반환합니다.
파일이 없거나 확장자가 .xlsx가 아니면 오류를 발생시킵니다.
업로드한 XLSX는 먼저 storage.put으로 files에 저장한 뒤 excel.open으로 읽습니다.
XLSX 변환은 Worker에서 실행되며 스타일과 수식 정보는 반환하지 않습니다.

export default async () => {
  return excel.open("imports/users.xlsx");
};

파일 함수

모든 영구 생성 파일은 storage로 관리합니다.
웹사이트 소스에서는 fs import·require, Bun.file과 Bun.write를 사용할 수 없습니다.
excel.open과 excel.save는 같은 storage와 용량 제한을 사용하지만 excel.download는 저장하지 않습니다.
files의 객체는 공개 URL로 제공될 수 있으므로 민감정보를 저장하지 않습니다.
Runtime 기본 기능은 웹사이트 package.json dependencies에 다시 추가하지 않습니다.

await storage.put("reports/data.json", JSON.stringify(data));
const content = await storage.get("reports/data.json");
const exists = await storage.has("reports/data.json");
const url = storage.url("reports/data.json");
await storage.remove("reports/data.json");