JavaScript API

@vegasjs/vegas는 설정, browser code, 서버 측 data helper, test adapter를 위해 소수의 package entry point를 공개합니다.

src 또는 dist 내부의 구현 파일을 직접 import하지 말고 이 페이지에 설명된 package entry point를 사용하세요.

Entry point	Public surface
@vegasjs/vegas	defineConfig()와 공개 config type을 통한 프로젝트 설정
@vegasjs/vegas/client	typed google.script.run client
@vegasjs/vegas/server	typed Spreadsheet data API
@vegasjs/vegas/vitest	Local Runtime Vitest adapter와 테스트용 Runtime type
@vegasjs/vegas/playwright	Browser test adapter와 Playwright expect

@vegasjs/vegas

defineConfig()

Vegas 설정 파일을 작성할 때 defineConfig()를 사용할 수 있습니다.

import { defineConfig } from "@vegasjs/vegas";

export default defineConfig({
  appType: "spa",
  appsScript: {
    manifest: {},
  },
});

helper는 전달된 설정 값을 유지하고 직접 UserConfig, Promise<UserConfig>, UserConfigFactory에 대한 overload를 제공합니다.

root entry point는 다음 config type도 export합니다.

import type {
  AppsScriptConfig,
  AppsScriptManifest,
  DevServerConfig,
  UserConfig,
  UserConfigExport,
  UserConfigFactory,
} from "@vegasjs/vegas";

설정 model은 Vegas 설정을, 개별 option은 공통 옵션을 참고하세요.

@vegasjs/vegas/client

서버에서 export하는 rpc 레지스트리와 createRpcClient<T>()를 사용하세요.

createRpcClient<T>()

function createRpcClient<T extends object>(): RpcClient<T>;

RpcClient<T>는 createRpcClient<T>()의 공개 반환 타입입니다. 기존 createServerFunctionClient() 함수와 ServerFunctionClient<T> 타입 별칭은 v0.3.0에서 제거되었습니다.

마이그레이션하려면 서버에서 rpc라는 이름으로 핸들러 레지스트리를 export하고 클라이언트의 createServerFunctionClient<T>()를 createRpcClient<T>()로 바꾸세요.

등록형 RPC는 각 메서드를 개별 이름으로 export하는 대신 하나의 GAS 진입점인 vegasRpcCall을 사용합니다. 공개 계약은 server 구현과 분리합니다.

// src/contracts/rpc.ts
export interface ServerRpc {
  greet(name: string): string;
}

// src/server/Code.ts
import { defineServerFunctions } from "@vegasjs/vegas/server";

import type { ServerRpc } from "../contracts/rpc";

export const rpc = defineServerFunctions<ServerRpc>({
  greet(name) {
    Logger.log(name);
    return `Hello, ${name}`;
  },
});

// src/client/main.ts
import { createRpcClient, type RpcClient } from "@vegasjs/vegas/client";

import type { ServerRpc } from "../contracts/rpc";

const server: RpcClient<ServerRpc> = createRpcClient<ServerRpc>();
const result = await server.greet("Vegas");

server 엔트리는 rpc라는 이름으로 객체를 export해야 합니다. Vegas는 Local Runtime과 Google Apps Script 양쪽에서 디스패처를 통해 해당 메서드를 실행합니다. 최상위 named export는 Apps Script 자체에서 계속 사용할 수 있지만 Vegas 클라이언트는 등록형 rpc 디스패처를 사용합니다. 이 방식에서는 rpc가 핸들러 export 이름이며 vegasRpcCall이 GAS 디스패처 이름이므로, rpc와 함께 vegasRpcCall 함수를 export하지 마세요.

RPC 레지스트리는 함수가 자체 프로퍼티로 존재하는 일반 객체 또는 null 프로토타입 객체여야 합니다. 클래스 인스턴스와 상속된 메서드는 지원하지 않습니다.

defineServerFunctions()는 등록 시점의 핸들러 이름과 함수 참조를 기록합니다. 원본 객체를 동결하지는 않지만 새 메서드를 추가하거나 교체해도 다시 등록하기 전에는 RPC를 통해 호출할 수 없습니다. 헬퍼 없이 rpc를 직접 export한 경우에는 호출 시점 검증만 적용됩니다.

defineServerFunctions()와 RpcClient<T>는 등록형 RPC 계약이 google.script.run으로 전달 가능한 값의 보수적인 부분집합(문자열, 숫자, 불리언, null, 배열, 일반 데이터 객체)에 부합하는지 정적으로 검사합니다. 지원되지 않는 시그니처를 가진 메서드는 RpcClient<T>에서 제외됩니다. TypeScript는 Date, 콜백, Promise 반환값, 선택적 undefined 프로퍼티, 지나치게 넓은 object / {} 타입, 재귀 객체 타입을 거부합니다. void 반환값은 허용됩니다. 정적 타입 검사만으로는 숫자가 유한한지 또는 객체에 순환 참조가 없는지 증명할 수 없습니다.

