galbe 0.10.1 → 0.12.0

package/docs/schemas.md

@@ -1,18 +1,18 @@
-# Shemas
+# Schemas
 
-Galbe provides a custom Schema Type processor that offers type safety, data parsing, and validation. The primary purpose of this feature is to simplify request input validation and error handling automatically. Additionally, it enhances the developer's experience by inferring static TypeScript types from schema definitions.
+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 start using Schema definitions, import `$T` from the `galbe` library:
+To use Schema definitions, import `$T` from the `galbe` library:
 
 ```js
 import { $T } from 'galbe'
 ```
 
-Here the list of available Schema types in Galbe:
+Here is the list of available Schema types in Galbe:
 
-#### Boolean
+#### boolean
 
 Schema Type matching `boolean` values.
 
@@ -20,15 +20,15 @@ Schema Type matching `boolean` values.
 const boolSchema = $T.boolean()
 ```
 
-#### String
+#### string
 
-Schema Type matching `string` vlues.
+Schema Type matching `string` values.
 
 ```ts
 const strSchema = $T.string(options)
 ```
 
-#### Number
+#### number
 
 Schema Type matching `number` values.
 
@@ -36,7 +36,7 @@ Schema Type matching `number` values.
 const numSchema = $T.number(options)
 ```
 
-#### Integer
+#### integer
 
 Schema Type matching integer `number` values.
 
@@ -44,7 +44,7 @@ Schema Type matching integer `number` values.
 const intSchema = $T.integer(options)
 ```
 
-#### Null
+#### null
 
 Schema Type matching `null` values.
 
@@ -52,7 +52,7 @@ Schema Type matching `null` values.
 const nullSchema = $T.null(options)
 ```
 
-#### Any
+#### any
 
 Schema Type matching `any` of the previous Schema Types.
 
@@ -60,7 +60,7 @@ Schema Type matching `any` of the previous Schema Types.
 const anySchema = $T.any()
 ```
 
-#### Array
+#### array
 
 Schema Type matching `array` values.
 
@@ -68,41 +68,41 @@ Schema Type matching `array` values.
 const arraySchema = $T.array($T.any(), options)
 ```
 
-#### Optional
+#### optional
 
-Makes any type optional. This allows for `undefined` values.
+Makes any type optional, allowing `undefined` values.
 
 ```ts
 const optionalSchema = $T.optional($T.string())
 ```
 
-#### Nullable
+#### nullable
 
-Makes any type nullable. This allows for `null` values.
+Makes any type nullable, allowing `null` values.
 
 ```ts
 const nullableSchema = $T.nullable($T.string())
 ```
 
-#### Nullish
+#### nullish
 
-Makes any type nullish. This allows for `undefined` and `null` values.
+Makes any type nullish, allowing both `undefined` and `null` values.
 
 ```ts
 const nullishSchema = $T.nullish($T.string())
 ```
 
-#### Union
+#### union
 
-Creates an union of Schema Types.
+Creates a union of Schema Types.
 
 ```ts
 const unionSchema = $T.union([$T.string(), $T.number()])
 ```
 
-## Request Schema definition
+## Request Schema Definition
 
