galbe 0.5.0 → 0.6.1

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: '[bug] '
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+
+<!-- A clear and concise description of what the bug is. -->
+
+**Steps To Reproduce**
+
+<!-- Steps to reproduce the behavior -->
+
+**Expected behavior**
+
+<!-- A clear and concise description of what you expected to happen. -->
+
+**Screenshots**
+
+<!-- If applicable, add screenshots to help explain your problem. -->
+
+**Environment (please complete the following information):**
+
+<!-- To help us diagnose the issue, please navigate to the root of your project in your terminal and execute "bunx galbe info". Then paste the output bellow -->
+
+```txt
+
+```
+
+**Additional context**
+
+<!-- Add any other context about the problem here. -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: '[feat] '
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+**Describe the solution you'd like**
+
+<!-- A clear and concise description of what you want to happen. -->
+
+**Describe alternatives you've considered**
+
+<!-- A clear and concise description of any alternative solutions or features you've considered. -->
+
+**Additional context**
+
+<!-- Add any other context or screenshots about the feature request here. -->

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/deploy.yml/dispatches \
+          https://api.github.com/repos/pierre-cm/galbe-website/actions/workflows/static.yml/dispatches \
           -d '{"ref":"main"}'

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)
@@ -22,3 +25,5 @@ bun install && bun dev
 The detailed documentation is available at [galbe.dev](https://galbe.dev).
 
 ## Contributing
+
+Please refer to the [Contributing Guide](https://github.com/pierre-cm/galbe/blob/main/docs/CONTRIBUTING.md) to start contributing to Galbe.

package/bin/cli.ts

@@ -7,11 +7,13 @@ import { pckg } from './util'
 import dev from './commands/dev'
 import build from './commands/build'
 import generate from './commands/generate'
+import info from './commands/info'
 
 program.name('galbe').description(pckg.description).version(pckg.version)
 
 dev(program.command('dev'))
 build(program.command('build'))
 generate(program.command('generate'))
+info(program.command('info'))
 
 program.parse()

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/commands/info.ts

@@ -0,0 +1,29 @@
+import os from 'os'
+import { Command } from 'commander'
+
+export default async (cmd: Command) => {
+  cmd.description('print informations about the current os, bun and galbe version').action(async () => {
+    const osName = os.type()
+    const osArch = os.arch()
+    const osVersion = os.release()
+
+    const bunVersion = Bun.version
+    const bunRevision = Bun.revision
+
+    let localPckg: any = {}
+    try {
+      localPckg = await Bun.file('./node_modules/galbe/package.json').json()
+    } catch (err) {}
+    const galbeVersion = localPckg?.version || 'not found'
+
+    console.log('OS')
+    console.log(`  name: ${osName}`)
+    console.log(`  arch: ${osArch}`)
+    console.log(`  version: ${osVersion}`)
+    console.log('Bun')
+    console.log(`  version: ${bunVersion}`)
+    console.log(`  revision: ${bunRevision}`)
+    console.log('Galbe')
+    console.log(`  version: ${galbeVersion}`)
+  })
+}

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/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to Galbe
+
+First off, thank you for considering contributing to our project! We appreciate your time and effort and want to make this as easy and transparent as possible for everyone.
+
+## Create an Issue
+
+If you encounter a bug, want to propose a new feature, or something that could be improved, please create an issue. Here's how:
+
+1. **Check Existing Issues**: Before creating a new issue, please search the [existing issues](https://github.com/pierre-cm/galbe/issues) to see if someone else has already reported the same problem or suggested the same feature.
+
+2. **Open a New Issue**: If your issue is new, [open a new issue](https://github.com/pierre-cm/galbe/issues/new/choose) and provide the following details:
+
+   - **Title**: A concise summary of the issue.
+   - **Description**: A detailed description of the problem or suggestion. Include steps to reproduce the issue if applicable.
+   - **Screenshots**: If possible, include screenshots or other visual aids that help explain the issue.
+   - **Environment**: Mention the environment in which you encountered the issue (e.g., OS, Bun version).
+   - **Labels**: Assign appropriate labels (e.g., bug, enhancement) to help categorize your issue.
+
+3. **Follow Up**: Once your issue is submitted, be ready to provide additional information if requested. We'll do our best to address the issue promptly.
+
+## Create a Pull Request
+
+### 1. Fork the Repository
+
+If you haven't already, [fork Galbe's repository on GitHub](https://github.com/pierre-cm/galbe/fork). This will create a copy of this repository under your GitHub account.
+
+### 2. Clone Your Fork
+
+Clone the forked repository to your local machine:
+
+```bash
+git clone https://github.com/<your-username>/galbe.git
+cd galbe
+```
+
+### 3. Create a New Branch
+
+Before making any changes, create a new branch for your work. Branches help keep your changes separate from the main branch and make it easier to review and merge:
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+Use a descriptive name for your branch to indicate what you are working on.
+
+### 4. Make Your Changes
+
+Make the necessary changes in your branch. Be sure to follow the project's coding style and best practices.
+
+### 5. Commit Your Changes
+
+Once you’ve made your changes, commit them with a clear and descriptive message:
+
+```bash
+git add .
+git commit -m "Add feature X to do Y"
+```
+
+### 6. Push to Your Fork
+
+Push your changes to your forked repository on GitHub:
+
+```bash
+git push origin feature/your-feature-name
+```
+
+### 7. Create a Pull Request
+
+Once your changes are pushed to GitHub, you can create a pull request. Go to the [original repository](https://github.com/pierre-cm/galbe) on GitHub, and you should see an option to create a pull request from your branch.
+
+- Make sure to provide a detailed description of your changes and why they are necessary.
+- Link any related issues if applicable.
+- If your pull request is still a work in progress, mark it as a draft to let others know that you are not yet ready for a review.
+
+### 8. Respond to Feedback
+
+Once your pull request is submitted, it will be reviewed by the project maintainers. They may ask for changes or provide feedback. Please be responsive and make the necessary adjustments.
+
+### Coding Standards
+
+Please follow these coding standards to ensure consistency across the project:
+
+- **Code Style**: Follow the [style guide]().
+- **Commit Messages**: Use clear and descriptive commit messages.
+- **Documentation**: Update documentation where applicable. This includes comments in the code and other documentation files under the `docs` directory.
+
+## Code of Conduct
+
+We are committed to creating a welcoming and inclusive environment for everyone. To ensure this, all contributors are expected to adhere to the following guidelines:
+
+1. **Be Respectful**: Treat everyone with respect. Disagreements are inevitable, but it's important to remain courteous and constructive. Personal attacks, harassment, or offensive comments will not be tolerated.
+
+2. **Collaborate Openly**: Collaboration is key to the success of the project. Be open to feedback and suggestions from others. Constructive criticism should be welcomed and given in a positive manner.
+
+3. **Resolve Disagreements Constructively**: If you find yourself in a disagreement, seek to resolve it in a way that is constructive and respectful. If necessary, involve a project maintainer to help mediate.
+
+4. **Report Issues**: If you witness or experience any behavior that violates this Code of Conduct, please report it immediately to the project maintainers. We take all reports seriously and will address them promptly.
+
+By participating in this project, you agree to abide by this Code of Conduct.
+
+## Getting Help
+
+If you have any questions or need help, feel free to open an issue or contact one of the maintainers.
+
+Thank you for your contribution!

package/docs/cli.md

@@ -0,0 +1,340 @@
+# 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
+```
+
+Or 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
+
+index.js
+
+```js
+import { Galbe } from 'galbe'
+
+const g = new Galbe()
+g.get('example', () => '')
+
+export default g
+```
+
+```bash
+$ galbe dev index.js -p 7357 -w
+```
+
+## 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
+
+index.js
+
+```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 first 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:
+
+client_example.ts
+
+```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.
+```
+
+> [!IMPORTANT]
+> A `GCLI_SERVER_URL` environment variable must be defined. It should indicates the url of the Galbe server you want to target.
+> In that specific case `http://localhost:3000`.
+
+### 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
+$ 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

@@ -60,8 +60,9 @@ 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 type { GalbePlugin } from 'galbe'
 import { walkMetaRoutes } from 'galbe/utils'
 
@@ -84,7 +85,6 @@ export default () => {
       let r = context.route
       if (!r) return
       if (deprecateds.has(JSON.stringify({ method: r.method, path: r.path }))) {
-        context.state[PLUGIN_ID] = { deprecated: true }
         console.warn(`Call to deprecated route "${r.method} ${r.path}"`)
       }
     },
@@ -92,9 +92,7 @@ export default () => {
     afterHandle(response, context) {
       let r = context.route
       if (!r) return
-      console.log('yooo', r.method, r.path)
       if (deprecateds.has(JSON.stringify({ method: r.method, path: r.path }))) {
-        console.log('OK...')
         response.headers.set('x-deprecated', 'true')
       }
     }
@@ -102,17 +100,14 @@ export default () => {
 }
 ```
 
-```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.5.0",
+  "version": "0.6.1",
   "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/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

@@ -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,11 +18,11 @@ 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}`)
 }
 
 /**