Artist: Daryna Mikhailenko

Boot Framework for Google Apps Script™

Introduction

Boot.gs is a lightweight framework designed to help build structured Google Apps Script applications. It aims to bring familiar development patterns, such as decorators and dependency injection, to the Apps Script environment to aid in code organization.

Installation

Install the framework via npm:

npm install bootgs

Quick Start

1. Define a Controller

Create a class to handle your application's logic. Decorators make it easy to map methods to specific endpoints or events.

import {Get, RestController} from "bootgs";

@RestController("api/sheet")
export class SheetController {
    /**
     * Handles GET requests to /api/sheet/active-range
     */
    @Get("active-range")
    getActiveRange(): string {
        return "This action returns the active sheet range.";
    }
}

2. Initialize the Application

Bootstrap your application by creating an App instance and delegating the standard Apps Script entry points (doGet, doPost) to it.

import {App} from "bootgs";
import {SheetController} from "./SheetController";

/**
 * Global entry point for GET requests.
 */
export function doGet(event: GoogleAppsScript.Events.DoGet) {
    const app = App.create({
        controllers: [SheetController]
    });
    return app.doGet(event);
}

/**
 * Global entry point for POST requests.
 */
export function doPost(event: GoogleAppsScript.Events.DoPost) {
    const app = App.create({
        controllers: [SheetController]
    });
    return app.doPost(event);
}

Features

• Decorator-based Routing: Intuitive mapping of HTTP and Apps Script events.
• Dependency Injection: Decouple your components for better testability.
• Type Safety: Built with TypeScript for a robust development experience.
• Modern Architecture: Inspired by frameworks like NestJS and Spring Boot.

Decorators

Class decorators

Class decorators

Decorator	Returns	Description
@Controller(type?: string, options?: object)	ClassDecorator	Marks a class as a general-purpose controller.
@HttpController(basePath?: string)	ClassDecorator	Marks a class as an HTTP request controller. Default base path is /.
@SheetController(sheetName?: string | string[] | RegExp)	ClassDecorator	Marks a class as a Google Sheets event controller. Can be filtered by sheet name (string, array, or RegExp).
@DocController()	ClassDecorator	Marks a class as a Google Docs event controller.
@SlideController()	ClassDecorator	Marks a class as a Google Slides event controller.
@FormController()	ClassDecorator	Marks a class as a Google Forms event controller.
@Service()	ClassDecorator	Marks a class as a service, typically holding business logic.
@Repository()	ClassDecorator	Marks a class as a repository, abstracting data access logic.
@Injectable()	ClassDecorator	Marks a class as available for dependency injection.
Aliases
@RestController(basePath?: string)	ClassDecorator	Alias for @HttpController().
@SheetsController(sheetName?: string | string[] | RegExp)	ClassDecorator	Alias for @SheetController().
@DocsController()	ClassDecorator	Alias for @DocController().
@SlidesController()	ClassDecorator	Alias for @SlideController().
@FormsController()	ClassDecorator	Alias for @FormController().

Method decorators

Method decorators

Decorator	Returns	Description
@Install()	MethodDecorator	Handles onInstall event.
@Open()	MethodDecorator	Handles onOpen event.
@Edit(...range?: (string | RegExp | string[])[])	MethodDecorator	Handles onEdit event. Filter by A1-notation, sheet name, or RegExp.
@Change(changeType?: SheetsOnChangeChangeType | SheetsOnChangeChangeType[])	MethodDecorator	Handles onChange event. Filter by SheetsOnChangeChangeType.
@SelectionChange()	MethodDecorator	Handles onSelectionChange event.
@FormSubmit(...formId?: (string | string[])[])	MethodDecorator	Handles onFormSubmit event. Filter by one or more form IDs.
HTTP Methods
@Get(path?: string)	MethodDecorator	Maps a method to handle HTTP GET requests. Default path is /.
@Post(path?: string)	MethodDecorator	Maps a method to handle HTTP POST requests.
@Put(path?: string)	MethodDecorator	Maps a method to handle HTTP PUT requests.
@Patch(path?: string)	MethodDecorator	Maps a method to handle HTTP PATCH requests.
@Delete(path?: string)	MethodDecorator	Maps a method to handle HTTP DELETE requests.
@Head(path?: string)	MethodDecorator	Maps a method to handle HTTP HEAD requests.
@Options(path?: string)	MethodDecorator	Maps a method to handle HTTP OPTIONS requests.
Aliases
@GetMapping(path?: string)	MethodDecorator	Alias for @Get().
@PostMapping(path?: string)	MethodDecorator	Alias for @Post().
@PutMapping(path?: string)	MethodDecorator	Alias for @Put().
@PatchMapping(path?: string)	MethodDecorator	Alias for @Patch().
@DeleteMapping(path?: string)	MethodDecorator	Alias for @Delete().
@HeadMapping(path?: string)	MethodDecorator	Alias for @Head().
@OptionsMapping(path?: string)	MethodDecorator	Alias for @Options().

Parameter decorators

Parameter decorators

Decorator	Returns	Description
@Event()	ParameterDecorator	Injects the full Google Apps Script event object.
@Request(key?: string)	ParameterDecorator	Injects the full request object or a specific property.
@Headers(key?: string)	ParameterDecorator	Injects request headers or a specific header value.
@Body(key?: string)	ParameterDecorator	Injects the full request body or a specific key.
@Param(key?: string)	ParameterDecorator	Injects values from URL path parameters.
@Query(key?: string)	ParameterDecorator	Injects values from URL query parameters.
@Inject(token: any)	ParameterDecorator	Explicitly specifies an injection token for a dependency.
Aliases
@RequestBody(key?: string)	ParameterDecorator	Alias for @Body().
@PathVariable(key?: string)	ParameterDecorator	Alias for @Param().
@RequestParam(key?: string)	ParameterDecorator	Alias for @Query().

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on our code of conduct, and the process for submitting pull requests.

Roadmap

Check out our Roadmap to see what we have planned for future releases.

Changelog

For a detailed list of changes and updates, please refer to the CHANGELOG.

License

This project is licensed under the Apache-2.0 License.

---

⭐ Like this project? Give it a star on GitHub!