Apps Script Utils
Available files
references/api-reference.md — full function catalog by category with signatures. Load on demand (see Categories below).scripts/check-latest-version.sh — checks the current published version against what's installed. Run with --help for options.
apps-script-utils is a standalone package — no framework required. Install it directly in any Apps Script or plain TypeScript project:
npm install apps-script-utils
It also happens to be a direct runtime dependency of bootgs (bootgs's own core imports guards like isString/isObject from it), so in a bootgs project it's already in node_modules and importable with no separate install — see the bootgs-quickstart skill. That relationship is one-directional: this package has no dependency on bootgs and works identically with or without it.
Check what's actually published before trusting a function list against a specific version:
scripts/check-latest-version.sh
The naming convention
Every category in the library follows the same three-function shape — learn it once, and every function name in references/api-reference.md is predictable without looking it up:
| Pattern |
Signature |
Behavior |
isX(value) |
value is X (type guard) |
Never throws. Use in conditionals. |
nonX(value) |
boolean |
Negation of isX. |
requireX(value, message?) |
X (narrowed) or throws |
Throws a typed exception from exception/ (e.g. EmptyStringException, NullPointerException) when the guard fails — not a generic Error. Returns the narrowed value on success, so it doubles as an assertion. |
Prefer requireX at the boundary of a function (repository/service entry points) over manual if (!x) throw ... — the thrown exception type is consistent across the whole codebase and callers can catch a specific exception class instead of pattern-matching a message string.
This is the target shape the library is rolling out toward, not a guarantee for every existing guard yet — some isX functions, particularly in lang/base, don't have a nonX or requireX counterpart published yet. references/api-reference.md lists exactly which variants exist per category; don't assume a nonX/requireX exists for a given isX without checking it there first.
Worked examples
import { parseA1Notation, requireNonEmptyString, isEmail } from "apps-script-utils";
const range = parseA1Notation("Sheet1!A1:B2"); // -> structured GridRange
const range2 = parseA1Notation("'My Sheet'!5:15"); // quoted sheet names and row-only ranges both parse
const name = requireNonEmptyString(rawInput); // throws EmptyStringException if rawInput is "", null, or undefined
if (isEmail(value)) {
// value is narrowed to `string` here, and matches a real email format (incl. plus-aliases), not a naive regex
}
Categories
| Category |
Contains |
appsscript/sheet |
A1-notation parsing/formatting, row helpers, GridRange containment checks, sheet lookup/guards — the largest category (~35 functions) |
appsscript/{slide,admin,ui,net} |
Service-specific helpers (isAdmin, isUi, checkMultipleAccount, requireValidToken) |
appsscript/{drive,doc,form} |
Reserved namespaces — currently empty, don't assume functions exist here without checking node_modules/apps-script-utils/dist first |
lang/base |
Generic guards: isArray, isBoolean, isEmpty, isNil, isObject, isString, ... — nonX/requireX pairs exist for some but not all of these yet, check references/api-reference.md |
lang/string |
toCamelCase, toKebabCase, toSnakeCase, isEmail, isValidSlug, isValidVersion + versionCompare, escapeRegExp |
lang/number |
isInteger, toInteger, nonNegative |
lang/array |
chunk, is2DArray, transpose |
exception/ |
Exception base class + NullPointerException, IllegalArgumentException, EmptyStringException, InvalidStringException, InvalidEmailFormatException, RuntimeException, RepositoryIsNotDefinedException, ServiceIsNotDefinedException |
net/path |
join, normalize, parse, isAbsolute, isRelative, isValidDomain |
net/url |
isUrl |
html/ |
encodeHtml, decodeHtml, escapeHtml, escapeXml |
json/ |
parseJson, stringifyJson — safe wrappers over JSON.parse/JSON.stringify |
time/ |
now |
Load references/api-reference.md when you need the exact signature of a specific function rather than just knowing it exists.
Gotchas
appsscript/drive, appsscript/doc, appsscript/form are placeholder namespaces with no exports yet — don't guess a function name into existence for these services.requireX exceptions extend the package's own Exception base, not Error directly in every case. If used inside a bootgs @ExceptionHandler (see the bootgs-validation skill), catch Error (their common ancestor) or the specific exception classes — not bootgs's AppException/HttpException, which these are unrelated to.
Verification
1---2name: apps-script-utils3description: Documents apps-script-utils, a standalone guard/utility library for Google Apps Script (isX/nonX/requireX convention, A1-notation and sheet helpers, string/number/array helpers, typed exceptions, HTML/JSON/path helpers). Use when writing Apps Script code that needs input guards, spreadsheet range parsing, or common data utilities. Independent of any framework — also used internally by bootgs, so the two pair naturally if the project already uses bootgs.4license: Apache-2.05---67# Apps Script Utils89## Available files1011- **`references/api-reference.md`** — full function catalog by category with signatures. Load on demand (see Categories below).12- **`scripts/check-latest-version.sh`** — checks the current published version against what's installed. Run with `--help` for options.1314`apps-script-utils` is a standalone package — no framework required. Install it directly in any Apps Script or plain TypeScript project:1516```bash17npm install apps-script-utils18```1920It also happens to be a direct runtime dependency of `bootgs` (bootgs's own core imports guards like `isString`/`isObject` from it), so in a bootgs project it's already in `node_modules` and importable with no separate install — see the `bootgs-quickstart` skill. That relationship is one-directional: this package has no dependency on bootgs and works identically with or without it.2122Check what's actually published before trusting a function list against a specific version:2324```bash25scripts/check-latest-version.sh26```2728## The naming convention2930Every category in the library follows the same three-function shape — learn it once, and every function name in `references/api-reference.md` is predictable without looking it up:3132| Pattern | Signature | Behavior |33|---|---|---|34| `isX(value)` | `value is X` (type guard) | Never throws. Use in conditionals. |35| `nonX(value)` | `boolean` | Negation of `isX`. |36| `requireX(value, message?)` | `X` (narrowed) or throws | Throws a **typed** exception from `exception/` (e.g. `EmptyStringException`, `NullPointerException`) when the guard fails — not a generic `Error`. Returns the narrowed value on success, so it doubles as an assertion. |3738Prefer `requireX` at the boundary of a function (repository/service entry points) over manual `if (!x) throw ...` — the thrown exception type is consistent across the whole codebase and callers can `catch` a specific exception class instead of pattern-matching a message string.3940This is the target shape the library is rolling out toward, not a guarantee for every existing guard yet — some `isX` functions, particularly in `lang/base`, don't have a `nonX` or `requireX` counterpart published yet. `references/api-reference.md` lists exactly which variants exist per category; don't assume a `nonX`/`requireX` exists for a given `isX` without checking it there first.4142## Worked examples4344```ts45import { parseA1Notation, requireNonEmptyString, isEmail } from "apps-script-utils";4647const range = parseA1Notation("Sheet1!A1:B2"); // -> structured GridRange48const range2 = parseA1Notation("'My Sheet'!5:15"); // quoted sheet names and row-only ranges both parse4950const name = requireNonEmptyString(rawInput); // throws EmptyStringException if rawInput is "", null, or undefined5152if (isEmail(value)) {53 // value is narrowed to `string` here, and matches a real email format (incl. plus-aliases), not a naive regex54}55```5657## Categories5859| Category | Contains |60|---|---|61| `appsscript/sheet` | A1-notation parsing/formatting, row helpers, `GridRange` containment checks, sheet lookup/guards — the largest category (~35 functions) |62| `appsscript/{slide,admin,ui,net}` | Service-specific helpers (`isAdmin`, `isUi`, `checkMultipleAccount`, `requireValidToken`) |63| `appsscript/{drive,doc,form}` | Reserved namespaces — currently empty, don't assume functions exist here without checking `node_modules/apps-script-utils/dist` first |64| `lang/base` | Generic guards: `isArray`, `isBoolean`, `isEmpty`, `isNil`, `isObject`, `isString`, ... — `nonX`/`requireX` pairs exist for some but not all of these yet, check `references/api-reference.md` |65| `lang/string` | `toCamelCase`, `toKebabCase`, `toSnakeCase`, `isEmail`, `isValidSlug`, `isValidVersion` + `versionCompare`, `escapeRegExp` |66| `lang/number` | `isInteger`, `toInteger`, `nonNegative` |67| `lang/array` | `chunk`, `is2DArray`, `transpose` |68| `exception/` | `Exception` base class + `NullPointerException`, `IllegalArgumentException`, `EmptyStringException`, `InvalidStringException`, `InvalidEmailFormatException`, `RuntimeException`, `RepositoryIsNotDefinedException`, `ServiceIsNotDefinedException` |69| `net/path` | `join`, `normalize`, `parse`, `isAbsolute`, `isRelative`, `isValidDomain` |70| `net/url` | `isUrl` |71| `html/` | `encodeHtml`, `decodeHtml`, `escapeHtml`, `escapeXml` |72| `json/` | `parseJson`, `stringifyJson` — safe wrappers over `JSON.parse`/`JSON.stringify` |73| `time/` | `now` |7475Load `references/api-reference.md` when you need the exact signature of a specific function rather than just knowing it exists.7677## Gotchas7879- `appsscript/drive`, `appsscript/doc`, `appsscript/form` are placeholder namespaces with no exports yet — don't guess a function name into existence for these services.80- `requireX` exceptions extend the package's own `Exception` base, not `Error` directly in every case. If used inside a bootgs `@ExceptionHandler` (see the `bootgs-validation` skill), catch `Error` (their common ancestor) or the specific exception classes — not bootgs's `AppException`/`HttpException`, which these are unrelated to.8182## Verification8384- [ ] Ran `scripts/check-latest-version.sh` before relying on a specific function's presence or signature, not just this document.85- [ ] For `appsscript/{drive,doc,form}`, confirmed the function actually exists in `node_modules/apps-script-utils/dist` rather than assuming the namespace is populated.86- [ ] Used the matching `isX`/`nonX`/`requireX` variant instead of hand-rolling an equivalent guard or a generic `if (!x) throw`.
bootgs