-The Request Schema definition allows you to define a schema for your request on your [Route Definition](routes.md#route-defintion). It must be defined right after the path of your route.
+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 = {}
@@ -117,9 +117,9 @@ The Request Schema has four optional properties:
 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 is the associated Schema.
+Defines request headers with their respective Schema types.
 
-**Example**:
+**Example:**
 
 ```ts
 const schema = {
@@ -135,9 +135,9 @@ const schema = {
 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 is the associated Schema.
+Defines route parameters with their respective Schema types.
 
-**Example**:
+**Example:**
 
 ```ts
 const schema = {
@@ -149,9 +149,7 @@ const schema = {
 ```
 
 > [!WARNING]
-> Every key should match an existing [route path](routes.md#route-defintion) parameter. Otherwise Typescript will show an error.
->
-> By default, if no schema is defined for a given parameter. Galbe will assume it is of type `string`.
+> 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
 
@@ -159,9 +157,9 @@ const schema = {
 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 is the associated Schema.
+Defines query parameters with their respective Schema types.
 
-**Example**:
+**Example:**
 
 ```ts
 const schema = {
@@ -176,56 +174,96 @@ const schema = {
 
 <!-- prettier-ignore -->
 ```ts
-body: STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | STObject | STArray | STMulripartForm | STUrlForm | STStream
+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
+}
 ```
 
-#### Object
+Defines the request body Schema type based on content type.
+
+#### Byte Array
 
-To define an `application/json` request body, use `STObject` Schema Type. Example:
+Defines an `application/octet-stream` request body.
 
 ```ts
-const jsonBody = $T.object({
-  name: $T.string(),
-  age: $T.integer({ min: 0 })
-})
+const body = {
+  byteArray: $T.byteArray()
+}
 ```
 
-#### Multipart
+#### Text
 
-To define a `multipart/form-data` request body, use `TMultipartForm` Schema Type. Example:
+Defines an `text/*` request body.
 
 ```ts
-const multipartBody = $T.multipartForm({
-  name: $T.string(),
-  age: $T.integer({ minimum: 0 })
-})
+const body = {
+  text: $T.string()
+}
 ```
 
-#### Url Form
+#### JSON
 
-To define an `application/x-www-form-urlencoded` request body, use `TUrlForm` Schema Type. Example:
+Defines an `application/json` request body.
 
 ```ts
-const urlBody = $T.urlForm({
-  name: $T.string(),
-  age: $T.integer({ minimum: 0 })
-})
+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
+#### stream
 
-Some body request types can be streamed by using `STStream` Schema Type wrapper. The 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.
+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.
 
-Let's look at a concrete example where this could be useful. Imagine you want a `multipart/form-data` body request that has two properties: `username` and `heavyImageFile`. In a normal case, you would define something like this:
+**Example**
+
+Let's consider a `multipart/form-data` body request that has two properties: `username` and `heavyImageFile`:
 
 ```ts
 galbe.post(
   'user/create',
   {
-    body: $T.multipartForm({
-      username: $T.string(),
-      heavyImageFile: $T.byteArray()
-    })
+    body: {
+      multipart: $T.multipartForm({
+        username: $T.string(),
+        heavyImageFile: $T.byteArray()
+      })
+    }
   },
   ctx => {
     // At that point, the full body request has been processed
@@ -236,20 +274,22 @@ galbe.post(
 })
 ```
 
-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. This would induce unnecessary time and resource consumption.
+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.
 
-The `STStream` Schema Type wrapper was created to remediate to remediate this 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 will receive an [AsyncGenerator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator).
+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: $T.stream($T.multipartForm({
-      username: $T.string(),
-      heavyImageFile: $T.byteArray()
-    }))
+    body: {
+      multipart: $T.stream($T.multipartForm({
+        username: $T.string(),
+        heavyImageFile: $T.byteArray()
+      }))
+    }
   },
-  ctx => {
+  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)) {
@@ -266,16 +306,22 @@ galbe.post(
 
 <!-- prettier-ignore -->
 ```ts
-response: Record<number, STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | STObject | STArray | STStream>
+response: Record<number | 'default', STByteArray | STString | STBoolean | STNumber | STInteger | STLiteral | STObject | STArray | STStream>
 ```
 
-Same as for request body validation but to validate handler responses. Every schema type must be associated to a specific response status.
+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
+**Example:**
 
 ```ts
 const response = {
-  200: $T.object({ data: $T.array($T.number()) })
-  404: $T.literal("Not found")
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Fast, lightweight and highly customizable JavaScript web framework based on Bun",
   "author": "Pierre Caillaud M (https://github.com/pierre-cm)",
   "type": "module",

package/src/extras/spec/openapi.serializer.ts

@@ -1,7 +1,16 @@
-import type { STArray, STJson, STLiteral, STObject, STProps, STSchema, STUnion } from '../../../src/schema'
+import type {
+  STArray,
+  STIntersection,
+  STJson,
+  STLiteral,
+  STObject,
+  STProps,
+  STSchema,
+  STUnion,
+} from '../../../src/schema'
 
 import { Galbe } from '../../../src'
-import { walkRoutes, HttpStatus } from '../../../src/util'
+import { walkRoutes, HttpStatus, inferContentType } from '../../../src/util'
 import { Kind, Optional } from '../../../src/schema'
 
 import { OpenAPIV3 } from 'openapi-types'
@@ -12,10 +21,10 @@ const schemaToMedia = ({ type, format, isJson }: SchemaType) =>
   isJson || (type && ['object', 'number', 'boolean', 'array'].includes(type))
     ? 'application/json'
     : format === 'byte'
-      ? 'application/octet-stream'
-      : type === 'string'
-        ? 'text/plain'
-        : '*/*'
+    ? 'application/octet-stream'
+    : type === 'string'
+    ? 'text/plain'
+    : '*/*'
 
 export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<OpenAPIV3.Document> => {
   let paths: any = {}
@@ -24,7 +33,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     schemas: {},
     parameters: {},
     requestBodies: {},
-    responses: {}
+    responses: {},
   }
 
   const schemaToOpenapi = (
@@ -54,7 +63,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
 
     if (kind === 'null') {
       s = {
-        anyOf: ['null']
+        anyOf: ['null'],
       }
     } else if (kind === 'boolean') s = { type: 'boolean' }
     else if (kind === 'byteArray') s = { type: 'string', format: 'byte' }
@@ -64,7 +73,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         ...(exclusiveMinimum ? { exclusiveMinimum } : {}),
         ...(exclusiveMaximum ? { exclusiveMaximum } : {}),
         ...(minimum ? { minimum } : {}),
-        ...(maximum ? { maximum } : {})
+        ...(maximum ? { maximum } : {}),
       }
     else if (kind === 'integer')
       s = {
@@ -72,14 +81,14 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         ...(exclusiveMinimum ? { exclusiveMinimum } : {}),
         ...(exclusiveMaximum ? { exclusiveMaximum } : {}),
         ...(minimum ? { minimum } : {}),
-        ...(maximum ? { maximum } : {})
+        ...(maximum ? { maximum } : {}),
       }
     else if (kind === 'string')
       s = {
         type: 'string',
         ...(pattern ? { pattern } : {}),
         ...(minLength ? { minLength } : {}),
-        ...(maxLength ? { maxLength } : {})
+        ...(maxLength ? { maxLength } : {}),
       }
     else if (kind === 'any') s = { type: 'string' }
     else if (kind === 'literal') {
@@ -91,7 +100,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         items: schemaToOpenapi((schema as STArray).items).schema,
         ...(minItems ? { minItems } : {}),
         ...(maxItems ? { maxItems } : {}),
-        ...(uniqueItems ? { uniqueItems } : {})
+        ...(uniqueItems ? { uniqueItems } : {}),
       }
     } else if (kind === 'object') {
       let props = (schema as STObject).props || {}
@@ -101,7 +110,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       s = {
         type: 'object',
         properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])),
-        ...(required.length ? { required } : {})
+        ...(required.length ? { required } : {}),
       }
     } else if (kind === 'json') {
       let props = ((schema as STJson).props || {}) as STProps
@@ -115,13 +124,13 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         type: type,
         ...(type === 'object'
           ? {
-            properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])),
-            ...(required.length ? { required } : {})
-          }
-          : {})
+              properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])),
+              ...(required.length ? { required } : {}),
+            }
+          : {}),
       }
     } else if (kind === 'union') {
-      let anyOf = (schema as STUnion).anyOf
+      let anyOf: STSchema[] = (schema as STUnion).anyOf
       let nullable = anyOf.some(s => s[Kind] === 'null')
       anyOf = anyOf.filter(s => s[Kind] !== 'null')
 
@@ -131,12 +140,23 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         s = schemaToOpenapi(anyOf[0]).schema
       } else if (anyOf.length > 1) {
         s = {
-          anyOf: anyOf.map(s => schemaToOpenapi(s).schema)
+          anyOf: anyOf.map(e => schemaToOpenapi(e).schema),
         }
       }
 
       //@ts-ignore
       if (nullable) s.nullable = nullable
