galbe 0.8.0 → 0.9.1

package/docs/error-handler.md

@@ -1,38 +1,49 @@
 # Error handler
 
-Any error happening during a request lifecycle will be intercepted by the error handler.
+Any error happening during a request lifecycle will be intercepted by the error
+handler.
 
-You can customize the default error handling behavior by defining a custom error handler using Galbe's intance `onError` method.
+You can customize the default error handling behavior by defining a custom error
+handler using Galbe's intance `onError` method.
 
 ```js
-const galbe = new Galbe()
-galbe.onError(customErrorHandler)
+const galbe = new Galbe();
+galbe.onError(customErrorHandler);
 ```
 
 ## Definition
 
-The error handler should be a function that takes two aguments: an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) and a [Context](context.md). This function may potentially return a [Response type](handler.md#response-types).
+The error handler should be a function that takes two aguments: an
+[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+and a [Context](context.md). This function may potentially return a
+[Response type](handler.md#response-types).
 
 ```js
-galbe.onErrorHandler((error, ctx) => {
+galbe.onError((error, ctx) => {
   if (error.status === 500) {
-    return new Response(`Server error ❌`, { status: 500 })
+    return new Response(`Server error ❌`, { status: 500 });
   }
   if (error.status === 404) {
-    return new Response(`Not found 🔎`, { status: 404 })
+    return new Response(`Not found 🔎`, { status: 404 });
   }
-})
+});
 ```
 
-The `error` argument could be any type of error thrown by your application. If the error originates from Galbe framework, it will be an instance of [RequestError](#request-error).
+The `error` argument could be any type of error thrown by your application. If
+the error originates from Galbe framework, it will be an instance of
+[RequestError](#request-error).
 
-For instance, the [Router](router.md) will throw a `RequestError` with a `404` status if no route matches the incoming request path. Similarly, the Parser will throw a `RequestError` with a `400` status.
+For instance, the [Router](router.md) will throw a `RequestError` with a `404`
+status if no route matches the incoming request path. Similarly, the Parser will
+throw a `RequestError` with a `400` status.
 
 ## Request Error
 
-The `RequestError` class is utilized to instanciate a runtime request error in Galbe. It has two optional attributes: a `status` and a `payload`.
+The `RequestError` class is utilized to instanciate a runtime request error in
+Galbe. It has two optional attributes: a `status` and a `payload`.
 
-If your application throws a `RequestError` instance, Galbe will, by default, construct a Response from your `RequestError` and send it back to the client.
+If your application throws a `RequestError` instance, Galbe will, by default,
+construct a Response from your `RequestError` and send it back to the client.
 
 ```js
 import { Galbe, RequestError } from 'galbe'

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/docs/routes.md

@@ -111,3 +111,6 @@ export default g => {
   g.get('/foo/:bar', ctx => ctx.params.bar)
 }
 ```
+
+> [!TIP]
+> You can ignore a specific route from being analyzed by adding a `//@galbe-ignore` comment before the route definition. This is useful if you want to exclude certain routes from automatic analysis or documentation generation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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

@@ -12,10 +12,10 @@ const schemaToMedia = ({ type, format, isJson }: SchemaType) =>
   isJson || (type && ['object', 'number', 'boolean', 'array'].includes(type))
     ? 'application/json'
     : format === 'byte'
-    ? 'application/octet-stream'
-    : type === 'string'
-    ? 'text/plain'
-    : '*/*'
+      ? 'application/octet-stream'
+      : type === 'string'
+        ? 'text/plain'
+        : '*/*'
 
 export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<OpenAPIV3.Document> => {
   let paths: any = {}
@@ -115,9 +115,9 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         type: type,
         ...(type === 'object'
           ? {
-              properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])),
-              ...(required.length ? { required } : {})
-            }
+            properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])),
+            ...(required.length ? { required } : {})
+          }
           : {})
       }
     } else if (kind === 'union') {
@@ -178,8 +178,13 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     (routes, c) => ({ ...routes, ...c.routes }),
     {} as Record<string, Record<string, Record<string, any>>>
   )
