galbe 0.10.1 → 0.12.0

package/bin/res/client.template.ts

@@ -1,4 +1,3 @@
-export type GalbeClientMode = 'response' | 'direct'
 export type GalbeClientConfig = {
   server?: { url?: string }
 }
@@ -7,7 +6,7 @@ export const Kind = Symbol.for('json.string')
 type Json<T> = { T: T }
 
 interface GR<S extends number | 'default' = 'default', B = any, OKS extends number = OKStatusCode> {
-  status: Exclude<S, "default">
+  status: Exclude<S, 'default'>
   ok: S extends OKS ? true : false
   redirected: boolean
   statusText: string
@@ -18,16 +17,16 @@ interface GR<S extends number | 'default' = 'default', B = any, OKS extends numb
     stream?: ST
   ) => B extends Uint8Array
     ? ST extends true
-    ? Promise<AsyncGenerator<Uint8Array, void, unknown>>
-    : B extends Json<infer T>
-    ? Promise<T>
-    : Promise<B>
+      ? Promise<AsyncGenerator<Uint8Array, void, unknown>>
+      : B extends Json<infer T>
+      ? Promise<T>
+      : Promise<B>
     : B extends string
     ? ST extends true
-    ? Promise<AsyncGenerator<string, void, unknown>>
-    : B extends Json<infer T>
-    ? Promise<T>
-    : Promise<B>
+      ? Promise<AsyncGenerator<string, void, unknown>>
+      : B extends Json<infer T>
+      ? Promise<T>
+      : Promise<B>
     : B extends Json<infer T>
     ? Promise<T>
     : Promise<B>
@@ -42,16 +41,32 @@ type PGR<
   O extends number = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226
 > = Promise<GR<S, B, O>>
 
