galbe 0.1.6 → 0.1.8

package/.github/workflows/deploy_website.yml

@@ -16,5 +16,5 @@ jobs:
           -H "Accept: application/vnd.github+json" \
           -H "Authorization: Bearer ${{ secrets.GH_WEBSITE_TOKEN }}" \
           -H "X-GitHub-Api-Version: 2022-11-28" \
-          https://api.github.com/repos/pierre-cm/galbe-website/actions/workflows/ci.yml/dispatches \
+          https://api.github.com/repos/pierre-cm/galbe-website/actions/workflows/deploy.yml/dispatches \
           -d '{"ref":"main"}'

package/README.md

@@ -12,7 +12,9 @@ Galbe is a fast, lightweight and highly customizable JavaScript web framework ba
 ## Getting started
 
 ```bash
-bun create galbe
+bun create galbe app
+cd app
+bun install && bun dev
 ```
 
 ## Documentation

package/bin/cli.ts

@@ -5,7 +5,7 @@ import type { RouteMeta } from '../src/routes'
 import { program } from 'commander'
 import { relative, resolve } from 'path'
 import { mkdir, readdir, lstat, rm } from 'fs/promises'
-import { metaAnalysis } from '../src/routes'
+import { DEFAULT_ROUTE_PATTERN, metaAnalysis } from '../src/routes'
 import { randomUUID } from 'crypto'
 import { Galbe } from '../src'
 
@@ -14,7 +14,8 @@ const BUILD_ID = randomUUID()
 
 Bun.env.FORCE_COLOR = '1'
 
