papyrus-db

v1.0.4

Published

8 months ago

Google API services for Papyrus application

0High
0Medium
0Low

yongjisoon

google-api sheets papyrus

papyrus-services

Google API 서비스를 제공하는 npm 패키지입니다. 구글 시트와 드라이브 API를 쉽게 사용할 수 있도록 도와줍니다.

설치 📦

npm install papyrus-db

Google 클라이언트 ID 설정 🔑

이 패키지를 사용하기 위해서는 Google Cloud Platform에서 클라이언트 ID를 발급받아야 합니다.

Google Cloud Console에 접속합니다.
프로젝트를 선택하거나 새 프로젝트를 생성합니다.
"API 및 서비스" > "사용자 인증 정보" 메뉴로 이동합니다.
"사용자 인증 정보 만들기" > "OAuth 클라이언트 ID"를 선택합니다.
애플리케이션 유형을 "웹 애플리케이션"으로 선택합니다.
승인된 자바스크립트 원본에 http://localhost:5173을 추가합니다.
생성된 클라이언트 ID를 프로젝트 루트 디렉토리의 .env 파일에 다음과 같이 설정합니다:

VITE_CLIENT_ID=your_google_client_id

Google 인증 및 초기화 🚀

Google Sheets/Drive API를 사용하려면 사용자의 Google 계정 인증이 필요합니다. gapiInit 함수 또는 useAuth 훅을 통해 인증 및 초기화를 간편하게 처리할 수 있습니다.

1. gapiInit만 사용하는 기본 예시

import { gapiInit } from 'papyrus-db';

const clientId = import.meta.env.VITE_CLIENT_ID; // .env에서 불러오기

async function handleGoogleAuth() {
  try {
    await gapiInit(clientId);
    // 인증 성공 후, 구글 시트/드라이브 API 사용 가능
    alert('구글 인증 성공!');
  } catch (e) {
    alert('구글 인증 실패: ' + (e as Error).message);
  }
}

// 예: 버튼 클릭 시 실행
<button onClick={handleGoogleAuth}>Google 로그인</button>

clientId는 반드시 환경변수(.env)에서 불러와야 안전합니다.
인증이 완료되어야만 Sheets/Drive API를 사용할 수 있습니다.
인증 상태는 isAuthenticated로 실시간 확인 가능.
인증 함수는 authenticate()로 트리거.
인증 후 원하는 구글 API 함수 호출 가능.

주요 기능 ✨

스프레드시트/시트 목록 조회
시트 데이터 조회 및 필터링
타입 자동 감지 및 변환 (string, number, boolean, date, datetime, currency, percentage)
타입 안전한 데이터 추가/수정/삭제
고급 쿼리 (WHERE, ORDER BY, 정규식, IN, 집계함수)
배치 요청 큐 (Batch Request Queue)
성능 모니터링 및 통계

주요 파일 및 역할 🗂️

types.ts : 데이터 타입, 셀/컬럼/시트 구조 정의
typeUtils.ts : 타입 감지, 변환, 비교, 조건 매칭 유틸리티
query.ts : 데이터 조회, 고급 쿼리, 컬럼 정보 추출
insert.ts : 데이터 추가, 타입 검증
update.ts : 데이터 수정, 조건부 수정
delete.ts : 데이터 삭제, 범위/행/열 삭제
schema.ts : 스프레드시트/시트 생성, 헤더 추가

데이터 타입 및 구조 🧩

Spreadsheet: 구글 스프레드시트(데이터베이스)
Sheet: 시트(테이블)
CellData: 셀 데이터(2차원 배열)
ColumnInfo: 컬럼명, 타입, 인덱스 등 정보
TypedCellData: 타입이 지정된 셀 데이터
TypedCellValue: 실제 타입별 값 (string, number, boolean, Date 등)
WhereCondition: 쿼리 조건 (column, op, value)

주요 함수/메서드 및 사용 예시 🔧

📄 조회(SELECT, LIST 등)

