galbe 0.1.8 → 0.2.0

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/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](https://galbe.dev/documentation/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

@@ -8,14 +8,14 @@ Designed with simplicity in mind, Galbe allows you to quickly create and set up
 
 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,7 +23,7 @@ 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 `localhost:3000`.
@@ -31,20 +31,20 @@ This will start a web server on `localhost:3000`.
 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!
 ```
 
 > [!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:
@@ -80,7 +80,7 @@ This is the recommended way to proceed but it is not mandatory. Galbe instances
 ### Galbe CLI
 
 ```bash
-galbe <command> <argument> [options]
+$ galbe <command> <argument> [options]
 ```
 
 Here are the available commands:
@@ -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}`.
 

package/docs/handler.md

@@ -1 +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](https://galbe.dev/documentation/lifecycle) 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

@@ -2,7 +2,7 @@
 
 Hooks provide a simple way to perform specific actions before and/or after reaching a specific route endpoint.
 
-## Hook Definition
+## Hook definition
 
 ```ts
 const hook = (context, next) => {
@@ -16,24 +16,26 @@ 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.
+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."
+> 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 declaration
 
-Hooks should be declared just before the handler method in the [Route Definition]() method as a list of Hooks.
+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]() 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.
+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.
 
 ### Examples
 
@@ -53,7 +55,7 @@ galbe.get('example', [hook1, hook2], ctx => {
 ```
 
 ```bash
-curl http://localhost:3000/example
+$ curl http://localhost:3000/example
 hook1
 hook2
 handler
@@ -79,7 +81,7 @@ galbe.get('example', [hook1, hook2], ctx => {
 ```
 
 ```bash
-curl http://localhost:3000/example
+$ curl http://localhost:3000/example
 hook1 start
 hook2 start
 handler

package/docs/plugins.md

@@ -1 +1,124 @@
 # 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).
+
+## Definition
+
+```ts
+type GalbePlugin = {
+  name: string
+  init?: (config: any, galbe: Galbe) => MaybePromise<void>
+  onFetch?: (context: Context) => MaybePromise<Response | void>
+  onRoute?: (context: Context) => MaybePromise<Response | void>
+  beforeHandle?: (context: Context) => MaybePromise<Response | void>
+  afterHandle?: (response: Response, context: Context) => MaybePromise<Response | void>
+}
+```
+
+**name**
+
+The name should be a Unique Plugin Identifier. It should be chosen to be unique to avoid conflicts with other potential plugins. For example, Galbe's official plugins names will always start with `dev.galbe.*`.
+
+**init**
+
+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`.
+
+**onFetch**
+
+This method is called at the beginning of an incoming request. 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.
+
+**onRoute**
+
+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).
+
+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.
+
+## Registration
+
+To register a plugin with your Galbe server, you must use the `use` method from you galbe instance.
+
+```js
+const galbe = new Galbe()
+galbe.use(plugin)
+```
+
+## Example
+
+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).
+
+```ts
+// myPlugin.ts
+
+import { Galbe, type Context, type Route } from 'galbe'
+
+class MyPlugin {
+  name = 'dev.galbe.example'
+  deprecated: Record<string, string[]> = {}
+  /**
+   * Retrieve and store all route with a @deprecated flag metadata
+   */
+  init(config: any, galbe: Galbe) {
+    if (config?.enabled && galbe.meta) {
+      for (const f of galbe.meta) {
+        for (const [path, methods] of Object.entries(f.routes)) {
+          for (const [method, meta] of Object.entries(methods)) {
+            if (meta.deprecated) {
+              if (!this.deprecated?.[method]) this.deprecated[method] = []
+              this.deprecated[method].push(path)
+            }
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Check if the current route is deprecated, flags it as is and logs it
+   */
+  onRoute(context: Context) {
+    let route = context.route
+    if (this.deprecated?.[route.method]?.includes(route.path)) {
+      context.state[this.name] = { deprecated: true }
+      console.warn(`Call to deprecated route [${route.method}]${route.path}`)
+    }
+  }
+  /**
+   * Adds a header if the request has previously been flagged as deprecated
+   */
+  afterHandle(response: Response, context: Context) {
+    if (context.state?.[this.name]?.deprecated) {
+      response.headers.set('x-deprecated', 'true')
+    }
+  }
+}
+
+export default new MyPlugin()
+```
+
+```ts
+// index.ts
+
+import { Galbe } from 'galbe'
+import config from './galbe.config'
+import myPlugin from './myPlugin'
+
+const galbe = new Galbe(config)
+galbe.use(myPlugin)
+
+export default galbe
+```
+
+As you can see in this example, the [Context](context.md#definition) `state` property is used to persist information between plugins interceptor methods. It is a good practice to scope any information stored in the state with the plugin name, as it can also be used by other plugins and hooks to store data in the context.

package/docs/router.md

@@ -1 +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

@@ -2,7 +2,7 @@
 
 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
+## Route definition
 
 Here is how to define routes in Galbe.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "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/index.ts

@@ -80,7 +80,6 @@ const galbeMethod = <
         [header: string]: string
       }
       status?: number