-const parseRoutes = async (routes?: string | string[]): Promise<{ path: string; meta: RouteMeta }[]> => {
+const parseRoutes = async (routes?: boolean | string | string[]): Promise<{ path: string; meta: RouteMeta }[]> => {
+  routes = routes === true ? DEFAULT_ROUTE_PATTERN : routes
   if (!routes) return []
   let files: { path: string; meta: RouteMeta }[] = []
   if (typeof routes === 'string') {
@@ -61,11 +62,12 @@ program.name('galbe').description('CLI to execute galbe utilities').version('0.1
 
 program
   .command('dev')
-  .description('Run a dev server running your galbe API')
+  .description('Start a dev server running your Galbe application')
   .argument('<string>', 'filename')
   .option('-p, --port <number>', 'port number', '')
+  .option('-w, --watch', 'watch file changes', 'true')
   .action(async (fileName, props) => {
-    const { port } = props
+    const { port, watch } = props
     const devRoot = resolve(ROOT, '.galbe', 'dev')
     await mkdir(devRoot, { recursive: true })
     await Bun.write(
@@ -76,15 +78,15 @@ program
       await rm(resolve(ROOT, '.galbe', 'dev'), { recursive: true })
     })
 
-    await $`BUN_ENV=development bun run --watch ${resolve(devRoot, 'index.ts')}`.cwd(ROOT)
+    await $`BUN_ENV=development bun run ${watch ? '--watch' : ''} ${resolve(devRoot, 'index.ts')}`.cwd(ROOT)
   })
 
 program
   .command('build')
-  .description('Build your galbe API')
+  .description('undle your Galbe application')
   .argument('<string>', 'filename')
-  .option('-o, --out <string>', 'output file', '')
-  .option('-c, --compile', 'standalone executable', false)
+  .option('-o, --out <string>', 'output file/directory', '')
+  .option('-c, --compile', 'create a standalone executable', false)
   .action(async (fileName, props) => {
     const { out, compile } = props
     const g: Galbe = (await import(resolve(ROOT, fileName))).default
@@ -97,7 +99,7 @@ program
       buildIndex,
       '--target',
       'bun',
-      ...(compile ? ['--compile', '--outfile', out ? out : 'api'] : ['--outdir', out ? out : 'dist'])
+      ...(compile ? ['--compile', '--outfile', out ? out : 'app'] : ['--outdir', out ? out : 'dist'])
     ].filter(c => c)
     Bun.spawn(cmds, {
       cwd: ROOT,

package/docs/getting-started.md

@@ -1,5 +1,223 @@
-### Create a project
+# Getting started
 
-```shell
-    bun create pierre-cm/create-galbe
+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.
+
+## Requirements
+
+To start developing your Galbe project, you first need to install [Bun](https://bun.sh).
+
+## Automatic Installation
+
+This is the recommended way of setting up a Galbe project.
+
+```bash
+bun create galbe app
+cd app
+bun install
 ```
+
+This will create a new project under `app` directory and install it.
+
+Now you can start the dev server by running:
+
+```bash
+bun dev
+```
+
+This will start a web server on `localhost:3000`.
+
+To verify that the project was setup correctly and is running, try to reach `localhost:3000/hello` endpoint, this should return following greeting message:
+
+```bash
+curl localhost:3000/hello
+Hello from Galbe!
+```
+
+> [!TIP]  
+> By default, the dev server automatically reloads on every file change.
+
+## Manual Installation
+
+Init a new Bun project and add Galbe as dependency:
+
+```bash
+bun init
+bun add galbe
+```
+
+Open `package.json` file and add the following scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "galbe dev index.ts",
+    "build": "galbe build index.ts",
+    "test": "bun test"
+  }
+}
+```
+
+As you can see, those scripts rely on Galbe CLI to run and build the application. You will find more info about Galbe CLI available options in the next section [Galbe CLI](#galbe-cli).
+
+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'
+
+const g = new Galbe({ port: 3000 })
+g.get('/hello', () => 'Hello Mom!')
+
+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.
+
+> [!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.
+
+### Galbe CLI
+
+```bash
+galbe <command> <argument> [options]
+```
+
+Here are the available commands:
+
+**dev**
+
+Start a dev server running your Galbe application.
+
+_argument_
+
+The path of the file exporting your Galbe instance
+
+_options_
+
+- `--port` or `-p`: port number (default: 3000)
+- `--watch` or `-w`: watch file changes (default: true)
+
+**build**
+
+Bundle your Galbe application.
+
+_argument_
+
+The path of the file exporting your Galbe instance
+
+_options_
+
+- `--out` or `-o`: output file | directory (default: app | dist )
+- `--compile` or `-c`: create a standalone executable (default: false)
+
+## Configuration
+
+To configure your Galbe server, you should pass your configuration to the Galbe constructor when you instanciate it.
+
+```ts
+const galbe = new Galbe(configuration)
+```
+
+### Properties
+
+**port**
+
+The port number that the server will be listening on. Default is `3000`.
+
+**basePath**
+
+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}`.
+
+**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).
+
+### 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:
+
+galbe.config.js
+
+```js
+export default {
+  port: Bun.env.GALBE_PORT
+  routes: 'src/**/*.route.ts',
+}
+```
+
+index.js
+
+```js
+import { Galbe } from 'galbe'
+import config from './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:
+>
+> ```ts
+> import type { GalbeConfig } from 'galbe'
+> const config: GalbeConfig = {
+>   port: Number(Bun.env.GALBE_PORT),
+>   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}`.
+
+Here are two examples of valid project structures by default:
+
+**Example 1**
+
+```txt
+┌── src
+│   ├── hooks
+│   │   └── log.hook.ts
+│   ├── routes
+│   │   ├── foo.route.ts
+│   │   └── foo.route.ts
+│   └── schemas
+│       ├── bar.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 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.
+
+> [!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.

package/docs/handler.md

@@ -0,0 +1 @@
+# Handler

package/docs/hooks.md

@@ -0,0 +1,88 @@
+# Hooks
+
+Hooks provide a simple way to perform specific actions before and/or after reaching a specific route endpoint.
+
+## Hook Definition
+
+```ts
+const hook = (context, next) => {
+  context.state['foo'] = 'bar'
+  await next()
+  console.log('Hook end')
+}
+```
+
+The hook takes only two arguments, a `context` object and a `next` function.
+
+**context**
+
+The `context` object contains the request information along with a state property that is modifiable and preserved across all hooks and the handler. It is useful for sharing information or objects across hooks and handler. You can find more information about it in the [Context]() section.
+
+**next**
+
+The `next` function calls the next hook in the hook list or the handler if the current hook is the last one declared. The `next` function should be called at most once. If it is omitted, Galbe will call it automatically at the end of the execution of the current hook.
+
+> [!TIP]
+> Hooks are interruptible objects, meaning they can return a response at any moment. This provides a powerful mechanism for implementing custom logic, such as authentication, authorization, caching, and more."
+
+## Hooks Declaration
+
+Hooks should be declared just before the handler method in the [Route Definition]() method as a list of Hooks.
+
+```ts
+galbe.get('foo', [ hook1, hook2, ... ], ctx => {})
+```
+
+Hooks are called just before the [Handler]() in the order that they have been declared in the hook list of the [Route Definition](). To get a better understanding of hooks execution during the request lifecycle, you can refer to the [Lifecycle]() section.
+
+### Examples
+
+Linear hooks declaration:
+
+```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 hooks declaration:
+
+```ts
+const hook1 = (context, next) => {
+  console.log('hook1 start')
+  await next()
+  console.log('hook1 end')
+}
+const hook2 = context => {
+  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

@@ -0,0 +1 @@
+# Plugins

package/docs/router.md

@@ -0,0 +1 @@
+# Router

package/docs/routes.md

@@ -0,0 +1,124 @@
+# Routes
+
+Routes are the entry points for handling client requests in a Galbe application. In this section, we'll cover how to define routes, the various options available for route definitions, and how to use the Automatic Route Analyzer to simplify route setup.
+
+## Route Definition
+
+Here is how to define routes in Galbe.
+
+```ts
+galbe.[method](path: string, schema?: Schema, hooks?: Hooks[], handler: Handler)
+```
+
+**method** ( get | post | put | delete | patch | options )
+
+The [HTTP Request Method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for the defined route.
+
+**path** (string)
+
+The path of the route. It should be composed of a sequence of segments separated by `/`. Each segment can be composed alphanumeric characters and dashes, but should not start or end with a dash.
+
+There are two special segments:
+
+- `:param` Any segment starting with `:` indicates a parameter segment.
+- `*` To indicate a wildcard segment. This will match any segment or sequence of segments.
+
+**schema** (Schema) _Optional_
+
+See [Schemas](schemas.md) section.
+
+**hooks** (Hook[]) _Optional_
+
+See [Hooks](hooks.md) section.
+
+**handler** (Handler)
+
+See [Handler](handler.md) section.
+
+### Examples
+
+**Basic route**
+
+```js
+galbe.get('/foo', ctx => 'Hello World!')
+```
+
+**Route with 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} !`
+)
+```
+
+## Automatic Route Analyzer
+
+> [!NOTE]
+> This feature is only available if you run/build the app via the [Galbe CLI](getting-started.md#galbe-cli), which is the case by default if you created your app following the [Automatic Installation](getting-started.md#automatic-installation) step or if you configured your package.json to do so.
+
+The Automatic Route Analyzer is responsible for analyzing all the Route Files of your project and setting up the route definitions for your Galbe server automatically. By default, the analyzer will search for Route Files matching paths like `src/**/*.route.{js,ts}`. This can be configured by modifying the value of `routes` property of your Galbe configuration. A value of `false` will disable the analyzer.
+
+### Route Files
+
+In order to be properly analyzed, Route Files must export a default function that takes a Galbe instance as unique argument. Your routes should be defined using that Galbe instance. Here's a basic example in JavaScript:
+
+```ts
+export default g => {
+  g.get('/foo/:bar', ctx => ctx.params.bar)
+}
+```
+
+The same example in Typescript:
+
+```ts
+import type { Galbe } from 'galbe'
+export default (g: Galbe) => {
+  g.get('/foo/:bar', ctx => ctx.params.bar)
+}
+```
+
+The Automatic Route Analyzer can also collect metadata about your Route File and your routes by analyzing multiline comments. This can be used by some plugins to perform specific tasks. Here's an example of a Route File with multiline comment metadata:
+
+```js
+/**
+ * This is the header's head comment
+ * @annotation example of header's annotation
+ */
+export default g => {
+  /**
+   * This is a route head comment
+   * @deprecated
+   * @tag tag1
+   * @tag tag2
+   */
+  g.get('/foo/:bar', ctx => ctx.params.bar)
+}
+```
+
+You will find more information about comment metadata and how to use them along with examples in the [Plugin](plugins.md) section.