+ 
+ 
+ 
+ 
+ 
More ...
- -#### Why is this needed? - -Google Apps Script has simple `doGet` and `doPost` functions for handling web requests, but they're quite basic. To -build a -more complex application with multiple API endpoints, you'd have to write a lot of manual routing logic. This can -quickly become clunky and difficult to manage. +### 2. Initialize the Application -**Boot.gs** solves this problem by providing decorators (`@RestController`, `@Get`) and automated routing. This -allows -you to structure your code in a way that is common in modern web frameworks like Express.js or NestJS. - -The result is code that is more organized, readable, and scalable. +Bootstrap your application by creating an `App` instance and delegating the standard Apps Script entry points (`doGet`, +`doPost`) to it. ```TypeScript -import {App, Newable, Get, RestController} from "boot"; +import {App} from "bootgs"; +import {SheetController} from "./SheetController"; /** - * This JSDoc comment describes the `doGet` function. - * It's the standard handler for GET requests in Google Apps Script. - * - * @param event The GET request event object, containing request information. - * @returns The result of the request processing, usually HTML content or JSON. + * Global entry point for GET requests. */ -// The `doGet` function is a mandatory entry point for web app GET requests. export function doGet(event: GoogleAppsScript.Events.DoGet) { - // Defines an array of controllers that the application will use. - // In this case, only the `Sheet` class is used. - const controllers: Newable[] = [Sheet]; - - // Defines an array of providers (services) that will be available for injection. - // There are no providers in this example. - const providers: Newable[] = []; - - // Creates an application instance, passing it the list of controllers and providers. - const app = App.create({ - controllers, - providers - }); - - // Delegates the processing of the GET request to the created application instance. - return app.doGet(event); + const app = App.create({ + controllers: [SheetController] + }); + return app.doGet(event); } /** - * This JSDoc comment describes the `doPost` function. - * It's the standard handler for POST requests in Google Apps Script. - * - * @param event The POST request event object. - * @returns The result of the request processing. + * Global entry point for POST requests. */ -// The `doPost` function is the entry point for web app POST requests. export function doPost(event: GoogleAppsScript.Events.DoPost) { - // Defines controllers for POST requests (same logic as for `doGet`). - const controllers: Newable[] = [Sheet]; - - // Defines providers (none here). - const providers: Newable[] = []; - - // Creates an application instance. - const app = App.create({ - controllers, - providers - }); - - // Delegates the processing of the POST request to the application. - return app.doPost(event); -} - -/** - * This JSDoc comment describes the `Sheet` class. - * It acts as a REST controller for handling API requests. - */ -// The `@RestController` decorator declares this class as a controller and sets the base path to "api/sheet". -@RestController("api/sheet") -export class Sheet { - /** - * This JSDoc comment describes the `getActiveRange` method. - * It is a handler for a GET request. - */ - // The `@Get` decorator marks this method as a GET request handler and sets the endpoint path to "active-range". - // The full path to this endpoint will be "api/sheet/active-range". - @Get("active-range") - // The method signature: it takes no arguments and returns a string. - getActiveRange(): string { - // The return value of the method. - return "This action return active range."; - } + const app = App.create({ + controllers: [SheetController] + }); + return app.doPost(event); } ``` -#### How does it work? - -The process is built on two key parts: +## Features -1. Entry Points (`doGet` and `doPost`): These are the only functions that Google Apps Script calls when it receives a - web - request. Instead of processing requests directly, they act as a "gateway." They initialize the application ( - `App.create`) - with its controllers and then delegate all further processing to the framework's core handler. - -2. Controllers (`@RestController`): The Sheet class is your controller. The `@RestController("api/sheet")` decorator - tells - the - framework that this class will handle all requests starting with the `/api/sheet` path. The methods within this - class ( - `getActiveRange`) become your endpoints. The `@Get("active-range")` decorator specifies that the method should handle - GET - requests to the `/api/sheet/active-range` path. - -So, when a GET request comes in for `https://script.google.com/macros/s/.../exec?path=/api/sheet/active-range`, Apps -Script -calls `doGet`, which then passes the request to the framework. The framework parses the URL, finds the matching -controller (`Sheet`) and method (`getActiveRange`), executes it, and returns the result as an HTTP response. - -This approach completely separates your request handling logic from the low-level details of Apps Script, making your -code **clean**, **modular**, and **maintainable**. - -Class decorators
-| Decorator | Description | -| --------------------- | ------------------------------------------------------------- | -| `@Controller()` | Marks a class as a general-purpose controller. | -| `@Service()` | Marks a class as a service, typically holding business logic. | -| `@Repository()` | Marks a class as a repository, abstracting data access logic. | -| `@Injectable()` | Marks a class as available for dependency injection. | -| `@HttpController()` | Marks a class as an HTTP request controller. | -| `@RestController()` | Alias for `@HttpController()`. | -| `@DocController()` | Marks a class as a Google Docs event controller. | -| `@DocsController()` | Alias for `@DocController()`. | -| `@FormController()` | Marks a class as a Google Forms event controller. | -| `@FormsController()` | Alias for `@FormController()`. | -| `@SheetController()` | Marks a class as a Google Sheets event controller. | -| `@SheetsController()` | Alias for `@SheetController()`. | -| `@SlideController()` | Marks a class as a Google Slides event controller. | -| `@SlidesController()` | Alias for `@SlideController()`. | +| 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
-| Decorator | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `@Install()` | Handles [`onInstall`](https://developers.google.com/apps-script/guides/triggers#oninstalle) event, triggered when the add-on is first installed. | -| `@Open()` | Handles [`onOpen`](https://developers.google.com/apps-script/guides/triggers#onopene) event, triggered when a Google Sheet is opened. | -| `@Edit()` | Handles [`onEdit`](https://developers.google.com/apps-script/guides/triggers#onedite) event, triggered by manual cell changes in a Google Sheet. | -| `@Change()` | Handles `onChange` event, triggered by any structural or content change in a Google Sheet. | -| `@SelectionChange()` | Handles [`onSelectionChange`](https://developers.google.com/apps-script/guides/triggers#onselectionchangee) event, triggered by user cell selection changes. | -| `@FormSubmit()` | Handles `onFormSubmit` event, triggered when a form connected to a Google Sheet is submitted. | -| `@Post()` | Maps a method to handle HTTP POST requests. | -| `@Get()` | Maps a method to handle HTTP GET requests. | -| `@Delete()` | Maps a method to handle HTTP DELETE requests. | -| `@Put()` | Maps a method to handle HTTP PUT requests. | -| `@Patch()` | Maps a method to handle HTTP PATCH requests. | -| `@Options()` | Maps a method to handle HTTP OPTIONS requests. | -| `@Head()` | Maps a method to handle HTTP HEAD requests. | -| `@PostMapping()` | Alias for `@Post()`. | -| `@GetMapping()` | Alias for `@Get()`. | -| `@DeleteMapping()` | Alias for `@Delete()`. | -| `@PutMapping()` | Alias for `@Put()`. | -| `@PatchMapping()` | Alias for `@Patch()`. | -| `@OptionsMapping()` | Alias for `@Options()`. | -| `@HeadMapping()` | Alias for `@Head()`. | +| 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
-| Decorator | Description | -| ----------------- | ---------------------------------------------------------- | -| `@Event()` | Injects the full Google Apps Script event object. | -| `@Request()` | Injects the full request object or a specific key from it. | -| `@Headers()` | Injects request headers or a specific header value. | -| `@Param()` | Injects values from URL path parameters. | -| `@PathVariable()` | Alias for `@Param()`. | -| `@Query()` | Injects values from URL query parameters. | -| `@RequestParam()` | Alias for `@Query()`. | -| `@Body()` | Injects the full request body or a specific key from it. | -| `@RequestBody()` | Alias for `@Body()`. | -| `@Inject()` | Explicitly specifies an injection token for a dependency. | +| 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(). |
+
More
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct, +and the process for submitting pull requests. -- [ ] Develop a `Cron` decorator for methods. -- [ ] Develop a `Response` decorator for parameters. +## Roadmap -+ ⭐ Like this project? Give it a star on GitHub! +
diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..cb66ae1 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,49 @@ +# Roadmap + +This document outlines the **proposed** vision and development direction for **Boot.gs**. + +> [!IMPORTANT] +> This roadmap is provided for informational purposes only. It does not represent a binding commitment. +> Priorities, features, and timelines are subject to change without notice based on community feedback, +> available resources, and the evolution of the Google Apps Script platform. + +## Phase 1: Foundation (Current) + +Focus on establishing core stability and essential developer experience. + +- [x] Core Dependency Injection (DI) system. +- [x] Basic HTTP and Trigger decorators. +- [x] Initial documentation and examples. +- [x] Automated testing and CI/CD setup. + +## Phase 2: Enhanced Features (Planned) + +Potential framework expansions to handle more complex scenarios. + +- [ ] **Middleware Support**: Research and implementation of request/event interception. +- [ ] **Validation Decorators**: Exploration of built-in validation support. +- [ ] **Advanced DI**: Further improvements to the injection system. + +## Phase 3: Ecosystem & Tooling (Future Exploration) + +Aims to simplify the Boot.gs development lifecycle. + +- [ ] **CLI Tool**: Potential scaffolding for new projects. +- [ ] **Project Templates**: Pre-configured templates for common Apps Script use cases. +- [ ] **Documentation Improvements**: Enhanced guides and API references. +- [ ] **Testing Utilities**: Mocks and helpers for testing Apps Script specific code. + +## Phase 4: Integration & Optimization (Long-term Vision) + +Refinement and integration with wider Google services. + +- [ ] **Service Integrations**: Easier interaction with common Google APIs. +- [ ] **Performance Analysis**: Tools to measure and optimize execution time. +- [ ] **State Management**: Support for external databases and caching. + +--- + +## Feedback + +We value your input! Suggestions and ideas are welcome via [GitHub Issues](https://github.com/bootgs/boot/issues). +Items marked as "Planned" or "Future Exploration" are not guaranteed to be implemented. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b27f6fc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,77 @@ +# Security Policy + +This document outlines how to report vulnerabilities in **Boot.gs**. We appreciate the efforts of security researchers +to help us keep the framework secure. + +## Supported Versions + +We aim to provide security updates for the following versions of **Boot.gs** on a best-effort basis: + +| Version | +Supported | +
|---|---|
>= 1.0.0 |
+ :white_check_mark: | +
< 1.0.0 |
+ :x: | +