Vegas

JavaScript API ​

@vegasjs/vegas は、設定・browser code・サーバー側data helper・test adapter向けに、少数のpackage entrypointを公開しています。

src や dist 内の実装ファイルを直接importするのではなく、ここに記載するpackage entrypointを使用してください。

Entrypoint公開surface
@vegasjs/vegasdefineConfig() と公開config typeによるプロジェクト設定
@vegasjs/vegas/client型付き google.script.run client
@vegasjs/vegas/server型付き Spreadsheet data API
@vegasjs/vegas/vitestLocal Runtime Vitest adapterとテスト向けRuntime type
@vegasjs/vegas/playwrightBrowser test adapterと Playwright expect

@vegasjs/vegas ​

defineConfig() ​

Vegas の設定ファイルを作成するときは defineConfig() を使用できます。

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

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

helperは指定された設定値を維持し、直接の UserConfig、Promise<UserConfig>、UserConfigFactory に対するoverloadを提供します。

root entrypointからは次のconfig typeも公開されています。

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

設定modelについては Vegas の設定 を、個々のoptionについては 共有オプション を参照してください。

@vegasjs/vegas/client ​

server が export する rpc レジストリと createRpcClient<T>() を使用してください。

createRpcClient<T>() ​

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

RpcClient<T> は createRpcClient<T>() の公開戻り値型です。createServerFunctionClient() 関数と ServerFunctionClient<T> 型エイリアスは v0.3.0 で削除されました。

移行するには、server から rpc という名前でハンドラレジストリを export し、client の createServerFunctionClient<T>() を createRpcClient<T>() に置き換えてください。

登録型 RPC は各メソッドを名前付き export する代わりに、GAS の単一エントリポイント vegasRpcCall を利用します。公開契約は server 実装から独立させます。

typescript
// src/contracts/rpc.ts
export interface ServerRpc {
  greet(name: string): string;
}
typescript
// 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}`;
  },
});
typescript
// 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 の両方で、そのメソッドを単一ディスパッチャー経由で実行します。トップレベルの名前付き export は Apps Script 自体から引き続き利用できますが、Vegas のクライアントは登録型の rpc ディスパッチャーを使用します。この方式では rpc がハンドラ名、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 entrypointには Vegas の型付き Spreadsheet data layerが含まれています。使い方、storage semantics、query、repositoryの挙動については Spreadsheet Data を参照してください。

Row / Schema / Table API ​

Runtime export:

text
createSpreadsheetRowCodec
createSpreadsheetColumn
createSpreadsheetSchema
createSpreadsheetTable

Type:

text
SpreadsheetRowCodec
SpreadsheetColumn
SpreadsheetSchema
SpreadsheetSchemaColumnSource
SpreadsheetTable
SpreadsheetTableEntry
SpreadsheetTableOptions

Query API ​

Runtime export:

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

Type:

text
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:

text
createSpreadsheetStorageLayout
createSpreadsheetStorageCodec

Type:

text
SpreadsheetStorageLayout
SpreadsheetStorageLayoutOptions
SpreadsheetStorageLocation
SpreadsheetStorageMode
SpreadsheetStorageCodec

Repository API ​

Runtime export:

text
createSpreadsheetRepository
createSpreadsheetRepositoryLockGuard
createSpreadsheetRepositoryScriptLockGuard
SpreadsheetRepositoryKeyConflictError

Type:

text
SpreadsheetRepository
SpreadsheetRepositoryMutationGuard
SpreadsheetRepositoryOptions
SpreadsheetRepositoryLock
SpreadsheetRepositoryLockGuardOptions
SpreadsheetRepositoryScriptLockGuardOptions

@vegasjs/vegas/vitest ​

Vitest entrypointは createLocalRuntimeTest() と、fixtureやinline Runtime Dataを記述するために必要なtypeを公開します。

Runtime export:

text
createLocalRuntimeTest

Type:

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

ライフサイクル、Runtime Data、分離、使用例については Vitest を参照してください。

@vegasjs/vegas/playwright ​

Playwright entrypointはbrowser test adapterを公開し、Playwright の expect をre-exportします。

Runtime export:

text
createBrowserTest
expect

Type:

text
BrowserTestFixture
BrowserTestOptions
RuntimeDataFixture

browserのライフサイクル、vegas.app、Runtime Data、cross-originのローカル Web app modelについては Playwright を参照してください。

Public API の境界 ​

package export mapが、このページに記載する対応import boundaryを定義します。内部実装moduleは、source fileがrepository内に存在するだけでpackage levelのAPIになるわけではなく、自由に変更される可能性があります。

専用guideを持つAPIについては、このreferenceでは公開symbolを一覧化し、ライフサイクルや挙動についてはguideをsource of truthとします。

MIT License で公開されています。

© Yasushi 2026