vite-plugin-gas-hoist 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md CHANGED
@@ -5,24 +5,27 @@
5
5
 
6
6
  [English](README.md)
7
7
 
8
- エントリーポイントの `export` を Google Apps Script (GAS) のグローバルスコープに公開する Vite プラグインです。
8
+ エントリーポイントの `export` を、ESM の宣言種別(`function` / `const` / `let` / `var`)を保ったまま、Google Apps Script (GAS) のグローバルスコープに公開する Vite プラグインです。
9
9
 
10
- ## 試してみる
10
+ ## デモ
11
11
 
12
12
  ブラウザ上でコードの編集とビルドを試すことができます。ビルド完了後、`dist/app.js` を開くとプラグインの出力を確認できます。
13
13
 
14
14
  [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/hd140283/vite-plugin-gas-hoist/tree/main/example?file=src/app.js)
15
15
 
16
- ## なぜ必要か?
16
+ ## 概要
17
17
 
18
- GAS はグローバルスコープの関数しか実行できないが、Vite でバンドルすると全てのコードが IIFE 内に閉じ込められます。このプラグインは、エントリーポイントの `export` を自動的にグローバル関数としてラップすることで、この問題を解決します。
18
+ GAS 向けに Vite でバンドルするときは、複数モジュールを 1 ファイルにまとめるために IIFE フォーマットを使います。`build.lib.name` に末尾 `_` 付きの変数名(例: `lib_`)を指定すれば、IIFE 全体が GAS のライブラリ可視性ルールで外部から隠れるので、内部実装をライブラリ利用者に見せずに済みます。
19
+
20
+ ただ、これだけだとライブラリとして公開したい関数も、エディタの「実行」ボタンから呼び出したい関数も、まとめて隠れてしまいます。このプラグインは、エントリーポイントから `export` したものだけを IIFE の外側に再宣言して、GAS のグローバルスコープに公開します。
19
21
 
20
22
  ```js
21
23
  // ビルド前(エントリーポイント)
22
24
  export const sayHello = (name) => `Hello, ${name}!`;
23
25
 
24
- // ビルド後(プラグインが自動追加)
25
- function sayHello(...args) { return lib_.sayHello(...args) }
26
+ // ビルド後
27
+ var lib_ = (function(){ /* バンドルされた sayHello を含む IIFE */ })({});
28
+ const sayHello = (...args) => lib_.sayHello(...args); // プラグインが追加
26
29
  ```
27
30
 
28
31
  ## インストール
@@ -51,12 +54,44 @@ export default defineConfig({
51
54
  });
