galbe 0.10.0 → 0.11.0

package/docs/plugins.md

@@ -1,10 +1,10 @@
 # Plugins
 
-Galbe provides a powerful plugin system that allows developers to extend and customize the behavior of the framework. The plugin capabilities are centered around the [Request Lifecycle](https://galbe.dev/documentation/lifecycle).
+Galbe provides a powerful plugin system that allows developers to extend and customize the framework’s behavior. The plugin capabilities integrate with the [Request Lifecycle](https://galbe.dev/documentation/lifecycle).
 
 ## Definition
 
-### Signature
+### Plugin Signature
 
 ```ts
 type GalbePlugin = {
@@ -17,52 +17,49 @@ type GalbePlugin = {
 }
 ```
 
-**name**
+### name
+The plugin name should be a Unique Plugin Identifier to prevent conflicts with other plugins. Ideally, it follows the format `com.example.myplugin`.
 
-The name should be a Unique Plugin Identifier. It should be chosen to be unique to avoid conflicts with other potential plugins. Ideally, it will have the form of `com.example.myplugin`.
+### init
+This method is called immediately after the server starts. It receives two arguments:
+- `config`: The plugin-specific configuration (See [Configuration](getting-started.md#properties) `plugin` property).
+- `galbe`: The Galbe server instance, from which you can retrieve routes using `galbe.router.routes`.
 
-**init**
+### onFetch
+This method is executed at the beginning of an incoming request. It receives a `context` object representing the [Request Context](context.md).
 
-This method is called right after the server starts. It takes two arguments: a `config` and a `galbe` instance. The `config` holds the configuration for the specific scope of the current plugin (See [Configuration](getting-started.md#properties) `plugin` property for more details). The `galbe` argument is the instance of the current server; you can for instance retrieve the current routes definitions with `galbe.router.routes`.
+It is **preemptable**, meaning that if a response is returned, it will be sent to the client immediately, bypassing further processing.
 
-**onFetch**
+### onRoute
+Executed after the router identifies a matching route for the request. It takes a `context` argument and is **preemptable**, meaning it can return an early response.
 
-This method is called at the beginning of an incoming request. It takes a single `context` argument representing the current request [Context](context.md).
+### beforeHandle
+Runs after request validation but before route hooks and the handler are called. Like the previous lifecycle methods, it is **preemptable**.
 
-It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
+### afterHandle
+Called after the route handler is executed but before sending the response. It receives two arguments:
+- `response`: The [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object from the handler.
+- `context`: The request [Context](context.md).
 
-**onRoute**
+It is also **preemptable**, meaning any returned response will override the original handler response.
 
-This method is called after the router has found a matching route for the current request. Its takes a single `context` argument representing the current request [Context](context.md).
+## Plugin Registration
 
-It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
-
-**beforeHandle**
-
-This method is called after the request has been validated and before the route hooks and the handler are called. It takes a single `context` argument representing the current request [Context](context.md).
-
-It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
-
-**afterHandle**
-
-This method is called after the route handler has been called and before the response is sent. Its takes two arguments: a `response` object containing the [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) returned by the handler, and a `context` argument representing the current request [Context](context.md).
-
-It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
-
-### Usage
-
-To register a plugin with your Galbe server, you must use the `use` method from you galbe instance.
+To register a plugin with your Galbe server, use the `use` method on your Galbe instance.
 
 ```js
 const galbe = new Galbe()
 galbe.use(plugin)
 ```
 
-## Create a plugin
+## How to Create a Plugin
+
+This section will walk you through the process of creating a plugin.
+Before creating a plugin, don't forget to check if there's an existing plugin that can be used. You can take a look at the official [Plugin List](https://galbe.dev/plugins).
 
 ### 1. Scaffolding
 
-The Galbe starter CLI provides a template that can be used to setup a Galbe plugin project.
+The Galbe starter CLI provides a template for setting up a plugin project:
 
 ```bash
 $ bun create galbe my-plugin --template plugin
@@ -70,45 +67,40 @@ $ cd my-plugin
 $ bun install
 ```
 
-Now you should be ready to start developing your plugin. Following section will present an example of a plugin implementation.
-
 ### 2. Implementation
 
-Here is an example of a plugin implementation that handles routes tagged with `@deprecated` metadata (See [Route files](routes.md#route-files) section about metadata).
+Below is an example of a plugin that handles routes tagged with `@deprecated` metadata (See [Route Files](routes.md#route-files) for metadata usage).
 
 deprecated.plugin.ts
-
 ```ts
-import type { GalbePlugin } from 'galbe'
+import type { GalbePlugin, Route } from 'galbe'
 import { walkMetaRoutes } from 'galbe/utils'
 
 const PLUGIN_ID = 'dev.galbe.deprecated'
 
-export default () => {
+export default (): GalbePlugin => {
   let deprecateds = new Set<string>()
+  const isRouteDeprecated = (route?: Route) => 
+    deprecateds.has(JSON.stringify({ method: route?.method, path: route?.path }))
+  
   return {
     name: PLUGIN_ID,
     // Init the plugin, check for deprecated metadata tags
     init(_config, galbe) {
-      if (galbe.meta) {
-        walkMetaRoutes(galbe.meta, (method, path, meta) => {
-          if (meta.deprecated) deprecateds.add(JSON.stringify({ method, path }))
-        })
-      }
+      walkMetaRoutes(galbe.meta || [], (method, path, meta) => {
+        if (meta.deprecated) deprecateds.add(JSON.stringify({ method, path }))
+      })
     },
     // Check if the current route is deprecated; if so, flag it as such and log it
     onRoute(context) {
       let r = context.route
-      if (!r) return
-      if (deprecateds.has(JSON.stringify({ method: r.method, path: r.path }))) {
-        console.warn(`Call to deprecated route "${r.method} ${r.path}"`)
+      if (isRouteDeprecated(r)) {
+        console.warn(`Call to deprecated route "${r?.method} ${r?.path}"`)
       }
     },
     // Add a header to the response if the route has been flagged as deprecated
     afterHandle(response, context) {
-      let r = context.route
-      if (!r) return
-      if (deprecateds.has(JSON.stringify({ method: r.method, path: r.path }))) {
+      if (isRouteDeprecated(context.route)) {
         response.headers.set('x-deprecated', 'true')
       }
     }
@@ -116,6 +108,8 @@ export default () => {
 }
 ```
 
+Register the plugin with your Galbe server:
+
 ```ts
 import { Galbe } from 'galbe'
 import deprecatedPlugin from './deprecated.plugin'
@@ -128,26 +122,25 @@ export default galbe
 
 ### 3. Publishing
 
-If you want to submit your plugin to the [official plugin list](https://galbe.dev/plugins), you should follow these steps:
-
-1. Create a **public** Github repository for your plugin. Make sure to include the following information in the README at the root of your repository:
+To submit your plugin to the [official plugin list](https://galbe.dev/plugins), follow these steps:
 
-   - A description of your plugin and what it does.
-   - How to install and configure it.
-   - How to use it.
+1. **Create a public GitHub repository** for your plugin, ensuring that the `README.md` includes:
+   - A clear description of your plugin.
+   - Installation and configuration instructions.
+   - Usage examples.
 
-2. (_Optional_) Publish your plugin to [NPM](https://npmjs.com).
+2. _(Optional)_ Publish your plugin to [NPM](https://npmjs.com).
 
-3. Create a Pull Request adding your plugin config to [plugins.json](https://github.com/pierre-cm/galbe-website/blob/main/plugins.json) file. The config should be in the following format:
+3. **Submit a Pull Request** to add your plugin configuration to [plugins.json](https://github.com/pierre-cm/galbe-website/blob/main/plugins.json) in the following format:
 
 ```json
 "plugin-id": {
   "name": "Plugin Name",
   "description": "Plugin description",
   "repo": "https://github.com/<username>/<repo-name>",
-  "npm": "https://www.npmjs.com/package/<package-name>",
+  "npm": "https://www.npmjs.com/package/<package-name>"
 }
 ```
 
 > [!IMPORTANT]
-> Please provide any relevent information about the plugin in the Pull Request description. It will be reviewed by the project maintainers as soon as possible. Be sure to check the [Glabe Contributing Guide](https://github.com/pierre-cm/galbe/blob/main/docs/CONTRIBUTING.md) before submitting any request. Same rules will apply here.
+> Provide all relevant details in the Pull Request description. It will be reviewed by project maintainers as soon as possible. Check the [Galbe Contributing Guide](https://github.com/pierre-cm/galbe/blob/main/docs/CONTRIBUTING.md) before submitting.

package/docs/router.md

@@ -1,8 +1,8 @@
 # Router
 
-Galbe router employs a hybrid approach to store and locating routes.
+Galbe router employs a hybrid approach to store and locate routes.
 
-The static routes are maintained in a Map structure. This ensure that any incoming request path matching a static route is resolved in a constant time `O(1)`.
+The static routes are maintained in a Map structure. This ensures that any incoming request path matching a static route is resolved in a constant time `O(1)`.
 
 > [!NOTE]
 > A static route is a route that doesn't contain any parameter (e.g.,`:param`) or wildcards `*`.

package/docs/routes.md

@@ -1,71 +1,64 @@
 # Routes
 
-Routes are the entry points for handling client requests in a Galbe application. In this section, we'll cover how to define routes, the various options available for route definitions, and how to use the Automatic Route Analyzer to simplify route setup.
+Routes serve as the entry points for handling client requests in a Galbe application. This section covers route definition, available configuration options, and the Automatic Route Analyzer, which simplifies route setup.
 
-## Route definition
+## Defining Routes
 
-Here is how to define routes in Galbe.
+Here's how to define routes in Galbe:
 
 ```ts
 galbe.[method](path: string, schema?: Schema, hooks?: Hooks[], handler: Handler)
 ```
 
-**method** ( get | post | put | delete | patch | options | head )
+- **method** (`get` | `post` | `put` | `delete` | `patch` | `options` | `head`)
+  - The [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for the route.
 
-The [HTTP Request Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for the defined route.
+- **path** (string)
+  - The URL path of the route, composed of segments separated by `/`. Each segment may contain alphanumeric characters and dashes but should not start or end with a dash.
+  - Special segments:
+    - `:param` → A segment starting with `:` represents a parameter.
+    - `*` → A wildcard segment matching any sequence of segments.
 
-**path** (string)
+- **schema** (Schema) _(Optional)_
+  - See the [Schemas](schemas.md) section.
 
-The path of the route. It should be composed of a sequence of segments separated by `/`. Each segment can be composed alphanumeric characters and dashes, but should not start or end with a dash.
+- **hooks** (Hook[]) _(Optional)_
+  - See the [Hooks](hooks.md) section.
 
-There are two special segments:
-
-- `:param` Any segment starting with `:` indicates a parameter segment.
-- `*` To indicate a wildcard segment. This will match any segment or sequence of segments.
-
-**schema** (Schema) _Optional_
-
-See [Schemas](schemas.md) section.
-
-**hooks** (Hook[]) _Optional_
-
-See [Hooks](hooks.md) section.
-
-**handler** (Handler)
-
-See [Handler](handler.md) section.
+- **handler** (Handler)
+  - See the [Handler](handler.md) section.
 
 ### Examples
 
-**Basic route**
+#### Basic Route
 
 ```js
-galbe.get('/foo', ctx => 'Hello World!')
+galbe.get('/foo', ctx => 'Hello, World!')
 ```
 
-**Route with Schema**
+#### Route with a Schema
 
 <!-- prettier-ignore -->
 ```js
 galbe.get(
   '/foo/:bar',
   { params: { bar: $T.string() } },
-  ctx => `Hello ${ctx.params.bar} !`
+  ctx => `Hello, ${ctx.params.bar}!`
 )
 ```
 
-**Route with Hooks**
+#### Route with Hooks
 
 <!-- prettier-ignore -->
 ```js
 galbe.get(
   '/foo/:bar',
   [() => console.log('Hook1'), () => console.log('Hook2')],
-  ctx => `Hello ${ctx.params.bar} !`
+  ctx => `Hello, ${ctx.params.bar}!`
 )
 ```
 
-**Route with Schemas and Hooks**
+#### Route with Schemas and Hooks
 
 <!-- prettier-ignore -->
 ```js
@@ -73,20 +66,43 @@ galbe.get(
   '/foo/:bar',
   { params: { bar: $T.string() } },
   [() => console.log('Hook')],
-  ctx => `Hello ${ctx.params.bar} !`
+  ctx => `Hello, ${ctx.params.bar}!`
 )
 ```
 
+## Defining Static Routes
+
+Static routes serve files from the filesystem.
+
+```ts
+galbe.static(path: string, target: string, options?: StaticEndpointOptions)
+```
+
+- **path** (string): The URL path of the route.
+
+- **target** (string): The path to the directory or file to serve.
+
+- **options** (StaticEndpointOptions) _(Optional)_:
+  - **resolve** ((path: string, target: string) => string | null | undefined | void) _(Optional)_
+    A function that resolves the path to the file to serve. The function may return a string corresponding to the new target.
+
+### Examples
+
+<!-- prettier-ignore -->
+```js
+galbe.static('/static', './public')
+```
+
 ## Automatic Route Analyzer
 
 > [!NOTE]
-> This feature is only available if you run/build the app via the [Galbe CLI](getting-started.md#galbe-cli), which is the case by default if you created your app following the [Automatic Installation](getting-started.md#automatic-installation) step or if you configured your package.json to do so.
+> This feature is only available if you run or build the app using the [Galbe CLI](getting-started.md#galbe-cli). The CLI is used by default if you followed the [Automatic Installation](getting-started.md#automatic-installation) or configured `package.json` accordingly.
 
-The Automatic Route Analyzer is responsible for analyzing all the Route Files of your project and setting up the route definitions for your Galbe server automatically. By default, the analyzer will search for Route Files matching paths like `src/**/*.route.{js,ts}`. This can be configured by modifying the value of `routes` property of your Galbe configuration. A value of `false` will disable the route analyzer.
+The Automatic Route Analyzer scans all Route Files in your project and sets up route definitions automatically. By default, it looks for files matching `src/**/*.route.{js,ts}`. This behavior can be customized via the `routes` property in your Galbe configuration. Setting it to `false` disables the analyzer.
 
 ### Route Files
 
-In order to be properly analyzed, Route Files must export a default function that takes a Galbe instance as unique argument. Your routes should be defined using that Galbe instance. Here's a basic example in JavaScript:
+To be analyzed correctly, a Route File must export a default function that accepts a Galbe instance as its only argument. Define your routes within this function. Example in JavaScript:
 
 ```ts
 export default g => {
@@ -94,16 +110,16 @@ export default g => {
 }
 ```
 
-The Automatic Route Analyzer can also collect metadata about your Route File and your routes by analyzing multiline comments. This can be used by some plugins to perform specific tasks. Here's an example of a Route File with multiline comment metadata:
+The Automatic Route Analyzer can also extract metadata from multiline comments. Some plugins utilize this metadata for specific tasks. Example:
 
 ```js
 /**
- * This is the header's head comment
- * @annotation example of header's annotation
+ * Header metadata description
+ * @annotation Example of a header annotation
  */
 export default g => {
   /**
-   * This is a route head comment
+   * Route-specific metadata
    * @deprecated
    * @operationId fooBar
    * @tags tag1 tag2
@@ -113,4 +129,5 @@ export default g => {
 ```
 
 > [!TIP]
-> You can ignore a specific route from being analyzed by adding a `//@galbe-ignore` comment before the route definition. This is useful if you want to exclude certain routes from automatic analysis or documentation generation.
+> To exclude a route from analysis, add `//@galbe-ignore` before its definition. This is useful for preventing certain routes from being included in automatic analysis or documentation generation.
+