@myfunction/apps-script-types 0.2.0 → 0.2.1
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.md +98 -42
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,28 +1,29 @@
|
|
|
1
1
|
# @myfunction/apps-script-types
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Editing in `script.google.com`?** [myFunction for Chrome](https://chromewebstore.google.com/detail/myfunction-for-google-app/pbhajeiediafkbgcolkpkoffphdaghkb?utm_source=npmjs.com&utm_medium=readme&utm_campaign=apps-script-types) adds these types, live errors, and quick fixes to the Apps Script editor.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
TypeScript and JSDoc declarations for Google Apps Script (V8), with the service surface checked against what the runtime exposes.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Use them in a [`clasp`](https://github.com/google/clasp) project or any local Apps Script workspace to get autocomplete, hover docs, and type errors in VS Code or any editor that runs the TypeScript language service. They work in plain `.js` files through JSDoc, so you do not have to switch your project to TypeScript.
|
|
8
8
|
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
11
|
-
- **
|
|
9
|
+
- **Runtime-verified services.** Service globals, their methods, and enums come from an introspection dump taken inside the Apps Script V8 runtime, so a service method that does not exist at runtime is not declared. Parameter, return, and class signatures, such as `SpreadsheetApp.Range`, are curated from the Apps Script reference.
|
|
10
|
+
- **Real `null` returns.** Methods such as `Spreadsheet.getSheetByName()` and `SpreadsheetApp.getActiveRange()` return `T | null`, so `strict` mode flags the missing check.
|
|
11
|
+
- **Short JSDoc names.** Write `{SpreadsheetApp.Range}` and `{Events.DoPost}`. The `GoogleAppsScript.*` names from `@types/google-apps-script` also resolve.
|
|
12
|
+
- **Distinct classes stay distinct.** Passing a `DocumentApp.Range` where a `SpreadsheetApp.Range` is expected is a type error.
|
|
13
|
+
- **Opt-in Advanced Google Services.** Add only the services your `appsscript.json` enables, typed from Google's Discovery documents.
|
|
14
|
+
- **No runtime dependencies.** The package ships `.d.ts` files only.
|
|
12
15
|
|
|
13
16
|
## Install
|
|
14
17
|
|
|
15
18
|
```bash
|
|
16
|
-
npm install -
|
|
19
|
+
npm install --save-dev @myfunction/apps-script-types
|
|
17
20
|
```
|
|
18
21
|
|
|
19
|
-
|
|
20
|
-
pnpm add -D @myfunction/apps-script-types
|
|
21
|
-
```
|
|
22
|
+
If `@types/google-apps-script` is installed, remove it first. Both packages declare the same globals, and loading both fails with `Duplicate identifier` errors. See [Migrate from `@types/google-apps-script`](#migrate-from-typesgoogle-apps-script).
|
|
22
23
|
|
|
23
|
-
##
|
|
24
|
+
## Configure your project
|
|
24
25
|
|
|
25
|
-
|
|
26
|
+
Add a `tsconfig.json` to the folder that holds your script files. For a JavaScript-only project, name it `jsconfig.json` instead. `clasp` stores `.gs` files locally as `.js`, so the same setup covers them.
|
|
26
27
|
|
|
27
28
|
```json
|
|
28
29
|
{
|
|
@@ -38,13 +39,16 @@ For a `clasp` project or local Apps Script workspace, configure `tsconfig.json`
|
|
|
38
39
|
}
|
|
39
40
|
```
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
Two settings matter:
|
|
42
43
|
|
|
43
|
-
|
|
44
|
+
- `"lib": ["ES2020"]` leaves out `"DOM"`. Apps Script has no `window`, `document`, or `fetch`, and the DOM `Blob` type collides with the Apps Script global `Blob`.
|
|
45
|
+
- `"types"` lists the package explicitly. Without it, TypeScript loads every `@types/*` package in `node_modules`.
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
To check the whole project from the command line or in CI, install `typescript` and run `npx tsc -p .`.
|
|
46
48
|
|
|
47
|
-
|
|
49
|
+
## Write typed Apps Script
|
|
50
|
+
|
|
51
|
+
Every built-in service global, such as `SpreadsheetApp`, `DriveApp`, `GmailApp`, `UrlFetchApp`, or `PropertiesService`, is both the runtime value and the namespace for its classes and enums. Trigger event objects live under `Events`.
|
|
48
52
|
|
|
49
53
|
```js
|
|
50
54
|
/**
|
|
@@ -52,8 +56,7 @@ Every built-in service global (`SpreadsheetApp`, `DriveApp`, `GmailApp`, `Docume
|
|
|
52
56
|
* @returns {Blob}
|
|
53
57
|
*/
|
|
54
58
|
function exportRangeCsv(range) {
|
|
55
|
-
const
|
|
56
|
-
const csv = values.map((row) => row.join(",")).join("\n");
|
|
59
|
+
const csv = range.getValues().map((row) => row.join(",")).join("\n");
|
|
57
60
|
return Utilities.newBlob(csv, MimeType.CSV, "export.csv");
|
|
58
61
|
}
|
|
59
62
|
|
|
@@ -76,23 +79,36 @@ function onEdit(e) {
|
|
|
76
79
|
}
|
|
77
80
|
```
|
|
78
81
|
|
|
79
|
-
|
|
82
|
+
With `strict` on, the checker reports a method that can return `null` when the code does not handle it:
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
function readTotals() {
|
|
86
|
+
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Totals");
|
|
87
|
+
return sheet.getRange("A1:B10").getValues();
|
|
88
|
+
// ~~~~~ error TS18047: 'sheet' is possibly 'null'.
|
|
89
|
+
}
|
|
90
|
+
```
|
|
80
91
|
|
|
81
|
-
|
|
92
|
+
The same names work in `.ts` files:
|
|
82
93
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
94
|
+
```ts
|
|
95
|
+
function listPdfNames(folder: DriveApp.Folder): string[] {
|
|
96
|
+
const names: string[] = [];
|
|
97
|
+
const files = folder.getFilesByType(MimeType.PDF);
|
|
98
|
+
while (files.hasNext()) {
|
|
99
|
+
names.push(files.next().getName());
|
|
100
|
+
}
|
|
101
|
+
return names;
|
|
102
|
+
}
|
|
103
|
+
```
|
|
88
104
|
|
|
89
105
|
## Advanced Google Services
|
|
90
106
|
|
|
91
|
-
The default
|
|
107
|
+
The default entry point covers the built-in services only. Advanced Google Services, such as `Sheets`, `Drive`, and `Gmail`, are separate entry points so your editor offers only the services your script can call.
|
|
92
108
|
|
|
93
|
-
###
|
|
109
|
+
### Add the services your manifest enables
|
|
94
110
|
|
|
95
|
-
|
|
111
|
+
For each service listed under `dependencies.enabledAdvancedServices` in `appsscript.json`, add its subpath to `"types"`:
|
|
96
112
|
|
|
97
113
|
```json
|
|
98
114
|
{
|
|
@@ -111,34 +127,36 @@ Add the subpath for each service enabled in `appsscript.json` (`dependencies.ena
|
|
|
111
127
|
}
|
|
112
128
|
```
|
|
113
129
|
|
|
114
|
-
|
|
130
|
+
To add a service for a single file, use a triple-slash reference at the top of that file:
|
|
115
131
|
|
|
116
132
|
```js
|
|
117
133
|
/// <reference types="@myfunction/apps-script-types/advanced/sheets" />
|
|
118
134
|
|
|
135
|
+
/**
|
|
136
|
+
* @param {string} spreadsheetId
|
|
137
|
+
*/
|
|
119
138
|
function readValues(spreadsheetId) {
|
|
120
139
|
return Sheets.Spreadsheets.Values.get(spreadsheetId, "Sheet1!A1:D10");
|
|
121
140
|
}
|
|
122
141
|
```
|
|
123
142
|
|
|
124
|
-
### Load
|
|
143
|
+
### Load every service
|
|
125
144
|
|
|
126
|
-
|
|
145
|
+
The `full` entry point includes the built-in services and all 31 Advanced Google Services. Use it in place of the default entry:
|
|
127
146
|
|
|
128
147
|
```json
|
|
129
148
|
{
|
|
130
149
|
"compilerOptions": {
|
|
131
|
-
"
|
|
132
|
-
"lib": ["ES2020"],
|
|
133
|
-
"types": ["@myfunction/apps-script-types/full"],
|
|
134
|
-
"checkJs": true,
|
|
135
|
-
"strict": true,
|
|
136
|
-
"noEmit": true
|
|
150
|
+
"types": ["@myfunction/apps-script-types/full"]
|
|
137
151
|
}
|
|
138
152
|
}
|
|
139
153
|
```
|
|
140
154
|
|
|
141
|
-
|
|
155
|
+
The full bundle is about 6.7 MB of declarations, compared with 1.4 MB for the default entry, so editors load it more slowly.
|
|
156
|
+
|
|
157
|
+
### Advanced service subpaths
|
|
158
|
+
|
|
159
|
+
The `serviceId` and `version` columns match the entries in `appsscript.json`.
|
|
142
160
|
|
|
143
161
|
| Global Symbol | `appsscript.json` (`serviceId` / `version`) | Subpath |
|
|
144
162
|
| --- | --- | --- |
|
|
@@ -174,15 +192,53 @@ To include all built-in services and all 31 Advanced Google Services at once:
|
|
|
174
192
|
| `YouTube` | `youtube` / `v3` | `@myfunction/apps-script-types/advanced/youtube` |
|
|
175
193
|
| `YouTubeAnalytics` | `youtubeAnalytics` / `v2` | `@myfunction/apps-script-types/advanced/youtubeanalytics` |
|
|
176
194
|
|
|
177
|
-
##
|
|
195
|
+
## Migrate from `@types/google-apps-script`
|
|
196
|
+
|
|
197
|
+
1. Remove the old package:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
npm uninstall @types/google-apps-script
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
2. Install this package and set `"types"` as shown in [Configure your project](#configure-your-project).
|
|
204
|
+
3. Add a subpath for each Advanced Google Service you use.
|
|
205
|
+
4. Run `npx tsc -p .` and fix the new errors. Most are `possibly 'null'` checks on methods that really can return `null`.
|
|
206
|
+
|
|
207
|
+
Existing `GoogleAppsScript.*` annotations keep working. Each alias resolves to the same type as its short name:
|
|
208
|
+
|
|
209
|
+
| `@types/google-apps-script` name | Short name |
|
|
210
|
+
| --- | --- |
|
|
211
|
+
| `GoogleAppsScript.Spreadsheet.Range` | `SpreadsheetApp.Range` |
|
|
212
|
+
| `GoogleAppsScript.Drive.File` | `DriveApp.File` |
|
|
213
|
+
| `GoogleAppsScript.Document.Document` | `DocumentApp.Document` |
|
|
214
|
+
| `GoogleAppsScript.Events.DoPost` | `Events.DoPost` |
|
|
215
|
+
| `GoogleAppsScript.Base.Blob` | `Blob` |
|
|
216
|
+
|
|
217
|
+
### How the two packages differ
|
|
178
218
|
|
|
179
219
|
| Capability | `@myfunction/apps-script-types` | `@types/google-apps-script` |
|
|
180
220
|
| --- | --- | --- |
|
|
181
|
-
| Surface authority |
|
|
221
|
+
| Surface authority | Service methods and enums verified against a live Apps Script V8 runtime dump; class and parameter signatures curated from the Apps Script reference | Hand-maintained DefinitelyTyped definitions |
|
|
182
222
|
| Cross-service nominal brands | `SpreadsheetApp.Range` and `DocumentApp.Range` carry distinct nominal brands so passing one to the other is a type error | Structural interfaces allow accidental cross-service matches when shapes overlap |
|
|
183
223
|
| JSDoc qualifier syntax | `@param {SpreadsheetApp.Range}` and `@param {Events.DoPost}` work alongside `@param {GoogleAppsScript.Spreadsheet.Range}` | Requires the `GoogleAppsScript.*` namespace prefix |
|
|
184
|
-
| Nullable return types | Includes `\| null` where Apps Script methods return `null` at runtime
|
|
185
|
-
| Advanced Google Services | Opt-in per service (`/advanced/sheets`, `/advanced/drive
|
|
224
|
+
| Nullable return types | Includes `\| null` where Apps Script methods return `null` at runtime such as `SpreadsheetApp.getActiveRange()` and `Spreadsheet.getSheetByName()` | Frequently typed as non-null |
|
|
225
|
+
| Advanced Google Services | Opt-in per service (`/advanced/sheets`, `/advanced/drive`) or all-in-one (`/full`), generated from Discovery REST documents | Bundled together in the global scope |
|
|
226
|
+
|
|
227
|
+
## Troubleshooting
|
|
228
|
+
|
|
229
|
+
- **`Duplicate identifier` or `Definitions of the following identifiers conflict`.** Another package declares the Apps Script globals, usually `@types/google-apps-script`. Uninstall it, or list only `@myfunction/apps-script-types` in `"types"`.
|
|
230
|
+
- **`Cannot find name 'Sheets'`** (or another advanced service). Add that service's subpath to `"types"`, or switch to `@myfunction/apps-script-types/full`.
|
|
231
|
+
- **`Blob` conflicts or browser globals such as `document` in completions.** Remove `"DOM"` from `"lib"`.
|
|
232
|
+
- **No errors in `.js` files.** Set `"checkJs": true`, or add `// @ts-check` as the first line of a file.
|
|
233
|
+
|
|
234
|
+
## More from myFunction
|
|
235
|
+
|
|
236
|
+
These declarations come from [myFunction](https://myfunction.dev?utm_source=npmjs.com&utm_medium=readme&utm_campaign=apps-script-types), which builds an Apps Script language server on top of them.
|
|
237
|
+
|
|
238
|
+
- **[myFunction MCP server](https://myfunction.dev/apps-script-mcp?utm_source=npmjs.com&utm_medium=readme&utm_campaign=apps-script-types)** gives Claude Code, Cursor, and other MCP clients the myFunction language server, so a coding agent can validate Apps Script edits before `clasp push`.
|
|
239
|
+
- **[Apps Script field guide](https://myfunction.dev/apps-script?utm_source=npmjs.com&utm_medium=readme&utm_campaign=apps-script-types)** has reference pages, trigger guides, and explanations for each diagnostic.
|
|
240
|
+
|
|
241
|
+
Report a wrong or missing declaration in [GitHub issues](https://github.com/benchcutlogic/myFunction/issues).
|
|
186
242
|
|
|
187
243
|
## License
|
|
188
244
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@myfunction/apps-script-types",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Runtime-verified TypeScript and JSDoc declarations for Google Apps Script (V8), including built-in services, trigger events, and opt-in Advanced Google Services.",
|
|
5
5
|
"license": "MIT AND CC-BY-4.0",
|
|
6
6
|
"private": false,
|