52
55
  ```
53
56
 
54
- `build.lib.name` に指定した変数名(上記例では `lib_`)を介して、エクスポートされた関数がグローバルスコープに公開されます。
57
+ `build.lib.name` に指定した変数名(上記例では `lib_`)を介して、エクスポートが GAS のグローバルスコープに公開されます。
58
+
59
+ ## 対応パターン
60
+
61
+ GAS でグローバルに公開するときの目的は、大きく 2 つに分かれます。
62
+
63
+ - **外部公開**: ライブラリとして使われたとき、利用者から `MyLib.foo()` で呼び出せる
64
+ - **内部公開**: 同じプロジェクト内で、エディタの「実行」ボタンやトリガー設定から呼び出せる
65
+
66
+ ESM の宣言種別(`function` / `const` / `let` / `var`)と右辺の形をそのまま保つことで、この 2 つの公開を組み合わせて表現できます。GAS のライブラリ可視性ルール(`function` / `var` は外部公開、`const` / `let` は非公開)がそのまま反映される挙動です。
67
+
68
+ | ESM 宣言 | 出力 | GAS ライブラリ可視性 |
69
+ |---|---|---|
70
+ | `export function foo() {}` | `function foo(...args){return lib_.foo(...args)}` | 公開 |
71
+ | `export const FOO = 42` | `const FOO = lib_.FOO` | 非公開 |
72
+ | `export const foo = (x) => x` | `const foo = (...args) => lib_.foo(...args)` | 非公開(エディタの "実行" ドロップダウンに表示) |
73
+ | `export const foo = function(x){...}` | `const foo = function(...args){return lib_.foo(...args)}` | 非公開(同上) |
74
+ | `export let foo = ...` | `let foo = ...`(右辺は const と同形) | 非公開 |
75
+ | `export var foo = ...` | `var foo = ...`(右辺は const と同形) | 公開 |
76
+
77
+ `export { foo }` や `export { foo as bar }` のような specifier 形式の再エクスポートも、ローカル宣言の種別を引き継ぎます。表に当てはまらないパターン(`export default` や `export class`、宣言種別を判定できない再エクスポートなど)はビルド時に警告を出してスキップします。
78
+
79
+ > 関数式・アロー関数式の右辺をそのままラップ形式で再宣言するのは、GAS のエディタの "実行" ドロップダウンに表示させる(トリガー設定や手動実行を可能にする)ためです。値の右辺をラップしないのは、関数として呼び出されないためエディタに出す必要がなく、純粋な参照のほうが読みやすいからです。
55
80
 
56
81
  ## 動作条件
57
82
 
58
83
  - `build.lib.formats` に `'iife'` を含むこと
59
- - エントリーポイントで関数を `export` していること
84
+ - エントリーポイントで何かを `export` していること
85
+
86
+ ## 0.1.x からの移行
87
+
88
+ 0.1.x までは全ての export を `function name(...){...}` 形式で hoist していましたが、0.2.0 以降は ESM の宣言種別を保つようになりました。
89
+
90
+ - `export function foo()`: 挙動は変わらず(`function foo(...){...}` のまま)
91
+ - `export const foo = (x) => x`: `const foo = (...args) => lib_.foo(...args)` に変更(0.1.x では `function foo(...){...}`)
92
+ - `export const FOO = 42`: `const FOO = lib_.FOO` に変更(0.1.x では `function FOO(...){...}`)
93
+
94
+ GAS のライブラリ可視性ルールに沿って宣言種別を意図的に選んでいる場合(公開したいものは `function` / `var`、非公開にしたいものは `const` / `let`)、その意図がビルド出力に反映されるようになります。
60
95
 
61
96
  ## ライセンス
62
97
 
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
 
6
6
  [日本語](README.ja.md)
7
7
 
8
- A Vite plugin that hoists entry point `export`s to the global scope for Google Apps Script (GAS).
8
+ A Vite plugin that hoists entry point `export`s to the global scope for Google Apps Script (GAS), preserving the original ESM declaration kind (`function` / `const` / `let` / `var`).
9
9
 
10
10
  ## Try it
11
11
 
@@ -15,14 +15,17 @@ Edit and build in your browser — no setup required. Once the build finishes, o
15
15
 
16
16
  ## Why?
17
17
 
18
- GAS can only execute functions in the global scope, but Vite bundles all code inside an IIFE. This plugin automatically wraps entry point exports as global functions, bridging the gap.
18
+ When you bundle code for GAS with Vite, you typically use the `iife` format to combine multiple modules into a single file. Naming the IIFE variable with a trailing underscore (e.g. `lib_` via `build.lib.name`) takes advantage of GAS's library visibility rules to hide the entire bundle from library consumers.
19
+
20
+ The catch: that also hides everything you actually want to expose — both functions called by library consumers and functions you want to run from the GAS editor's "Run" dropdown or triggers. This plugin re-declares each entry-point `export` outside the IIFE, so only what you explicitly export becomes globally visible.
19
21
 
20
22
  ```js
21
23
  // Before build (entry point)
22
24
  export const sayHello = (name) => `Hello, ${name}!`;
23
25
 
24
- // After build (plugin adds this)
25
- function sayHello(...args) { return lib_.sayHello(...args) }
26
+ // After build
27
+ var lib_ = (function(){ /* IIFE bundle containing sayHello */ })({});
28
+ const sayHello = (...args) => lib_.sayHello(...args); // added by the plugin
26
29
  ```
27
30
 
28
31
  ## Install
@@ -51,13 +54,45 @@ export default defineConfig({
51
54
  });
52
55
  ```
