galbe 0.10.0 → 0.11.0

package/README.md

@@ -20,6 +20,9 @@ cd app
 bun install && bun dev
 ```
 
+The Galbe CLI ships with the package. You can invoke it with `bunx galbe` or
+install it globally using `bun install -g galbe`.
+
 ## Documentation
 
 The detailed documentation is available at [galbe.dev](https://galbe.dev).

package/bin/commands/build.ts

@@ -10,6 +10,7 @@ import { Galbe } from '../../src'
 import { defineRoutes, GalbeProxy } from '../../src/routes'
 import { BuildConfig } from 'bun'
 import { existsSync } from 'fs'
+import { softMerge } from '../../src/util'
 
 const createBuildIndex = async (indexPath: string, g: Galbe, buildId: string) => {
   const buildPath = resolve(tmpdir(), buildId)
@@ -61,10 +62,19 @@ export default (cmd: Command) => {
     .option('-c, --config <file>', 'bun js or ts config file')
     .action(async (index, props) => {
       const { out, compile, config } = props
-
+      const indexPath = resolve(CWD, index)
+      const indexDir = dirname(indexPath)
       const buildID = crypto.randomUUID()
       const outPath = resolve(CWD, out)
 
+      let galbeConfig = {}
+
+      if (existsSync(`${indexDir}/galbe.config.ts`)) {
+        galbeConfig = (await import(`${indexDir}/galbe.config.ts`)).default
+      } else if (existsSync(`${indexDir}/galbe.config.js`)) {
+        galbeConfig = (await import(`${indexDir}/galbe.config.js`)).default
+      }
+
       Bun.env.GALBE_BUILD = buildID
       Bun.env.GALBE_BUILD_OUT = outPath
 
@@ -77,6 +87,8 @@ export default (cmd: Command) => {
       let g: Galbe = await silentExec(async () => {
         try {
           const g = (await import(resolve(CWD, index))).default
+          let conf = g.config
+          g.config = softMerge(galbeConfig, conf)
           return g
         } catch (err) {
           error = err

package/docs/cli.md

@@ -9,7 +9,7 @@ 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
+$ bun i -g galbe
 ```
 
 Or run it with `bunx`:
@@ -26,15 +26,16 @@ Start a dev server running your Galbe application.
 
 | Name  | Description                                              |
 | ----- | -------------------------------------------------------- |
-| index | The js or ts file that export you Galbe server instance. |
+| index | The js or ts file that export your 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   |
+| Short | Long            | Descritpion                 | Default |
+| ----- | --------------- | --------------------------- | ------- |
+| -p    | --port          | port number [1-65535]       | 3000    |
+| -w    | --watch         | watch file changes dir      | false   |
+| -wi   | --watchignore   | ignored watch files regex   |         |
+| -nc   | --noclear       | don't clear on file changes | false   |
 
 #### Example
 
@@ -51,6 +52,13 @@ export default g
 
 ```bash
 $ galbe dev index.js -p 7357 -w
+🏗️  Constructing routes
+
+    [GET]     /example
+
+done
+
+🚀 Server running at http://localhost:7357
 ```
 
 ## build
@@ -61,11 +69,11 @@ Bundle your Galbe application.
 
 | Name  | Description                                              |
 | ----- | -------------------------------------------------------- |
-| index | The js or ts file that export you Galbe server instance. |
+| index | The js or ts file that export your Galbe server instance. |
 
 #### Options
 
-| Short | Long      | Descritpion                    | Default  |
+| Short | Long      | Description                    | Default  |
 | ----- | --------- | ------------------------------ | -------- |
 | -o    | --out     | output directory               | dist/app |
 | -C    | --compile | create a standalone executable | false    |
@@ -74,7 +82,6 @@ Bundle your Galbe application.
 #### Example
 
 index.js