-type RequestOptions<H = any, Q = any, B = any> = {
+type ContentType = 'byteArray' | 'text' | 'json' | 'urlForm' | 'multipart' | 'default'
+type RequestOptions<
+  H = any,
+  Q = any,
+  B extends Partial<Record<ContentType, any>> = Partial<Record<ContentType, any>>,
+  C extends keyof B = keyof B
+> = {
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD'
   headers?: H
   query?: Q
-  body?: B
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD'
+  contentType?: C
+  body?: B[C]
 }
 
 const decoder = new TextDecoder()
 const DEFAULT_HEADERS = {
-  'user-agent': 'Galbe//*%(()=>version)()%*/'
+  'user-agent': 'Galbe//*%(()=>version)()%*/',
+}
+
+const formdata = (data: Record<string, string | string[] | Blob>): FormData => {
+  const form = new FormData()
+  for (const [k, v] of Object.entries(data)) {
+    if (Array.isArray(v)) for (const v2 of v) form.append(String(k), String(v2))
+    else form.append(String(k), String(v))
+  }
+  return form
 }
 
 // Typescript types
@@ -62,27 +77,23 @@ Object.entries(types).map(([tk, t])=>{
 %*/
 
 export default class GalbeClient {
-  config?: GalbeClientConfig
   /*%
   Object.entries(routes).map(([method, list])=>{
     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.query??'any'},${r.schemas.body??'any'}>`: 
+        `<${r.schemas.headers??'any'},${r.schemas.query??'any'},${r.schemas.body??'any'},CT>`: 
         ''
       let oks = Object.keys(r.schemas?.response||{}).filter(s=>s>=200&&s<300)
       let responses = Object.keys(r.schemas?.response||{}).length ?
         `${Object.entries(r.schemas.response).filter(([s,_])=>s!=='"default"').map(([k,v])=>`PGR<${k},${v}${oks?.length?`,${oks.join('|')}`:''}>`).join('|')}|PGR<Exclude<HttpStatusCode,${Object.keys(r.schemas.response).filter(s=>s!=='"default"').join('|')}>,${'"default"' in r.schemas.response ? r.schemas.response['"default"'] : 'any'}${oks?.length?`,${oks.join('|')}`:''}>`: 
         `PGR<HttpStatusCode,any${oks?.length?`,${oks.join('|')}`:',any'}>`
-      return `  '${r.path}':(${p.length?p.map(([k,v])=>`${k}:${v.type}`).join(',')+', ':''}options:RequestOptions${schemas}={})=>this.fetch(\`${r.pathT}\`,{...options,method:'${r.method.toUpperCase()}'}) as ${responses}`
+      return `  '${r.path}':<CT extends ${r.contentTypes}>(${p.length?p.map(([k,v])=>`${k}:${v.type}`).join(',')+', ':''}options:RequestOptions${schemas}={})=>this.fetch(\`${r.pathT}\`,{...options,method:'${r.method.toUpperCase()}'}) as ${responses}`
     }).join(',\n')}\n}`
   }).join('\n')
   %*/
 
-  constructor(config?: GalbeClientConfig) {
-    //@ts-ignore
-    this.config = { mode: 'response', ...config }
-  }
+  constructor(private readonly config?: GalbeClientConfig) {}
 
   async fetch(path: string, options: RequestOptions) {
     let url = `${this?.config?.server?.url ?? ''}${path}`
@@ -90,8 +101,23 @@ export default class GalbeClient {
     url = `${url}?${params.toString()}`
     let res = await fetch(url, {
       method: options?.method || 'GET',
-      headers: { ...DEFAULT_HEADERS, ...(options?.headers || {}) },
-      ...(options?.body ? { body: JSON.stringify(options.body) } : {})
+      headers: {
+        ...DEFAULT_HEADERS,
+        ...(options?.contentType && ['byteArray', 'text', 'json', 'urlForm'].includes(options.contentType)
+          ? {
+              'content-type': {
+                byteArray: 'application/octet-stream',
+                text: 'text/plain',
+                json: 'application/json',
+                urlForm: 'application/x-www-form-urlencoded',
+              }[options.contentType],
+            }
+          : {}),
+        ...(options?.headers || {}),
+      },
+      ...(options?.body
+        ? { body: options?.contentType === 'multipart' ? formdata(options?.body) : JSON.stringify(options.body) }
+        : {}),
     })
     return {
       headers: res.headers,
@@ -147,7 +173,7 @@ export default class GalbeClient {
           }
         }
         return res.body
-      }
+      },
     }
   }
 
@@ -157,7 +183,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.query??'any'},${r.schemas.body??'any'}>`: 
+        `<${r.schemas.headers??'any'},${r.schemas.query??'any'},${r.schemas.body??'any'},CT>`: 
         ''
       let oks = Object.keys(r.schemas?.response||{}).filter(s=>s>=200&&s<300)
       let responses = Object.keys(r.schemas?.response||{}).length ?
@@ -167,7 +193,7 @@ export default class GalbeClient {
       let description = r.description ? `   * ${r.description.replace(/\n/g,'\n   * ')}` : ''
       let params = Object.entries(r.schema.params || {}).map( ([k,v])=>`\n   * @param ${k} - ${v.description?.replace(/\n/g,'\n     ')}` ).join('')
       let query = Object.entries(r.schema.query || {}).map( ([k,v])=>`\n   * @param options.query.${k} - ${v.description?.replace(/\n/g,'\n     ')}` ).join('')
-      return `/**\n${summary}${description}\n   *${params}${query}\n   *\/\n  ${r.alias}(${p.length ? p.map(([k,v])=>`${k}: ${v.type}`).join(', ')+', ':''}options: RequestOptions${schemas} = {}){return this.fetch(\`${r.pathT}\`, {...options, method: '${r.method.toUpperCase()}'}) as ${responses}}\n`
+      return `/**\n${summary}${description}\n   *${params}${query}\n   *\/\n  ${r.alias}<CT extends ${r.contentTypes}>(${p.length ? p.map(([k,v])=>`${k}: ${v.type}`).join(', ')+', ':''}options: RequestOptions${schemas} = {}){return this.fetch(\`${r.pathT}\`, {...options, method: '${r.method.toUpperCase()}'}) as ${responses}}\n`
     }).join('  ')
   })
   %*/

package/bin/util.ts

@@ -15,14 +15,14 @@ export const fmtVal = (v: any) => {
   if (typeof v === 'number') return `\x1b[36m${v}\x1b[0m`
   return v
 }
-export const fmtList = (l: any) => `[${l.map((v:any) => fmtVal(v)).join(', ')}]`
+export const fmtList = (l: any) => `[${l.map((v: any) => fmtVal(v)).join(', ')}]`
 export const fmtInterval = (a: any, b: any) => `[${fmtVal(a)}-${fmtVal(b)}]`
 
 export const silentExec = async (fn: () => any) => {
   let consoleMock = Object.fromEntries(
     Object.entries(console)
       .filter(([_, v]) => typeof v === 'function')
-      .map(([k, _]) => [k, () => { }])
+      .map(([k, _]) => [k, () => {}])
   )
   const _console = console
   const _processStdoutWrite = process.stdout.write
@@ -30,9 +30,9 @@ export const silentExec = async (fn: () => any) => {
   //@ts-ignore
   global.console = consoleMock
   //@ts-ignore
-  process.stdout.write = function () { }
+  process.stdout.write = function () {}
   //@ts-ignore
-  process.stderr.write = function () { }
+  process.stderr.write = function () {}
   const r = await fn()
   global.console = _console
   process.stdout.write = _processStdoutWrite
@@ -50,7 +50,7 @@ export const watchDir = async (
   let watcher = watch(path, {
     persistent: false,
     ignored: options?.ignore,
-    ignoreInitial: true
+    ignoreInitial: true,
   })
   watcher.on('all', async (eventType, filename) => {
     if (filename.match(WATCH_IGNORE)) return
@@ -90,11 +90,31 @@ export const instanciateRoutes = async (g: Galbe) => {
       console.log(`\x1b\[0;31m    Error:\x1b[0m`)
       console.log(errors?.[fp])
     }
-    console.log("")
+    console.log('')
   }
   console.log('\x1b[1;30m\x1b[32mdone\x1b[0m\n')
 }
 
+export function abbreviateVar(input: string): string {
+  if (!input) return ''
+  const normalized = input
+    .replace(/[_\-\s]+/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+
+  const tokens = normalized
+    .trim()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean)
+
+  if (tokens.length === 0) return ''
+
+  return tokens
+    .map(t => t[0])
+    .join('')
+    .toLowerCase()
+}
+
 export const killPort = async (port: number) => {
   let getProcCmd: string[], killCmd: (port: string) => string[]
 
@@ -172,5 +192,5 @@ export const HttpStatus = {
   504: 'Gateway Timeout',
   505: 'HTTP Version Not Supported',
   507: 'Insufficient Storage',
-  511: 'Network Authentication Required'
+  511: 'Network Authentication Required',
 }

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.