galbe 0.1.4 → 0.1.7

package/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      scope:
+        description: 'Version bump scope (patch, minor, major)'
+        required: true
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      RELEASE_SCOPE: ${{ github.event.inputs.scope }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+          registry-url: https://registry.npmjs.org
+      - name: Setup SSH
+        uses: webfactory/ssh-agent@v0.8.0
+        with:
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+      - name: Setup Git
+        run: |
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+          git config user.name "${GITHUB_ACTOR}"
+      - name: Install dependencies & build
+        run: |
+          bun install & bun run build
+      - name: Release
+        run: |
+          npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
+          bun run release --increment $RELEASE_SCOPE --ci --no-git.requireCleanWorkingDir

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Galbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,22 @@
 # Galbe
+
+[![Build & Test](https://github.com/pierre-cm/galbe/actions/workflows/build_test.yml/badge.svg?branch=main)](https://github.com/pierre-cm/galbe/actions/workflows/build_test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/pierre-cm/galbe/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/galbe)](https://www.npmjs.com/package/galbe)
+
+Galbe is a fast, lightweight and highly customizable JavaScript web framework based on [Bun](https://bun.sh).
+
+> [!IMPORTANT]  
+> Galbe is currently under active development and not guaranteed to be stable. Future releases may potentially introduce breaking changes.
+
+## Getting started
+
+```bash
+bun create galbe
+```
+
+## Documentation
+
+The detailed documentation is available at [galbe.dev](https://galbe.dev).
+
+## Contributing

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/bunfig.toml

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

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 to build fast and versatile backend servers with Bun.
+
+It was designed with simplicity in mind, allowing you to quickly create and setup a project. In addition, Galbe also offers usefull features, allowing you to focus on your application logic rather than the rest.
+
+## 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 `loclahost:3000`.
+
+To verify that the project was setup correctly and is running, try to reach `loclahost: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
+
+An common way to handle server configuration is to create new file a `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 under the [Routes](routes.md) section.
+
+> [!NOTE]  
+> Those are just examples that will work with the default configuration. You can of course redefine `routes` property with your own pattern(s) to fit your own project structure.

package/docs/routes.md

@@ -0,0 +1,124 @@
+# Routes
+
+## 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) section.
+
+**hooks** (Hook[]) _Optional_
+
+See [Hooks](hooks) section.
+
+**handler** (Handler)
+
+See [Handler](handler) 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](), which is the case by default if you created your app following the [Automatic Installation]() step or properly configured your package.json to do so.
+
+The Automatic Route Analyzer is in charge of analyzing all the Route Files of your project and set up the routes defintions to your Glabe 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 a basic js example:
+
+```ts
+export default g => {
+  g.get('/foo/:bar', ctx => ctx.params.bar)
+}
+```
+
+The same example using Typescript:
+
+```ts
+import type { Galbe } from 'galbe'
+export default (g: Galbe) => {
+  g.get('/foo/:bar', ctx => ctx.params.bar)
+}
+```
+
+The Automatic Route Analyzer is also capable of collecting metadata about your Routefile and your routes by analyzing multiline comments. This can be used by some plugins to perform specific tasks. Here is an example of Routefile with multiline comments 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's metadata and how to use them along with examples in a plugin in the [Plugin](plugins) section.