galbe 0.10.1 → 0.11.0

package/docs/getting-started.md

@@ -1,37 +1,31 @@
-# Getting started
+# Getting Started
 
-Galbe is a Javascript web framework for building fast and versatile backend
-servers with Bun.
+Galbe is a JavaScript web framework for building fast and versatile backend servers with Bun.
 
-Designed with simplicity in mind, Galbe allows you to quickly create and set up
-a project. In addition to its ease of use, Galbe also offers a range of useful
-features that help you focus on the core logic of your application.
+Designed for simplicity, Galbe allows you to quickly create and configure a project. In addition to its ease of use, it offers various features that help you focus on your application's core logic.
 
 ## Requirements
 
-To start developing your Galbe project, you first need to install
-[Bun](https://bun.sh).
+To start developing with Galbe, you first need to install [Bun](https://bun.sh).
 
-## Automatic installation
+## Automatic Installation (Recommended)
 
-This is the recommended way of setting up a Galbe project.
+This is the recommended way to set up a Galbe project.
 
 ```bash
 $ bun create galbe app
 ```
 
-The Galbe starter CLI will request you to chose a template and a target language
-for your project. Let's select `hello` as template and `ts` as language. This
-will create a new project under `app` directory.
+The Galbe starter CLI will prompt you to choose a template and a target language. Select `hello` as the template and `typescript` as the language. This will create a new project in the `app` directory.
 
-Now you can navigate to your newly created project and install it:
+Now, navigate to your newly created project and install dependencies:
 
 ```bash
 $ cd app
-$ bun install
+$ bun i
 ```
 
-And start the dev server by running:
+Start the development server by running:
 
 ```bash
 $ bun dev
@@ -45,7 +39,7 @@ done
 🚀 Server running at http://localhost:3000
 ```
 
-Let's try to reach the hello endpoint:
+Try accessing the hello endpoint:
 
 ```bash
 $ curl localhost:3000/hello/John?age=32
@@ -53,167 +47,64 @@ Hello John! You're 32 y.o.
 ```
 
 > [!TIP]
-> If you want to have a more complete view of Galbe capabilities, feel free to
-> take a look at the `demo` template from the Galbe starter CLI.
+> To explore more of Galbe's capabilities, check out the `demo` template in the Galbe starter CLI.
 
-## Manual installation
+## Manual Installation
 
-Init a new Bun project and add Galbe as dependency:
+Initialize a new Bun project and add Galbe as a dependency:
 
 ```bash
 $ bun init
 $ bun add galbe
 ```
 
-Open `package.json` file and add the following scripts:
+Open `package.json` and add the following scripts:
 
 ```json
 {
   "scripts": {
-    "dev": "galbe dev index.ts",
+    "dev": "galbe dev index.ts -w .",
     "build": "galbe build index.ts",
     "test": "bun test"
   }
 }
 ```
 
-As you can see, those scripts rely on Galbe CLI to run and build the
-application. You will find more info about it on the [CLI](cli.md) page.
+These scripts use the Galbe CLI to run and build the application. More details are available in the [CLI](cli.md) section.
 
-This require your `index.ts` to export a default Galbe instance in order to
-work. As in the following example:
+Your `index.ts` file must export a default Galbe instance:
 
 ```ts
-import { Galbe } from "galbe";
+import { Galbe } from "galbe"
 
-const galbe = new Galbe({ port: 3000 });
-galbe.get("/hello", () => "Hello Mom!");
+const galbe = new Galbe({ port: 3000 })
+galbe.get("/hello", () => "Hello Mom!")
 
-export default galbe;
+export default galbe
 ```
 
-This is the recommended way to proceed but it is not mandatory. Galbe instances
-also provide a `listen` method that will allow you to manually start your server
-instance from the code.
+This approach is recommended but not mandatory. Galbe instances also provide a `listen` method, allowing you to manually start your server from within your code.
 
 > [!WARNING]
-> In the case you decide to not rely on Galbe CLI to run/build your app, you
-> will not have access to
-> [Automatic Route Analyzer](routes.md#automatic-route-analyzer) feature.
+> If you choose not to use the Galbe CLI for running or building your app, you will not have access to features such as the [Automatic Route Analyzer](routes.md#automatic-route-analyzer).
 
-## Configuration
+## Project Structure
 
-To configure your Galbe server, you should pass your configuration to the Galbe
-constructor when you instanciate it.
+Galbe is highly flexible in terms of project structure. The [Automatic Route Analyzer](routes.md#automatic-route-analyzer), triggered by the `routes` configuration option (default: `src/**/*.route.{js,ts}`), enables versatile project organization.
 
-```ts
-const galbe = new Galbe(configuration);
-```
-
-### Properties
-
-**hostname**
-
-The hostname of the server. Default is `localhost`.
-
-**port**
-
-The port number that the server will be listening on. Default is `3000`.
-
-**basePath**
-
-The base path is added as a prefix to all the routes created.
-
-**routes**
-
-A Glob Pattern or a list of Glob patterns defining the route files to be
-analyzed by the [Automatic Route Analyzer](routes.md#automatic-route-analyzer).
-Default is `src/**/*.route.{js,ts}`.
-
-**plugin**
-
-A property that can be used by plugins to add plugin's specific configuration.
-Every key should correspond to a [Unique Plugin Identifier](plugins.md).
-
-**tls**
-
-Enable or disable TLS support. Default value is `false`.
-
-- **tls.key**: The path to the private key file
-
-- **tls.cert**: The path to the certificate file
-
-- **tls.ca**: The path to the certificate authority file
-
-**requestValidator.enabled**
-
-Enable or disable the _request_ schema validation (See
-[Request Schema definition](schemas.md#request-schema-definition)). Default
-value is `true`.
-
-**responseValidator.enabled**
-
-Enable or disable the _response_ schema validation (See
-[Request Schema definition](schemas.md#request-schema-definition)). Default
-value is `true`.
-
-### Examples
-
-A common way to handle server configuration is to create new file
-`galbe.config.(js|ts|json)` at the root of your project directory and import it
-in your code. Here is an example:
-
-galbe.config.js
-
-```js
-export default {
-  port: Bun.env.GALBE_PORT
-  routes: 'src/**/*.route.ts',
-}
-```
-
-index.js
-
-```js
-import { Galbe } from "galbe";
-import config from "./galbe.config";
-
-export default new Galbe(config);
-```
-
-> [!TIP]
-> If you are using Typescript, you can import `GalbeConfig` type from galbe
-> package to ensure type consistency for your configuration. Here is an example:
->
-> ```ts
-> import type { GalbeConfig } from "galbe";
-> const config: GalbeConfig = {
->   port: Number(Bun.env.GALBE_PORT),
->   routes: "routes/*.route.ts",
-> };
-> export default config;
-> ```
-
-## Project structure
-
-One key aspect of Galbe, is its versatility in terms of project structure. This
-is partly allowed by the
-[Automatic Route Analyzer](routes.md#automatic-route-analyzer) and the `routes`
-config property which defaults to `src/**/*.route.{js,ts}`.
-
-Here are two examples of valid project structures by default:
+Here are two examples of valid project structures:
 
 **Example 1**
 
 ```txt
 ┌── src
 │   ├── hooks
-│   │   └── log.hook.ts
+│   │   └── log.hook.ts
 │   ├── routes
-│   │   ├── foo.route.ts
-│   │   └── foo.route.ts
+│   │   ├── foo.route.ts
+│   │   └── bar.route.ts
 │   └── schemas
-│       ├── bar.schema.ts
+│       ├── foo.schema.ts
 │       └── bar.schema.ts
 ├── galbe.config.ts
 ├── index.ts
@@ -227,10 +118,10 @@ Here are two examples of valid project structures by default:
 ```txt
 ┌── src
 │   ├── hooks
-│   │   └── log.hook.ts
+│   │   └── log.hook.ts
 │   ├── foo
-│   │   ├── foo.route.ts
-│   │   └── foo.schema.ts
+│   │   ├── foo.route.ts
+│   │   └── foo.schema.ts
 │   └── bar
 │       ├── bar.route.ts
 │       └── bar.schema.ts
@@ -241,26 +132,18 @@ Here are two examples of valid project structures by default:
 └── tsconfig.json
 ```
 
-In both cases, the
-[Automatic Route Analyzer](routes.md#automatic-route-analyzer) will analyze
-`foo.route.ts` and `bar.route.ts` Route Files to find route definitions.
+In both cases, the [Automatic Route Analyzer](routes.md#automatic-route-analyzer) will detect `foo.route.ts` and `bar.route.ts` to set up route definitions.
 
-You can find more info about Route Files definition in the
-[Routes Files](routes.md#route-files) section.
+For more details, see the [Route Files](routes.md#route-files) section.
 
 > [!NOTE]
-> The examples provided above will work with the default configuration, but you
-> can easily customize the routes property to fit your own project structure.
-> Simply redefine the `routes` property with your own pattern(s) to to fit your
-> own project structure.
+> These examples work with the default configuration, but you can customize the `routes` property to fit your project structure. Define `routes` with your preferred pattern(s) to match your file organization.
 
-## How to debug
+## Debugging
 
-The easiest way to debug your app is by installing the
-[VSCode Bun extension](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode).
+The easiest way to debug your application is by using the [VSCode Bun extension](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode).
 
-You can then create a `.vscode/launch.json` config file in your project root
-directory. Here is an example of configuration:
+Create a `.vscode/launch.json` configuration file in your project root with the following content:
 
 ```json
 {

package/docs/handler.md

@@ -2,17 +2,17 @@
 
 A handler is a function that gets executed when a request matches the route definition. It is responsible for processing the request and sending a response.
 
-## Handler declaration
+## Handler Declaration
 
-The handler should be declared as last argument of the [Route Definition](routes.md#route-defintion) method.
+The handler should be declared as the last argument of the [Route Definition](routes.md#route-definition) method.
 
 ```js
 galbe.get('foo', schema, [hook1, hook2], ctx => {})
 ```
 
-Handler are called after the last hook call, or right after the request parsing if no hook is declared. To get a better understanding of the request lifecycle, you can refer to the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
+Handlers are called after the last hook call, or right after the request parsing if no hook is declared. To get a better understanding of the request lifecycle, you can refer to the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
 
-## Handler definition
+## Handler Definition
 
 ```js
 const handler = ctx => {
@@ -21,29 +21,29 @@ const handler = ctx => {
 }
 ```
 
-The handler function takes a `context` object as single argument and might return a `response`.
+The handler function takes a `context` object as its single argument and might return a `response`.
 
-**context**
+### Context
 
-The `context` object contains the request information as well as a `set` object that serves as a response modifier. You can find more detailed informations about the `context` object in the [Context](context.md) section.
+The `context` object contains the request information as well as a `set` object that serves as a response modifier. You can find more detailed information about the `context` object in the [Context](context.md) section.
 
-**response**
+### Response
 
 To send a response, your handler can return an object. The response sent will depend on the type of the object returned. There are four types of responses that can be returned by a handler method. More about that in the next section.
 
-## Response types
+## Response Types
 
 > [!NOTE]
-> This section only cover response body payloads, to return specific response headers and/or status, you should define them with the `context.set` object before the return statement. More about it in the [Context](context.md) section.
+> This section only covers response body payloads. To return specific response headers and/or status, you should define them with the `context.set` object before the return statement. More about it in the [Context](context.md) section.
 
 ### String
 
-Case where `string` is returned by the handler.
+Case where a `string` is returned by the handler.
 
 - status: 200
-- content-type: `text-plain`
+- content-type: `text/plain`
 
-**Example**
+#### Example
 
 ```js
 galbe.get('/example', ctx => {
@@ -58,29 +58,29 @@ Case where an `object` is returned by the handler.
 - status: 200
 - content-type: `application/json`
 
-**Example**
+#### Example
 
 ```js
 galbe.get('/example', ctx => {
-  return 'Hello Mom!'
+  return { message: 'Hello Mom!' }
 })
 ```
 
-### Response instance
+### Response Instance
 
 Case where a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance is returned by the handler.
 
-In that case, `context.set` properties are not taken into account to contruct the response.
+In this case, `context.set` properties are not taken into account to construct the response.
 
-**Example**
+#### Example
 
 <!-- prettier-ignore -->
 ```js
 galbe.get('/example', ctx => {
   return new Response(
     'Hello Mom',
-    { status: 200, headers: { 'content-type': 'text/plain' } 
-  })
+    { status: 200, headers: { 'content-type': 'text/plain' } }
+  )
 })
 ```
 
@@ -91,7 +91,7 @@ Case where a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript
 - status: 200
 - content-type: `text/event-stream`
 
-**Example**
+#### Example
 
 ```js
 async function* generator(array) {
@@ -103,3 +103,17 @@ async function* generator(array) {
 
 galbe.get('/example', ctx => generator(['one', 'two', 'three']))
 ```
+
+## Throwing Errors
+
+Throwing a `RequestError` at any point in the handler execution will result in a response with the specified status and payload.
+
+#### Example
+
+```ts
+g.get("/test", () => {
+  throw new RequestError({ status: 418, payload: '🫖' })
+})
+```
+
+Any other kind of error will result in a `500` response with the error message `"Internal Server Error"` by default. You can always customize it by defining a custom [Error Handler](error-handler.md).

package/docs/hooks.md

@@ -1,45 +1,45 @@
 # Hooks
 
-Hooks provide a simple way to perform specific actions before and/or after reaching a specific route endpoint.
+Hooks provide a simple way to execute specific actions before and/or after reaching a route endpoint in Galbe.
 
-## Hook definition
+## Defining Hooks
 
 ```ts
-const hook = (context, next) => {
+const hook = async (context, next) => {
   context.state['foo'] = 'bar'
   await next()
   console.log('Hook end')
 }
 ```
 
-The hook takes only two arguments, a `context` object and a `next` function.
+A hook takes two arguments: `context` and `next`.
 
-**context**
+### context
 
-The `context` object contains the request information along with a state property that is modifiable and preserved across all hooks and the handler. It is useful for sharing information or objects across hooks and handler. You can find more information about it in the [Context](context.md) section.
+The `context` object contains request information and a modifiable `state` property that persists across all hooks and the handler. This is useful for sharing data across hooks and handlers. More details are available in the [Context](context.md) section.
 
-**next**
+### next
 
-The `next` function calls the next hook in the hook list or the handler if the current hook is the last one declared. The `next` function should be called at most once. If it is omitted, Galbe will call it automatically at the end of the execution of the current hook.
+The `next` function calls the next hook in the list, or the handler if the current hook is the last one. The `next` function should be called at most once. If omitted, Galbe will automatically call it at the end of the current hook’s execution.
 
 > [!TIP]
-> Hooks are interruptible objects, meaning they can return a response at any moment. This provides a powerful mechanism for implementing custom logic, such as authentication, authorization, caching, and more.
+> Hooks are interruptible, meaning they can return a response at any time. This is useful for implementing custom logic such as authentication, authorization, and caching.
 >
-> To learn more about response types, ou can take a look at the [Response types](handler.md#response-types) section.
+> For more details on response handling, see [Response Types](handler.md#response-types).
 
-## Hooks declaration
+## Declaring Hooks
 
-Hooks should be declared just before the handler method in the [Route Definition](routes.md#route-defintion) method as a list of Hooks.
+Hooks should be declared before the handler method in the [Route Definition](routes.md#route-definition) as a list of hook functions.
 
 ```ts
-galbe.get('foo', [ hook1, hook2, ... ], ctx => {})
+galbe.get('/foo', [hook1, hook2, ...], ctx => {})
 ```
 
-Hooks are called just before the [Handler](handler.md) in the order that they have been declared in the hook list of the [Route Definition](routes.md#route-defintion). To get a better understanding of hooks execution during the request lifecycle, you can refer to the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
+Hooks execute in the order they are declared, just before the [Handler](handler.md). For a deeper understanding of their execution in the request lifecycle, see the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
 
 ### Examples
 
-Linear hooks declaration:
+#### Linear Hook Execution
 
 ```ts
 const hook1 = context => {
@@ -61,7 +61,7 @@ hook2
 handler
 ```
 
-Nested hooks declaration:
+#### Nested Hook Execution
 
 ```ts
 const hook1 = async (context, next) => {