galbe 0.12.1 → 0.13.0

package/bunfig.toml

@@ -1,2 +0,0 @@
-[install]
-registry = "https://registry.npmjs.org/"

package/docs/CONTRIBUTING.md

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

package/docs/cli.md

@@ -1,343 +0,0 @@
-# CLI
-
-A Command Line Interface is shipped with Galbe package. You can use it to perform useful tasks around your application.
-
-After [Installing Galbe](getting-started.md#automatic-installation), the CLI will be available locally to your project.
-
-However, if you want to use it directly from your terminal, you must either:
-
-Install it globally using the following command:
-
-```bash
-$ bun i -g galbe
-```
-
-Or run it with `bunx`:
-
-```bash
-$ bunx galbe
-```
-
-## dev
-
-Start a dev server running your Galbe application.
-
-#### Arguments
-
-| Name  | Description                                              |
-| ----- | -------------------------------------------------------- |
-| index | The js or ts file that export your Galbe server instance. |
-
-#### Options
-
-| 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
-
-index.js
-
-```js
-import { Galbe } from 'galbe'
-
-const g = new Galbe()
-g.get('example', () => '')
-
-export default g
-```
-
-```bash
-$ galbe dev index.js -p 7357 -w
-🏗️  Constructing routes
-
-    [GET]     /example
-
-done
-
-🚀 Server running at http://localhost:7357
-```
-
-## build
-
-Bundle your Galbe application.
-
-#### Arguments
-
-| Name  | Description                                              |
-| ----- | -------------------------------------------------------- |
-| index | The js or ts file that export your Galbe server instance. |
-
-#### Options
-
-| Short | Long      | Description                    | Default  |
-| ----- | --------- | ------------------------------ | -------- |
-| -o    | --out     | output directory               | dist/app |
-| -C    | --compile | create a standalone executable | false    |
-| -c    | --config  | bun config (js or ts)          |          |
-
-#### Example
-
-index.js
-```js
-import { Galbe } from 'galbe'
-
-export default new Galbe()
-```
-
-```bash
-$ galbe build index.js
-```
-
-## generate
-
-Generate resources around your Galbe application.
-
-### client
-
-Generate a client for your Galbe application.
-
-#### Arguments
-
-| Name  | Description                                              |
-| ----- | -------------------------------------------------------- |
-| index | The js or ts file that export your Galbe server instance. |
-
-#### Options
-
-| Short | Long     | Description                | Default                              |
-| ----- | -------- | -------------------------- | ------------------------------------ |
-| -o    | --out    | output file                | dist/(client.ts \| client.js \| cli) |
-| -t    | --target | build target [ts, js, cli] | ts                                   |
-
-#### Examples
-
-Let's first setup a new Galbe project:
-
-```bash
-$ bun create galbe galbe-example --template hello --lang ts
-$ cd galbe-example
-$ bun install
-```
-
-##### JS or TS client
-
-To generate a JS or TS client of that application, you can run the following command:
-
-```bash
-$ galbe generate client index.ts
-```
-
-This will generate a `dist/client.ts` client lib by default.
-You can import it and use it like in the following example:
-
-client_example.ts
-
-```ts
-import HelloClient from './dist/client'
-
-const client = new HelloClient({ server: { url: 'http://localhost:3000' } })
-
-const response = await client.hello('Bob', { query: { age: 42 } })
-// This is equivalent as calling
-// const response = await client.get["/hello/:name"]("Bob", { query: { age: 42 } })
-
-if (response.ok) console.log(await response.body())
-// Hello Bob! You're 42 y.o.
-```
-
-##### CLI client
-
-To generate a CLI of that application, you can run the following command:
-
-```bash
-$ galbe generate client index.ts -t cli
-```
-
-This will generate a `cli` binary file under `dist` directory by default.
-
-```bash
-$ ./dist/cli --help
-Usage: galbe-example [options] [command]
-
-Options:
-  -V, --version    output the version number
-  -h, --help       display help for command
-
-Commands:
-  hello [options]  Greeting endpoint
-  help [command]   display help for command
-```
-
-```bash
-$ ./dist/cli hello --help
-Usage: galbe-example hello [options] <name>
-
-Greeting endpoint
-
-Arguments:
-  name                        name argument
-
-Options:
-  -%f, --%format [string]     response format ['s','h','b','t','p'] (default: ["s","b","p"])
-  -%h, --%header <string...>  request header formated as headerName=headerValue (default: [])
-  -%q, --%query <string...>   query param formated as paramName=paramValue (default: [])
-  -%b, --%body <string>       request body (default: "")
-  -%bf, --%bodyFile <path>    request body file (default: "")
-  -a, --age <number>
-  -h, --help                  display help for command
-```
-
-```bash
-$ ./dist/cli hello Pierre -a 29
-200
-Hello Pierre! You're 29 y.o.
-```
-
-> [!IMPORTANT]
-> A `GCLI_SERVER_URL` environment variable must be defined. It should indicate the url of the Galbe server you want to target.
-> In that specific case `http://localhost:3000`.
-
-### spec
-
-Generate the spec of your Galbe application.
-
-#### Arguments
-
-| Name  | Description                                              |
-| ----- | -------------------------------------------------------- |
-| index | The js or ts file that export your Galbe server instance. |
-
-#### Options
-
-| 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                                   |                         |
-| -o    | --out    | output file                                      | spec/api.(yaml \| json) |
-
-#### Example
-
-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
-```
-
-This should generate the following `spec/api.yaml` file:
-
-```yaml
-openapi: 3.0.3
-info:
-  title: galbe-app
-  version: 0.1.0
-paths:
-  /hello/{name}:
-    get:
-      summary: Greeting endpoint
-      operationId: hello
-      parameters:
-        - name: age
-          in: query
-          required: true
-          schema:
-            type: integer
-      responses:
-        '200':
-          description: OK
-          content:
-            text/plain:
-              schema:
-                type: string
-```
-
-### code
-
-Generate the code and project structure from spec.
-
-#### Arguments
-
-| Name  | Description                                                |
-| ----- | ---------------------------------------------------------- |
-| input | The input spec file from which the code will be generated. |
-
-#### Options
-
-| Short | Long     | 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                         |
-| -o    | --out    | output dir                                        | src                        |
-| -F    | --force  | force overriding output                           | false                      |
-
-#### Example
-
-For that example, we will generate the Galbe source code from the [Swagger Petstore Openapi spec](https://petstore3.swagger.io/).
-
-First, initiate a new bun project and install the galbe dependency.
-
-```bash
-$ mkdir petstore && cd petstore
-$ bun init && bun add galbe
-```
-
-Now modify the `index.ts` file with the following content:
-
-```ts
-import { Galbe } from 'galbe'
-
-export default new Galbe()
-```
-
-Then download the petstore json spec from Swagger website into `petstore.spec.json`:
-
-```bash
-$ curl -o petstore.spec.json https://petstore3.swagger.io/api/v3/openapi.json
-```
-
-You can now generate the sources from the petstore spec:
-
-```bash
-$ galbe generate code petstore.spec.json
-```
-
-This should generate the code of our application in the `src` directory by default.
-
-To test that the code was successfully generated, you can run:
-
-```bash
-$ galbe dev index.ts
-🏗️  Constructing routes
-
-    src/routes/pet.route.ts
-    [PUT]     /pet                     Update an existing pet
-    [POST]    /pet                     Add a new pet to the store
-    [GET]     /pet/findByStatus        Finds Pets by status
-    [GET]     /pet/findByTags          Finds Pets by tags
-    [GET]     /pet/:petId              Find pet by ID
-    [POST]    /pet/:petId              Updates a pet in the store with form data
-    [DELETE]  /pet/:petId              Deletes a pet
-    [POST]    /pet/:petId/uploadImage  uploads an image
-
-    src/routes/store.route.ts
-    [GET]     /store/inventory       Returns pet inventories by status
-    [POST]    /store/order           Place an order for a pet
-    [GET]     /store/order/:orderId  Find purchase order by ID
-    [DELETE]  /store/order/:orderId  Delete purchase order by ID
-
-    src/routes/user.route.ts
-    [POST]    /user                 Create user
-    [POST]    /user/createWithList  Creates list of users with given input array
-    [GET]     /user/login           Logs user into the system
-    [GET]     /user/logout          Logs out current logged in user session
-    [GET]     /user/:username       Get user by user name
-    [PUT]     /user/:username       Update user
-    [DELETE]  /user/:username       Delete user
-
-done
-
-🚀 Server running at http://localhost:3000
-```

package/docs/configuration.md

@@ -1,80 +0,0 @@
-# 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,104 +0,0 @@
-# Context
-
-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 carry all relevant information about the request and facilitate data sharing between different stages of the request lifecycle.
-
-## Definition
-
-A context object has the following properties:
-
-### request
-
-An instance of the [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object created by the server.
-
-### headers
-
-A JavaScript object representing the headers of the current request.
-
-- **key** (string): Header name
-- **value** (string | [schema defined](schemas.md#headers)): Header value
-
-### params
-
-A JavaScript object representing the route parameters of the current request.
-
-- **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))
-// GET /default/four/foo/2
-{ p1: "four", p2: "2" }
-```
-
-### query
-
-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
-
-```js
-galbe.get('/test', ctx => console.log(ctx.query))
-// GET /test?one=1&two=2
-{ one: "1", two: "2" }
-```
-
-### body
-
-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 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>`
-
-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
-
-The `set` property contains modifiable attributes intended to provide information to the response parser.
-
-- **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";
-})
-```
-
-### state
-
-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
-
-```js
-galbe.get(
-  '/example',
-  [
-    ctx => {
-      ctx.state['foo'] = 'bar';
-    }
-  ],
-  ctx => {
-    return ctx.state.foo;
-  }
-)
-```
-
-```bash
-$ curl http://localhost:3000/example
-bar
-```
-
-### remoteAddress
-
-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,54 +0,0 @@
-# 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 instance `onError` method.
-
-```js
-const galbe = new Galbe()
-galbe.onError(customErrorHandler)
-```
-
-## Definition
-
-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 })
-  }
-  if (error.status === 404) {
-    return new Response(`Not found 🔎`, { status: 404 })
-  }
-})
-```
-
-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 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 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.
-
-```js
-import { RequestError } from 'galbe'
-
-galbe.get('/coffee', () => {
-  throw new RequestError({ status: 418, payload: '🫖' })
-})
-```
-
-When called, the above endpoint should respond:
-
-```bash
-$ curl -i http://localhost:3000/coffee
-HTTP/1.1 418 I'm a Teapot
-Content-Type: application/json
-Content-Length: 6
-
-🫖
-```