-
 ```js
 import { Galbe } from 'galbe'
 
@@ -87,7 +94,7 @@ $ galbe build index.js
 
 ## generate
 
-Generate resources arround your Galbe application.
+Generate resources around your Galbe application.
 
 ### client
 
@@ -97,11 +104,11 @@ Generate a client for your Galbe application.
 
 | Name  | Description                                              |
 | ----- | -------------------------------------------------------- |
-| index | The js or ts file that export you Galbe server instance. |
+| index | The js or ts file that export your Galbe server instance. |
 
 #### Options
 
-| Short | Long     | Descritpion                | Default                              |
+| Short | Long     | Description                | Default                              |
 | ----- | -------- | -------------------------- | ------------------------------------ |
 | -o    | --out    | output file                | dist/(client.ts \| client.js \| cli) |
 | -t    | --target | build target [ts, js, cli] | ts                                   |
@@ -116,10 +123,6 @@ $ 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:
@@ -195,7 +198,7 @@ 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.
+> A `GCLI_SERVER_URL` environment variable must be defined. It should indicate the url of the Galbe server you want to target.
 > In that specific case `http://localhost:3000`.
 
 ### spec
@@ -206,11 +209,11 @@ Generate the spec of your Galbe application.
 
 | Name  | Description                                              |
 | ----- | -------------------------------------------------------- |
-| index | The js or ts file that export you Galbe server instance. |
+| index | The js or ts file that export your Galbe server instance. |
 
 #### Options
 
-| Short | Long     | Descritpion                                      | Default                 |
+| Short | Long     | Description                                      | Default                 |
 | ----- | -------- | ------------------------------------------------ | ----------------------- |
 | -t    | --target | spec target [openapi:3.0:json, openapi:3.0:yaml] | openapi:3.0:yaml        |
 | -b    | --base   | base spec file                                   |                         |
@@ -218,7 +221,7 @@ Generate the spec of your Galbe application.
 
 #### Example
 
