galbe 0.1.7 → 0.1.8

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/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/getting-started.md

@@ -1,8 +1,8 @@
 # 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
 
@@ -26,12 +26,12 @@ Now you can start the dev server by running:
 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
+curl localhost:3000/hello
 Hello from Galbe!
 ```
 
@@ -74,7 +74,7 @@ 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
@@ -85,7 +85,7 @@ 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
 
@@ -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 @@
+# Handler

package/docs/hooks.md

@@ -0,0 +1,88 @@
+# 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]() 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."
+
+## Hooks Declaration
+
+Hooks should be declared just before the handler method in the [Route Definition]() method as a list of Hooks.
+
+```ts
+galbe.get('foo', [ hook1, hook2, ... ], ctx => {})
+```
+
+Hooks are called just before the [Handler]() in the order that they have been declared in the hook list of the [Route Definition](). To get a better understanding of hooks execution during the request lifecycle, you can refer to the [Lifecycle]() 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 @@
+# Router

package/docs/routes.md

@@ -1,5 +1,7 @@
 # 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.
+
 ## 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.

package/docs/schemas.md

@@ -1,12 +1,10 @@
 # Shemas
 
-Galbe offers a custom Schema Type processor that provides type safety along with data parsing and validation.
-
-The prime intention of that features is to offer an easy way to manage automatically request inputs validation and error handling. Moreover, it also greatly improve developper's experience by infering static Typescript types from schema definitions.
+Galbe provides a custom Schema Type processor that offers type safety, data parsing, and validation. The primary purpose of this feature is to simplify request input validation and error handling automatically. Additionally, it enhances the developer's experience by inferring static TypeScript types from schema definitions.
 
 ## Schema Types
 
-To get started with Schema defintion, just import `$T` from `galbe` library:
+To start using Schema definitions, import `$T` from the `galbe` library:
 
 ```js
 import { $T } from 'galbe'
@@ -62,32 +60,32 @@ Schema Type matching `array` values.
 const arraySchema = $T.array($T.any(), options)
 ```
 
-#### Union
+#### Optional
 
-Creates an union of Schema Types. .
+Makes any type optional. This allows for `undefined` values.
 
 ```ts
-const unionSchema = $T.union([$T.string(), $T.number()])
+const optionalSchema = $T.optional($T.string())
 ```
 
-#### TOptional
+#### Union
 
-Makes any type optional. In practice, this allows for `undefined` values.
+Creates an union of Schema Types.
 
 ```ts
-const optionalSchema = $T.optional($T.string())
+const unionSchema = $T.union([$T.string(), $T.number()])
 ```
 
 ## Request Schema definition
 
-The Request Schema definition allows you to define a schema for your request on your [Route Definition](). It must be defined right after the [path]() of your route.
+The Request Schema definition allows you to define a schema for your request on your [Route Definition](routes.md#route-defintion). It must be defined right after the path of your route.
 
 ```js
 const schema = {}
 galbe.get('/foo/:bar', schema, ctx => {})
 ```
 
-The Request Schema has 4 optional properties
+The Request Schema has four optional properties:
 
 ### headers
 
@@ -95,7 +93,7 @@ The Request Schema has 4 optional properties
 headers: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
 ```
 
-This is a key-value object where each key represents a request `header` name and the value the Schema associated.
+This is a key-value object where each key represents a request header name, and the value is the associated Schema.
 
 **Example**:
 
