galbe 0.12.1 → 0.13.0

package/docs/getting-started.md

@@ -1,164 +0,0 @@
-# Getting Started
-
-Galbe is a JavaScript web framework for building fast and versatile backend servers with Bun.
-
-Designed for simplicity, Galbe allows you to quickly create and configure a project. In addition to its ease of use, it offers various features that help you focus on your application's core logic.
-
-## Requirements
-
-To start developing with Galbe, you first need to install [Bun](https://bun.sh).
-
-## Automatic Installation (Recommended)
-
-This is the recommended way to set up a Galbe project.
-
-```bash
-$ bun create galbe app
-```
-
-The Galbe starter CLI will prompt you to choose a template and a target language. Select `hello` as the template and `typescript` as the language. This will create a new project in the `app` directory.
-
-Now, navigate to your newly created project and install dependencies:
-
-```bash
-$ cd app
-$ bun i
-```
-
-Start the development server by running:
-
-```bash
-$ bun dev
-🏗️  Constructing routes
-
-    hello.route.ts
-    [GET]     /hello/:name  Greeting endpoint
-
-done
-
-🚀 Server running at http://localhost:3000
-```
-
-Try accessing the hello endpoint:
-
-```bash
-$ curl localhost:3000/hello/John?age=32
-Hello John! You're 32 y.o.
-```
-
-> [!TIP]
-> To explore more of Galbe's capabilities, check out the `demo` template in the Galbe starter CLI.
-
-## Manual Installation
-
-Initialize a new Bun project and add Galbe as a dependency:
-
-```bash
-$ bun init
-$ bun add galbe
-```
-
-Open `package.json` and add the following scripts:
-
-```json
-{
-  "scripts": {
-    "dev": "galbe dev index.ts -w .",
-    "build": "galbe build index.ts",
-    "test": "bun test"
-  }
-}
-```
-
-These scripts use the Galbe CLI to run and build the application. More details are available in the [CLI](cli.md) section.
-
-Your `index.ts` file must export a default Galbe instance:
-
-```ts
-import { Galbe } from "galbe"
-
-const galbe = new Galbe({ port: 3000 })
-galbe.get("/hello", () => "Hello Mom!")
-
-export default galbe
-```
-
-This approach is recommended but not mandatory. Galbe instances also provide a `listen` method, allowing you to manually start your server from within your code.
-
-> [!WARNING]
-> If you choose not to use the Galbe CLI for running or building your app, you will not have access to features such as the [Automatic Route Analyzer](routes.md#automatic-route-analyzer).
-
-## Project Structure
-
-Galbe is highly flexible in terms of project structure. The [Automatic Route Analyzer](routes.md#automatic-route-analyzer), triggered by the `routes` configuration option (default: `src/**/*.route.{js,ts}`), enables versatile project organization.
-
-Here are two examples of valid project structures:
-
-**Example 1**
-
-```txt
-┌── src
-│   ├── hooks
-│   │   └── log.hook.ts
-│   ├── routes
-│   │   ├── foo.route.ts
-│   │   └── bar.route.ts
-│   └── schemas
-│       ├── foo.schema.ts
-│       └── bar.schema.ts
-├── galbe.config.ts
-├── index.ts
-├── package.json
-├── README.md
-└── tsconfig.json
-```
-
-**Example 2**
-
-```txt
-┌── src
-│   ├── hooks
-│   │   └── log.hook.ts
-│   ├── foo
-│   │   ├── foo.route.ts
-│   │   └── foo.schema.ts
-│   └── bar
-│       ├── bar.route.ts
-│       └── bar.schema.ts
-├── galbe.config.ts
-├── index.ts
-├── package.json
-├── README.md
-└── tsconfig.json
-```
-
-In both cases, the [Automatic Route Analyzer](routes.md#automatic-route-analyzer) will detect `foo.route.ts` and `bar.route.ts` to set up route definitions.
-
-For more details, see the [Route Files](routes.md#route-files) section.
-
-> [!NOTE]
-> These examples work with the default configuration, but you can customize the `routes` property to fit your project structure. Define `routes` with your preferred pattern(s) to match your file organization.
-
-## Debugging
-
-The easiest way to debug your application is by using the [VSCode Bun extension](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode).
-
-Create a `.vscode/launch.json` configuration file in your project root with the following content:
-
-```json
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "bun",
-      "request": "launch",
-      "name": "Debug Galbe",
-      "program": "node_modules/galbe/bin/cli.ts",
-      "env": { "TERM": "xterm" },
-      "cwd": "${workspaceFolder}",
-      "runtime": "bun",
-      "runtimeArgs": ["dev", "index.ts", "-w", "."]
-    }
-  ]
-}
-```

package/docs/handler.md

@@ -1,119 +0,0 @@
-# Handler
-
-A handler is a function that gets executed when a request matches the route definition. It is responsible for processing the request and sending a response.
-
-## Handler Declaration
-
-The handler should be declared as the last argument of the [Route Definition](routes.md#route-definition) method.
-
-```js
-galbe.get('foo', schema, [hook1, hook2], ctx => {})
-```
-
-Handlers are called after the last hook call, or right after the request parsing if no hook is declared. To get a better understanding of the request lifecycle, you can refer to the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
-
-## Handler Definition
-
-```js
-const handler = ctx => {
-  const { name } = ctx.query
-  return `Hello ${name}!`
-}
-```
-
-The handler function takes a `context` object as its single argument and might return a `response`.
-
-### Context
-
-The `context` object contains the request information as well as a `set` object that serves as a response modifier. You can find more detailed information about the `context` object in the [Context](context.md) section.
-
-### Response
-
-To send a response, your handler can return an object. The response sent will depend on the type of the object returned. There are four types of responses that can be returned by a handler method. More about that in the next section.
-
-## Response Types
-
-> [!NOTE]
-> This section only covers response body payloads. To return specific response headers and/or status, you should define them with the `context.set` object before the return statement. More about it in the [Context](context.md) section.
-
-### String
-
-Case where a `string` is returned by the handler.
-
-- status: 200
-- content-type: `text/plain`
-
-#### Example
-
-```js
-galbe.get('/example', ctx => {
-  return 'Hello Mom!'
-})
-```
-
-### Object
-
-Case where an `object` is returned by the handler.
-
-- status: 200
-- content-type: `application/json`
-
-#### Example
-
-```js
-galbe.get('/example', ctx => {
-  return { message: 'Hello Mom!' }
-})
-```
-
-### Response Instance
-
-Case where a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance is returned by the handler.
-
-In this case, `context.set` properties are not taken into account to construct the response.
-
-#### Example
-
-<!-- prettier-ignore -->
-```js
-galbe.get('/example', ctx => {
-  return new Response(
-    'Hello Mom',
-    { status: 200, headers: { 'content-type': 'text/plain' } }
-  )
-})
-```
-
-### Generator
-
-Case where a [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) instance is returned by the handler.
-
-- status: 200
-- content-type: `text/event-stream`
-
-#### Example
-
-```js
-async function* generator(array) {
-  for (const item of array) {
-    await Bun.sleep(500)
-    yield item
-  }
-}
-
-galbe.get('/example', ctx => generator(['one', 'two', 'three']))
-```
-
-## Throwing Errors
-
-Throwing a `RequestError` at any point in the handler execution will result in a response with the specified status and payload.
-
-#### Example
-
-```ts
-g.get("/test", () => {
-  throw new RequestError({ status: 418, payload: '🫖' })
-})
-```
-
-Any other kind of error will result in a `500` response with the error message `"Internal Server Error"` by default. You can always customize it by defining a custom [Error Handler](error-handler.md).

package/docs/hooks.md

@@ -1,90 +0,0 @@
-# Hooks
-
-Hooks provide a simple way to execute specific actions before and/or after reaching a route endpoint in Galbe.
-
-## Defining Hooks
-
-```ts
-const hook = async (context, next) => {
-  context.state['foo'] = 'bar'
-  await next()
-  console.log('Hook end')
-}
-```
-
-A hook takes two arguments: `context` and `next`.
-
-### context
-
-The `context` object contains request information and a modifiable `state` property that persists across all hooks and the handler. This is useful for sharing data across hooks and handlers. More details are available in the [Context](context.md) section.
-
-### next
-
-The `next` function calls the next hook in the list, or the handler if the current hook is the last one. The `next` function should be called at most once. If omitted, Galbe will automatically call it at the end of the current hook’s execution.
-
-> [!TIP]
-> Hooks are interruptible, meaning they can return a response at any time. This is useful for implementing custom logic such as authentication, authorization, and caching.
->
-> For more details on response handling, see [Response Types](handler.md#response-types).
-
-## Declaring Hooks
-
-Hooks should be declared before the handler method in the [Route Definition](routes.md#route-definition) as a list of hook functions.
-
-```ts
-galbe.get('/foo', [hook1, hook2, ...], ctx => {})
-```
-
-Hooks execute in the order they are declared, just before the [Handler](handler.md). For a deeper understanding of their execution in the request lifecycle, see the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
-
-### Examples
-
-#### Linear Hook Execution
-
-```ts
-const hook1 = context => {
-  console.log('hook1 called')
-}
-const hook2 = context => {
-  console.log('hook2 called')
-}
-
-galbe.get('/example', [hook1, hook2], ctx => {
-  console.log('handler')
-})
-```
-
-```bash
-$ curl http://localhost:3000/example
-hook1
-hook2
-handler
-```
-
-#### Nested Hook Execution
-
-```ts
-const hook1 = async (context, next) => {
-  console.log('hook1 start')
-  await next()
-  console.log('hook1 end')
-}
-const hook2 = async (context, next) => {
-  console.log('hook2 start')
-  await next()
-  console.log('hook2 end')
-}
-
-galbe.get('/example', [hook1, hook2], ctx => {
-  console.log('handler')
-})
-```
-
-```bash
-$ curl http://localhost:3000/example
-hook1 start
-hook2 start
-handler
-hook2 end
-hook1 end
-```

package/docs/plugins.md

@@ -1,146 +0,0 @@
-# Plugins
-
-Galbe provides a powerful plugin system that allows developers to extend and customize the framework’s behavior. The plugin capabilities integrate with the [Request Lifecycle](https://galbe.dev/documentation/lifecycle).
-
-## Definition
-
-### Plugin Signature
-
-```ts
-type GalbePlugin = {
-  name: string
-  init?: (config: any, galbe: Galbe) => MaybePromise<void>
-  onFetch?: (context: Context) => MaybePromise<Response | void>
-  onRoute?: (context: Context) => MaybePromise<Response | void>
-  beforeHandle?: (context: Context) => MaybePromise<Response | void>
-  afterHandle?: (response: Response, context: Context) => MaybePromise<Response | void>
-}
-```
-
-### name
-The plugin name should be a Unique Plugin Identifier to prevent conflicts with other plugins. Ideally, it follows the format `com.example.myplugin`.
-
-### init
-This method is called immediately after the server starts. It receives two arguments:
-- `config`: The plugin-specific configuration (See [Configuration](getting-started.md#properties) `plugin` property).
-- `galbe`: The Galbe server instance, from which you can retrieve routes using `galbe.router.routes`.
-
-### onFetch
-This method is executed at the beginning of an incoming request. It receives a `context` object representing the [Request Context](context.md).
-
-It is **preemptable**, meaning that if a response is returned, it will be sent to the client immediately, bypassing further processing.
-
-### onRoute
-Executed after the router identifies a matching route for the request. It takes a `context` argument and is **preemptable**, meaning it can return an early response.
-
-### beforeHandle
-Runs after request validation but before route hooks and the handler are called. Like the previous lifecycle methods, it is **preemptable**.
-
-### afterHandle
-Called after the route handler is executed but before sending the response. It receives two arguments:
-- `response`: The [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object from the handler.
-- `context`: The request [Context](context.md).
-
-It is also **preemptable**, meaning any returned response will override the original handler response.
-
-## Plugin Registration
-
-To register a plugin with your Galbe server, use the `use` method on your Galbe instance.
-
-```js
-const galbe = new Galbe()
-galbe.use(plugin)
-```
-
-## How to Create a Plugin
-
-This section will walk you through the process of creating a plugin.
-Before creating a plugin, don't forget to check if there's an existing plugin that can be used. You can take a look at the official [Plugin List](https://galbe.dev/plugins).
-
-### 1. Scaffolding
-
-The Galbe starter CLI provides a template for setting up a plugin project:
-
-```bash
-$ bun create galbe my-plugin --template plugin
-$ cd my-plugin
-$ bun install
-```
-
-### 2. Implementation
-
-Below is an example of a plugin that handles routes tagged with `@deprecated` metadata (See [Route Files](routes.md#route-files) for metadata usage).
-
-deprecated.plugin.ts
-```ts
-import type { GalbePlugin, Route } from 'galbe'
-import { walkMetaRoutes } from 'galbe/utils'
-
-const PLUGIN_ID = 'dev.galbe.deprecated'
-
-export default (): GalbePlugin => {
-  let deprecateds = new Set<string>()
-  const isRouteDeprecated = (route?: Route) => 
-    deprecateds.has(JSON.stringify({ method: route?.method, path: route?.path }))
-  
-  return {
-    name: PLUGIN_ID,
-    // Init the plugin, check for deprecated metadata tags
-    init(_config, galbe) {
-      walkMetaRoutes(galbe.meta || [], (method, path, meta) => {
-        if (meta.deprecated) deprecateds.add(JSON.stringify({ method, path }))
-      })
-    },
-    // Check if the current route is deprecated; if so, flag it as such and log it
-    onRoute(context) {
-      let r = context.route
-      if (isRouteDeprecated(r)) {
-        console.warn(`Call to deprecated route "${r?.method} ${r?.path}"`)
-      }
-    },
-    // Add a header to the response if the route has been flagged as deprecated
-    afterHandle(response, context) {
-      if (isRouteDeprecated(context.route)) {
-        response.headers.set('x-deprecated', 'true')
-      }
-    }
-  } as GalbePlugin
-}
-```
-
-Register the plugin with your Galbe server:
-
-```ts
-import { Galbe } from 'galbe'
-import deprecatedPlugin from './deprecated.plugin'
-
-const galbe = new Galbe()
-galbe.use(deprecatedPlugin())
-
-export default galbe
-```
-
-### 3. Publishing
-
-To submit your plugin to the [official plugin list](https://galbe.dev/plugins), follow these steps:
-
-1. **Create a public GitHub repository** for your plugin, ensuring that the `README.md` includes:
-   - A clear description of your plugin.
-   - Installation and configuration instructions.
-   - Usage examples.
-
-2. _(Optional)_ Publish your plugin to [NPM](https://npmjs.com).
-
-3. **Submit a Pull Request** to add your plugin configuration to [plugins.json](https://github.com/pierre-cm/galbe-website/blob/main/plugins.json) in the following format:
-
-```json
-"plugin-id": {
-  "name": "Plugin Name",
-  "description": "Plugin description",
-  "repo": "https://github.com/<username>/<repo-name>",
-  "npm": "https://www.npmjs.com/package/<package-name>"
-}
-```
-
-> [!IMPORTANT]
-> Provide all relevant details in the Pull Request description. It will be reviewed by project maintainers as soon as possible. Check the [Galbe Contributing Guide](https://github.com/pierre-cm/galbe/blob/main/docs/CONTRIBUTING.md) before submitting.

package/docs/router.md

@@ -1,10 +0,0 @@
-# Router
-
-Galbe router employs a hybrid approach to store and locate routes.
-
-The static routes are maintained in a Map structure. This ensures that any incoming request path matching a static route is resolved in a constant time `O(1)`.
-
-> [!NOTE]
-> A static route is a route that doesn't contain any parameter (e.g.,`:param`) or wildcards `*`.
-
-All other routes are stored in a [Trie](https://en.wikipedia.org/wiki/Trie)-like data structure. The time complexity of the search operation in this case is `O(n)`, where `n` represents the number of segments in the incoming request path.

package/docs/routes.md

@@ -1,133 +0,0 @@
-# Routes
-
-Routes serve as the entry points for handling client requests in a Galbe application. This section covers route definition, available configuration options, and the Automatic Route Analyzer, which simplifies route setup.
-
-## Defining Routes
-
-Here's how to define routes in Galbe:
-
-```ts
-galbe.[method](path: string, schema?: Schema, hooks?: Hooks[], handler: Handler)
-```
-
-- **method** (`get` | `post` | `put` | `delete` | `patch` | `options` | `head`)
-  - The [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for the route.
-
-- **path** (string)
-  - The URL path of the route, composed of segments separated by `/`. Each segment may contain alphanumeric characters and dashes but should not start or end with a dash.
-  - Special segments:
-    - `:param` → A segment starting with `:` represents a parameter.
-    - `*` → A wildcard segment matching any sequence of segments.
-
-- **schema** (Schema) _(Optional)_
-  - See the [Schemas](schemas.md) section.
-
-- **hooks** (Hook[]) _(Optional)_
-  - See the [Hooks](hooks.md) section.
-
-- **handler** (Handler)
-  - See the [Handler](handler.md) section.
-
-### Examples
-
-#### Basic Route
-
-```js
-galbe.get('/foo', ctx => 'Hello, World!')
-```
-
-#### Route with a Schema
-
-<!-- prettier-ignore -->
-```js
-galbe.get(
-  '/foo/:bar',
-  { params: { bar: $T.string() } },
-  ctx => `Hello, ${ctx.params.bar}!`
-)
-```
-
-#### Route with Hooks
-
-<!-- prettier-ignore -->
-```js
-galbe.get(
-  '/foo/:bar',
-  [() => console.log('Hook1'), () => console.log('Hook2')],
-  ctx => `Hello, ${ctx.params.bar}!`
-)
-```
-
-#### Route with Schemas and Hooks
-
-<!-- prettier-ignore -->
-```js
-galbe.get(
-  '/foo/:bar',
-  { params: { bar: $T.string() } },
-  [() => console.log('Hook')],
-  ctx => `Hello, ${ctx.params.bar}!`
-)
-```
-
-## Defining Static Routes
-
-Static routes serve files from the filesystem.
-
-```ts
-galbe.static(path: string, target: string, options?: StaticEndpointOptions)
-```
-
-- **path** (string): The URL path of the route.
-
-- **target** (string): The path to the directory or file to serve.
-
-- **options** (StaticEndpointOptions) _(Optional)_:
-  - **resolve** ((path: string, target: string) => string | null | undefined | void) _(Optional)_
-    A function that resolves the path to the file to serve. The function may return a string corresponding to the new target.
-
-### Examples
-
-<!-- prettier-ignore -->
-```js
-galbe.static('/static', './public')
-```
-
-## Automatic Route Analyzer
-
-> [!NOTE]
-> This feature is only available if you run or build the app using the [Galbe CLI](getting-started.md#galbe-cli). The CLI is used by default if you followed the [Automatic Installation](getting-started.md#automatic-installation) or configured `package.json` accordingly.
-
-The Automatic Route Analyzer scans all Route Files in your project and sets up route definitions automatically. By default, it looks for files matching `src/**/*.route.{js,ts}`. This behavior can be customized via the `routes` property in your Galbe configuration. Setting it to `false` disables the analyzer.
-
-### Route Files
-
-To be analyzed correctly, a Route File must export a default function that accepts a Galbe instance as its only argument. Define your routes within this function. Example in JavaScript:
-
-```ts
-export default g => {
-  g.get('/foo/:bar', ctx => ctx.params.bar)
-}
-```
-
-The Automatic Route Analyzer can also extract metadata from multiline comments. Some plugins utilize this metadata for specific tasks. Example:
-
-```js
-/**
- * Header metadata description
- * @annotation Example of a header annotation
- */
-export default g => {
-  /**
-   * Route-specific metadata
-   * @deprecated
-   * @operationId fooBar
-   * @tags tag1 tag2
-   */
-  g.get('/foo/:bar', ctx => ctx.params.bar)
-}
-```
-
-> [!TIP]
-> To exclude a route from analysis, add `//@galbe-ignore` before its definition. This is useful for preventing certain routes from being included in automatic analysis or documentation generation.
-