-Let's try to generate the specof the project defined in the previous client section. You can then run:
+Let's try to generate the spec of the project defined in the previous client section. You can then run:
 
 ```bash
 $ galbe generate spec index.ts
@@ -263,7 +266,7 @@ Generate the code and project structure from spec.
 
 #### Options
 
-| Short | Long     | Descritpion                                       | Default                    |
+| Short | Long     | Description                                       | 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                         |

package/docs/configuration.md

@@ -0,0 +1,80 @@
+# Configuration
+
+## Configuring Galbe
+
+By default, Galbe automatically attempts to resolve a configuration file named `galbe.config.{js,ts}` located in the same directory as your entry file.
+
+The configuration file should export a default object containing your settings:
+
+```js
+export default {
+  // config properties
+}
+```
+
+Alternatively, you can pass your configuration directly to your Galbe server during instantiation, as shown below:
+
+```ts
+import { Galbe } from "galbe"
+
+const galbe = new Galbe({
+  // config properties
+})
+
+export default galbe
+```
+
+> [!NOTE]
+> You can use both configuration methods simultaneously. Galbe will first apply the settings from `galbe.config.{js,ts}`, and any properties passed during instantiation will override the corresponding ones from the configuration file.
+
+## Configuration Properties
+
+### hostname
+The hostname of the server. Default: `localhost`.
+
+### port
+The port number the server will listen on. Default: `3000`.
+
+### basePath
+A base path added as a prefix to all routes.
+
+### routes
+A glob pattern or list of glob patterns defining the route files to be analyzed by the [Automatic Route Analyzer](routes.md#automatic-route-analyzer). Default: `src/**/*.route.{js,ts}`.
+
+### plugin
+A property used by plugins to add specific configurations. Each key should correspond to a [Unique Plugin Identifier](plugins.md).
+
+### tls
+Enables or disables TLS support. Default: `false`.
+- **tls.key**: Path to the private key file.
+- **tls.cert**: Path to the certificate file.
+- **tls.ca**: Path to the certificate authority file.
+
+### requestValidator.enabled
+Enables or disables _request_ schema validation (see [Request Schema Definition](schemas.md#request-schema-definition)). Default: `true`.
+
+### responseValidator.enabled
+Enables or disables _response_ schema validation (see [Response Schema Definition](schemas.md#request-schema-definition#response)). Default: `true`.
+
+## Config Type Safety
+
+To ensure type safety for your configuration, use the `config` helper method, which leverages your IDE’s IntelliSense:
+
+```ts
+import { config } from "galbe"
+
+export default config({
+  // ...
+})
+```
+
+Alternatively, if you are using TypeScript, you can apply the `GalbeConfig` type to enforce type consistency:
+
+```ts
+import type { GalbeConfig } from "galbe"
+
+export default {
+  // ...
+} satisfies GalbeConfig
+```
+

package/docs/context.md

@@ -1,41 +1,30 @@
 # Context
 
-An instance of the context object is created when a new request is initiated and carrieds out along durring all the request lifecycle.
-See the [Lifecycle](https://galbe.dev/documentation/lifecycle) section to get more details.
+An instance of the context object is created when a new request is initiated and is carried throughout the entire request lifecycle. See the [Lifecycle](https://galbe.dev/documentation/lifecycle) section for more details.
 
-Its purpose is to carrie all the relevent information about the request and to allow sharing informations between each step of the request lifecycle.
+Its purpose is to carry all relevant information about the request and facilitate data sharing between different stages of the request lifecycle.
 
 ## Definition
 
-A context has the following properties:
+A context object has the following properties:
 
-**request**
+### request
 
 An instance of the [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object created by the server.
 
-**headers**
+### headers
 
-A javascript object representing the `headers` of the current request.
+A JavaScript object representing the headers of the current request.
 
-- key (string): header name
-- value: (string | [schema defined](schemas.md#headers)): header value
+- **key** (string): Header name
+- **value** (string | [schema defined](schemas.md#headers)): Header value
 
-```js
-{
-    "accept": "*/*",
-    "accept-encoding": "gzip, deflate, br",
-    "cookie": "Cookie_1=value; Cookie_2=value",
-    "host": "localhost:3000",
-    "user-agent": "galbe/1.0.0"
-}
-```
-
-**params**
+### params
 
-A javascript object representing the request `parameters` of the current request.
+A JavaScript object representing the route parameters of the current request.
 
-- key (string): parameter name
-- value: (string | [schema defined](schemas.md#params)): parameter value
+- **key** (string): Parameter name
+- **value** (string | [schema defined](schemas.md#params)): Parameter value
 
 ```js
 galbe.get('/default/:p1/foo/:p2', ctx => console.log(ctx.params))
@@ -43,67 +32,64 @@ galbe.get('/default/:p1/foo/:p2', ctx => console.log(ctx.params))
 { p1: "four", p2: "2" }
 ```
 
-**query**
+### query
 
-A javascript object representing the request `query parameters` of the current request.
+A JavaScript object representing the query parameters of the current request.
 
-- key (string): query parameter name
-- value: (string | [schema defined](schemas.md#query)): query parameter value
+- **key** (string): Query parameter name
+- **value** (string | [schema defined](schemas.md#query)): Query parameter value
 
 ```js
