galbe 0.12.0 → 0.12.2

package/docs/schemas.md

@@ -1,327 +0,0 @@
-# Schemas
-
-Galbe provides a custom Schema Type processor that offers type safety, data parsing, and validation. The use of Schemas highly simplifies request input validation and automatic error handling. Additionally, it enhances the developer experience by inferring static TypeScript types from schema definitions.
-
-## Schema Types
-
-To use Schema definitions, import `$T` from the `galbe` library:
-
-```js
-import { $T } from 'galbe'
-```
-
-Here is the list of available Schema types in Galbe:
-
-#### boolean
-
-Schema Type matching `boolean` values.
-
-```ts
-const boolSchema = $T.boolean()
-```
-
-#### string
-
-Schema Type matching `string` values.
-
-```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)
-```
-
-#### null
-
-Schema Type matching `null` values.
-
-```ts
-const nullSchema = $T.null(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)
-```
-
-#### optional
-
-Makes any type optional, allowing `undefined` values.
-
-```ts
-const optionalSchema = $T.optional($T.string())
-```
-
-#### nullable
-
-Makes any type nullable, allowing `null` values.
-
-```ts
-const nullableSchema = $T.nullable($T.string())
-```
-
-#### nullish
-
-Makes any type nullish, allowing both `undefined` and `null` values.
-
-```ts
-const nullishSchema = $T.nullish($T.string())
-```
-
-#### union
-
-Creates a union of Schema Types.
-
-```ts
-const unionSchema = $T.union([$T.string(), $T.number()])
-```
-
-## Request Schema Definition
-
-The Request Schema definition allows you to define a schema for your request in your [Route Definition](routes.md#route-definition). It must be defined right after the route path.
-
-```js
-const schema = {}
-galbe.get('/foo/:bar', schema, ctx => {})
-```
-
-The Request Schema has four optional properties:
-
-### headers
-
-```ts
-headers: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
-```
-
-Defines request headers with their respective Schema types.
-
-**Example:**
-
-```ts
-const schema = {
-  headers: {
-    'User-Agent': $T.optional($T.string({ pattern: '^Bun' }))
-  }
-}
-```
-
-### params
-
-```ts
-params: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
-```
-
-Defines route parameters with their respective Schema types.
-
-**Example:**
-
-```ts
-const schema = {
-  params: {
-    name: $T.string(),
-    age: $T.integer({ min: 0 })
-  }
-}
-```
-
-> [!WARNING]
-> Every key should match an existing [route path](routes.md#route-definition) parameter. Otherwise, TypeScript will show an error. If no schema is defined for a given parameter, Galbe assumes it is of type `string`.
-
-### query
-
-```ts
-query: { [key: string]: STString | STBoolean | STNumber | STInteger | STLiteral }
-```
-
-Defines query parameters with their respective Schema types.
-
-**Example:**
-
-```ts
-const schema = {
-  query: {
-    name: $T.literal('Galbe'),
-    list: $T.array($T.number())
-  }
-}
-```
-
-### body
-
-<!-- prettier-ignore -->
-```ts
-body: {
-  byteArray?: STByteArray | STStream
-  text?: STString | STLiteral | STBoolean | STNumber | STInteger | STUnion | STStream
-  json?: STJson | STObject | STBoolean | STInteger | STNumber | STString | STArray | STUnion
-  urlForm?: STObject | STStream | STUnion
-  multipart?: STMultipartForm | STStream | STUnion
-  default?: STString | STByteArray | STStream | STAny
-}
-```
-
-Defines the request body Schema type based on content type.
-
-#### Byte Array
-
-Defines an `application/octet-stream` request body.
-
-```ts
-const body = {
-  byteArray: $T.byteArray()
-}
-```
-
-#### Text
-
-Defines an `text/*` request body.
-
-```ts
-const body = {
-  text: $T.string()
-}
-```
-
-#### JSON
-
-Defines an `application/json` request body.
-
-```ts
-const body = {
-  json: $T.object({
-    name: $T.string(),
-    age: $T.integer({ min: 0 })
-  })
-}
-```
-
-#### URL Form
-
-Defines an `application/x-www-form-urlencoded` request body.
-
-```ts
-const body = { 
-  urlForm: {$T.object({
-    name: $T.string(),
-    age: $T.integer({ min: 0 })
-  })
-}
-```
-
-#### Multipart Form
-
-Defines a `multipart/form-data` request body.
-
-```ts
-const body = {
-  multipart: $T.multipartForm({
-    name: $T.string(),
-    age: $T.integer({ min: 0 })
-  })
-}
-```
-
-#### stream
-
-Certain request body types can be streamed using `STStream` wrapper, improving performance by validating data incrementally.
-This can be usefull to imporve performances in case you have heavy body payloads by leveraging early validation and fail fast behaviors.
-
-**Example**
-
-Let's consider a `multipart/form-data` body request that has two properties: `username` and `heavyImageFile`:
-
-```ts
-galbe.post(
-  'user/create',
-  {
-    body: {
-      multipart: $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
-  }
-})
-```
-
-In that case, even if the `username` doesn't pass the validation, the full request body, including the `heavyImageFile` is processed before sending the response. This induces unnecessary time and resource consumption because the `heavyImageFile` is processed despite never been used.
-
-A better approach would consist in leveraging `STStream` wrapper to implement early validation and fail fast behavior. By defining the request body as a stream. Instead of receiving a plain js object as `ctx.body`, you will receive an [AsyncGenerator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
-
-```ts
-galbe.post(
-  'user/create',
-  {
-    body: {
-      multipart: $T.stream($T.multipartForm({
-        username: $T.string(),
-        heavyImageFile: $T.byteArray()
-      }))
-    }
-  },
-  async 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
-  }
-})
-```
-
-### response
-
-<!-- prettier-ignore -->
-```ts
-response: Record<number | 'default', STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | STObject | STArray | STStream>
-```
-
-Defines response validation by associating schema types with specific HTTP status codes. The special key `default` can also be used to define the Response Schema for the remaining status codes.
-
-**Example:**
-
-```ts
-const response = {
-  200: $T.object({ data: $T.array($T.number()) }),
-  404: $T.literal("Not found"),
-  default: $T.string(),
-}
-```
-
-This ensures all responses adhere to the defined schema.
-
-> [!NOTE]
-> The response validation is enabled by default, meaning that every enpoint response that has a schema defined will be validated at runtime. To disable runtime validation, you can set the `responseValidator?.enabled` option to `false` in the [configuration](getting-started.md#configuration).

package/test/hooks.test.ts

@@ -1,200 +0,0 @@
-import { expect, test, describe } from 'bun:test'
-import { Galbe } from '../src'
-
-const port = 7360
-
-describe('hooks', async () => {
-  const galbe = new Galbe()
-  await galbe.listen(port)
-
-  test('hooks, empty', async () => {
-    galbe.get('/hooks/empty', [], () => 'handled')
-
-    let resp = await fetch(`http://localhost:${port}/hooks/empty`, {
-      method: 'GET'
-    })
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, void', async () => {
-    galbe.get('/hooks/void', [(_ctx, _next) => {}], () => 'handled')
-
-    let resp = await fetch(`http://localhost:${port}/hooks/void`, {
-      method: 'GET'
-    })
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, called without next', async () => {
-    let hookCalled = 0
-    galbe.get(
-      '/hooks/called',
-      [
-        _ => {
-          hookCalled++
-        }
-      ],
-      () => 'handled'
-    )
-    expect(hookCalled).toBe(0)
-    let resp = await fetch(`http://localhost:${port}/hooks/called`, {
-      method: 'GET'
-    })
-    expect(hookCalled).toBe(1)
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, called with next', async () => {
-    let hookCalled = 0
-    galbe.get(
-      '/hooks/called',
-      [
-        async (_, next) => {
-          hookCalled++
-          await Bun.sleep(10)
-          await next()
-        }
-      ],
-      () => 'handled'
-    )
-    expect(hookCalled).toBe(0)
-    let resp = await fetch(`http://localhost:${port}/hooks/called`, {
-      method: 'GET'
-    })
-    expect(hookCalled).toBe(1)
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, wrapper hook', async () => {
-    let before = 0
-    let after = 0
-    galbe.get(
-      '/hooks/called',
-      [
-        async (_, next) => {
-          before++
-          await Bun.sleep(10)
-          await next()
-          after++
-        }
-      ],
-      () => {
-        expect(before).toBe(1)
-        expect(after).toBe(0)
-        return 'handled'
-      }
-    )
-    expect(before).toBe(0)
-    expect(after).toBe(0)
-    let resp = await fetch(`http://localhost:${port}/hooks/called`, {
-      method: 'GET'
-    })
-    expect(before).toBe(1)
-    expect(after).toBe(1)
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, nested wrappers', async () => {
-    let before1 = 0
-    let after1 = 0
-    let before2 = 0
-    let after2 = 0
-    galbe.get(
-      '/hooks/called',
-      [
-        async (_, next) => {
-          before1++
-          await Bun.sleep(10)
-          await next()
-          after1++
-        },
-        async (_, next) => {
-          before2++
-          await Bun.sleep(10)
-          await next()
-          after2++
-        }
-      ],
-      () => {
-        expect(before1).toBe(1)
-        expect(before2).toBe(1)
-        expect(after1).toBe(0)
-        expect(after2).toBe(0)
-        return 'handled'
-      }
-    )
-    expect(before1).toBe(0)
-    expect(before2).toBe(0)
-    expect(after1).toBe(0)
-    expect(after2).toBe(0)
-    let resp = await fetch(`http://localhost:${port}/hooks/called`, {
-      method: 'GET'
-    })
-    expect(before1).toBe(1)
-    expect(before2).toBe(1)
-    expect(after1).toBe(1)
-    expect(after2).toBe(1)
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, linear chaining', async () => {
-    let hook1 = 0
-    let hook2 = 0
-    galbe.get(
-      '/hooks/called',
-      [
-        async _ => {
-          hook1++
-          await Bun.sleep(10)
-        },
-        async _ => {
-          hook2++
-          await Bun.sleep(10)
-        }
-      ],
-      () => {
-        expect(hook1).toBe(1)
-        expect(hook2).toBe(1)
-        return 'handled'
-      }
-    )
-    expect(hook1).toBe(0)
-    expect(hook2).toBe(0)
-    let resp = await fetch(`http://localhost:${port}/hooks/called`, {
-      method: 'GET'
-    })
-    expect(hook1).toBe(1)
-    expect(hook2).toBe(1)
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('handled')
-  })
-
-  test('hooks, early response', async () => {
-    let hook = 0
-    galbe.get(
-      '/hooks',
-      [
-        async _ => {
-          hook++
-          return 'hook'
-        }
-      ],
-      () => {
-        expect.unreachable()
-      }
-    )
-    expect(hook).toBe(0)
-    let resp = await fetch(`http://localhost:${port}/hooks`, {
-      method: 'GET'
-    })
-    expect(hook).toBe(1)
-    expect(resp.status).toBe(200)
-    expect(await resp?.text()).toBe('hook')
-  })
-})