Vegas는 등록형 RPC 값도 런타임에 검증합니다. createRpcClient()는 google.script.run을 호출하기 전에 인수를 검증하고, 생성된 vegasRpcCall 디스패처는 전달받은 인수와 핸들러 반환값을 검증합니다. Date, 함수, 심벌, 접근자, 순환 참조, 유한하지 않은 숫자, 희소 배열, 열거 불가능한 데이터 프로퍼티, 사용자 정의 프로토타입을 가진 객체 등은 거부됩니다. void 형식의 핸들러에서는 최상위 undefined 반환값을 허용합니다. 이 검증은 값을 직렬화하지 않으며 Google이 허용된 모든 값을 받아들인다고 보장하지도 않습니다. 날짜는 문자열로 변환해 전달하세요.

이름이 _로 끝나는 핸들러와 then, constructor, prototype, __proto__는 예약되어 있습니다. 등록, 클라이언트 Proxy, GAS 디스패처에서 사용할 수 없습니다.

@vegasjs/vegas/server

server entry point에는 Vegas의 typed Spreadsheet data layer가 포함되어 있습니다. 사용법, storage semantics, query, repository 동작은 Spreadsheet Data를 참고하세요.

Row / Schema / Table API

Runtime export:

createSpreadsheetRowCodec
createSpreadsheetColumn
createSpreadsheetSchema
createSpreadsheetTable

Type:

SpreadsheetRowCodec
SpreadsheetColumn
SpreadsheetSchema
SpreadsheetSchemaColumnSource
SpreadsheetTable
SpreadsheetTableEntry
SpreadsheetTableOptions

Query API

Runtime export:

createSpreadsheetQuery
createSpreadsheetQueryFields
createSpreadsheetQueryPlan
spreadsheetOrderBy
spreadsheetAnd
spreadsheetOr
spreadsheetEq
spreadsheetNe
spreadsheetGt
spreadsheetGte
spreadsheetLt
spreadsheetLte

Type:

SpreadsheetQuery
SpreadsheetQueryField
SpreadsheetComparableQueryField
SpreadsheetQueryFields
SpreadsheetQueryExpression
SpreadsheetComparisonExpression
SpreadsheetComparisonKind
SpreadsheetComparableValue
SpreadsheetAndExpression
SpreadsheetOrExpression
SpreadsheetEqualExpression
SpreadsheetNotEqualExpression
SpreadsheetGreaterThanExpression
SpreadsheetGreaterThanOrEqualExpression
SpreadsheetLessThanExpression
SpreadsheetLessThanOrEqualExpression
SpreadsheetOrderBy
SpreadsheetQueryPlan
SpreadsheetQueryPlanOptions
SpreadsheetQueryPlanSource
SpreadsheetSortDirection

Storage API

Runtime export:

createSpreadsheetStorageLayout
createSpreadsheetStorageCodec

Type:

SpreadsheetStorageLayout
SpreadsheetStorageLayoutOptions
SpreadsheetStorageLocation
SpreadsheetStorageMode
SpreadsheetStorageCodec

Repository API

Runtime export:

createSpreadsheetRepository
createSpreadsheetRepositoryLockGuard
createSpreadsheetRepositoryScriptLockGuard
SpreadsheetRepositoryKeyConflictError

Type:

SpreadsheetRepository
SpreadsheetRepositoryMutationGuard
SpreadsheetRepositoryOptions
SpreadsheetRepositoryLock
SpreadsheetRepositoryLockGuardOptions
SpreadsheetRepositoryScriptLockGuardOptions

@vegasjs/vegas/vitest

Vitest entry point는 createLocalRuntimeTest()와 fixture 및 inline Runtime Data를 설명하는 데 필요한 type을 export합니다.

Runtime export:

createLocalRuntimeTest

Type:

LocalRuntimeTestOptions
LocalRuntimeHarness
LocalRuntimeProject
RuntimeDataFixture
LocalRuntime
Program
RuntimeExecutionRequest
RuntimeDataProperties
RuntimeDataSession
RuntimeDataSpreadsheet
RuntimeDataSpreadsheetCellValue
RuntimeDataSpreadsheetSheet

lifecycle, Runtime Data, 격리, 사용 예는 Vitest를 참고하세요.

@vegasjs/vegas/playwright

Playwright entry point는 browser test adapter를 export하고 Playwright의 expect를 re-export합니다.

Runtime export:

createBrowserTest
expect

Type:

BrowserTestFixture
BrowserTestOptions
RuntimeDataFixture

browser lifecycle, vegas.app, Runtime Data, cross-origin 로컬 Web app model은 Playwright를 참고하세요.

Public API 경계

package export map이 이 페이지에 나열된 지원 import boundary를 정의합니다. 내부 구현 module은 repository에 source file이 존재한다는 이유만으로 package-level API가 되는 것이 아니며 자유롭게 변경될 수 있습니다.

전용 guide가 있는 API는 이 reference에서 public symbol을 나열하고, lifecycle과 동작은 해당 guide를 source of truth로 합니다.