galbe 0.9.0 → 0.10.0

package/docs/getting-started.md

@@ -1,12 +1,16 @@
 # Getting started
 
-Galbe is a Javascript web framework for building fast and versatile backend servers with Bun.
+Galbe is a Javascript web framework for building fast and versatile backend
+servers with Bun.
 
-Designed with simplicity in mind, Galbe allows you to quickly create and set up a project. In addition to its ease of use, Galbe also offers a range of useful features that help you focus on the core logic of your application.
+Designed with simplicity in mind, Galbe allows you to quickly create and set up
+a project. In addition to its ease of use, Galbe also offers a range of useful
+features that help you focus on the core logic of your application.
 
 ## Requirements
 
-To start developing your Galbe project, you first need to install [Bun](https://bun.sh).
+To start developing your Galbe project, you first need to install
+[Bun](https://bun.sh).
 
 ## Automatic installation
 
@@ -16,7 +20,9 @@ This is the recommended way of setting up a Galbe project.
 $ 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.
+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:
 
@@ -46,8 +52,9 @@ $ curl localhost:3000/hello/John?age=32
 Hello John! You're 32 y.o.
 ```
 
-> [!TIP]  
-> 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.
+> [!TIP]
+> 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
 
@@ -70,30 +77,37 @@ 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 it on the [CLI](cli.md) page.
+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:
+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'
+import { Galbe } from "galbe";
 
-const galbe = new Galbe({ port: 3000 })
-galbe.get('/hello', () => 'Hello Mom!')
+const galbe = new Galbe({ port: 3000 });
+galbe.get("/hello", () => "Hello Mom!");
 
-export default galbe
+export default galbe;
 ```
 
-This is the recommended way to proceed but it is not mandatory. Galbe instances also provide a `listen` method that will allow you to manually start your server instance from the code.
+This is the recommended way to proceed but it is not mandatory. Galbe instances
+also provide a `listen` method that will allow you to manually start your server
+instance from the code.
 
 > [!WARNING]
-> 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.
+> 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.
 
 ## Configuration
 
-To configure your Galbe server, you should pass your configuration to the Galbe constructor when you instanciate it.
+To configure your Galbe server, you should pass your configuration to the Galbe
+constructor when you instanciate it.
 
 ```ts
-const galbe = new Galbe(configuration)
+const galbe = new Galbe(configuration);
 ```
 
 ### Properties
@@ -112,11 +126,14 @@ The base path is added as a prefix to all the routes created.
 
 **routes**
 
-A Glob Pattern or a list of Glob patterns defining the route files to be analyzed by the [Automatic Route Analyzer](routes.md#automatic-route-analyzer). Default is `src/**/*.route.{js,ts}`.
+A Glob Pattern or a list of Glob patterns defining the route files to be
+analyzed by the [Automatic Route Analyzer](routes.md#automatic-route-analyzer).
+Default is `src/**/*.route.{js,ts}`.
 
 **plugin**
 
-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).
+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**
 
@@ -130,15 +147,21 @@ Enable or disable TLS support. Default value is `false`.
 
 **requestValidator.enabled**
 
-Enable or disable the _request_ schema validation (See [Request Schema definition](schemas.md#request-schema-definition)). Default value is `true`.
+Enable or disable the _request_ schema validation (See
+[Request Schema definition](schemas.md#request-schema-definition)). Default
+value is `true`.
 
 **responseValidator.enabled**
 
-Enable or disable the _response_ schema validation (See [Request Schema definition](schemas.md#request-schema-definition)). Default value is `true`.
+Enable or disable the _response_ schema validation (See
+[Request Schema definition](schemas.md#request-schema-definition)). Default
+value is `true`.
 
 ### Examples
 
-A common way to handle server configuration is to create new file `galbe.config.(js|ts|json)` at the root of your project directory and import it in your code. Here is an example:
+A common way to handle server configuration is to create new file
+`galbe.config.(js|ts|json)` at the root of your project directory and import it
+in your code. Here is an example:
 
 galbe.config.js
 
@@ -152,27 +175,31 @@ export default {
 index.js
 
 ```js
-import { Galbe } from 'galbe'
-import config from './galbe.config'
+import { Galbe } from "galbe";
+import config from "./galbe.config";
 
-export default new Galbe(config)
+export default new Galbe(config);
 ```
 
-> [!TIP]  
-> If you are using Typescript, you can import `GalbeConfig` type from galbe package to ensure type consistency for your configuration. Here is an example:
+> [!TIP]
+> If you are using Typescript, you can import `GalbeConfig` type from galbe
+> package to ensure type consistency for your configuration. Here is an example:
 >
 > ```ts
-> import type { GalbeConfig } from 'galbe'
+> import type { GalbeConfig } from "galbe";
 > const config: GalbeConfig = {
 >   port: Number(Bun.env.GALBE_PORT),
->   routes: 'routes/*.route.ts'
-> }
-> export default config
+>   routes: "routes/*.route.ts",
+> };
+> export default config;
 > ```
 
 ## 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}`.
+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}`.
 
 Here are two examples of valid project structures by default:
 
@@ -214,18 +241,26 @@ Here are two examples of valid project structures by default:
 └── tsconfig.json
 ```
 
-In both cases, the [Automatic Route Analyzer](routes.md#automatic-route-analyzer) will analyze `foo.route.ts` and `bar.route.ts` Route Files to find route definitions.
+In both cases, the
+[Automatic Route Analyzer](routes.md#automatic-route-analyzer) will analyze
+`foo.route.ts` and `bar.route.ts` Route Files to find route definitions.
 
-You can find more info about Route Files definition in the [Routes Files](routes.md#route-files) section.
+You can find more info about Route Files definition in the
+[Routes Files](routes.md#route-files) section.
 
 > [!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.
+> 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).
+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:
+You can then create a `.vscode/launch.json` config file in your project root
+directory. Here is an example of configuration:
 
 ```json
 {
@@ -239,7 +274,7 @@ You can then create a `.vscode/launch.json` config file in your project root dir
       "env": { "TERM": "xterm" },
       "cwd": "${workspaceFolder}",
       "runtime": "bun",
-      "runtimeArgs": ["dev", "index.ts", "--watch", "--force"]
+      "runtimeArgs": ["dev", "index.ts", "-w", "."]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Fast, lightweight and highly customizable JavaScript web framework based on Bun",
   "author": "Pierre Caillaud M (https://github.com/pierre-cm)",
   "type": "module",
@@ -29,6 +29,7 @@
   "license": "MIT",
   "scripts": {
     "test": "bun test",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false",
     "postinstall": "bun run ./scripts/postinstall.ts",
     "release": "release-it"
   },

package/src/extras/spec/openapi.serializer.ts

@@ -239,16 +239,17 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     if (r.schema.response && Object.keys(r.schema.response).length) {
       responses = Object.fromEntries(
         Object.entries(r.schema.response).map(([status, v]) => {
-          let s = Number(status) as keyof typeof HttpStatus
+          if(!v) return []
+          let s = status as keyof typeof HttpStatus | 'default'
           let { schema, isJson } = schemaToOpenapi(v)
           let { type, format } = resolveRef(schema)
           let media = schemaToMedia({ type, format, isJson } as SchemaType)
           let response: OpenAPIV3.ResponseObject = {
-            description: v.description || HttpStatus[Number(s) as keyof typeof HttpStatus] || 'Response',
+            description: v.description || HttpStatus[s as keyof typeof HttpStatus] || 'Response',
             content: { [media]: { schema: schema } }
           }
           if (components.responses && r.schema.response?.[s]?.id) {
-            components.responses[r.schema.response?.[s].id as string] = response
+            components.responses[r.schema.response?.[s]?.id as string] = response
             //@ts-ignore
             response = { $ref: `#/components/responses/${r.schema.response?.[s].id}` }
           }
@@ -260,9 +261,12 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         default: { description: HttpStatus[200] }
       }
     }
+    let summary = meta?.head.match(/^([^\n]+)/)?.[1]
+    console.log('#', r.method, r.path)
+    console.log(r.schema.body)
     paths[path][r.method] = {
       tags: tags.length ? tags : undefined,
-      summary: meta?.head,
+      summary: summary,
       operationId: meta?.operationId,
       parameters: parameters.length ? parameters : undefined,
       requestBody,

package/src/index.ts

@@ -111,6 +111,8 @@ export const $T = new SchemaType()
 
 export { RequestError } from './types'
 
+export const config = (config: GalbeConfig) => config
+
 /**
  * #### Galbe Server
  * Instanciate a Galbe web server
@@ -136,13 +138,10 @@ export class Galbe {
   plugins: GalbePlugin[] = []
   constructor(config?: GalbeConfig) {
     this.config = config ?? {}
-    this.config.routes = this.config.routes ?? true
     this.router = new GalbeRouter({
       prefix: this.config?.basePath || '',
       cacheEnabled: this.config?.router?.cacheEnabled
     })
-    this.config.requestValidator = config?.requestValidator ?? { enabled: true }
-    this.config.responseValidator = config?.responseValidator ?? { enabled: true }
   }
   private add(route: any) {
     this.router.add(route)

package/src/parser.ts

@@ -655,7 +655,7 @@ export const responseParser = (response: any, ctx: Context, schema?: STResponse)
   if (response instanceof Response) return response
   else if (typeof response === 'string') {
     if (!details?.headers?.has('content-type')) {
-      if (schema?.[details.status][Kind] === 'json') {
+      if (schema?.[details.status]?.[Kind] === 'json') {
         details?.headers?.set('content-type', 'application/json')
         response = `"${response}"`
       } else details?.headers?.set('content-type', 'text/plain')

package/src/routes.ts

@@ -234,7 +234,7 @@ export const defineRoutes = async (
   options: Pick<GalbeConfig, 'routes'>,
   proxy: GalbeProxy,
 ) => {
-  const routes = options?.routes === true ? DEFAULT_ROUTE_PATTERN : options?.routes
+  const routes = options?.routes === undefined || options?.routes === true ? DEFAULT_ROUTE_PATTERN : options?.routes
   if (!routes) return
   const root = process.cwd()
   if (typeof routes === 'string') {

package/src/server.ts

@@ -30,6 +30,7 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
 
   const server = Bun.serve({
     port: port || galbe.config?.port || 3000,
+    reusePort: galbe?.config?.reusePort,
     hostname: hostname || galbe.config?.hostname || 'localhost',
     tls: galbe.config?.tls,
 
@@ -81,7 +82,7 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
         context.params = inParams
 
         // request validation
-        if (galbe.config?.requestValidator?.enabled) {
+        if (galbe.config?.requestValidator?.enabled !== false) {
           let errors: RequestError[] = []
           try {
             if (schema?.headers)
@@ -150,7 +151,7 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
 
         const parsedResponse = responseParser(response, context as Context, schema.response)
 
-        if (galbe.config?.responseValidator?.enabled && schema.response)
+        if (galbe.config?.responseValidator?.enabled !== false && schema.response)
           validateResponse(response, schema.response, parsedResponse.status || 200)
 
         for (const p of pluginsCb.afterHandle) {
@@ -172,14 +173,20 @@ export default async (galbe: Galbe, port?: number, hostname?: string) => {
             headers: { 'Content-Type': 'application/json' }
           })
         } else if (error instanceof RequestError) {
-          let payload = ''
-          if (typeof error.payload === 'string') payload = error.payload
-          try {
-            payload = JSON.stringify(error.payload)
-          } catch (err) { }
+          let payload = error.payload
+          let headers = new Headers(error?.headers || {})
+          if (!headers.has('content-type')) {
+            if (typeof error.payload === 'string') headers.set('content-type', 'text/plain')
+            else {
+              headers.set('content-type', 'application/json')
+              try {
+                payload = JSON.stringify(error.payload)
+              } catch (err) { }
+            }
+          }
           return new Response(payload, {
             status: error.status,
-            headers: { 'Content-Type': 'application/json' }
+            headers
           })
         } else console.log(error)
         return new Response('"Internal Server Error"', {

package/src/types.ts

@@ -52,7 +52,7 @@ export type STResponseValue =
   | STStream
   | STAny
   | STNull
-export type STResponse = Record<number | 'default', STResponseValue>
+export type STResponse = Partial<Record<number | 'default', STResponseValue>>
 
 export type MaybeArray<T> = T | T[]
 export type MaybeSTArray<T extends STSchema> = T | STArray<T>
@@ -99,15 +99,25 @@ export type STQuery = Record<string, STQueryValue>
  * ```
  */
 export type GalbeConfig = {
+  /** The port number that the server will be listening on. */
   port?: number
+  /** Allow to share the same port across processes (Linux only). */
+  reusePort?: boolean
+  /** The hostname of the server. */
   hostname?: string
+  /** The base path is added as a prefix to all the routes created. */
   basePath?: string
+  /** Enable or disable TLS support. */
   tls?: TLSOptions
   server?: Exclude<ServeOptions, 'port'> | TLSServeOptions
+  /** A Glob Pattern or a list of Glob patterns defining the route files to be analyzed by the Automatic Route Analyzer. */
   routes?: boolean | string | string[]
   router?: { cacheEnabled: boolean }
+  /** A property that can be used by plugins to add plugin's specific configuration. */
   plugin?: Record<string, any>
+  /** Enable or disable the request schema validation.*/
   requestValidator?: { enabled: boolean }
+  /** Enable or disable the response schema validation.*/
   responseValidator?: { enabled: boolean }
 }
 /**
@@ -136,7 +146,7 @@ export type RequestSchema<
   P extends Partial<STParams<Path>> = Partial<STParams<Path>>,
   Q extends STQuery = STQuery,
   B extends STBody = STBody,
-  R extends Partial<STResponse> = Partial<STResponse>
+  R extends Partial<STResponse> = STResponse
 > = {
   headers?: H
   params?: P
@@ -194,7 +204,7 @@ export type Endpoint<M extends Method> = {
     H extends STHeaders = any,
     Q extends STQuery = any,
     B extends STBody = any,
-    R extends Partial<STResponse> = Partial<STResponse>
+    R extends STResponse = STResponse
   >(
     path: Path,
     schema: RequestSchema<M, Path, H, P, Q, B, R>,
@@ -207,7 +217,7 @@ export type Endpoint<M extends Method> = {
     H extends STHeaders = any,
     Q extends STQuery = any,
     B extends STBody = any,
-    R extends Partial<STResponse> = Partial<STResponse>
+    R extends STResponse = STResponse
   >(
     path: Path,
     schema: RequestSchema<M, Path, H, P, Q, B, R>,
@@ -219,7 +229,7 @@ export type Endpoint<M extends Method> = {
     H extends STHeaders = any,
     Q extends STQuery = any,
     B extends STBody = any,
-    R extends Partial<STResponse> = Partial<STResponse>
+    R extends STResponse = STResponse
   >(
     path: Path,
     hooks: Hook<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>[],
@@ -231,7 +241,7 @@ export type Endpoint<M extends Method> = {
     H extends STHeaders = any,
     Q extends STQuery = any,
     B extends STBody = any,
-    R extends Partial<STResponse> = Partial<STResponse>
+    R extends STResponse = STResponse
   >(
     path: Path,
     handler: Handler<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>
@@ -245,10 +255,12 @@ export type StaticEndpoint<P extends string = string, T extends string = string>
 
 export class RequestError {
   status: number
-  payload: any
-  constructor(options: { status?: number; payload?: any }) {
+  payload?: any
+  headers?: Record<string, string>
+  constructor(options: { status?: number; payload?: any, headers?: Record<string, string> }) {
     this.status = options.status ?? 500
     this.payload = options.payload
+    this.headers = options.headers
   }
 }
 
@@ -267,7 +279,7 @@ export type Route<
   H extends STHeaders = STHeaders,
   Q extends STQuery = STQuery,
   B extends STBody = STBody,
-  R extends Partial<STResponse> = Partial<STResponse>,
+  R extends STResponse = STResponse,
   SP extends string = string,
   SR extends string = string
 > = {

package/src/util.ts

@@ -12,6 +12,15 @@ const METHOD_COLOR: Record<string, string> = {
 }
 const ansiRegex = /[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g
 
+export const softMerge = <T> (base: T, override: T): T => {
+  for (const key in override) {
+    if (override[key] instanceof Object && !(override[key] instanceof Array)) {
+      if (!base[key]) Object.assign(base as any, { [key]: {} })
+      softMerge(base[key], override[key])
+    } else Object.assign(base as any, { [key]: override[key] })
+  }
+  return base
+}
 export const logRoute = (
   r: { method: string; path: string, static?: { path: string, root: string } },
   meta?: RouteMeta,

package/src/validator.ts

@@ -96,6 +96,7 @@ export const validate = (elt: any, schema: STSchema, parse = false): any => {
 export const validateResponse = (response: any, schema: STResponse, status: number) => {
   if (!(status in schema)) return
   const s = schema?.[status] || schema?.['default']
+  if(!s) return
   if (response instanceof ReadableStream) {
     if (!s[Stream]) throw new InternalError(`Expected ${s[Kind]} response, but got ReadableStream`)
   } else if (isIterator(response)) {

package/test/plugins.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, describe, afterEach, mock } from 'bun:test'
-import { Context, Galbe, GalbePlugin, Route } from '../src'
+import { type Context, Galbe, type GalbePlugin, type Route } from '../src'
 
 const port = 7361
 

package/test/responses.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, describe, beforeAll } from 'bun:test'
-import { Galbe, $T } from '../src'
+import { Galbe, $T, type Context } from '../src'
 import { decoder } from './test.utils'
 
 const port = 7359
@@ -21,7 +21,7 @@ const rsTxt = (text: string) => {
   })
 }
 
-const handleResp = ctx => ctx.body
+const handleResp = (ctx: Context) => ctx.body
 
 describe('responses', () => {
   beforeAll(async () => {
@@ -143,6 +143,7 @@ describe('responses', () => {
 
     expect(resp.status).toBe(200)
     expect(resp.headers.get('content-type')).toBe('application/octet-stream')
+    //@ts-ignore
     expect(body).toEqual(reqBody)
   })
 

package/test/routeFiles.test.ts

@@ -1,5 +1,5 @@
 import { expect, test, describe } from 'bun:test'
-import { defineRoutes, metaAnalysis } from '../src/routes'
+import { defineRoutes, GalbeProxy, metaAnalysis } from '../src/routes'
 import { Galbe } from '../src'
 
 describe('routeFiles', () => {
@@ -68,7 +68,7 @@ describe('routeFiles', () => {
   })
 
   test('define routes, no route', async () => {
-    const k = new Galbe()
+    const k = new GalbeProxy(new Galbe())
     await defineRoutes({}, k)
     expect(k.router.routes).toEqual({
       routes: {}
@@ -76,7 +76,7 @@ describe('routeFiles', () => {
   })
 
   test('define routes, no route (false)', async () => {
-    const k = new Galbe({ routes: false })
+    const k = new GalbeProxy(new Galbe({ routes: false }))
     await defineRoutes({}, k)
     expect(k.router.routes).toEqual({
       routes: {}
@@ -84,7 +84,7 @@ describe('routeFiles', () => {
   })
 
   test('define routes, no route found', async () => {
-    const k = new Galbe()
+    const k = new GalbeProxy(new Galbe())
     await defineRoutes({ routes: 'unexisting_route' }, k)
     expect(k.router.routes).toEqual({
       routes: {}
@@ -92,7 +92,7 @@ describe('routeFiles', () => {
   })
 
   test('define routes, route.empty', async () => {
-    const k = new Galbe()
+    const k = new GalbeProxy(new Galbe())
 
     await defineRoutes({ routes: 'test/resources/test.route.empty.ts' }, k)
 
@@ -132,7 +132,7 @@ describe('routeFiles', () => {
   })
 
   test('define routes, all', async () => {
-    const k = new Galbe()
+    const k = new GalbeProxy(new Galbe())
 
     await defineRoutes({ routes: ['test/resources/test.route.*.ts'] }, k)
 

package/tsconfig.json

@@ -18,6 +18,6 @@
     "noFallthroughCasesInSwitch": true,
     "forceConsistentCasingInFileNames": true,
   },
-  "include": ["src"],
+  "include": ["src","test"],
   "exclude": ["node_modules"]
 }