-galbe.get('/test', ctx => console.log(ctx.params))
+galbe.get('/test', ctx => console.log(ctx.query))
 // GET /test?one=1&two=2
 { one: "1", two: "2" }
 ```
 
-**body**
+### body
 
-The body payload of the incoming request. The body type is computed according to the following rules.
+The body payload of the incoming request. The body type is determined based on the following rules:
 
-If no [Schema](schemas.md) is defined, Galbe will parse the body type according to `content-type` Header value:
+If no [Schema](schemas.md) is defined, Galbe will parse the body type according to the `Content-Type` header:
 
 - `text/.*`: string
 - `application/json`: object
-- `application/x-www-form-urlencoded`: { [key: string]: any }
-- `multipart/form-data`: { [key: string]:
-  { headers: { name: string; type?: string; filename?: string };
-  content: any
-  } }
-- `other`: AsyncGenerator\<Uint8Array\>
+- `application/x-www-form-urlencoded`: `{ [key: string]: any }`
+- `multipart/form-data`: `{ [key: string]: { headers: { name: string; type?: string; filename?: string }; content: any } }`
+- `other`: `AsyncGenerator<Uint8Array>`
 
-If a [Schema](schemas.md) is defined, Galbe will parse the body type according to the [Schema.body](schemas.md#body) defined for the current route.
+If a [Schema](schemas.md) is defined, Galbe will parse the body according to the [Schema.body](schemas.md#body) definition for the current route.
 
-**set**
+### set
 
-The set property contains modifiable properties which purpose are to give informations to the Response parser.
+The `set` property contains modifiable attributes intended to provide information to the response parser.
 
-- `status`: Set the response status
-- `headers`: Set the response headers
+- **status**: Sets the response status.
+- **headers**: Sets the response headers.
 
 ```js
 galbe.get('/example', ctx => {
-  ctx.set.status = 418
-  return "I don't do coffee"
+  ctx.set.status = 418;
+  return "I don't do coffee";
 })
 ```
 
-**state**
+### state
 
-The state property purpose is to carry custom user object accross request lifecycle. In general it is used to share informations between the [hooks](hooks.md) and the [handler](handler.md).
+The `state` property allows storing custom user-defined objects throughout the request lifecycle. It is commonly used to share data between [hooks](hooks.md) and the [handler](handler.md).
 
-- key (string): user defined key
-- value (any): user defined object
+- **key** (string): User-defined key
+- **value** (any): User-defined object
 
 ```js
 galbe.get(
   '/example',
   [
     ctx => {
-      ctx.state['foo'] = 'bar'
+      ctx.state['foo'] = 'bar';
     }
   ],
   ctx => {
-    return ctx.state.foo
+    return ctx.state.foo;
   }
 )
 ```
@@ -113,6 +99,6 @@ $ curl http://localhost:3000/example
 bar
 ```
 
-**remoteAddress**
+### remoteAddress
 
-An instance of the [SocketAdress](https://github.com/oven-sh/bun/blob/fe62a614046948ebba260bed87db96287e67921f/packages/bun-types/bun.d.ts#L2600-L2613) representing the remote address of the client.
+An instance of [SocketAddress](https://github.com/oven-sh/bun/blob/fe62a614046948ebba260bed87db96287e67921f/packages/bun-types/bun.d.ts#L2600-L2613) representing the remote address of the client.

package/docs/error-handler.md

@@ -1,59 +1,48 @@
-# Error handler
+# Error Handler
 
-Any error happening during a request lifecycle will be intercepted by the error
-handler.
+Any error occurring during a request lifecycle is 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 instance `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 arguments: an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) and a [Context](context.md). This function may return a [Response type](handler.md#response-types).
 
 ```js
 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 can be any type of error thrown by your application. If the error originates from the 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 example, 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 in case of invalid input.
 
 ## 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 used to instantiate a runtime request error in Galbe. It has three optional attributes: `status`, `payload`, and `headers`.
 
-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'
-
-const galbe = new Galbe()
+import { RequestError } from 'galbe'
 
-galbe.get('/coffee', () => throw new RequestError({ status: 418, payload: '🫖' }))
+galbe.get('/coffee', () => {
+  throw new RequestError({ status: 418, payload: '🫖' })
+})
 ```
 
-When called, above endpoint should respond:
+When called, the above endpoint should respond:
 
 ```bash
 $ curl -i http://localhost:3000/coffee
@@ -61,5 +50,5 @@ HTTP/1.1 418 I'm a Teapot
 Content-Type: application/json
 Content-Length: 6
 
-"🫖"
-```
+🫖
+```