+  let metaStatic = Object.fromEntries(Object.entries(metaRoutes || {}).filter((([_, d]) => d?.static)))
+
   walkRoutes(g.router.routes, r => {
     let meta = metaRoutes?.[r.path]?.[r.method]
+    if (r.static?.root)
+      meta = metaStatic[r.static?.root]?.static
+    if (meta?.hide) return
     let path = r.path.replaceAll(/:([^\/]+)/g, '{$1}')
     if (!(path in paths)) paths[path] = {}
     let tags = [
@@ -196,19 +201,19 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       : []
     let headerParam = r.schema?.headers
       ? Object.entries(r.schema?.headers as Record<string, STSchema>)
-          .map(([k, v]) => {
-            let p = parseParam(k, v, 'header')
-            if (k.match(/authorization/i)) {
-              // TODO: handle other auth methods
-              if (v.pattern && v?.pattern?.toString() === '/^Bearer /') {
-                security.push({ bearerAuth: [] })
-                components.securitySchemes = { bearerAuth: { type: 'http', scheme: 'bearer' } }
-                return null
-              }
+        .map(([k, v]) => {
+          let p = parseParam(k, v, 'header')
+          if (k.match(/authorization/i)) {
+            // TODO: handle other auth methods
+            if (v.pattern && v?.pattern?.toString() === '/^Bearer /') {
+              security.push({ bearerAuth: [] })
+              components.securitySchemes = { bearerAuth: { type: 'http', scheme: 'bearer' } }
+              return null
             }
-            return p
-          })
-          .filter(p => p)
+          }
+          return p
+        })
+        .filter(p => p)
       : []
     // TODO cookieParam
     let parameters = [...pathParam, ...queryParam, ...headerParam]
@@ -234,6 +239,7 @@ 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]) => {
+          if(!v) return []
           let s = Number(status) as keyof typeof HttpStatus
           let { schema, isJson } = schemaToOpenapi(v)
           let { type, format } = resolveRef(schema)
@@ -242,8 +248,8 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
             description: v.description || HttpStatus[Number(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
+          if (components.responses && r.schema.response?.[s]?.id) {
+            components.responses[r.schema.response?.[s]?.id as string] = response
             //@ts-ignore
             response = { $ref: `#/components/responses/${r.schema.response?.[s].id}` }
           }

package/src/index.ts

@@ -14,9 +14,14 @@ import type {
   STResponse,
   STParams,
   STHeaders,
-  STQuery
+  STQuery,
+  StaticEndpoint,
+  Route,
+  StaticEndpointOptions
 } from './types'
 
+import { readdirSync, statSync } from 'fs'
+import { resolve as resolvePath } from 'path'
 import server from './server'
 import { GalbeRouter } from './router'
 import { SchemaType, type STObject, type Static } from './schema'
@@ -41,7 +46,7 @@ const overloadDiscriminer = <
     | Hook<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>[]
     | Handler<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>,
   arg4?: Handler<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>
-) => {
+): Route<M, Path, P, H, Q, B, R> => {
   const defaultSchema = {}
   if (typeof arg2 === 'function') {
     return galbeMethod(galbe, method, path, defaultSchema, undefined, arg2)
@@ -70,7 +75,7 @@ const galbeMethod = <
   schema: RequestSchema<M, Path, H, P, Q, B, R> | undefined,
   hooks: Hook<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>[] | undefined,
   handler: Handler<M, Path, RequestSchema<M, Path, H, P, Q, B, R>>
-) => {
+): Route<M, Path, P, H, Q, B, R> => {
   schema = schema ?? {}
   hooks = hooks || []
   const context: Context<M, Path, typeof schema> = {
@@ -85,7 +90,8 @@ const galbeMethod = <
     state: {},
     set: {} as {
       headers: {
-        [header: string]: string
+        'set-cookie': string[]
+        [header: string]: string | string[]
       }
       status?: number
     }
@@ -306,6 +312,40 @@ export class Galbe {
       | Handler<'head', Path, RequestSchema<'head', Path, H, P, Q, B, R>>,
     arg4?: Handler<'head', Path, RequestSchema<'head', Path, H, P, Q, B, R>>
   ) => this.add(overloadDiscriminer(this, 'head', path, arg2, arg3, arg4))
+  static: StaticEndpoint = (path: string, target: string, options?: StaticEndpointOptions) => {
+    let { resolve } = options ?? {}
+    const rootPath = path
+
+    const walkStatic = (path: string, target: string) => {
+      path = path?.[0] === '/' ? path : `/${path}`
+      path = path.endsWith('/') ? path.slice(0, -1) : path;
+
+      let t = target
+      if (Bun.env.BUN_ENV === 'production') {
+        t = resolvePath(import.meta.dir, `static-${Bun.env.GALBE_BUILD}/${target}`)
+      }
+
+      if (!statSync(t).isDirectory()) {
+        let ut: string | null | undefined | void = t
+        if (path.endsWith('.html')) path = path.slice(0, -5)
+        if (resolve) ut = resolve(path, ut)
+        if (ut) {
+          let handler = () => new Response(Bun.file(ut))
+          this.add({ ...galbeMethod(this, 'get', path, {}, undefined, handler), static: { path: ut, root: rootPath } })
+        }
+      } else {
+        let root = readdirSync(t)
+        for (let f of root) {
+          let p = f === 'index.html' ? path : `${path}/${f}`
+          walkStatic(p, `${target}/${f}`)
+        }
+      }
+
+      return { ...galbeMethod(this, 'get', path, {}, undefined, () => { }), static: { path: t, root: rootPath } }
+    }
+
+    return walkStatic(path, target)
+  }
 }
 
 export * from './types'

package/src/parser.ts

@@ -89,8 +89,8 @@ export const requestBodyParser = async (
         let received = contentType?.match(FORM_HEADER_RX)
           ? 'urlForm'
           : contentType?.match(MP_HEADER_RX)
-          ? 'multipartForm'
-          : contentType
+            ? 'multipartForm'
+            : contentType
         throw new RequestError({ status: 400, payload: { body: `Expected ${kind}, received ${received}` } })
       } else if (!contentType || contentType === BA_HEADER) {
         if (!schema) {
@@ -377,7 +377,7 @@ async function* $streamToMultipartForm(data: ReadableStream<Uint8Array>, boundar
       payload: { body: `Missing field${reqKeys.length > 1 ? 's' : ''}: ${reqKeys.join(', ')}` }
     })
 }
-const parseMultipartHeader = (header: string): { name: string; [key: string]: string } | null => {
+const parseMultipartHeader = (header: string): { name: string;[key: string]: string } | null => {
   if (!header) return null
   let disposition = 'form-data'
   const multipartHeader = [
@@ -537,24 +537,24 @@ const paramParser = (
       if (typeof value === 'boolean') return value
       if (value === 'true') return true
       if (value === 'false') return false
-      else throw `${value} is not a valid boolean. Should be 'true' or 'false'`
+      else throw `Not a valid boolean. Should be 'true' or 'false'`
     } else if (type[Kind] === 'integer') {
-      if (value === null || value === undefined) throw `${value} is not a valid integer`
+      if (value === null || value === undefined) throw `Not a valid integer`
       const parsedValue = parseInt(value, 10)
-      if (isNaN(parsedValue) || String(parsedValue) !== String(value)) throw `${value} is not a valid integer`
+      if (isNaN(parsedValue) || String(parsedValue) !== String(value)) throw `Not a valid integer`
       validate(parsedValue, type)
       return parsedValue
     } else if (type[Kind] === 'number') {
-      if (value === null || value === undefined) throw `${value} is not a valid number`
+      if (value === null || value === undefined) throw `Not a valid number`
       const parsedValue = Number(value)
-      if (isNaN(parsedValue) || String(parsedValue) !== String(value)) throw `${value} is not a valid number`
+      if (isNaN(parsedValue) || String(parsedValue) !== String(value)) throw `Not a valid number`
       validate(parsedValue, type)
       return parsedValue
     } else if (type[Kind] === 'string') {
       validate(value, type)
       return value
     } else if (type[Kind] === 'literal') {
-      if (value !== type.value) throw `${value} is not a valid value`
+      if (value !== type.value) throw `Not a valid value`
       return value
     } else if (type[Kind] === 'array') {
       return [paramParser(value, type.items as STMultipartFormValues) as Static<STUrlFormValues>]
@@ -569,9 +569,9 @@ const paramParser = (
           continue
         }
       }
-      throw `${value} could not be parsed to any of ${union
+      throw `Could not be parsed to any of [${union
         .map(u => (u as STLiteral)?.value ?? (u as STSchema)[Kind])
-        .join(', ')}`
+        .join(', ')}]`
     } else if (type[Kind] === 'any') {
       return value
     }
@@ -645,12 +645,17 @@ export const parseEntry = <T extends STProps>(
 export const responseParser = (response: any, ctx: Context, schema?: STResponse) => {
   const details = {
     status: ctx.set.status || 200,
-    headers: new Headers(ctx.set.headers)
+    headers: new Headers()
+  }
+  for (const [key, value] of Object.entries(ctx.set.headers)) {
+    if (Array.isArray(value)) {
+      value.forEach(v => details.headers.append(key, v))
+    } else details.headers.set(key, value)
   }
   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')