listSpreadsheets

기능: 구글 드라이브 내 모든 스프레드시트 목록을 조회합니다. 사용 예시

import { listSpreadsheets } from 'papyrus-db';
const spreadsheets = await listSpreadsheets();

getSheets

기능: 특정 스프레드시트의 시트(테이블) 목록을 조회합니다. 사용 예시

import { getSheets } from 'papyrus-db';
const sheets = await getSheets('spreadsheetId');

getSheetColumns

기능: 시트의 컬럼명(헤더) 목록을 조회합니다. 사용 예시

import { getSheetColumns } from 'papyrus-db';
const columns = await getSheetColumns('spreadsheetId', 'Sheet1');

getSheetFormats

기능: 시트의 포맷(서식) 정보를 조회합니다. 사용 예시

import { getSheetFormats } from 'papyrus-db';
const formats = await getSheetFormats('spreadsheetId', 'Sheet1!A1:Z100');

getSheetData

기능: 시트의 원본 데이터를 2차원 배열로 조회합니다. 사용 예시

import { getSheetData } from 'papyrus-db';
const data = await getSheetData('spreadsheetId', 'Sheet1!A1:Z100');

getTypedSheetData

기능: 시트 데이터를 자동 타입 감지하여 반환합니다. 사용 예시

import { getTypedSheetData } from 'papyrus-db';
const typed = await getTypedSheetData('spreadsheetId', 'Sheet1');

getSheetColumnsWithInfo

기능: 컬럼명, 타입, 그리고 기본키/외래키 여부를 포함한 컬럼 정보를 배열로 반환합니다. 사용 예시

import { getSheetColumnsWithInfo } from 'papyrus-db';
const columns = await getSheetColumnsWithInfo('spreadsheetId', 'Sheet1');
// 기본키 컬럼 찾기
const pkCol = columns.find(col => col.isPrimaryKey);
// 외래키 컬럼 찾기
const fkCols = columns.filter(col => col.isForeignKey);
// 컬럼명 + 역할 출력
columns.forEach(col => {
  if (col.isPrimaryKey) console.log(col.name, '[PK]');
  else if (col.isForeignKey) console.log(col.name, '[FK]');
  else console.log(col.name);
});

findRowsByColumnValue

기능: 특정 컬럼의 값이 일치하는 행만 조회합니다. 사용 예시

import { findRowsByColumnValue } from 'papyrus-db';
const rows = await findRowsByColumnValue('spreadsheetId', 'Sheet1', '이름', '홍길동');

findRowsByWhere

기능: WHERE 조건, 정렬, 논리연산을 적용해 행을 조회합니다.
컬럼명이 기본키/외래키 컬럼일 경우, 컬럼 정보에서 isPrimaryKey/isForeignKey로 판별하여 조건을 구성할 수 있습니다. 사용 예시

import { getSheetColumnsWithInfo, findRowsByWhere } from 'papyrus-db';
const columns = await getSheetColumnsWithInfo('spreadsheetId', 'Sheet1');
const pkCol = columns.find(col => col.isPrimaryKey);
if (pkCol) {
  // 기본키로 특정 행 조회
  const rows = await findRowsByWhere('spreadsheetId', 'Sheet1', [
    { column: pkCol.name, op: '=', value: '123' }
  ]);
}

aggregateData

기능: SUM, AVG, COUNT 등 집계 함수를 실행합니다. 사용 예시

import { aggregateData } from 'papyrus-db';
const total = await aggregateData('spreadsheetId', 'Sheet1', '매출', 'sum');

➕ 추가(INSERT)

append

기능: 시트에 행(들)을 추가합니다. 사용 예시

import { append } from 'papyrus-db';
await append('spreadsheetId', 'Sheet1', [['홍길동', '30', '서울']]);

appendTyped

기능: 타입 검증 및 변환 후 행 추가(타입 안전). 사용 예시

import { appendTyped } from 'papyrus-db';
await appendTyped('spreadsheetId', 'Sheet1', [['홍길동', '30', '서울']], ['string', 'number', 'string']);