53
56
 
54
- Exported functions are hoisted to the global scope via the variable name specified in `build.lib.name` (e.g. `lib_`).
57
+ Exports are hoisted to the global scope via the variable name specified in `build.lib.name` (e.g. `lib_`).
58
+
59
+ ## What gets hoisted
60
+
61
+ Exposing something globally in GAS serves one of two purposes:
62
+
63
+ - **External**: callable by library consumers as `MyLib.foo()`
64
+ - **Internal**: visible inside the same project — selectable in the editor's "Run" dropdown and trigger settings
65
+
66
+ By preserving the original ESM declaration kind (`function` / `const` / `let` / `var`) and the right-hand-side shape, the plugin lets you express both axes naturally. GAS's library visibility rules apply directly: `function` and `var` are externally visible, `const` and `let` are not.
67
+
68
+ | ESM declaration | Output | GAS library visibility |
69
+ |---|---|---|
70
+ | `export function foo() {}` | `function foo(...args){return lib_.foo(...args)}` | external |
71
+ | `export const FOO = 42` | `const FOO = lib_.FOO` | internal only |
72
+ | `export const foo = (x) => x` | `const foo = (...args) => lib_.foo(...args)` | internal only (appears in the editor's "Run" dropdown) |
73
+ | `export const foo = function(x){...}` | `const foo = function(...args){return lib_.foo(...args)}` | internal only (same) |
74
+ | `export let foo = ...` | `let foo = ...` (right-hand side as above) | internal only |
75
+ | `export var foo = ...` | `var foo = ...` (right-hand side as above) | external |
76
+
77
+ Specifier-form re-exports like `export { foo }` and `export { foo as bar }` inherit the kind of the local declaration. Patterns not covered above (`export default`, `export class`, re-exports whose kind cannot be determined, etc.) are skipped with a build-time warning.
78
+
79
+ > Function and arrow-function right-hand sides are kept as wrapper forms so the binding shows up in the GAS editor's "Run" dropdown (enabling trigger setup and manual invocation). Plain values are hoisted as direct references — they aren't called as functions, so they don't need to appear in the editor.
55
80
 
56
81
  ## Requirements
57
82
 
58
83
  - `build.lib.formats` must include `'iife'`
59
84
  - Entry point must have at least one `export`
60
85
 
86
+ ## Migration from 0.1.x
87
+
88
+ In 0.1.x, every export was hoisted as `function name(...){...}`. From 0.2.0 onward, the plugin preserves the original ESM declaration kind:
89
+
90
+ - `export function foo()`: unchanged (still `function foo(...){...}`)
91
+ - `export const foo = (x) => x`: now `const foo = (...args) => lib_.foo(...args)` (was `function foo(...){...}` in 0.1.x)
92
+ - `export const FOO = 42`: now `const FOO = lib_.FOO` (was `function FOO(...){...}` in 0.1.x)
93
+
94
+ If you've been choosing declaration kinds intentionally to align with GAS's library visibility rules (`function` / `var` for external, `const` / `let` for internal), that intent is now reflected in the build output.
95
+
61
96
  ## License
62
97
 
63
98
  [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vite-plugin-gas-hoist",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "A Vite plugin that hoists entry point exports to the global scope for Google Apps Script",
5
5
  "keywords": [
6
6
  "vite-plugin",
@@ -35,10 +35,11 @@
35
35
  }
36
36
  },
37
37
  "peerDependencies": {
38
- "vite": "^8.0.0"
38
+ "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
39
39
  },
40
40
  "devDependencies": {
41
41
  "@biomejs/biome": "^2.3.6",
42
+ "acorn": "^8.16.0",
42
43
  "vite": "^8.0.3",
43
44
  "vitest": "^4.1.4"
44
45
  },
package/src/index.js CHANGED
@@ -19,10 +19,15 @@
19
19
  *
20
20
  * @returns {import('vite').Plugin}
21
21
  */
22
+ /** @typedef {'function' | 'const' | 'let' | 'var'} ExportKind */
23
+ /** @typedef {{ kind: ExportKind, isFn: boolean, isArrow: boolean }} ExportInfo */
22
24
  export const vitePluginGasHoist = () => {
23
25
  /** @type {string} IIFE variable name from build.lib.name */
24
26
  let varName;
25
27
 
28
+ /** @type {Map<string, ExportInfo>} */
29
+ const exportKinds = new Map();
30
+
26
31
  return {
27
32
  name: 'vite-plugin-gas-hoist',
28
33
  apply: 'build',
@@ -32,15 +37,76 @@ export const vitePluginGasHoist = () => {
32
37
  varName = config.build.lib?.name;
33
38
  },
34
39
 
40
+ buildStart() {
41
+ exportKinds.clear();
42
+ },
43
+
44
+ /**
45
+ * Records the declaration kind of each top-level named export so that
46
+ * renderChunk can emit a binding that preserves the original visibility.
47
+ *
48
+ * @param {string} code
49
+ * @param {string} _id
50
+ */
51
+ transform(code, _id) {
52
+ // Cheap pre-filter: skip modules that obviously have no exports (node_modules, virtual modules, CSS-as-JS, etc.) before paying acorn's cost.
53
+ if (!code.includes('export')) return null;
54
+
55
+ let ast;
56
+ try {
57
+ ast = this.parse(code);
58
+ } catch {
59
+ // Parse errors are surfaced by Vite/Rollup elsewhere; staying silent here avoids double-reporting.
60
+ return null;
61
+ }
62
+
63
+ /** @type {Map<string, ExportInfo>} */
64
+ const localKinds = new Map();
65
+ for (const node of ast.body) {
66
+ if (node.type === 'FunctionDeclaration' && node.id) {
67
+ localKinds.set(node.id.name, { kind: 'function', isFn: true, isArrow: false });
68
+ } else if (node.type === 'VariableDeclaration') {
69
+ for (const decl of node.declarations) {
70
+ if (decl.id.type === 'Identifier') {
71
+ localKinds.set(decl.id.name, classifyVariable(node.kind, decl.init));
72
+ }
73
+ }
74
+ }
75
+ }
76
+
77
+ for (const node of ast.body) {
78
+ if (node.type !== 'ExportNamedDeclaration') continue;
79
+
80
+ if (node.declaration?.type === 'VariableDeclaration') {
81
+ const kind = node.declaration.kind;
82
+ for (const decl of node.declaration.declarations) {
83
+ if (decl.id.type === 'Identifier') {
84
+ exportKinds.set(decl.id.name, classifyVariable(kind, decl.init));
85
+ }
86
+ }
87
+ } else if (node.declaration?.type === 'FunctionDeclaration') {
88
+ if (node.declaration.id?.type === 'Identifier') {
89
+ exportKinds.set(node.declaration.id.name, { kind: 'function', isFn: true, isArrow: false });
90
+ }
91
+ } else if (node.specifiers.length > 0 && !node.source) {
92
+ for (const spec of node.specifiers) {
93
+ if (spec.type !== 'ExportSpecifier') continue;
94
+ const info = localKinds.get(spec.local.name);
95
+ if (info) {
96
+ exportKinds.set(spec.exported.name, info);
97
+ }
98
+ }
99
+ }
100
+ }
101
+ return null;
102
+ },
103
+
35
104
  renderChunk: {
36
105
  order: 'post',
37
106
  /**
38
- * Appends global wrapper functions for each export.
39
- *
40
- * Given `export { sayHello }` with `lib.name = 'lib_'`, produces:
41
- * ```js
42
- * function sayHello(...args){return lib_.sayHello(...args)}
43
- * ```
107
+ * Appends kind-appropriate global hoist bindings for each entry export,
108
+ * skipping unsupported patterns (e.g. `export default`, `export class`,
109
+ * re-exports) whose declaration kind was not recorded by `transform`.
44
110
  *
45
111
  * @param {string} code
46
112
  * @param {import('rollup').RenderedChunk} chunk
@@ -49,19 +115,75 @@ export const vitePluginGasHoist = () => {
49
115
  handler(code, chunk, options) {
50
116
  if (options.format !== 'iife' || !chunk.isEntry) return null;
51
117
 
52
- const { exports } = chunk;
53
- if (exports.length === 0) return null;
118
+ /** @type {Array<{ name: string, info: ExportInfo }>} */
119
+ const known = [];
120
+ /** @type {string[]} */
121
+ const skipped = [];
122
+
123
+ for (const name of chunk.exports) {
124
+ const info = exportKinds.get(name);
125
+ if (info) {
126
+ known.push({ name, info });
127
+ } else {
128
+ skipped.push(name);
129
+ }
130
+ }
131
+
132
+ if (known.length > 0) {
133
+ const label = known.length === 1 ? 'export' : 'exports';
134
+ const list = known.map(({ name, info }) => ` - ${name} (${info.kind})`).join('\n');
135
+ console.log(`[vite-plugin-gas-hoist] Hoisted ${known.length} ${label} to global scope:\n${list}`);
136
+ }
54
137
 
55
- const wrappers = exports
56
- .map((name) => `function ${name}(...args){return ${varName}.${name}(...args)}`)
57
- .join('\n');
138
+ if (skipped.length > 0) {
139
+ const label = skipped.length === 1 ? 'export' : 'exports';
140
+ const list = skipped.map((name) => ` - ${name}`).join('\n');
141
+ this.warn(`Skipped ${skipped.length} ${label} (unsupported pattern):\n${list}`);
142
+ }
58
143
 
59
- const label = exports.length === 1 ? 'function' : 'functions';
60
- const list = exports.map((name) => ` - ${name}`).join('\n');
61
- console.log(`[vite-plugin-gas-hoist] Hoisted ${exports.length} ${label} to global scope:\n${list}`);
144
+ if (known.length === 0) return null;
145
+
146
+ const wrappers = known.map(({ name, info }) => emitWrapper(name, info, varName)).join('\n');
62
147
 
63
148
  return `${code}\n${wrappers}\n`;
64
149
  },
65
150
  },
66
151
  };
67
152
  };