+    } else if (kind === 'intersection') {
+      let allOf: STSchema[] = (schema as STIntersection).allOf
+      if (allOf.length === 0) {
+        s = {}
+      } else if (allOf.length === 1) {
+        s = schemaToOpenapi(allOf[0]).schema
+      } else if (allOf.length > 1) {
+        s = {
+          allOf: allOf.map(s => schemaToOpenapi(s).schema),
+        }
+      }
     }
 
     s = { title: schema.title, description: schema.description, ...s }
@@ -168,7 +188,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       description: param?.description,
       required: kind === 'path' ? true : !param[Optional] || undefined,
       deprecated: param.deprecated,
-      schema
+      schema,
     }
     if (components.parameters && param.id) components.parameters[param.id] = p
     return p
@@ -178,18 +198,17 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     (routes, c) => ({ ...routes, ...c.routes }),
     {} as Record<string, Record<string, Record<string, any>>>
   )
-  let metaStatic = Object.fromEntries(Object.entries(metaRoutes || {}).filter((([_, d]) => d?.static)))
+  let metaStatic = Object.fromEntries(Object.entries(metaRoutes || {}).filter(([_, d]) => d?.static))
 
   walkRoutes(g.router.routes, r => {
     let meta = metaRoutes?.[r.path]?.[r.method]
-    if (r.static?.root)
-      meta = metaStatic[r.static?.root]?.static
+    if (r.static?.root) meta = metaStatic[r.static?.root]?.static
     if (meta?.hide) return
     let path = r.path.replaceAll(/:([^\/]+)/g, '{$1}')
     if (!(path in paths)) paths[path] = {}
     let tags = [
       ...(meta?.tags?.split(' ')?.map((t: string) => t.trim()) || []),
-      ...(typeof meta?.tag === 'string' ? [meta?.tag] : meta?.tag || [])
+      ...(typeof meta?.tag === 'string' ? [meta?.tag] : meta?.tag || []),
     ]
     let security: Record<string, any> = []
 
@@ -201,52 +220,62 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       : []
     let headerParam = r.schema?.headers
       ? Object.entries(r.schema?.headers as Record<string, STSchema>)
-        .map(([k, v]) => {
-          let p = parseParam(k, v, 'header')
-          if (k.match(/authorization/i)) {
-            // TODO: handle other auth methods
-            if (v.pattern && v?.pattern?.toString() === '/^Bearer /') {
-              security.push({ bearerAuth: [] })
-              components.securitySchemes = { bearerAuth: { type: 'http', scheme: 'bearer' } }
-              return null
+          .map(([k, v]) => {
+            let p = parseParam(k, v, 'header')
+            if (k.match(/authorization/i)) {
+              // TODO: handle other auth methods
+              if (v.pattern && v?.pattern?.toString() === '/^Bearer /') {
+                security.push({ bearerAuth: [] })
+                components.securitySchemes = { bearerAuth: { type: 'http', scheme: 'bearer' } }
+                return null
+              }
             }
-          }
-          return p
-        })
-        .filter(p => p)
+            return p
+          })
+          .filter(p => p)
       : []
     // TODO cookieParam
     let parameters = [...pathParam, ...queryParam, ...headerParam]
 
     let requestBody
     if (r.schema.body) {
-      let { schema, isJson } = schemaToOpenapi(r.schema.body)
-      let { type, format } = resolveRef(schema)
-      let media = schemaToMedia({ type, format, isJson } as SchemaType)
+      let description: string | undefined
+      let conflictDescription = false
+      let required = false
+      let content = Object.fromEntries(
+        Object.entries(r.schema.body).map(([bodyType, schema]) => {
+          const s = schema.description
+          const isDefined = typeof s === 'string' && s !== ''
+          if (s?.[Optional] === false) required = true
+          if (isDefined) {
+            if (description === undefined) {
+              description = s
+            } else if (description !== s) {
+              conflictDescription = true
+            }
+          }
+          description = conflictDescription ? undefined : description ?? undefined
+          return [inferContentType(bodyType), { schema: schemaToOpenapi(schema).schema }]
+        })
+      )
       requestBody = {
-        description: r.schema.body.description,
-        required: !r.schema.body[Optional],
-        content: {
-          [media]: { schema }
-        }
-      }
-      if (r.schema.body.id && components.requestBodies) {
-        components.requestBodies[r.schema.body.id] = requestBody
-        requestBody = { $ref: `#/components/requestBodies/${r.schema.body.id}` }
+        description,
+        required,
+        content,
       }
     }
     let responses
     if (r.schema.response && Object.keys(r.schema.response).length) {
       responses = Object.fromEntries(
         Object.entries(r.schema.response).map(([status, v]) => {
-          if(!v) return []
+          if (!v) return []
           let s = status as keyof typeof HttpStatus | 'default'
           let { schema, isJson } = schemaToOpenapi(v)
           let { type, format } = resolveRef(schema)
           let media = schemaToMedia({ type, format, isJson } as SchemaType)
           let response: OpenAPIV3.ResponseObject = {
             description: v.description || HttpStatus[s as keyof typeof HttpStatus] || 'Response',
-            content: { [media]: { schema: schema } }
+            content: { [media]: { schema: schema } },
           }
           if (components.responses && r.schema.response?.[s]?.id) {
             components.responses[r.schema.response?.[s]?.id as string] = response
@@ -258,12 +287,10 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       )
     } else {
       responses = {
-        default: { description: HttpStatus[200] }
+        default: { description: HttpStatus[200] },
       }
     }
     let summary = meta?.head.match(/^([^\n]+)/)?.[1]
-    console.log('#', r.method, r.path)
-    console.log(r.schema.body)
     paths[path][r.method] = {
       tags: tags.length ? tags : undefined,
       summary: summary,
@@ -272,7 +299,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       requestBody,
       responses,
       ...(security.length ? { security } : {}),
-      deprecated: meta?.deprecated ? true : undefined
+      deprecated: meta?.deprecated ? true : undefined,
     }
   })
 
@@ -285,9 +312,9 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     openapi: version,
     info: {
       title: 'Galbe app',
-      version: '0.1.0'
+      version: '0.1.0',
     },
     paths,
-    components: Object.keys(components)?.length ? components : undefined
+    components: Object.keys(components)?.length ? components : undefined,
   }
 }