galbe 0.1.7 → 0.1.13

package/.github/workflows/deploy_website.yml

@@ -16,5 +16,5 @@ jobs:
           -H "Accept: application/vnd.github+json" \
           -H "Authorization: Bearer ${{ secrets.GH_WEBSITE_TOKEN }}" \
           -H "X-GitHub-Api-Version: 2022-11-28" \
-          https://api.github.com/repos/pierre-cm/galbe-website/actions/workflows/ci.yml/dispatches \
+          https://api.github.com/repos/pierre-cm/galbe-website/actions/workflows/deploy.yml/dispatches \
           -d '{"ref":"main"}'

package/.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
           git config user.name "${GITHUB_ACTOR}"
       - name: Install dependencies & build
         run: |
-          bun install & bun run build
+          bun install && bun run build
       - name: Release
         run: |
           npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN

package/README.md

@@ -12,7 +12,9 @@ Galbe is a fast, lightweight and highly customizable JavaScript web framework ba
 ## Getting started
 
 ```bash
-bun create galbe
+bun create galbe app
+cd app
+bun install && bun dev
 ```
 
 ## Documentation

package/docs/context.md

@@ -0,0 +1,114 @@
+# Context
+
+An instance of the context object is created when a new request is initiated and carrieds out along durring all the request lifecycle.
+See the [Lifecycle](lifecycle) section to get more details.
+
+Its purpose is to carrie all the relevent information about the request and to allow sharing informations between each step of the request lifecycle.
+
+## Definition
+
+A context has the following properties:
+
+**request**
+
+An instance of the [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object created by th server.
+
+**headers**
+
+A javascript object representing the `headers` of the current request.
+
+- key (string): header name
+- value: (string | [schema defined](schemas.md#headers)): header value
+
+```js
+{
+    "accept": "*/*",
+    "accept-encoding": "gzip, deflate, br",
+    "cookie": "Cookie_1=value; Cookie_2=value",
+    "host": "localhost:3000",
+    "user-agent": "galbe/1.0.0"
+}
+```
+
+**params**
+
+A javascript object representing the request `parameters` of the current request.
+
+- key (string): parameter name
+- value: (string | [schema defined](schemas.md#params)): parameter value
+
+```js
+galbe.get('/default/:p1/foo/:p2', ctx => console.log(ctx.params))
+// GET /default/four/foo/2
+{ p1: "four", p2: "2" }
+```
+
+**query**
+
+A javascript object representing the request `query parameters` of the current request.
+
+- key (string): query parameter name
+- value: (string | [schema defined](schemas.md#query)): query parameter value
+
+```js
+galbe.get('/test', ctx => console.log(ctx.params))
+// GET /test?one=1&two=2
+{ one: "1", two: "2" }
+```
+
+**body**
+
+The body payload of the incoming request. The body type is computed according to the following rules.
+
+If no [Schema](schemas.md) is defined, Galbe will parse the body type according to `content-type` Header value:
+
+- `text/.*`: string
+- `application/json`: object
+- `application/x-www-form-urlencoded`: { [key: string]: any }
+- `multipart/form-data`: { [key: string]:
+  { headers: { name: string; type?: string; filename?: string };
+  content: any
+  } }
+- `other`: AsyncGenerator\<Uint8Array\>
+
+If a [Schema](schemas.md) is defined, Galbe will parse the body type according to the [Schema.body](schemas.md#body) defined for the current route.
+
+**set**
+
+The set property contains modifiable properties which purpose are to give informations to the Response parser.
+
+- `status`: Set the response status
+- `headers`: Set the response headers
+
+```js
+galbe.get('/example', ctx => {
+  ctx.set.status = 418
+  return "I don't do coffee"
+})
+```
+
+**state**
+
+The state property purpose is to carry custom user object accross request lifecycle. In general it is used to share informations between the [hooks](hooks.md) and the [handler](handler.md).
+
+- key (string): user defined key
+- value (any): user defined object
+
+```js
+galbe.get(
+  '/example',
+  [
+    ctx => {
+      ctx.state['foo'] = 'bar'
+    }
+  ],
+  ctx => {
+    return ctx.state.foo
+  }
+)
+```
+
+```bash
+$ curl http://localhost:3000/example
+bar
+```

package/docs/error-handler.md

@@ -0,0 +1,54 @@
+# Error handler
+
+Any error happening during a request lifecycle will be intercepted by the error handler.
+
+You can customize the default error handling behavior by defining a custom error handler using Galbe's intance `onError` method.
+
+```js
+const galbe = new Galbe()
+galbe.onError(customErrorHandler)
+```
+
+## Definition
+
+The error handler should be a function that takes two aguments: an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) and a [Context](context.md). This function may potentially return a [Response type](handler.md#response-types).
+
+```js
+galbe.onErrorHandler((error, ctx) => {
+  if (error.status === 500) {
+    return new Response(`Server error ❌`, { status: 500 })
+  }
+  if (error.status === 404) {
+    return new Response(`Not found 🔎`, { status: 404 })
+  }
+})
+```
+
+The `error` argument could be any type of error thrown by your application. If the error originates from Galbe framework, it will be an instance of [RequestError](#request-error).
+
+For instance, the [Router](router.md) will throw a `RequestError` with a `404` status if no route matches the incoming request path. Similarly, the Parser will throw a `RequestError` with a `400` status.
+
+## Request Error
+
+The `RequestError` class is utilized to instanciate a runtime request error in Galbe. It has two optional attributes: a `status` and a `payload`.
+
+If your application throws a `RequestError` instance, Galbe will, by default, construct a Response from your `RequestError` and send it back to the client.
+
+```js
+import { Galbe, RequestError } from 'galbe'
+
+const galbe = new Galbe()
+
+galbe.get('/coffee', () => throw new RequestError({ status: 418, payload: '🫖' }))
+```
+
+When called, above endpoint should respond:
+
+```bash
+$ curl -i http://localhost:3000/coffee
+HTTP/1.1 418 I'm a Teapot
+Content-Type: application/json
+Content-Length: 6
+
+"🫖"
+```

package/docs/getting-started.md

@@ -1,21 +1,21 @@
 # Getting started
 
-Galbe is a Javascript web framework to build fast and versatile backend servers with Bun.
+Galbe is a Javascript web framework for building fast and versatile backend servers with Bun.
 
-It was designed with simplicity in mind, allowing you to quickly create and setup a project. In addition, Galbe also offers usefull features, allowing you to focus on your application logic rather than the rest.
+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.
 
 ## Requirements
 
 To start developing your Galbe project, you first need to install [Bun](https://bun.sh).
 
-## Automatic Installation
+## Automatic installation
 
 This is the recommended way of setting up a Galbe project.
 
 ```bash
-bun create galbe app
-cd app
-bun install
+$ bun create galbe app
+$ cd app
+$ bun install
 ```
 
 This will create a new project under `app` directory and install it.
@@ -23,12 +23,12 @@ This will create a new project under `app` directory and install it.
 Now you can start the dev server by running:
 
 ```bash
-bun dev
+$ bun dev
 ```
 
-This will start a web server on `loclahost:3000`.
+This will start a web server on `localhost:3000`.
 
-To verify that the project was setup correctly and is running, try to reach `loclahost:3000/hello` endpoint, this should return following greeting message:
+To verify that the project was setup correctly and is running, try to reach `localhost:3000/hello` endpoint, this should return following greeting message:
 
 ```bash
 $ curl localhost:3000/hello
@@ -38,13 +38,13 @@ Hello from Galbe!
 > [!TIP]  
 > By default, the dev server automatically reloads on every file change.
 
-## Manual Installation
+## Manual installation
 
 Init a new Bun project and add Galbe as dependency:
 
 ```bash
-bun init
-bun add galbe
+$ bun init
+$ bun add galbe
 ```
 
 Open `package.json` file and add the following scripts:
@@ -74,18 +74,18 @@ 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.
 
-> [!WARNING]  
+> [!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.
 
 ### Galbe CLI
 
 ```bash
-galbe <command> <argument> [options]
+$ galbe <command> <argument> [options]
 ```
 
 Here are the available commands:
 
-#### dev
+**dev**
 
 Start a dev server running your Galbe application.
 
@@ -98,7 +98,7 @@ _options_
 - `--port` or `-p`: port number (default: 3000)
 - `--watch` or `-w`: watch file changes (default: true)
 
-#### build
+**build**
 
 Bundle your Galbe application.
 
@@ -121,25 +121,25 @@ const galbe = new Galbe(configuration)
 
 ### Properties
 
-#### port
+**port**
 
 The port number that the server will be listening on. Default is `3000`.
 
-#### basePath
+**basePath**
 
 The base path is added as a prefix to all the routes created.
 
-#### routes
+**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
+**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).
 
 ### Examples
 
-An common way to handle server configuration is to create new file a `galbe.config.(js|ts|json)` at the root of your project directory and import it in your code. Here is an example:
+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
 
@@ -171,7 +171,7 @@ export default new Galbe(config)
 > export default config
 > ```
 
-## Project Structure
+## 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}`.
 
@@ -217,7 +217,7 @@ Here are two examples of valid project structures by default:
 
 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.
 
-You can find more info about Route Files definition under the [Routes](routes.md) section.
+You can find more info about Route Files definition in the [Routes Files](routes.md#route-files) section.
 
-> [!NOTE]  
-> Those are just examples that will work with the default configuration. You can of course redefine `routes` property with your own pattern(s) to fit your own project structure.
+> [!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.

package/docs/handler.md

@@ -0,0 +1,105 @@
+# Handler
+
+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
+
+The handler should be declared as last argument of the [Route Definition](routes.md#route-defintion) 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](lifecycle.md) section.
+
+## Handler definition
+
+```js
+const handler = ctx => {
+  const { name } = ctx.query
+  return `Hello ${name}!`
+}
+```
+
+The handler function takes a `context` object as single argument and might return a `response`.
+
+**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.
+
+**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
+
+> [!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.
+
+### String
+
+Case where `string` is returned by the handler.
+
+- status: 200
+- content-type: `text-plain`
+
+**Example**
+
+```js
+galbe.get('/example', ctx => {
+  return 'Hello Mom!'
+})
+```
+
+### Object
+
+Case where an `object` is returned by the handler.
+
+- status: 200
+- content-type: `application/json`
+
+**Example**
+
+```js
+galbe.get('/example', ctx => {
+  return 'Hello Mom!'
+})
+```
+
+### 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.
+
+**Example**
+
+<!-- prettier-ignore -->
+```js
+galbe.get('/example', ctx => {
+  return new Response(
+    'Hello Mom',
+    { status: 200, headers: { 'content-type': 'text/plain' } 
+  })
+})
+```
+
+### Generator
+
+Case where a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) instance is returned by the handler.
+
+- status: 200
+- content-type: `text/event-stream`
+
+**Example**
+
+```js
+async function* generator(array) {
+  for (const item of array) {
+    await Bun.sleep(500)
+    yield item
+  }
+}
+
+galbe.get('/example', ctx => generator(['one', 'two', 'three']))
+```

package/docs/hooks.md

@@ -0,0 +1,90 @@
+# Hooks
+
+Hooks provide a simple way to perform specific actions before and/or after reaching a specific route endpoint.
+
+## Hook definition
+
+```ts
+const hook = (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.
+
+**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.
+
+**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.
+
+> [!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.
+>
+> To learn more about response types, ou can take a look at the [Response types](handler.md#response-types) section.
+
+## Hooks declaration
+
+Hooks should be declared just before the handler method in the [Route Definition](routes.md#route-defintion) method as a list of Hooks.
+
+```ts
+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](lifecycle.md) section.
+
+### Examples
+
+Linear hooks declaration:
+
+```ts
+const hook1 = context => {
+  console.log('hook1 called')
+}
+const hook2 = context => {
+  console.log('hook2 called')
+}
+
+galbe.get('example', [hook1, hook2], ctx => {
+  console.log('handler')
+})
+```
+
+```bash
+$ curl http://localhost:3000/example
+hook1
+hook2
+handler
+```
+
+Nested hooks declaration:
+
+```ts
+const hook1 = (context, next) => {
+  console.log('hook1 start')
+  await next()
+  console.log('hook1 end')
+}
+const hook2 = context => {
+  console.log('hook2 start')
+  await next()
+  console.log('hook2 end')
+}
+
+galbe.get('example', [hook1, hook2], ctx => {
+  console.log('handler')
+})
+```
+
+```bash
+$ curl http://localhost:3000/example
+hook1 start
+hook2 start
+handler
+hook2 end
+hook1 end
+```

package/docs/plugins.md

@@ -0,0 +1 @@
+# Plugins

package/docs/router.md

@@ -0,0 +1,10 @@
+# Router
+
+Galbe router employs a hybrid approach to store and locating 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)`.
+
+> [!NOTE]
+> A static route is a route that doesn't contain any parameter (e.g.,`:param`) or wildcards `*`.
+
+All other routes are stored in a [Trie](https://en.wikipedia.org/wiki/Trie)-like data structure. The time complexity of the search operation in this case is `O(n)`, where `n` represents the number of segments in the incoming request path.

package/docs/routes.md

@@ -1,6 +1,8 @@
 # Routes
 
-## Route Definition
+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.
+
+## Route definition
 
 Here is how to define routes in Galbe.
 
@@ -23,15 +25,15 @@ There are two special segments:
 
 **schema** (Schema) _Optional_
 
-See [Schemas](schemas) section.
+See [Schemas](schemas.md) section.
 
 **hooks** (Hook[]) _Optional_
 
-See [Hooks](hooks) section.
+See [Hooks](hooks.md) section.
 
 **handler** (Handler)
 
-See [Handler](handler) section.
+See [Handler](handler.md) section.
 
 ### Examples
 
@@ -78,15 +80,13 @@ galbe.get(
 ## Automatic Route Analyzer
 
 > [!NOTE]
-> This feature is only available if you run/build the app via the [Galbe CLI](), which is the case by default if you created your app following the [Automatic Installation]() step or properly configured your package.json to do so.
-
-The Automatic Route Analyzer is in charge of analyzing all the Route Files of your project and set up the routes defintions to your Glabe server automatically.
+> 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.
 
-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 analyzer.
+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 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 a basic js example:
+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:
 
 ```ts
 export default g => {
@@ -94,7 +94,7 @@ export default g => {
 }
 ```
 
-The same example using Typescript:
+The same example in Typescript:
 
 ```ts
 import type { Galbe } from 'galbe'
@@ -103,7 +103,7 @@ export default (g: Galbe) => {
 }
 ```
 
-The Automatic Route Analyzer is also capable of collecting metadata about your Routefile and your routes by analyzing multiline comments. This can be used by some plugins to perform specific tasks. Here is an example of Routefile with multiline comments metadata.
+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:
 
 ```js
 /**
@@ -121,4 +121,4 @@ export default g => {
 }
 ```
 
-You will find more information about comment's metadata and how to use them along with examples in a plugin in the [Plugin](plugins) section.
+You will find more information about comment metadata and how to use them along with examples in the [Plugin](plugins.md) section.