appendRow

기능: 객체 형태로 행 추가(컬럼명-값 매핑). 사용 예시

import { appendRow } from 'papyrus-db';
await appendRow('spreadsheetId', 'Sheet1', { 이름: '홍길동', 나이: 30, 도시: '서울' });

appendRows

기능: 여러 객체(행)를 한 번에 추가합니다. 사용 예시

import { appendRows } from 'papyrus-db';
await appendRows('spreadsheetId', 'Sheet1', [
  { 이름: '홍길동', 나이: 30 },
  { 이름: '김철수', 나이: 25 }
]);

appendBatch

기능: 대용량 데이터를 배치로 추가합니다. 사용 예시

import { appendBatch } from 'papyrus-db';
await appendBatch('spreadsheetId', 'Sheet1', [
  ['홍길동', '30'],
  ['김철수', '25'],
  // ...
], 100); // 100개씩 배치

✏️ 수정(UPDATE)

update

기능: 특정 범위의 데이터를 수정합니다. 사용 예시

import { update } from 'papyrus-db';
await update('spreadsheetId', 'Sheet1', 'A2:C2', [['홍길동', '31', '서울']]);

updateTyped

기능: 타입 검증 후 범위 데이터 수정. 사용 예시

import { updateTyped } from 'papyrus-db';
await updateTyped('spreadsheetId', 'Sheet1', 'A2:C2', [['홍길동', '31', '서울']], ['string', 'number', 'string']);

updateRowsByCondition

기능: WHERE 조건에 맞는 행만 일괄 수정. 사용 예시

import { updateRowsByCondition } from 'papyrus-db';
await updateRowsByCondition('spreadsheetId', 'Sheet1', [{ column: '이름', op: '=', value: '홍길동' }], { 나이: 32 });

updateCell

기능: 특정 셀만 수정. 사용 예시

import { updateCell } from 'papyrus-db';
await updateCell('spreadsheetId', 'Sheet1', 2, '나이', 33, 'number');

updateCells

기능: 여러 셀을 한 번에 수정. 사용 예시

import { updateCells } from 'papyrus-db';
await updateCells('spreadsheetId', 'Sheet1', [
  { rowIndex: 2, columnName: '나이', value: 34 }
]);

🗑️ 삭제(DELETE)

clear

기능: 특정 범위의 데이터를 삭제(비움). 사용 예시

import { clear } from 'papyrus-db';
await clear('spreadsheetId', 'Sheet1', 'A2:C2');

deleteRow

기능: 특정 행을 삭제. 사용 예시

import { deleteRow } from 'papyrus-db';
await deleteRow('spreadsheetId', 0, 2); // sheetId는 시트의 ID

deleteColumn

기능: 특정 열을 삭제. 사용 예시

import { deleteColumn } from 'papyrus-db';
await deleteColumn('spreadsheetId', 0, 1); // colIndex는 0부터 시작

🏗️ 구조/스키마(SCHEMA)

createSpreadsheet

기능: 새 스프레드시트(데이터베이스) 생성. 사용 예시

import { createSpreadsheet } from 'papyrus-db';
const { spreadsheetId } = await createSpreadsheet('새 DB');

createSheet

기능: 기존 스프레드시트에 새 시트(테이블) 생성. 사용 예시

import { createSheet } from 'papyrus-db';
const { sheetId } = await createSheet('spreadsheetId', '새 시트');

addHeaderRow

기능: 시트의 1행에 컬럼명(헤더) 추가. 사용 예시

import { addHeaderRow } from 'papyrus-db';
await addHeaderRow('spreadsheetId', 'Sheet1', ['이름', '나이', '도시']);

참고 ℹ️

모든 함수는 TypeScript 기반, async/await 지원
Google Sheets API(gapi) 기반
CLI/웹 양쪽에서 동일한 서비스 레이어 사용
README.md 및 각 서비스 파일 참고