galbe 0.1.6 → 0.1.7

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 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.

package/docs/schemas.md

@@ -0,0 +1,244 @@
+# Shemas
+
+Galbe offers a custom Schema Type processor that provides type safety along with data parsing and validation.
+
+The prime intention of that features is to offer an easy way to manage automatically request inputs validation and error handling. Moreover, it also greatly improve developper's experience by infering static Typescript types from schema definitions.
+
+## Schema Types
+
+To get started with Schema defintion, just import `$T` from `galbe` library:
+
+```js
+import { $T } from 'galbe'
+```
+
+Here the list of available Schema types in Galbe:
+
+#### Boolean
+
+Schema Type matching `boolean` values.
+
+```ts
+const boolSchema = $T.boolean()
+```
+
+#### String
+
+Schema Type matching `string` vlues.
+
+```ts
+const strSchema = $T.string(options)
+```
+
+#### Number
+
+Schema Type matching `number` values.
+
+```ts
+const numSchema = $T.number(options)
+```
+
+#### Integer
+
+Schema Type matching integer `number` values.
+
+```ts
+const intSchema = $T.integer(options)
+```
+
+#### Any
+
+Schema Type matching `any` of the previous Schema Types.
+
+```ts
+const anySchema = $T.any()
+```
+
+#### Array
+
+Schema Type matching `array` values.
+
+```ts
+const arraySchema = $T.array($T.any(), options)
+```
+
+#### Union
+
+Creates an union of Schema Types. .
+
+```ts
+const unionSchema = $T.union([$T.string(), $T.number()])
+```
+
+#### TOptional
+
+Makes any type optional. In practice, this allows for `undefined` values.
+
+```ts
+const optionalSchema = $T.optional($T.string())
+```
+
+## Request Schema definition
+
+The Request Schema definition allows you to define a schema for your request on your [Route Definition](). It must be defined right after the [path]() of your route.
+
+```js
+const schema = {}
+galbe.get('/foo/:bar', schema, ctx => {})
+```
+
+The Request Schema has 4 optional properties
+
+### headers
+
+```ts
+headers: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
+```
+
+This is a key-value object where each key represents a request `header` name and the value the Schema associated.
+
+**Example**:
+
+```ts
+const schema = {
+  headers: {
+    'User-Agent': $T.optional($T.string({ pattern: '^Bun' }))
+  }
+}
+```
+
+### params
+
+```ts
+params: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
+```
+
+This is a key-value object where each key represents a request `path parameter` name and the value the Schema associated.
+
+**Example**:
+
+```ts
+const schema = {
+  params: {
+    name: $T.string(),
+    age: $T.integer({ min: 0 })
+  }
+}
+```
+
+> [!WARNING]
+> Every key should match an existing [route path]() parameter. Otherwise Typescript will show you an error.
+>
+> By default, if no schema is defined for a given parameter. Galbe will assume it is of type `string`.
+
+### query
+
+```ts
+query: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
+```
+
+This is a key-value object where each key represents a request `query parameter` name and the value the Schema associated.
+
+**Example**:
+
+```ts
+const schema = {
+  query: {
+    name: $T.literal('Galbe'),
+    list: $T.array($T.number())
+  }
+}
+```
+
+### body
+
+```ts
+body: STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | STObject | STMulripartForm | STUrlForm
+```
+
+#### Json
+
+To define an `application/json` request body. You must use `STObject` Schema Type. Example:
+
+```ts
+const jsonBody = $T.object({
+  name: $T.string(),
+  age: $T.integer({ min: 0 })
+})
+```
+
+#### Multipart
+
+To define a `multipart/form-data` request body. You must use `TMultipartForm` Schema Type. Example:
+
+```ts
+const multipartBody = $T.multipartForm({
+  name: $T.string(),
+  age: $T.integer({ minimum: 0 })
+})
+```
+
+#### Url Form
+
+To define an `application/x-www-form-urlencoded` request body. You must use `TUrlForm` Schema Type. Example:
+
+```ts
+const urlBody = $T.urlForm({
+  name: $T.string(),
+  age: $T.integer({ minimum: 0 })
+})
+```
+
+#### Stream
+
+Some body request types can be streamed by using `STStream` Schema Type wrapper. Streamable Schema Types are `STByteArray`, `STString`, `STUrlForm` and `STMultipartForm`.
+
+This can be usefull to imporve performances in case you have heavy body payloads and you want to perform early validations on the body.
+
+Let's see a concrete example where that could be usefull. Imagine you want a `multipart/form-data` body request that has two properties `username` and `heavyImageFile`. In the normal case you would define something like that:
+
+```ts
+galbe.post(
+  'user/create',
+  {
+    body: $T.multipartForm({
+      username: $T.string(),
+      heavyImageFile: $T.byteArray()
+    })
+  },
+  ctx => {
+    // At that point, the full body request has been processed
+    if(!isValid(ctx.body.username))
+      throw new RequestError({ status: 400 })
+    else ctx.set.status = 201
+  }
+})
+```
+
+This means that in the case where the username wouldn't pass the validation, the full request body including the `heavyImageFile` would have been processed for nothing as it is not used. Inducing unnecessary time and resource consumption.
+
+The `STStream` Schema Type wrapper was created to remediate to that issue. In practice it allows you to perform validations on the fly.
+
+Now in your handler, instead of receiving an object as ctx.body, you'll receive an [AsyncGenerator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
+
+```ts
+galbe.post(
+  'user/create',
+  {
+    body: $T.stream($T.multipartForm({
+      username: $T.string(),
+      heavyImageFile: $T.byteArray()
+    }))
+  },
+  ctx => {
+    // At that point, the body has not been processed yet.
+    for await (const [key, value] of ctx.body) {
+      if (key === "username" && !isValid(value)) {
+        // Returns an early response before heavyImageFile is processed
+        throw new RequestError({ status: 400 })
+      }
+    }
+    ctx.set.status = 201
+  }
+})
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Fast, lightweight and highly customizable JavaScript web framework based on Bun",
   "author": "Pierre Caillaud M (https://github.com/pierre-cm)",
   "type": "module",
@@ -41,7 +41,6 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.31.28",
     "@swc/core": "^1.3.107",
     "@swc/wasm": "^1.4.0",
     "acorn": "^8.11.2",