@gasboost/vite 1.0.1 → 1.2.0

package/README.md

@@ -603,6 +603,152 @@ URL encoded な RPC 名も decode されます。
 
 ---
 
+## Client Transport
+
+`@gasboost/client` を利用している場合、dev plugin はローカル開発時の transport を自動で Local RPC に切り替えます。
+
+アプリケーション側では development / production を判定する必要はありません。
+
+```ts
+import { appsScriptClient } from "@gasboost/client";
+import type { App } from "./server";
+
+const { client } = appsScriptClient<App>();
+
+const result = await client.sum(1, 2);
+```
+
+Vite Dev Server 上では、`appsScriptClient()` に transport が指定されていない場合、dev plugin が自動的に `FetchTransport` を適用します。
+
+```text
+appsScriptClient()
+        ↓
+FetchTransport
+        ↓
+POST /__gasboost/{rpcName}
+        ↓
+AppsScript.dispatch()
+```
+
+そのため、ローカル開発用に transport を切り替えるコードを書く必要はありません。
+
+```ts
+// 不要
+appsScriptClient({
+  transport: import.meta.env.DEV
+    ? new FetchTransport({
+        endpoint: "/__gasboost",
+      })
+    : new AppsScriptTransport(),
+});
+```
+
+production build では dev plugin による差し替えは行われません。
+
+GAS 上では `appsScriptClient()` のデフォルトである `AppsScriptTransport` がそのまま利用されます。
+
+```text
+appsScriptClient()
+        ↓
+AppsScriptTransport
+        ↓
+google.script.run
+```
+
+つまり、同じ application code のまま local development と GAS production の両方で利用できます。
+
+```ts
+const { client } = appsScriptClient<App>();
+```
+
+また、明示的に `transport` を指定した場合はその transport が優先されます。
+
+```ts
+const { client } = appsScriptClient<App>({
+  transport: customTransport,
+});
+```
+
+dev plugin が明示指定された transport を上書きすることはありません。
+
+---
+
+## HtmlTemplate variables
+
+GAS の `HtmlTemplate` では、`<?= variable ?>` を使用してサーバー側の値を HTML に埋め込めます。
+
+```html
+<script>
+  const variables = "<?= variables ?>";
+</script>
+```
+
+GAS 上では `HtmlTemplate` によって評価されますが、Vite Dev Server では GAS のテンプレート処理が実行されません。
+
+`@gasboost/vite` では、`template` オプションを指定することで、開発時にこれらの template variables を置換できます。
+
+```ts
+import { gasboost } from "@gasboost/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    gasboost({
+      entry: "./src/backend/main.ts",
+      template: {
+        variables: JSON.stringify({
+          scriptId: "local-script-id",
+          isSetupCompleted: true,
+          isTermsAccepted: true,
+        }),
+      },
+    }).dev,
+  ],
+});
+```
+
+例えば、次の HTML は、
+
+```html
+<script>
+  const variables = "<?= variables ?>";
+</script>
+```
+
+Vite の開発環境では次のように変換されます。
+
+```html
+<script>
+  const variables =
+    '{"scriptId":"local-script-id","isSetupCompleted":true,"isTermsAccepted":true}';
+</script>
+```
+
+複数の template variable も指定できます。
+
+```ts
+gasboost({
+  entry: "./src/backend/main.ts",
+  template: {
+    environment: "development",
+    userName: "Tiger",
+  },
+});
+```
+
+```html
+<p>Environment: <?= environment ?></p>
+<p>User: <?= userName ?></p>
+```
+
+`template` の型は `Record<string, string>` です。
+
+値の serialize は `@gasboost/vite` では行いません。オブジェクトなどを埋め込む場合は、利用側で `JSON.stringify()` などを使用して文字列へ変換してください。
+
+`template` による置換は Vite Dev Server でのみ行われます。production build では値を埋め込まず、GAS 上で実際の `HtmlTemplate` が template expression を評価します。
+
+---
+
 # build と dev の責務
 
 ```text
@@ -643,6 +789,58 @@ export default defineConfig(({ mode }) => {
 
 `build` を通常の frontend build に含めると、server entry が Vite の build input になるため、frontend と backend の build は分離してください。
 
+---
+
+## GAS ランタイム
+
+`@gasboost/vite` は、build 時と local RPC 実行時に server entry を実際に評価します。
+
+一般的な GAS API は、デフォルトのローカルランタイムから提供されます。
+
+```ts
+import { gasboost } from "@gasboost/vite";
+
+export default gasboost({
+  entry: "./src/server.ts",
+});
+```
+
+entry の初期化時に追加の GAS API が必要な場合は、`runtime` から差し込めます。
+
+```ts
+import { SpreadsheetAppStub } from "@gasboost/sheetorm";
+import { gasboost } from "@gasboost/vite";
+
+export default gasboost({
+  entry: "./src/server.ts",
+  runtime: {
+    SpreadsheetApp: SpreadsheetAppStub,
+  },
+});
+```
+
+`runtime` に渡した値は、デフォルトのローカルランタイムを上書きします。
+
+このランタイムは build 時の entry 評価と、local RPC 実行時の両方で利用されます。
+
+基本的には、module 初期化時に必要な API だけを差し込み、実際の GAS API 呼び出しは handler 実行時まで遅延させることを推奨します。
+
+## ランタイム解析
+
+GET / POST / RPC の登録状態は、entry ファイルを静的解析するのではなく、実際に評価された `AppsScript` インスタンスから取得します。
+
+そのため、import 先、ヘルパー関数、loop、`AppsScript.calls()` 経由の登録にも対応できます。
+
+```ts
+const app = new AppsScript();
+
+for (const [name, handler] of Object.entries(handlers)) {
+  app.call(name, handler);
+}
+
+export default app;
+```
+
 ## 関連パッケージ
 
 - `@gasboost/app` — GAS バックエンドランタイムと RPC 定義

package/dist/dev.d.ts

@@ -1,2 +1,3 @@
-import type { Plugin } from "vite";
-export declare function createDevPlugin(entry: string): Plugin;
+import { type Plugin } from "vite";
+import type { GasboostOptions } from "./gasboost";
+export declare function createDevPlugin(options: GasboostOptions): Plugin;

package/dist/gasboost.d.ts

@@ -1,7 +1,10 @@
 import type { Plugin } from "vite";
+export type GasRuntime = Readonly<Record<string, unknown>>;
 export interface GasboostOptions {
     entry: string;
     envDir?: string;
+    runtime?: GasRuntime;
+    template?: Record<string, string>;
 }
 export declare function gasboost(options: GasboostOptions): {
     build: Plugin;

package/dist/globals.d.ts

@@ -1,2 +1,2 @@
-import type { AppsScriptAnalysis } from "./analyzer";
-export declare function createGlobalCode(analysis: AppsScriptAnalysis): string;
+import type { AppsScriptDescription } from "@gasboost/app";
+export declare function createGlobalCode(analysis: AppsScriptDescription): string;

package/dist/index.js

@@ -1,91 +1,12 @@
-import e from "node:fs";
-import t from "node:path";
-import { isCallExpression as n, isIdentifier as r, isNewExpression as i, isPropertyAccessExpression as a, isStringLiteral as o, isVariableDeclaration as s } from "typescript/unstable/ast/is";
-import { createVirtualFileSystem as c } from "typescript/unstable/fs";
-import { API as l } from "typescript/unstable/sync";
-//#region src/analyzer.ts
-function u(r) {
-	let i = t.resolve(r);
-	if (!e.existsSync(i)) throw Error(`Entry file not found: ${i}`);
-	let s = d(i, e.readFileSync(i, "utf8")), c = f(s);
-	if (c.length === 0) throw Error("AppsScript instance not found.");
-	if (c.length > 1) throw Error("Multiple AppsScript instances found in entry.");
-	let l = c[0];
-	g(s, l);
-	let u = {
-		hasGet: !1,
-		hasPost: !1,
-		calls: []
-	}, p = /* @__PURE__ */ new Set();
-	function m(e) {
-		if (!a(e.expression)) return;
-		let t = e.expression, n = t.name.text;
-		if (!h(t.expression, l)) return;
-		if (n === "get") {
-			if (u.hasGet) throw Error("Duplicate GET handler registration.");
-			u.hasGet = !0;
-			return;
-		}
-		if (n === "post") {
-			if (u.hasPost) throw Error("Duplicate POST handler registration.");
-			u.hasPost = !0;
-			return;
-		}
-		if (n !== "call") return;
-		let r = e.arguments[0];
-		if (!r) throw Error(".call() requires a function name.");
-		if (!o(r)) throw Error(".call() function name must be a string literal.");
-		if (p.has(r.text)) throw Error(`Duplicate RPC registration: "${r.text}".`);
-		p.add(r.text), u.calls.unshift(r.text);
-	}
-	function _(e) {
-		n(e) && m(e), e.forEachChild(_);
-	}
-	return _(s), u;
-}
-function d(e, t) {
-	let n = "/entry.ts", r = "/tsconfig.json", i = c({
-		[r]: JSON.stringify({ files: [n] }),
-		[n]: t
-	}), a = new l({
-		cwd: "/",
-		fs: i
-	}).updateSnapshot({ openProject: r }).getProject(r);
-	if (!a) throw Error("Failed to create TypeScript project.");
-	let o = a.program.getSourceFile(n);
-	if (!o) throw Error(`Failed to parse entry: ${e}`);
-	return o;
-}
-function f(e) {
-	let t = [];
-	function n(e) {
-		s(e) && p(e) && t.push(e.name.text), e.forEachChild(n);
-	}
-	return n(e), t;
-}
-function p(e) {
-	return !r(e.name) || !e.initializer ? !1 : m(e.initializer);
-}
-function m(e) {
-	return i(e) && r(e.expression) && e.expression.text === "AppsScript" ? !0 : n(e) && a(e.expression) ? m(e.expression.expression) : !1;
-}
-function h(e, t) {
-	return r(e) && e.text === t || i(e) && r(e.expression) && e.expression.text === "AppsScript" ? !0 : n(e) && a(e.expression) ? h(e.expression.expression, t) : !1;
-}
-function g(e, t) {
-	let n = !1;
-	for (let r of e.statements) if (r.getText() === `export default ${t};`) {
-		n = !0;
-		break;
-	}
-	if (!n) throw Error("AppsScript instance must be default exported.");
-}
-//#endregion
+import e from "node:path";
+import { createServer as t, isRunnableDevEnvironment as n } from "vite";
+import { InMemoryCacheService as r, InMemoryContext as i, InMemoryPropertiesService as a, InMemorySession as o, SecurityPolicy as s } from "@gasboost/fake-core";
+import { NodeUtilities as c } from "@gasboost/fake-node";
 //#region src/config.ts
-function _(e) {
-	let n = t.resolve(e.entry);
+function l(t) {
+	let n = e.resolve(t.entry);
 	return {
-		envDir: e.envDir,
+		envDir: t.envDir,
 		build: {
 			target: "es2019",
 			outDir: "dist",
@@ -94,7 +15,7 @@ function _(e) {
 				input: n,
 				output: {
 					format: "cjs",
-					entryFileNames: t.basename(n, t.extname(n)) + ".js"
+					entryFileNames: e.basename(n, e.extname(n)) + ".js"
 				}
 			}
 		}
@@ -102,75 +23,157 @@ function _(e) {
 }
 //#endregion
 //#region src/globals.ts
-var v = /* @__PURE__ */ new Set(["doGet", "doPost"]);
-function y(e) {
-	if (v.has(e)) throw Error(`RPC name "${e}" is reserved by Google Apps Script.`);
+var u = /* @__PURE__ */ new Set(["doGet", "doPost"]);
+function d(e) {
+	if (u.has(e)) throw Error(`RPC name "${e}" is reserved by Google Apps Script.`);
 	if (!/^[$A-Z_a-z][$\w]*$/u.test(e)) throw Error(`RPC name "${e}" is not a valid JavaScript identifier.`);
 }
-function b(e) {
+function f(e) {
 	let t = [];
 	e.hasGet && t.push("function doGet() {}"), e.hasPost && t.push("function doPost() {}");
-	for (let n of e.calls) y(n), t.push(`function ${n}() {}`);
+	for (let n of e.calls) d(n), t.push(`function ${n}() {}`);
 	return t.join("\n");
 }
 //#endregion
+//#region src/runtime.ts
+var p = new i("", "", {
+	type: "WEB_APP",
+	executeAs: "USER"
+}, new s([]), "en", "UTC"), m = {
+	CacheService: new r(),
+	PropertiesService: new a(),
+	Session: new o(p),
+	Utilities: new c()
+};
+function h(e = {}) {
+	Object.assign(globalThis, {
+		...m,
+		...e
+	});
+}
+//#endregion
+//#region src/loadAppsScript.ts
+async function g(e, r) {
+	h(e.runtime);
+	let i = await t({
+		configFile: !1,
+		root: r.root,
+		mode: r.mode,
+		envDir: e.envDir,
+		appType: "custom",
+		ssr: { external: ["@gasboost/app"] },
+		server: {
+			middlewareMode: !0,
+			hmr: !1
+		}
+	});
+	try {
+		let t = i.environments.ssr;
+		if (!n(t)) throw Error("Vite SSR environment is not runnable.");
+		let r = await t.runner.import(e.entry);
+		if (!r.default) throw Error("AppsScript entry must have a default export.");
+		return r.default.describe();
+	} finally {
+		await i.close();
+	}
+}
+//#endregion
 //#region src/build.ts
-function x(e) {
-	let t;
+function _(e) {
+	let t, n;
 	return {
 		name: "gasboost:build",
 		apply: "build",
 		config() {
-			return _(e);
+			return l(e);
+		},
+		configResolved(e) {
+			t = e;
 		},
-		buildStart() {
-			t = u(e.entry);
+		async buildStart() {
+			n = await g(e, t);
 		},
-		generateBundle(e, n) {
-			let r = b(t);
-			for (let e of Object.values(n)) e.type === "chunk" && e.isEntry && (e.code = `${r}\n\n${e.code}`);
+		generateBundle(e, t) {
+			let r = f(n);
+			for (let e of Object.values(t)) e.type === "chunk" && e.isEntry && (e.code = `${r}\n\n${e.code}`);
 		}
 	};
 }
 //#endregion
 //#region src/dev.ts
-var S = class extends Error {
+var v = class extends Error {
 	constructor(e) {
 		super(e), this.name = "InvalidRpcRequestError";
 	}
-};
-function C(e) {
+}, y = "@gasboost/client", b = "\0gasboost:client", x = "/__gasboost";
+function S(e) {
+	let { runtime: t, template: r } = e, i;
 	return {
 		name: "gasboost:dev",
 		apply: "serve",
-		configureServer(t) {
-			t.middlewares.use(async (n, r, i) => {
-				if (!n.url) {
-					i();
+		enforce: "pre",
+		async resolveId(e, t, n) {
+			if (e !== y || this.environment.config.consumer !== "client") return null;
+			let r = await this.resolve(e, t, {
+				...n,
+				skipSelf: !0
+			});
+			return r ? (i = r.id, b) : null;
+		},
+		load(e) {
+			if (e !== b) return null;
+			if (!i) throw Error("@gasboost/client could not be resolved.");
+			let t = JSON.stringify(i);
+			return `
+import {
+  appsScriptClient as originalAppsScriptClient,
+  FetchTransport,
+} from ${t};
+
+export * from ${t};
+
+export function appsScriptClient(options = {}) {
+  return originalAppsScriptClient({
+    ...options,
+    transport:
+      options.transport ??
+      new FetchTransport({
+        endpoint: ${JSON.stringify(x)},
+      }),
+  });
+}
+`;
+		},
+		configureServer(r) {
+			h(t), r.middlewares.use(async (t, i, a) => {
+				if (!t.url) {
+					a();
 					return;
 				}
-				let a = n.url.split("?")[0];
-				if (!a.startsWith("/__gasboost/")) {
-					i();
+				let o = t.url.split("?")[0], s = `${x}/`;
+				if (!o.startsWith(s)) {
+					a();
 					return;
 				}
-				let o = a.slice(12);
-				if (!o || o.includes("/")) {
-					i();
+				let c = o.slice(s.length);
+				if (!c || c.includes("/")) {
+					a();
 					return;
 				}
-				if (n.method !== "POST") {
-					r.statusCode = 405, r.setHeader("Content-Type", "application/json; charset=utf-8"), r.end(JSON.stringify({ error: {
+				if (t.method !== "POST") {
+					i.statusCode = 405, i.setHeader("Content-Type", "application/json; charset=utf-8"), i.end(JSON.stringify({ error: {
 						name: "MethodNotAllowedError",
 						message: "Only POST is allowed."
 					} }));
 					return;
 				}
 				try {
-					let { args: i } = await w(n), a = await (await t.ssrLoadModule(e)).default.dispatch(decodeURIComponent(o), ...i);
-					r.statusCode = 200, r.setHeader("Content-Type", "application/json; charset=utf-8"), r.end(a.contents);
+					let { args: a } = await w(t), o = r.environments.ssr;
+					if (!n(o)) throw Error("Vite SSR environment is not runnable.");
+					let s = await (await o.runner.import(e.entry)).default.dispatch(decodeURIComponent(c), ...a);
+					i.statusCode = 200, i.setHeader("Content-Type", "application/json; charset=utf-8"), i.end(s.contents);
 				} catch (e) {
-					r.statusCode = e instanceof S ? 400 : 500, r.setHeader("Content-Type", "application/json; charset=utf-8"), r.end(JSON.stringify({ error: e instanceof Error ? {
+					i.statusCode = e instanceof v ? 400 : 500, i.setHeader("Content-Type", "application/json; charset=utf-8"), i.end(JSON.stringify({ error: e instanceof Error ? {
 						name: e.name,
 						message: e.message,
 						stack: e.stack
@@ -180,9 +183,21 @@ function C(e) {
 					} }));
 				}
 			});
+		},
+		transformIndexHtml(e) {
+			if (!r) return e;
+			let t = e;
+			for (let [e, n] of Object.entries(r)) {
+				let r = RegExp(`<\\?=\\s*${C(e)}\\s*\\?>`, "g");
+				t = t.replace(r, () => n);
+			}
+			return t;
 		}
 	};
 }
+function C(e) {
+	return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function w(e) {
 	return new Promise((t, n) => {
 		let r = [];
@@ -198,11 +213,11 @@ function w(e) {
 			try {
 				i = JSON.parse(e);
 			} catch {
-				n(new S("Invalid RPC request body. Expected valid JSON."));
+				n(new v("Invalid RPC request body. Expected valid JSON."));
 				return;
 			}
 			if (typeof i != "object" || !i || !("args" in i) || !Array.isArray(i.args)) {
-				n(new S("Invalid RPC request body. Expected { args: unknown[] }."));
+				n(new v("Invalid RPC request body. Expected { args: unknown[] }."));
 				return;
 			}
 			t({ args: i.args });
@@ -213,8 +228,8 @@ function w(e) {
 //#region src/gasboost.ts
 function T(e) {
 	return {
-		build: x(e),
-		dev: C(e.entry)
+		build: _(e),
+		dev: S(e)
 	};
 }
 //#endregion

package/dist/loadAppsScript.d.ts

@@ -0,0 +1,4 @@
+import type { AppsScriptDescription } from "@gasboost/app";
+import { type ResolvedConfig } from "vite";
+import type { GasboostOptions } from "./gasboost";
+export declare function loadAppsScript(options: GasboostOptions, config: ResolvedConfig): Promise<AppsScriptDescription>;

package/dist/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { GasRuntime } from "./gasboost";
+export declare const defaultGasRuntime: GasRuntime;
+export declare function installGasRuntime(runtime?: GasRuntime): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasboost/vite",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "A Vite plugin for building @gasboost/app applications for Google Apps Script.",
   "keywords": [
     "google-apps-script",
@@ -33,11 +33,14 @@
   },
   "type": "module",
   "devDependencies": {
+    "@types/google-apps-script": "^2.0.12",
     "vite": "^8.2.2"
   },
   "dependencies": {
+    "@gasboost/fake-core": "^0.1.2",
+    "@gasboost/fake-node": "^0.1.2",
     "typescript": "^7.0.2",
-    "@gasboost/app": "1.0.1"
+    "@gasboost/app": "1.3.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/analyzer.d.ts

@@ -1,6 +0,0 @@
-export interface AppsScriptAnalysis {
-    hasGet: boolean;
-    hasPost: boolean;
-    calls: string[];
-}
-export declare function analyzeAppsScript(entry: string): AppsScriptAnalysis;