@@ -113,7 +111,7 @@ const schema = {
 params: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
 ```
 
-This is a key-value object where each key represents a request `path parameter` name and the value the Schema associated.
+This is a key-value object where each key represents a request path parameter name, and the value is the associated Schema.
 
 **Example**:
 
@@ -127,7 +125,7 @@ const schema = {
 ```
 
 > [!WARNING]
-> Every key should match an existing [route path]() parameter. Otherwise Typescript will show you an error.
+> Every key should match an existing [route path](routes.md#route-defintion) parameter. Otherwise Typescript will show an error.
 >
 > By default, if no schema is defined for a given parameter. Galbe will assume it is of type `string`.
 
@@ -137,7 +135,7 @@ const schema = {
 query: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
 ```
 
-This is a key-value object where each key represents a request `query parameter` name and the value the Schema associated.
+This is a key-value object where each key represents a request query parameter name, and the value is the associated Schema.
 
 **Example**:
 
@@ -152,13 +150,15 @@ const schema = {
 
 ### body
 
+<!-- prettier-ignore -->
 ```ts
-body: STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | STObject | STMulripartForm | STUrlForm
+body: STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | 
+      STObject | STMulripartForm | STUrlForm
 ```
 
 #### Json
 
-To define an `application/json` request body. You must use `STObject` Schema Type. Example:
+To define an `application/json` request body, use `STObject` Schema Type. Example:
 
 ```ts
 const jsonBody = $T.object({
@@ -169,7 +169,7 @@ const jsonBody = $T.object({
 
 #### Multipart
 
-To define a `multipart/form-data` request body. You must use `TMultipartForm` Schema Type. Example:
+To define a `multipart/form-data` request body, use `TMultipartForm` Schema Type. Example:
 
 ```ts
 const multipartBody = $T.multipartForm({
@@ -180,7 +180,7 @@ const multipartBody = $T.multipartForm({
 
 #### Url Form
 
-To define an `application/x-www-form-urlencoded` request body. You must use `TUrlForm` Schema Type. Example:
+To define an `application/x-www-form-urlencoded` request body, use `TUrlForm` Schema Type. Example:
 
 ```ts
 const urlBody = $T.urlForm({
@@ -191,11 +191,9 @@ const urlBody = $T.urlForm({
 
 #### Stream
 
-Some body request types can be streamed by using `STStream` Schema Type wrapper. Streamable Schema Types are `STByteArray`, `STString`, `STUrlForm` and `STMultipartForm`.
+Some body request types can be streamed by using `STStream` Schema Type wrapper. The streamable Schema Types are `STByteArray`, `STString`, `STUrlForm` and `STMultipartForm`. This can be usefull to imporve performances in case you have heavy body payloads and you want to perform early validations on the body.
 
-This can be usefull to imporve performances in case you have heavy body payloads and you want to perform early validations on the body.
-
-Let's see a concrete example where that could be usefull. Imagine you want a `multipart/form-data` body request that has two properties `username` and `heavyImageFile`. In the normal case you would define something like that:
+Let's look at a concrete example where this could be useful. Imagine you want a `multipart/form-data` body request that has two properties: `username` and `heavyImageFile`. In a normal case, you would define something like this:
 
 ```ts
 galbe.post(
@@ -215,11 +213,9 @@ galbe.post(
 })
 ```
 
-This means that in the case where the username wouldn't pass the validation, the full request body including the `heavyImageFile` would have been processed for nothing as it is not used. Inducing unnecessary time and resource consumption.
-
-The `STStream` Schema Type wrapper was created to remediate to that issue. In practice it allows you to perform validations on the fly.
+This means that in the case where the username wouldn't pass the validation, the full request body, including the `heavyImageFile`, would have been processed for nothing, as it is not used. This would induce unnecessary time and resource consumption.
 
-Now in your handler, instead of receiving an object as ctx.body, you'll receive an [AsyncGenerator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
+The `STStream` Schema Type wrapper was created to remediate to remediate this issue. In practice it allows you to perform validations on the fly. Now in your handler, instead of receiving an object as `ctx.body`, you will receive an [AsyncGenerator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
 
 ```ts
 galbe.post(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Fast, lightweight and highly customizable JavaScript web framework based on Bun",
   "author": "Pierre Caillaud M (https://github.com/pierre-cm)",
   "type": "module",

package/src/server.ts

@@ -127,7 +127,11 @@ export default async (galbe: Galbe, port?: number) => {
           call: async () => {
             let nextCalled = false
             let next = async () => {
-              await callChain[idx + 1].call()
+              if (nextCalled) console.error('Hook already called - ignored')
+              else {
+                nextCalled = true
+                await callChain[idx + 1].call()
+              }
             }
             await hook(context, next)
             if (!nextCalled && !handlerCalled) await next()