-      redirect?: string
     }
   }
   return {
@@ -123,7 +122,10 @@ export class Galbe {
   constructor(config?: GalbeConfig) {
     this.config = config ?? {}
     this.config.routes = this.config.routes ?? true
-    this.router = new GalbeRouter(this.config?.basePath || '')
+    this.router = new GalbeRouter({
+      prefix: this.config?.basePath || '',
+      cacheEnabled: this.config?.router?.cacheEnabled
+    })
   }
   private add(route: any) {
     this.router.add(route)

package/src/parser.ts

@@ -9,16 +9,14 @@ import type {
   MultipartFormData,
   STUrlFormValues,
   STMultipartFormValues,
-  STUnion,
   STLiteral,
-  STArray,
   STSchema
 } from './schema'
 
 import { readableStreamToArrayBuffer } from 'bun'
 import { Kind, Optional, Stream } from './schema'
 import { validate } from './validator'
-import { RequestError, $T } from './index'
+import { InternalError, RequestError } from './index'
 
 const textDecoder = new TextDecoder()
 const textEncoder = new TextEncoder()
@@ -39,10 +37,10 @@ const MP_HEADER_RX = /^multipart\/form-data/
 
 export const requestBodyParser = async (
   body: ReadableStream | null,
-  headers: { 'content-type'?: string; 'content-length'?: string },
+  headers: Record<string, string>,
   schema?: STBody
 ) => {
-  const { 'content-type': contentType, 'content-length': _contentLength } = headers
+  const contentType = headers?.['content-type']
   const kind = schema?.[Kind]
   const isStream = schema && Stream in schema
   try {
@@ -60,19 +58,19 @@ export const requestBodyParser = async (
         } else if (schema?.[Optional]) {
           return null
         } else {
-          throw new RequestError({ status: 400, error: { body: `Not a valid ${kind}` } })
+          throw new RequestError({ status: 400, payload: { body: `Not a valid ${kind}` } })
         }
       } else {
         if (contentType === BA_HEADER) {
           return new Uint8Array()
         } else if (contentType === JSON_HEADER) {
-          throw new RequestError({ status: 400, error: { body: 'Not a valid json' } })
+          throw new RequestError({ status: 400, payload: { body: 'Not a valid json' } })
         } else if (contentType?.match(TXT_HEADER_RX)) {
-          throw new RequestError({ status: 400, error: { body: 'Not a valid text' } })
+          throw new RequestError({ status: 400, payload: { body: 'Not a valid text' } })
         } else if (contentType?.match(FORM_HEADER_RX)) {
-          throw new RequestError({ status: 400, error: { body: 'Not a valid form' } })
+          throw new RequestError({ status: 400, payload: { body: 'Not a valid form' } })
         } else if (contentType?.match(MP_HEADER_RX)) {
-          throw new RequestError({ status: 400, error: { body: 'Not a valid multipart form' } })
+          throw new RequestError({ status: 400, payload: { body: 'Not a valid multipart form' } })
         } else return null
       }
     } else {
@@ -91,7 +89,7 @@ export const requestBodyParser = async (
           : contentType?.match(MP_HEADER_RX)
           ? 'multipartForm'
           : contentType
-        throw new RequestError({ status: 400, error: { body: `Expected ${kind}, received ${received}` } })
+        throw new RequestError({ status: 400, payload: { body: `Expected ${kind}, received ${received}` } })
       } else if (!contentType || contentType === BA_HEADER) {
         if (!schema) {
           if (isStream) return rsToAsyncIterator(body)
@@ -104,7 +102,14 @@ export const requestBodyParser = async (
         }
       } else if (contentType === JSON_HEADER) {
         if (!schema) {
-          return await streamToString(body, $T.object($T.any()))
+          try {
+            return JSON.parse(await streamToString(body))
+          } catch (err: any) {
+            throw new RequestError({
+              status: 400,
+              payload: { body: err?.message ?? 'Parsing error' }
+            })
+          }
         } else {
           const str = await streamToString(body)
           let json
@@ -113,7 +118,7 @@ export const requestBodyParser = async (
           } catch (err: any) {
             throw new RequestError({
               status: 400,
-              error: { body: err?.message ?? 'Parsing error' }
+              payload: { body: err?.message ?? 'Parsing error' }
             })
           }
           return validate(json, schema, true)
@@ -129,7 +134,7 @@ export const requestBodyParser = async (
           return await streamToUrlForm(body)
         } else {
           if (kind !== 'urlForm')
-            throw new RequestError({ status: 400, error: { body: `Expected ${kind}, received urlForm` } })
+            throw new RequestError({ status: 400, payload: { body: `Expected ${kind}, received urlForm` } })
           if (isStream) return $streamToUrlForm(body, schema as STStream<STUrlForm>)
           else return await streamToUrlForm(body, schema as STUrlForm)
         }
@@ -139,7 +144,7 @@ export const requestBodyParser = async (
           return await streamToMultipartForm(body, boundary)
         } else {
           if (kind !== 'multipartForm')
-            throw new RequestError({ status: 400, error: { body: `Expected ${kind}, received MultipartForm` } })
+            throw new RequestError({ status: 400, payload: { body: `Expected ${kind}, received MultipartForm` } })
           if (isStream) return $streamToMultipartForm(body, boundary, schema as STStream<STMultipartForm>)
           else {
             return streamToMultipartForm(body, boundary, schema as STMultipartForm)
@@ -151,7 +156,7 @@ export const requestBodyParser = async (
     }
   } catch (error) {
     if (error instanceof RequestError) throw error
-    else throw new RequestError({ status: 400, error: { body: error } })
+    else throw new RequestError({ status: 400, payload: { body: error } })
   }
 }
 async function* $streamToString(body: ReadableStream) {
@@ -189,7 +194,7 @@ async function* $streamToUrlForm(
           let s = schema?.props?.[key]?.[Kind] === 'array' ? schema?.props?.[key].items : schema?.props?.[key]
           val = s ? paramParser(val, s) : val
         } catch (error) {
-          throw new RequestError({ status: 400, error: { body: { [key]: error } } })
+          throw new RequestError({ status: 400, payload: { body: { [key]: error } } })
         }
         delete required[key]
         yield [key, val]
@@ -220,7 +225,7 @@ async function* $streamToUrlForm(
     let s = schema?.props?.[key]?.[Kind] === 'array' ? schema?.props?.[key].items : schema?.props?.[key]
     val = s ? paramParser(val, s) : val
   } catch (error) {
-    throw new RequestError({ status: 400, error: { body: { [key]: error } } })
+    throw new RequestError({ status: 400, payload: { body: { [key]: error } } })
   }
   delete required[key]
   yield [key, val]
@@ -234,7 +239,7 @@ async function* $streamToUrlForm(
   if (reqKeys.length > 0)
     throw new RequestError({
       status: 400,
-      error: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
+      payload: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
     })
 }
 const streamToUrlForm = async (body: ReadableStream<Uint8Array>, schema?: STUrlForm) => {
@@ -260,7 +265,7 @@ const streamToUrlForm = async (body: ReadableStream<Uint8Array>, schema?: STUrlF
         errors[k] = k in errors ? [...errors[k], error] : error
       }
     }
-  if (Object.keys(errors).length) throw new RequestError({ status: 400, error: { body: errors } })
+  if (Object.keys(errors).length) throw new RequestError({ status: 400, payload: { body: errors } })
   for (const [k, s] of Object.entries(required)) {
     if (s[Kind] === 'array') {
       object[k] = []
@@ -271,7 +276,7 @@ const streamToUrlForm = async (body: ReadableStream<Uint8Array>, schema?: STUrlF
   if (reqKeys.length > 0)
     throw new RequestError({
       status: 400,
-      error: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
+      payload: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
     })
   return object
 }
@@ -310,7 +315,7 @@ async function* $streamToMultipartForm(data: ReadableStream<Uint8Array>, boundar
             }
           } catch (err) {
             if (err instanceof RequestError) throw err
-            throw new RequestError({ status: 400, error: { body: { [headers.name]: err } } })
+            throw new RequestError({ status: 400, payload: { body: { [headers.name]: err } } })
           }
         }
         bK = new Uint8Array()
@@ -343,7 +348,7 @@ async function* $streamToMultipartForm(data: ReadableStream<Uint8Array>, boundar
         content: parseMultipartContent(bV, headers, schema)
       }
     } catch (err) {
-      throw new RequestError({ status: 400, error: { body: { [headers.name]: err } } })
+      throw new RequestError({ status: 400, payload: { body: { [headers.name]: err } } })
     }
   }
   for (const [k, s] of Object.entries(required)) {
@@ -356,7 +361,7 @@ async function* $streamToMultipartForm(data: ReadableStream<Uint8Array>, boundar
   if (reqKeys.length > 0)
     throw new RequestError({
       status: 400,
-      error: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
+      payload: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
     })
 }
 const parseMultipartHeader = (header: string): { name: string; [key: string]: string } | null => {
@@ -394,19 +399,22 @@ const parseMultipartContent = (
       try {
         result = JSON.parse(textDecoder.decode(content).trim())
       } catch (err: any) {
-        throw new RequestError({ status: 400, error: { body: { [headers.name]: err?.message || 'Parsing error' } } })
+        throw new RequestError({ status: 400, payload: { body: { [headers.name]: err?.message || 'Parsing error' } } })
       }
     } else if (schema?.props) {
       if (schema?.props[headers.name][Kind] === 'object') {
         try {
           result = JSON.parse(textDecoder.decode(content).trim())
         } catch (err: any) {
-          throw new RequestError({ status: 400, error: { body: { [headers.name]: err?.message || 'Parsing error' } } })
+          throw new RequestError({
+            status: 400,
+            payload: { body: { [headers.name]: err?.message || 'Parsing error' } }
+          })
         }
         try {
           validate(result, schema?.props[headers.name])
         } catch (err) {
-          throw new RequestError({ status: 400, error: { body: { [headers.name]: err } } })
+          throw new RequestError({ status: 400, payload: { body: { [headers.name]: err } } })
         }
       } else if (schema?.props[headers.name][Kind] === 'byteArray') {
         return content
@@ -415,7 +423,7 @@ const parseMultipartContent = (
       } else {
         throw new RequestError({
           status: 400,
-          error: { body: { [headers.name]: `Expect ${schema?.props[headers.name][Kind]} found json` } }
+          payload: { body: { [headers.name]: `Expect ${schema?.props[headers.name][Kind]} found json` } }
         })
       }
     }
@@ -424,7 +432,7 @@ const parseMultipartContent = (
       let s = schema?.props[headers.name]
       validate(result, s?.[Kind] === 'array' ? s?.items : s)
     } catch (err) {
-      throw new RequestError({ status: 400, error: { body: { [headers.name]: err } } })
+      throw new RequestError({ status: 400, payload: { body: { [headers.name]: err } } })
     }
   }
   return result
@@ -473,7 +481,7 @@ const streamToMultipartForm = async (data: ReadableStream<Uint8Array>, boundary:
   if (Object.keys(errors).length)
     throw new RequestError({
       status: 400,
-      error: { body: errors }
+      payload: { body: errors }
     })
   for (const [k, s] of Object.entries(required)) {
     if (s[Kind] === 'array') {
@@ -485,7 +493,7 @@ const streamToMultipartForm = async (data: ReadableStream<Uint8Array>, boundary:
   if (reqKeys.length > 0)
     throw new RequestError({
       status: 400,
-      error: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
+      payload: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
     })
   return res
 }
@@ -559,14 +567,28 @@ const paramParser = (
 }
 
 export const requestPathParser = (input: string, path: string) => {
-  let pPath = path.replace(/^\/$(.*)\/?$/, '$1').split('/')
-  let pInput = input.replace(/^\/$(.*)\/?$/, '$1').split('/')
+  let pInput = input.split('/')
   let params: Record<string, any> = {}
-  pPath.shift()
-  pInput.shift()
-  for (const [i, p] of pPath.entries()) {
-    const match = p.match(/^:(.*)/)
-    if (match) params[match[1]] = pInput[i]
+  let idx = 0
+  for (let i = 0; i < path.length; i++) {
+    let c = path[i]
+    if (c === '/') {
+      idx++
+      continue
+    }
+    if (c === ':') {
+      let name = ''
+      while (true) {
+        i++
+        c = path[i]
+        if (c === '/' || i >= path.length) {
+          i--
+          break
+        }
+        name += c
+      }
+      params[name] = pInput[idx]
+    }
   }
   return params
 }
@@ -601,7 +623,7 @@ export const parseEntry = <T extends STProps>(
   })
 
   if (Object.keys(errors).length) {
-    throw new RequestError({ status: 400, error: options?.name ? { [options.name]: errors } : errors })
+    throw new RequestError({ status: 400, payload: options?.name ? { [options.name]: errors } : errors })
   }
 
   return parsedParams as Static<STObject<T>>
@@ -631,7 +653,7 @@ export const responseParser = (response: any, ctx: Context) => {
           let data = `id:${id}\ndata:${r}\n\n`
           try {
             await controller.write(data)
-            // await controller.flush()
+            await controller.flush()
           } catch (err) {
             console.error(err)
           }
@@ -648,7 +670,7 @@ export const responseParser = (response: any, ctx: Context) => {
       return new Response(JSON.stringify(response), details)
     } catch (error) {
       console.error(error)
-      throw new RequestError({ status: 500, error: 'Internal Server Error' })
+      throw new InternalError()
     }
   }
 }

package/src/router.ts

@@ -44,19 +44,21 @@ const walkRoutes = (path: string[], node: RouteNode, alts: RouteNode[] = []): Ro
 export class GalbeRouter {
   routes: RouteTree
   prefix: string
-  staticRoutes: Map<string, Route>
-  constructor(prefix?: string) {
+  cacheEnabled: boolean
+  cachedRoutes: Map<string, Route | null>
+  constructor(options?: { prefix?: string; cacheEnabled?: boolean }) {
     this.routes = { GET: {}, POST: {}, PUT: {}, PATCH: {}, DELETE: {}, OPTIONS: {} }
-    prefix = prefix || ''
+    let prefix = options?.prefix || ''
     if (prefix && !prefix.match(/^\//)) prefix = `/${prefix}`
     this.prefix = prefix
-    this.staticRoutes = new Map()
+    this.cachedRoutes = new Map()
+    this.cacheEnabled = options?.cacheEnabled ?? false
   }
   add(route: Route) {
     route.path = route?.path?.[0] === '/' ? route.path : `/${route.path}`
     if (!route.path.match(ROUTE_REGEX)) throw new SyntaxError(`${route.path} is not a valid route path.`)
     const isStatic = !route.path.match(/(:[\w\d-]+|\*)/)
-    if (isStatic) this.staticRoutes.set(`[${route.method.toUpperCase()}]${route.path}`, route)
+    if (isStatic) this.cachedRoutes.set(`[${route.method.toUpperCase()}]${route.path}`, route)
     route.path = `${this.prefix || ''}${route.path}`
     let path = route.path.replace(/^\/$(.*)\/?$/, '$1').split('/')
     path.shift()
@@ -87,14 +89,16 @@ export class GalbeRouter {
     }
   }
   find(method: string, path: string) {
-    const staticRoute = this.staticRoutes.get(`[${method}]${path}`)
+    const staticRoute = this.cachedRoutes.get(`[${method}]${path}`)
+    if (staticRoute === null) throw new NotFoundError()
     if (staticRoute !== undefined) return staticRoute
-    let parts = path
-      .replace(/\/+/g, '/')
-      .replace(/^\/$(.*)\/?$/, '$1')
-      .split('/')
+    let parts = path.split('/')
     const route = walkRoutes(parts, this.routes[method]).route
-    if (!route) throw new NotFoundError()
+    if (!route) {
+      if (this.cacheEnabled) this.cachedRoutes.set(`[${method}]${path}`, null)
+      throw new NotFoundError()
+    }
+    if (this.cacheEnabled) this.cachedRoutes.set(`[${method}]${path}`, route)
     return route
   }
 }

package/src/server.ts

@@ -1,35 +1,20 @@
 import type { Context, Route } from './types'
 
-import { NotFoundError, RequestError } from './types'
+import { InternalError, RequestError } from './types'
 import { parseEntry, requestBodyParser, requestPathParser, responseParser } from './parser'
 import { Galbe } from './index'
 
 const handleInternalError = (error: any) => {
   console.error(error)
-  return new RequestError({ status: 500, error: 'Internal Server Error' })
+  return new InternalError()
 }
 
 const setupPluginCallbacks = (galbe: Galbe) => ({
-  init: galbe.plugins.reduce((l: { name: string; cb: Function }[], p) => {
-    if (p.init) l.push({ name: p.name, cb: p.init })
-    return l
-  }, []),
-  onFetch: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.onFetch) l.push(p.onFetch)
-    return l
-  }, []),
-  onRoute: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.onRoute) l.push(p.onRoute)
-    return l
-  }, []),
-  beforeHandle: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.beforeHandle) l.push(p.beforeHandle)
-    return l
-  }, []),
-  afterHandle: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.afterHandle) l.push(p.afterHandle)
-    return l
-  }, [])
+  init: galbe.plugins.filter(p => p.init),
+  onFetch: galbe.plugins.filter(p => p.onFetch),
+  onRoute: galbe.plugins.filter(p => p.onRoute),
+  beforeHandle: galbe.plugins.filter(p => p.beforeHandle),
+  afterHandle: galbe.plugins.filter(p => p.afterHandle)
 })
 
 export default async (galbe: Galbe, port?: number) => {
@@ -37,7 +22,8 @@ export default async (galbe: Galbe, port?: number) => {
   if (galbe?.config?.basePath && galbe?.config?.basePath[0] !== '/')
     galbe.config.basePath = `/${galbe?.config?.basePath}`
   let pluginsCb = setupPluginCallbacks(galbe)
-  for (const { name, cb } of pluginsCb.init) await cb(galbe?.config?.plugin?.[name], galbe)
+  //@ts-ignore
+  for (const p of pluginsCb.init) await p.init(galbe?.config?.plugin?.[p.name], galbe)
 
   return Bun.serve({
     port: port || galbe.config?.port || 3000,
@@ -51,8 +37,9 @@ export default async (galbe: Galbe, port?: number) => {
         body: {},
         state: {}
       }
-      for (const cb of pluginsCb.onFetch) {
-        const r = await cb(req)
+      for (const p of pluginsCb.onFetch) {
+        //@ts-ignore
+        const r = await p.onFetch(context)
         if (r) return r
       }
       const url = new URL(req.url)
@@ -60,23 +47,26 @@ export default async (galbe: Galbe, port?: number) => {
       let response: any = ''
       try {
         // find route
-        if (!url.pathname.match(new RegExp(`^${galbe.config?.basePath || ''}`))) throw new NotFoundError()
         try {
           route = router.find(req.method, url.pathname)
         } catch (error) {
           if (error instanceof RequestError) throw error
           else throw handleInternalError(error)
         }
+        context.route = route
 
-        for (const cb of pluginsCb.onRoute) {
-          const r = await cb(route)
+        for (const p of pluginsCb.onRoute) {
+          //@ts-ignore
+          const r = await p.onRoute(context)
           if (r) return r
         }
 
         // parse request
         const schema = route.schema
-        let inHeaders = Object.fromEntries(req.headers.entries())
-        let inQuery = Object.fromEntries(url.searchParams.entries())
+        const inHeaders: Record<string, any> = {}
+        for (let [k, v] of req.headers) inHeaders[k] = v
+        let inQuery: Record<string, any> = {}
+        for (let [k, v] of url.searchParams) inQuery[k] = v
         let inParams = requestPathParser(url.pathname, route.path)
 
         context.body = await requestBodyParser(req.body, inHeaders, schema.body)
@@ -109,11 +99,12 @@ export default async (galbe: Galbe, port?: number) => {
           else throw handleInternalError(error)
         }
         if (errors.length) {
-          throw new RequestError({ status: 400, error: errors.reduce((acc, c) => ({ ...acc, ...c.error }), {}) })
+          throw new RequestError({ status: 400, payload: errors.reduce((acc, c) => ({ ...acc, ...c.payload }), {}) })
         }
 
-        for (const cb of pluginsCb.beforeHandle) {
-          const r = await cb(context)
+        for (const p of pluginsCb.beforeHandle) {
+          //@ts-ignore
+          const r = await p.beforeHandle(context)
           if (r) return r
         }
 
@@ -123,7 +114,7 @@ export default async (galbe: Galbe, port?: number) => {
           handlerCalled = true
           return route.handler(context)
         }
-        const callChain = route.hooks.map((hook, idx) => ({
+        const callChain: { call: () => any }[] = route.hooks.map((hook, idx) => ({
           call: async () => {
             let nextCalled = false
             let next = async () => {
@@ -133,7 +124,8 @@ export default async (galbe: Galbe, port?: number) => {
                 await callChain[idx + 1].call()
               }
             }
-            await hook(context, next)
+            let r = await hook(context, next)
+            if (r) return r
             if (!nextCalled && !handlerCalled) await next()
           }
         }))
@@ -143,34 +135,45 @@ export default async (galbe: Galbe, port?: number) => {
             context.set.status = response instanceof Response ? response.status : 200
           }
         })
-        if (callChain.length > 1) await callChain[0].call()
-        else response = await handlerWrapper(context)
+        if (callChain.length > 1) {
+          let r = await callChain[0].call()
+          if (r) response = r
+        } else response = await handlerWrapper(context)
+
         const parsedResponse = responseParser(response, context)
 
-        for (const cb of pluginsCb.afterHandle) {
-          const r = await cb(parsedResponse)
+        for (const p of pluginsCb.afterHandle) {
+          //@ts-ignore
+          const r = await p.afterHandle(parsedResponse, context)
           if (r) return r
         }
 
         return parsedResponse
       } catch (error) {
         context.set.status = error instanceof RequestError ? error.status : 500
-        if (galbe.errorHandler) return galbe.errorHandler(error, context)
+        let customError
+        if (galbe.errorHandler) customError = responseParser(galbe.errorHandler(error, context), context)
+        if (customError) return customError
         if (error instanceof RequestError) {
-          return new Response(JSON.stringify(error.error), {
+          return new Response(JSON.stringify(error.payload), {
             status: error.status,
             headers: { 'Content-Type': 'application/json' }
           })
         }
-        return new Response('Internal Server Error', { status: 500 })
+        return new Response('"Internal Server Error"', {
+          status: 500,
+          headers: {
+            'content-type': 'application/json'
+          }
+        })
       }
     },
     error(error) {
       console.error(error)
-      return new Response('Internal Server Error', {
+      return new Response('"Internal Server Error"', {
         status: 500,
         headers: {
-          'Content-Type': 'text/plain'
+          'content-type': 'application/json'
         }
       })
     }

package/src/types.ts

@@ -72,6 +72,7 @@ export type GalbeConfig = {
   basePath?: string
   server?: Exclude<ServeOptions, 'port'> | TLSServeOptions
   routes?: boolean | string | string[]
+  router?: { cacheEnabled: boolean }
   plugin?: Record<string, any>
 }
 /**
@@ -123,13 +124,13 @@ export type Context<Path extends string = string, S extends RequestSchema = Requ
   query: Static<STObject<Exclude<S['query'], undefined>>>
   body: Static<Exclude<S['body'], undefined>>
   request: Request
+  route?: Route
   state: Record<string, any>
   set: {
     headers: {
       [header: string]: string
     }
     status?: number
-    redirect?: string
   }
 }
 export type Next = () => void | Promise<void>
@@ -146,7 +147,7 @@ export type Endpoint = {
     H extends STHeaders,
     P extends Partial<STParams<Path>>,
     Q extends STQuery,
-    B extends STBody = STObject
+    B extends STBody = any
   >(
     path: Path,
     schema: RequestSchema<Path, H, P, Q, B>,
@@ -158,7 +159,7 @@ export type Endpoint = {
     H extends STHeaders,
     P extends Partial<STParams<Path>>,
     Q extends STQuery,
-    B extends STBody = STObject
+    B extends STBody = any
   >(
     path: Path,
     schema: RequestSchema<Path, H, P, Q, B>,
@@ -169,7 +170,7 @@ export type Endpoint = {
     H extends STHeaders,
     P extends Partial<STParams<Path>>,
     Q extends STQuery,
-    B extends STBody = STObject
+    B extends STBody = any
   >(
     path: Path,
     hooks: Hook<Path, RequestSchema<Path, H, P, Q, B>>[],
@@ -180,7 +181,7 @@ export type Endpoint = {
     H extends STHeaders,
     P extends Partial<STParams<Path>>,
     Q extends STQuery,
-    B extends STBody = STObject
+    B extends STBody = any
   >(
     path: Path,
     handler: Handler<Path, RequestSchema<Path, H, P, Q, B>>
@@ -189,10 +190,10 @@ export type Endpoint = {
 
 export class RequestError {
   status: number
-  error: any
-  constructor(options: { status?: number; error?: any }) {
+  payload: any
+  constructor(options: { status?: number; payload?: any }) {
     this.status = options.status ?? 500
-    this.error = options.error ?? 'Internal server error'
+    this.payload = options.payload ?? 'Internal server error'
   }
 }
 
@@ -225,7 +226,13 @@ export type RouteTree = {
 
 export class NotFoundError extends RequestError {
   constructor(message?: string) {
-    super({ status: 404, error: message ?? 'Not found' })
+    super({ status: 404, payload: message ?? 'Not found' })
+  }
+}
+
+export class InternalError extends RequestError {
+  constructor(message?: string) {
+    super({ status: 500, payload: message ?? 'Internal Server Error' })
   }
 }
 
@@ -253,8 +260,8 @@ export class NotFoundError extends RequestError {
 export type GalbePlugin = {
   name: string
   init?: (config: any, galbe: Galbe) => MaybePromise<void>
-  onFetch?: (request: Request) => MaybePromise<Response | void>
-  onRoute?: (route: Route) => MaybePromise<Response | void>
+  onFetch?: (context: Context) => MaybePromise<Response | void>
+  onRoute?: (context: Context) => MaybePromise<Response | void>
   beforeHandle?: (context: Context) => MaybePromise<Response | void>
-  afterHandle?: (response: Response) => MaybePromise<Response | void>
+  afterHandle?: (response: Response, context: Context) => MaybePromise<Response | void>
 }

package/test/hooks.test.ts

@@ -174,4 +174,27 @@ describe('hooks', async () => {
     expect(resp.status).toBe(200)
     expect(await resp?.text()).toBe('handled')
   })
+
+  test('hooks, early response', async () => {
+    let hook = 0
+    galbe.get(
+      '/hooks',
+      [
+        async _ => {
+          hook++
+          return 'hook'
+        }
+      ],
+      () => {
+        expect.unreachable()
+      }
+    )
+    expect(hook).toBe(0)
+    let resp = await fetch(`http://localhost:${port}/hooks`, {
+      method: 'GET'
+    })
+    expect(hook).toBe(1)
+    expect(resp.status).toBe(200)
+    expect(await resp?.text()).toBe('hook')
+  })
 })

package/test/plugins.test.ts

@@ -39,8 +39,8 @@ describe('plugins', async () => {
     let request: any = null
     const plugin: GalbePlugin = {
       name: 'dev.galbe.test.init',
-      onFetch: mock(req => {
-        request = req
+      onFetch: mock(ctx => {
+        request = ctx.request
       })
     }
 
@@ -86,7 +86,7 @@ describe('plugins', async () => {
     const plugin: GalbePlugin = {
       name: 'dev.galbe.test.init',
       onRoute: mock(r => {
-        route = r
+        route = r.route
       })
     }
 

package/test/router.test.ts

@@ -141,7 +141,7 @@ describe('router', () => {
     } catch (err: any) {
       expect(err).toBeInstanceOf(NotFoundError)
       expect(err.status).toBe(404)
-      expect(err.error).toBe('Not found')
+      expect(err.payload).toBe('Not found')
     }
 
     try {
@@ -150,7 +150,7 @@ describe('router', () => {
     } catch (err: any) {
       expect(err).toBeInstanceOf(NotFoundError)
       expect(err.status).toBe(404)
-      expect(err.error).toBe('Not found')
+      expect(err.payload).toBe('Not found')
     }
   })
 
@@ -188,10 +188,6 @@ describe('router', () => {
     expect(r1.path).toBe('/test/foo/*')
     expect(r1.handler).toBe(h1)
 
-    let r2 = router.find('GET', '/test//foo/bar')
-    expect(r2.path).toBe('/test/foo/bar')
-    expect(r2.handler).toBe(h2)
-
     let r3 = router.find('GET', '/test/foo/bar/bar')
     expect(r3.path).toBe('/test/foo/:p/bar')
     expect(r3.handler).toBe(h3)