galbe 0.4.1 → 0.6.0

package/README.md

@@ -1,4 +1,7 @@
-# Galbe
+<p align="center">
+  <a href="https://galbe.dev"><img src="https://galbe.dev/galbe.svg" alt="Logo" height=150></a>
+</p>
+<h1 align="center">Galbe</h1>
 
 [![Build & Test](https://github.com/pierre-cm/galbe/actions/workflows/build_test.yml/badge.svg?branch=main)](https://github.com/pierre-cm/galbe/actions/workflows/build_test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/pierre-cm/galbe/blob/main/LICENSE)

package/bin/commands/build.ts

@@ -79,9 +79,12 @@ export default (cmd: Command) => {
         ...Object.fromEntries(Object.entries(bunfig).filter(([k, v]) => v)),
         entrypoints: [buildIndex],
         outdir: resolve(CWD, out),
+        sourcemap: 'external',
         target: 'bun'
       }
 
+      await rm(resolve(CWD, out), { recursive: true })
+
       let bo = await Bun.build(buildConfig)
       if (bo.success) process.stdout.write(' : \x1b[1;30m\x1b[32mdone\x1b[0m\n')
       else {

package/bin/commands/dev.ts

@@ -2,7 +2,7 @@ import { $ } from 'bun'
 import { Command, Option } from 'commander'
 import { resolve } from 'path'
 
-import { CWD, fmtInterval, fmtVal, instanciateRoutes, watchDir } from '../util'
+import { CWD, fmtInterval, fmtVal, instanciateRoutes, killPort, watchDir } from '../util'
 import { Galbe } from '../../src'
 
 const defaultPort = 3000
@@ -22,13 +22,21 @@ export default (cmd: Command) => {
     )
     .addOption(new Option('-w, --watch', 'watch file changes').default(false, fmtVal(false)))
     .addOption(new Option('-nc, --noclear', "don't clear on file changes").default(false, fmtVal(false)))
+    .addOption(
+      new Option('-f, --force', 'kills any process running on defined port before strating the server').default(
+        false,
+        fmtVal(false)
+      )
+    )
     .action(async (index, props) => {
-      const { port, watch, noclear } = props
+      const { port, watch, noclear, force } = props
       const clear = !noclear
       const indexPath = resolve(CWD, index)
       let g: Galbe
 
-      Bun.env.BUN_ENV = 'development'
+      if (!Bun.env.BUN_ENV) Bun.env.BUN_ENV = 'development'
+
+      if (force) await killPort(port || 3000)
 
       if (watch) {
         await watchDir(

package/bin/commands/generate/client.ts

@@ -82,7 +82,14 @@ export default (cmd: Command) => {
               [...r.path.matchAll(/:([^\/]+)/g)]?.map(m => [
                 m?.[1],
                 {
-                  ...(r.schema?.params?.[m?.[1]] ? { type: schemaToTypeStr(r.schema.params[m[1]]) } : {})
+                  ...(r.schema?.params?.[m?.[1]]
+                    ? {
+                        type: schemaToTypeStr(r.schema.params[m[1]]),
+                        ...(r.schema.params[m[1]]?.description
+                          ? { description: r.schema.params[m[1]].description as string }
+                          : {})
+                      }
+                    : { type: 'string' })
                 }
               ])
             ) || {},
@@ -106,14 +113,15 @@ export default (cmd: Command) => {
             description: meta.head,
             route,
             arguments:
-              Object.entries((r.schema?.params || {}) as Record<string, STSchema>)?.map(([k, p]) => {
-                let type = schemaToTypeStr({ ...p, [Optional]: false })
-                return {
-                  name: k,
-                  type: type === 'boolean' ? '' : `<${type}>`,
-                  description: p?.description || ''
+              Object.entries((route?.params || {}) as Record<string, { type: string; description?: string }>)?.map(
+                ([k, p]) => {
+                  return {
+                    name: k,
+                    type: p.type === 'boolean' ? '' : `<${p.type}>`,
+                    description: p?.description || ''
+                  }
                 }
-              }) || [],
+              ) || [],
             options:
               Object.entries((r.schema?.query || {}) as Record<string, STSchema>)?.map(([k, o]) => {
                 let type = schemaToTypeStr({ ...o, [Optional]: false })

package/bin/res/cli.template.js

@@ -100,7 +100,7 @@ const formatDefault = def =>
     : def ?? 'undefined';
 
 result = commands.map(c=>{
-  let args = c.arguments.map(a=>`.argument("${a.type}", "${a.description}")`)
+  let args = c.arguments.map(a=>`.argument("${a.name}", "${a.description || a.name+' argument' || ''}")`)
   let optionsBase = [
     {name: '%format', short:'%f', type: '[string]', description: 'response format [\'s\',\'h\',\'b\',\'t\',\'p\']', default:["s","b","p"]},
     {name: '%header', short:'%h', type: '<string...>', description: 'request header formated as headerName=headerValue', default:[]},

package/bin/res/client.template.ts

@@ -42,8 +42,9 @@ type PGR<
   O extends number = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226
 > = Promise<GR<S, B, O>>
 
-type RequestOptions<H = any, B = any> = {
+type RequestOptions<H = any, Q = any, B = any> = {
   headers?: H
+  query?: Q
   body?: B
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD'
 }
@@ -61,7 +62,7 @@ export default class GalbeClient {
     return`${method} = {\n${list.map( r => {
       let p = Object.entries(r.params)
       let schemas = Object.keys(r.schemas).length ?
-        `<${r.schemas.headers??'any'},${r.schemas.body??'any'}>`: 
+        `<${r.schemas.headers??'any'},${r.schemas.query??'any'},${r.schemas.body??'any'}>`: 
         ''
       let oks = Object.keys(r.schemas?.response||{}).filter(s=>s>=200&&s<300)
       let responses = Object.keys(r.schemas?.response||{}).length ?
@@ -79,6 +80,8 @@ export default class GalbeClient {
 
   async fetch(path: string, options: RequestOptions) {
     let url = `${this?.config?.server?.url ?? ''}${path}`
+    const params = new URLSearchParams(options?.query || {})
+    url = `${url}?${params.toString()}`
     let res = await fetch(url, {
       method: options?.method || 'GET',
       headers: { ...DEFAULT_HEADERS, ...(options?.headers || {}) },
@@ -148,7 +151,7 @@ export default class GalbeClient {
     return list.filter(r=>r.alias).map(r => {
       let p = Object.entries(r.params)
       let schemas = Object.keys(r.schemas).length ?
-        `<${r.schemas.headers??'any'},${r.schemas.body??'any'}>`: 
+        `<${r.schemas.headers??'any'},${r.schemas.query??'any'},${r.schemas.body??'any'}>`: 
         ''
       let oks = Object.keys(r.schemas?.response||{}).filter(s=>s>=200&&s<300)
       let responses = Object.keys(r.schemas?.response||{}).length ?

package/bin/util.ts

@@ -58,7 +58,7 @@ export const watchDir = async (
   })
 }
 export const instanciateRoutes = async (g: Galbe) => {
-  console.log('🏗️  \x1b[1;30mConstructing routes\x1b[0m\n')
+  console.log('🏗️  \x1b[1mConstructing routes\x1b[0m\n')
   // Main thread routes definitions
   let hasMainRoutes = false
   walkRoutes(g.router.routes, r => {
@@ -102,6 +102,25 @@ export const softMerge = (base, override) => {
   return base
 }
 
+export const killPort = async (port: number) => {
+  let getProcCmd: string[], killCmd: (port: string) => string[]
+
+  if (process.platform === 'win32') {
+    getProcCmd = ['cmd', '-c', `netstat -aon | findstr ${port}`]
+    killCmd = (pid: string) => ['taskkill', '/pid', pid, '/f']
+  } else {
+    getProcCmd = ['lsof', '-t', `-i:${port}`, '-sTCP:LISTEN']
+    killCmd = (pid: string) => ['kill', '-9', pid]
+  }
+
+  let proc = Bun.spawn(getProcCmd, { stdout: 'pipe' })
+  const pid = (await new Response(proc.stdout).text()).trim()
+  if (pid) {
+    proc = Bun.spawn(killCmd(pid), { stdout: 'pipe' })
+    await proc.exited
+  }
+}
+
 export const HttpStatus = {
   100: 'Continue',
   101: 'Switching Protocols',

package/docs/cli.md

@@ -0,0 +1,336 @@
+# CLI
+
+A Command Line Interface is shipped with Galbe package. You can use it to perform useful tasks around your application.
+
+After [Installing Galbe](getting-started.md#automatic-installation), the CLI will be available locally to your project.
+
+However, if you want to use it directly from your terminal, you must either:
+
+Install it globally using the following command:
+
+```bash
+$ bun install -g galbe
+```
+
+Run it with `bunx`:
+
+```bash
+$ bunx galbe
+```
+
+## dev
+
+Start a dev server running your Galbe application.
+
+#### Arguments
+
+| Name  | Description                                              |
+| ----- | -------------------------------------------------------- |
+| index | The js or ts file that export you Galbe server instance. |
+
+#### Options
+
+| Short | Long      | Descritpion                 | Default |
+| ----- | --------- | --------------------------- | ------- |
+| -p    | --port    | port number [1-65535]       | 3000    |
+| -w    | --watch   | watch file changes          | false   |
+| -nc   | --noclear | don't clear on file changes | false   |
+
+#### Example
+
+```js
+// index.js
+
+import { Galbe } from 'galbe'
+
+export default new Galbe()
+```
+
+```bash
+$ galbe dev index.js -p 7357 --watch
+```
+
+## build
+
+Bundle your Galbe application.
+
+#### Arguments
+
+| Name  | Description                                              |
+| ----- | -------------------------------------------------------- |
+| index | The js or ts file that export you Galbe server instance. |
+
+#### Options
+
+| Short | Long      | Descritpion                    | Default  |
+| ----- | --------- | ------------------------------ | -------- |
+| -o    | --out     | output directory               | dist/app |
+| -C    | --compile | create a standalone executable | false    |
+| -c    | --config  | bun config (js or ts)          | -        |
+
+#### Example
+
+```js
+// index.js
+
+import { Galbe } from 'galbe'
+
+export default new Galbe()
+```
+
+```bash
+$ galbe build index.js
+```
+
+## generate
+
+Generate resources arround your Galbe application.
+
+### client
+
+Generate a client for your Galbe application.
+
+#### Arguments
+
+| Name  | Description                                              |
+| ----- | -------------------------------------------------------- |
+| index | The js or ts file that export you Galbe server instance. |
+
+#### Options
+
+| Short | Long     | Descritpion                | Default                              |
+| ----- | -------- | -------------------------- | ------------------------------------ |
+| -o    | --out    | output file                | dist/(client.ts \| client.js \| cli) |
+| -t    | --target | build target [ts, js, cli] | ts                                   |
+
+#### Examples
+
+Let's setup a new Galbe project:
+
+```bash
+$ bun create galbe galbe-example -t hello -l ts
+$ cd galbe-example
+$ bun install
+```
+
+> [!NOTE]
+> In order for the following examples to work, you must ensure that an instance of you galbe app is running on port 3000.
+> You can do that by running `bun run dev`.
+
+##### JS or TS client
+
+To generate a JS or TS client of that application, you can run the following command:
+
+```bash
+$ galbe generate client index.ts
+```
+
+This will generate a `dist/client.ts` client lib by default.
+You can import it and use it like in the following example:
+
+```ts
+// client_example.ts
+
+import HelloClient from './dist/client'
+
+const client = new HelloClient({ server: { url: 'http://localhost:3000' } })
+
+const response = await client.hello('Bob', { query: { age: 42 } })
+// This is equivalent as calling
+// const response = await client.get["/hello/:name"]("Bob", { query: { age: 42 } })
+
+if (response.ok) console.log(await response.body())
+// Hello Bob! You're 42 y.o.
+```
+
+##### CLI client
+
+To generate a CLI of that application, you can run the following command:
+
+```bash
+$ galbe generate client index.ts -t cli
+```
+
+This will generate a `cli` binary file under `dist` directory by default.
+
+```bash
+$ ./dist/cli --help
+Usage: galbe-example [options] [command]
+
+Options:
+  -V, --version    output the version number
+  -h, --help       display help for command
+
+Commands:
+  hello [options]  Greeting endpoint
+  help [command]   display help for command
+```
+
+```bash
+$ ./dist/cli hello --help
+Usage: galbe-example hello [options] <name>
+
+Greeting endpoint
+
+Arguments:
+  name                        name argument
+
+Options:
+  -%f, --%format [string]     response format ['s','h','b','t','p'] (default: ["s","b","p"])
+  -%h, --%header <string...>  request header formated as headerName=headerValue (default: [])
+  -%q, --%query <string...>   query param formated as paramName=paramValue (default: [])
+  -%b, --%body <string>       request body (default: "")
+  -%bf, --%bodyFile <path>    request body file (default: "")
+  -a, --age <number>
+  -h, --help                  display help for command
+```
+
+```bash
+$ ./dist/cli hello Pierre -a 29
+200
+Hello Pierre! You're 29 y.o.
+```
+
+> [!NOTE]
+> In order to be able to fetch the correct server url, the cli requires to set an env variable `GCLI_SERVER_URL` with the url of your Galbe app.
+
+### spec
+
+Generate the spec of your Galbe application.
+
+#### Arguments
+
+| Name  | Description                                              |
+| ----- | -------------------------------------------------------- |
+| index | The js or ts file that export you Galbe server instance. |
+
+#### Options
+
+| Short | Long     | Descritpion                                      | Default                 |
+| ----- | -------- | ------------------------------------------------ | ----------------------- |
+| -t    | --target | spec target [openapi:3.0:json, openapi:3.0:yaml] | openapi:3.0:yaml        |
+| -b    | --base   | base spec file                                   | -                       |
+| -o    | --out    | output file                                      | spec/api.(yaml \| json) |
+
+#### Example
+
+Let's try to generate the specof the project defined in the previous client section. You can then run:
+
+```bash
+$ galbe generate spec index.ts
+```
+
+This should generate the following `spec/api.yaml` file:
+
+```yaml
+openapi: 3.0.3
+info:
+  title: galbe-app
+  version: 0.1.0
+paths:
+  /hello/{name}:
+    get:
+      summary: Greeting endpoint
+      operationId: hello
+      parameters:
+        - name: age
+          in: query
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: OK
+          content:
+            text/plain:
+              schema:
+                type: string
+```
+
+### code
+
+Generate the code and project structure from spec.
+
+#### Arguments
+
+| Name  | Description                                                |
+| ----- | ---------------------------------------------------------- |
+| input | The input spec file from which the code will be generated. |
+
+#### Options
+
+| Short | Long     | Descritpion                                       | Default                    |
+| ----- | -------- | ------------------------------------------------- | -------------------------- |
+| -f    | --format | input format [openapi:3.0:yaml, openapi:3.0:json] | openapi:3.0:(yaml \| json) |
+| -t    | --target | source target [ts, js]                            | ts                         |
+| -o    | --out    | output dir                                        | src                        |
+| -F    | --force  | force overriding output                           | false                      |
+
+#### Example
+
+For that example, we will generate the Galbe source code from the [Swagger Petstore Openapi spec](https://petstore3.swagger.io/).
+
+First, initiate a new bun project and install the galbe dependency.
+
+```bash
+$ mkdir petstore && cd petstore
+$ bun init && bun add galbe
+```
+
+Now modify the `index.ts` file with the following content:
+
+```ts
+import { Galbe } from 'galbe'
+
+export default new Galbe()
+```
+
+Then download the petstore json spec from Swagger website into `petstore.spec.json`:
+
+```bash
+$ curl -o petstore.spec.json https://petstore3.swagger.io/api/v3/openapi.json
+```
+
+You can now generate the sources from the petstore spec:
+
+```bash
+$ galbe generate code petstore.spec.json
+```
+
+This should generate the code of our application in the `src` directory by default.
+
+To test that the code was successfully generated, you can run:
+
+```bash
+$ bunx galbe dev index.ts
+🏗️  Constructing routes
+
+    src/routes/pet.route.ts
+    [PUT]     /pet                     Update an existing pet
+    [POST]    /pet                     Add a new pet to the store
+    [GET]     /pet/findByStatus        Finds Pets by status
+    [GET]     /pet/findByTags          Finds Pets by tags
+    [GET]     /pet/:petId              Find pet by ID
+    [POST]    /pet/:petId              Updates a pet in the store with form data
+    [DELETE]  /pet/:petId              Deletes a pet
+    [POST]    /pet/:petId/uploadImage  uploads an image
+
+    src/routes/store.route.ts
+    [GET]     /store/inventory       Returns pet inventories by status
+    [POST]    /store/order           Place an order for a pet
+    [GET]     /store/order/:orderId  Find purchase order by ID
+    [DELETE]  /store/order/:orderId  Delete purchase order by ID
+
+    src/routes/user.route.ts
+    [POST]    /user                 Create user
+    [POST]    /user/createWithList  Creates list of users with given input array
+    [GET]     /user/login           Logs user into the system
+    [GET]     /user/logout          Logs out current logged in user session
+    [GET]     /user/:username       Get user by user name
+    [PUT]     /user/:username       Update user
+    [DELETE]  /user/:username       Delete user
+
+done
+
+🚀 Server running at http://localhost:3000
+```

package/docs/getting-started.md

@@ -14,29 +14,40 @@ This is the recommended way of setting 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.
+
+Now you can navigate to your newly created project and install it:
+
+```bash
 $ cd app
 $ bun install
 ```
 
-This will create a new project under `app` directory and install it.
-
-Now you can start the dev server by running:
+And start the dev server by running:
 
 ```bash
 $ bun dev
-```
+🏗️  Constructing routes
+
+    hello.route.ts
+    [GET]     /hello/:name  Greeting endpoint
 
-This will start a web server on `localhost:3000`.
+done
 
-To verify that the project was setup correctly and is running, try to reach `localhost:3000/hello` endpoint, this should return following greeting message:
+🚀 Server running at http://localhost:3000
+```
+
+Let's try to reach the hello endpoint:
 
 ```bash
-$ curl localhost:3000/hello
-Hello from Galbe!
+$ curl localhost:3000/hello/John?age=32
+Hello John! You're 32 y.o.
 ```
 
 > [!TIP]  
-> By default, the dev server automatically reloads on every file change.
+> 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.
 
 ## Manual installation
 
@@ -59,15 +70,15 @@ Open `package.json` file and add the following scripts:
 }
 ```
 
-As you can see, those scripts rely on Galbe CLI to run and build the application. You will find more info about Galbe CLI available options in the next section [Galbe CLI](#galbe-cli).
+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.
 
 This require your `index.ts` to export a default Galbe instance in order to work. As in the following example:
 
 ```ts
 import { Galbe } from 'galbe'
 
-const g = new Galbe({ port: 3000 })
-g.get('/hello', () => 'Hello Mom!')
+const galbe = new Galbe({ port: 3000 })
+galbe.get('/hello', () => 'Hello Mom!')
 
 export default galbe
 ```
@@ -77,40 +88,6 @@ This is the recommended way to proceed but it is not mandatory. Galbe instances
 > [!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]
-```
-
-Here are the available commands:
-
-**dev**
-
-Start a dev server running your Galbe application.
-
-_argument_
-
-The path of the file exporting your Galbe instance
-
-_options_
-
-- `--port` or `-p`: port number (default: 3000)
-- `--watch` or `-w`: watch file changes (default: true)
-
-**build**
-
-Bundle your Galbe application.
-
-_argument_
-
-The path of the file exporting your Galbe instance
-
-_options_
-
-- `--out` or `-o`: output file | directory (default: app | dist )
-- `--compile` or `-c`: create a standalone executable (default: false)
-
 ## Configuration
 
 To configure your Galbe server, you should pass your configuration to the Galbe constructor when you instanciate it.
@@ -121,6 +98,10 @@ 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`.
@@ -137,6 +118,16 @@ A Glob Pattern or a list of Glob patterns defining the route files to be analyze
 
 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`.
@@ -229,3 +220,27 @@ You can find more info about Route Files definition in the [Routes Files](routes
 
 > [!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.
+
+## How to debug
+
+The easiest way to debug your app is by installing 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:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "bun",
+      "request": "launch",
+      "name": "Debug Galbe",
+      "program": "node_modules/galbe/bin/cli.ts",
+      "env": { "TERM": "xterm" },
+      "cwd": "${workspaceFolder}",
+      "runtime": "bun",
+      "runtimeArgs": ["dev", "index.ts", "--watch", "--force"]
+    }
+  ]
+}
+```

package/docs/plugins.md

@@ -17,7 +17,7 @@ type GalbePlugin = {
 
 **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.*`.
+The name should be a Unique Plugin Identifier. It should be chosen to be unique to avoid conflicts with other potential plugins. Ideally, it will have the form of `com.example.myplugin`.
 
 **init**
 
@@ -60,59 +60,54 @@ galbe.use(plugin)
 
 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).
 
+deprecated.plugin.ts
+
 ```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)
-            }
-          }
-        }
+import type { GalbePlugin } from 'galbe'
+import { walkMetaRoutes } from 'galbe/utils'
+
+const PLUGIN_ID = 'dev.galbe.deprecated'
+
+export default () => {
+  let deprecateds = new Set<string>()
+  return {
+    name: PLUGIN_ID,
+    // Init the plugin, check for deprecated metadata tags
+    init(_config, galbe) {
+      if (galbe.meta) {
+        walkMetaRoutes(galbe.meta, (method, path, meta) => {
+          if (meta.deprecated) deprecateds.add(JSON.stringify({ method, path }))
+        })
+      }
+    },
+    // Check if the current route is deprecated; if so, flag it as such and log it
+    onRoute(context) {
+      let r = context.route
+      if (!r) return
+      if (deprecateds.has(JSON.stringify({ method: r.method, path: r.path }))) {
+        console.warn(`Call to deprecated route "${r.method} ${r.path}"`)
+      }
+    },
+    // Add a header to the response if the route has been flagged as deprecated
+    afterHandle(response, context) {
+      let r = context.route
+      if (!r) return
+      if (deprecateds.has(JSON.stringify({ method: r.method, path: r.path }))) {
+        response.headers.set('x-deprecated', 'true')
       }
     }
-  }
-  // Check if the current route is deprecated; if so, flag it as such and log 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}`)
-    }
-  }
-  // Add 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')
-    }
-  }
+  } as GalbePlugin
 }
-
-export default new MyPlugin()
 ```
 
-```ts
-// index.ts
+index.ts
 
+```ts
 import { Galbe } from 'galbe'
-import config from './galbe.config'
-import myPlugin from './myPlugin'
+import deprecatedPlugin from './deprecated.plugin'
 
-const galbe = new Galbe(config)
-galbe.use(myPlugin)
+const galbe = new Galbe()
+galbe.use(deprecatedPlugin())
 
 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/routes.md

@@ -82,7 +82,7 @@ galbe.get(
 > [!NOTE]
 > This feature is only available if you run/build the app via the [Galbe CLI](getting-started.md#galbe-cli), which is the case by default if you created your app following the [Automatic Installation](getting-started.md#automatic-installation) step or if you configured your package.json to do so.
 
-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.
+The Automatic Route Analyzer is responsible for analyzing all the Route Files of your project and setting up the route definitions for your Galbe server automatically. By default, the analyzer will search for Route Files matching paths like `src/**/*.route.{js,ts}`. This can be configured by modifying the value of `routes` property of your Galbe configuration. A value of `false` will disable the route analyzer.
 
 ### Route Files
 
@@ -94,15 +94,6 @@ export default g => {
 }
 ```
 
-The same example in Typescript:
-
-```ts
-import type { Galbe } from 'galbe'
-export default (g: Galbe) => {
-  g.get('/foo/:bar', ctx => ctx.params.bar)
-}
-```
-
 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
@@ -120,5 +111,3 @@ export default g => {
   g.get('/foo/:bar', ctx => ctx.params.bar)
 }
 ```
-
-You will find more information about comment metadata and how to use them along with examples in the [Plugin](plugins.md) section.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.4.1",
+  "version": "0.6.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/extras/spec/openapi.serializer.ts

@@ -165,7 +165,10 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     let meta = metaRoutes?.[r.path]?.[r.method]
     let path = r.path.replaceAll(/:([^\/]+)/g, '{$1}')
     if (!(path in paths)) paths[path] = {}
-    let tags = [...(meta?.tags?.split(' ')?.map((t: string) => t.trim()) || []), ...(meta?.tag || [])]
+    let tags = [
+      ...(meta?.tags?.split(' ')?.map((t: string) => t.trim()) || []),
+      ...(typeof meta?.tag === 'string' ? [meta?.tag] : meta?.tag || [])
+    ]
     let security: Record<string, any> = []
 
     let pathParam = r.schema?.params

package/src/index.ts

@@ -122,7 +122,9 @@ export class Galbe {
   config: GalbeConfig
   meta?: Array<RouteFileMeta> = []
   router: GalbeRouter
-  errorHandler?: ErrorHandler
+  startCb: (() => void)[] = []
+  stopCb: (() => void)[] = []
+  errorCb: ErrorHandler[] = []
   listening: boolean = false
   server?: Server
   plugins: GalbePlugin[] = []
@@ -148,24 +150,34 @@ export class Galbe {
       if (p.init) await p.init(this.config?.plugin?.[p.name] || {}, this)
     }
   }
-  async listen(port?: number) {
+  async listen(port?: number, hostname?: string) {
     port = port || this.config?.port || 3000
+    hostname = hostname || this.config?.hostname || 'localhost'
     this.config.port = port
+    this.config.hostname = hostname
     if (this.listening) this.stop()
     await this.init()
-    this.server = await server(this, port)
+    this.server = await server(this, port, hostname)
     if (Bun.env.BUN_ENV === 'development') {
-      const url = `http://localhost:${port}${this.config?.basePath || ''}`
-      console.log(`\x1b[1;30m🚀 Server running at\x1b[0m \x1b[4;34m${url}\x1b[0m\n`)
+      const url = `http${this.config.tls ? 's' : ''}://${hostname}:${port}${this.config?.basePath || ''}`
+      console.log(`\x1b[1m🚀 Server running at\x1b[0m \x1b[4;34m${url}\x1b[0m\n`)
     }
     this.listening = true
+    for (let sh of this.startCb) sh()
     return this.server
   }
   stop() {
     this.server?.stop(true)
+    for (let sh of this.stopCb) sh()
+  }
+  onStart(callback: () => void) {
+    this.startCb.push(callback)
+  }
+  onStop(callback: () => void) {
+    this.stopCb.push(callback)
   }
   onError(handler: ErrorHandler) {
-    this.errorHandler = handler
+    this.errorCb.push(handler)
   }
   get: Endpoint<'get'> = <
     Path extends string,
@@ -203,7 +215,6 @@ export class Galbe {
       | Hook<'post', Path, RequestSchema<'post', Path, H, P, Q, B, R>>[]
       | Handler<'post', Path, RequestSchema<'post', Path, H, P, Q, B, R>>,
     arg4?: Handler<'post', Path, RequestSchema<'post', Path, H, P, Q, B, R>>
-    //@ts-ignore
   ) => this.add(overloadDiscriminer(this, 'post', path, arg2, arg3, arg4))
   put: Endpoint<'put'> = <
     Path extends string,

package/src/routes.ts

@@ -1,4 +1,4 @@
-import type { GalbeConfig, Route } from './types'
+import type { GalbeConfig, Method, Route } from './types'
 
 import { readdir, lstat } from 'fs/promises'
 import { extname } from 'path'
@@ -13,7 +13,7 @@ export const DEFAULT_ROUTE_PATTERN = 'src/**/*.route.{js,ts}'
 export type RouteMeta = { head?: string } & Record<string, boolean | string | string[]>
 export type RoutesMeta = {
   header: Record<string, boolean | string | string[]>
-  routes: Record<string, Record<string, RouteMeta>>
+  routes: Record<string, Partial<Record<Method, RouteMeta>>>
 }
 export type RouteInstanciationCallback = <T extends 'add' | 'error'>(event: {
   type: T
@@ -204,7 +204,7 @@ export const metaAnalysis = async (filePath: string): Promise<RoutesMeta> => {
             // @ts-ignore
             const path = node.arguments[0].value
             // @ts-ignore
-            const method = node.callee.property.name
+            const method = node.callee.property.name as Method
             const line = node.loc?.start.line || -1
             const col = node.loc?.start.column || -1
             const com = comments?.[line]?.[col - 1] ? comments[line][col - 1] : ''

package/src/server.ts

@@ -4,6 +4,9 @@ import { InternalError, RequestError } from './types'
 import { parseEntry, requestBodyParser, requestPathParser, responseParser } from './parser'
 import { Galbe } from './index'
 import { validateResponse } from './validator'
+import { logger } from 'girok'
+
+type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
 
 const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']
 const EMPTY_BODY_METHODS = ['GET', 'OPTIONS', 'HEAD']
@@ -20,7 +23,7 @@ const setupPluginCallbacks = (galbe: Galbe) => ({
   afterHandle: galbe.plugins.filter(p => p.afterHandle)
 })
 
-export default async (galbe: Galbe, port?: number) => {
+export default async (galbe: Galbe, port?: number, hostname?: string) => {
   const router = galbe.router
   if (galbe?.config?.basePath && galbe?.config?.basePath[0] !== '/')
     galbe.config.basePath = `/${galbe?.config?.basePath}`
@@ -28,17 +31,16 @@ export default async (galbe: Galbe, port?: number) => {
 
   return Bun.serve({
     port: port || galbe.config?.port || 3000,
+    hostname: hostname || galbe.config?.hostname || 'localhost',
+    tls: galbe.config?.tls,
+
     async fetch(req) {
       if (!METHODS.includes(req.method)) return new Response('', { status: 501 })
-      const context: Context = {
+      const context = {
         request: req,
         set: { headers: {} },
-        headers: {},
-        params: {},
-        query: {},
-        body: {},
         state: {}
-      }
+      } as MakeOptional<Context, 'headers' | 'params' | 'query' | 'body'>
       for (const p of pluginsCb.onFetch) {
         //@ts-ignore
         const r = await p.onFetch(context)
@@ -130,23 +132,23 @@ export default async (galbe: Galbe, port?: number) => {
                 await callChain[idx + 1].call()
               }
             }
-            let r = await hook(context, next)
+            let r = await hook(context as Context, next)
             if (r) return r
             if (!nextCalled && !handlerCalled) await next()
           }
         }))
         callChain.push({
           call: async () => {
-            response = await handlerWrapper(context)
+            response = await handlerWrapper(context as Context)
             context.set.status = response instanceof Response ? response.status : 200
           }
         })
         if (callChain.length > 1) {
           let r = await callChain[0].call()
           if (r) response = r
-        } else response = await handlerWrapper(context)
+        } else response = await handlerWrapper(context as Context)
 
-        const parsedResponse = responseParser(response, context, schema.response)
+        const parsedResponse = responseParser(response, context as Context, schema.response)
 
         if (galbe.config?.responseValidator?.enabled && schema.response)
           validateResponse(response, schema.response, parsedResponse.status || 200)
@@ -161,7 +163,7 @@ export default async (galbe: Galbe, port?: number) => {
       } catch (error) {
         context.set.status = error instanceof RequestError ? error.status : 500
         let customError
-        if (galbe.errorHandler) customError = responseParser(galbe.errorHandler(error, context), context)
+        for (let eh of galbe.errorCb) customError = responseParser(eh(error, context as Context), context as Context)
         if (customError) return customError
         if (error instanceof InternalError) {
           console.log(`Internal Error`, error?.payload || '')

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ServeOptions, TLSServeOptions } from 'bun'
+import type { ServeOptions, TLSOptions, TLSServeOptions } from 'bun'
 import type {
   STAny,
   STArray,
@@ -96,7 +96,9 @@ export type STQuery = Record<string, STQueryValue>
  */
 export type GalbeConfig = {
   port?: number
+  hostname?: string
   basePath?: string
+  tls?: TLSOptions
   server?: Exclude<ServeOptions, 'port'> | TLSServeOptions
   routes?: boolean | string | string[]
   router?: { cacheEnabled: boolean }
@@ -306,8 +308,8 @@ export class InternalError extends RequestError {
 export type GalbePlugin = {
   name: string
   init?: (config: any, galbe: Galbe) => MaybePromise<void>
-  onFetch?: (context: Context) => MaybePromise<Response | void>
-  onRoute?: (context: Context) => MaybePromise<Response | void>
+  onFetch?: (context: Pick<Context, 'request' | 'set' | 'state'>) => MaybePromise<Response | void>
+  onRoute?: (context: Pick<Context, 'request' | 'set' | 'state' | 'route'>) => MaybePromise<Response | void>
   beforeHandle?: (context: Context) => MaybePromise<Response | void>
   afterHandle?: (response: Response, context: Context) => MaybePromise<Response | void>
   cli?: (commands: GalbeCLICommand[]) => MaybePromise<GalbeCLICommand[] | void>

package/src/util.ts

@@ -1,5 +1,5 @@
-import type { Route, RouteNode } from '.'
-import type { RouteMeta } from './routes'
+import type { Method, Route, RouteNode } from '.'
+import type { RouteFileMeta, RouteMeta } from './routes'
 
 const METHOD_COLOR: Record<string, string> = {
   get: '\x1b[32m',
@@ -10,6 +10,7 @@ const METHOD_COLOR: Record<string, string> = {
   options: '',
   head: ''
 }
+const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g
 
 export const logRoute = (
   r: { method: string; path: string },
@@ -17,19 +18,38 @@ export const logRoute = (
   format?: { maxPathLength?: number }
 ) => {
   let color = METHOD_COLOR?.[r.method] || ''
-  console.log(
-    `    [${color}${`${r.method.toUpperCase()}\x1b[0m]`.padEnd(12, ' ')} ${r.path
-      .padEnd(format?.maxPathLength ?? r.path.length, ' ')
-      .replaceAll(/:([^\/]+)/g, '\x1b[0;33m:$1\x1b[0m')}${meta?.head ? `  ${meta.head}` : ''}`
-  )
+  let routeLog = `[${color}${`${r.method.toUpperCase()}\x1b[0m]`.padEnd(12, ' ')} ${r.path
+    .padEnd(format?.maxPathLength ?? r.path.length, ' ')
+    .replaceAll(/:([^\/]+)/g, '\x1b[0;33m:$1\x1b[0m')}${meta?.head ? `  ${meta.head}` : ''}\x1b[0m`
+  if (meta?.deprecated) routeLog = `\x1b[0;9m\x1b[38;5;244m${routeLog.replaceAll(ansiRegex, '')}\x1b[0m`
+  console.log(`    ${routeLog}`)
 }
 
+/**
+ * Walk over the routes tree. A callback is called for each route with Route infos.
+ */
 export const walkRoutes = (node: RouteNode, cb: (route: Route) => void) => {
   if (node?.routes) Object.values(node.routes).forEach(r => cb(r))
   for (let c of Object.values(node?.children || {})) walkRoutes(c, cb)
   if (node?.param) walkRoutes(node.param, cb)
 }
 
+/**
+ * Walk over the routes metadata tree. A callback is called for each route metadata with RouteMeta infos.
+ */
+export const walkMetaRoutes = (
+  meta: RouteFileMeta[],
+  cb: (method: Method, path: string, routeMeta: RouteMeta) => void
+) => {
+  for (const f of meta) {
+    for (const [path, methods] of Object.entries(f.routes)) {
+      for (const [method, meta] of Object.entries(methods)) {
+        cb(method as Method, path, meta)
+      }
+    }
+  }
+}
+
 export const isIterator = (obj: any) => typeof obj?.next === 'function'
 
 export const HttpStatus = {