153
+
154
+ /**
155
+ * Classifies a `VariableDeclaration` declarator as a value or function expression.
156
+ *
157
+ * @param {ExportKind} kind
158
+ * @param {import('estree').Expression | null | undefined} init
159
+ * @returns {ExportInfo}
160
+ */
161
+ const classifyVariable = (kind, init) => {
162
+ const isArrow = init?.type === 'ArrowFunctionExpression';
163
+ const isFn = isArrow || init?.type === 'FunctionExpression';
164
+ return { kind, isFn, isArrow };
165
+ };
166
+
167
+ /**
168
+ * Renders the hoisted binding for a single export, preserving the original
169
+ * declaration kind and (for `const`/`let` function expressions) the function
170
+ * shape (arrow vs `function` expression) so callers see a callable wrapper
171
+ * that GAS recognizes as a function.
172
+ *
173
+ * @param {string} name
174
+ * @param {ExportInfo} info
175
+ * @param {string} varName
176
+ * @returns {string}
177
+ */
178
+ const emitWrapper = (name, info, varName) => {
179
+ if (info.kind === 'function') {
180
+ return `function ${name}(...args){return ${varName}.${name}(...args)}`;
181
+ }
182
+ if (info.isFn) {
183
+ if (info.isArrow) {
184
+ return `${info.kind} ${name} = (...args) => ${varName}.${name}(...args)`;
185
+ }
186
+ return `${info.kind} ${name} = function(...args){return ${varName}.${name}(...args)}`;
187
+ }
188
+ return `${info.kind} ${name} = ${varName}.${name}`;
189
+ };