galbe 0.1.13 → 0.2.0

package/docs/context.md

@@ -1,7 +1,7 @@
 # Context
 
 An instance of the context object is created when a new request is initiated and carrieds out along durring all the request lifecycle.
-See the [Lifecycle](lifecycle) section to get more details.
+See the [Lifecycle](https://galbe.dev/documentation/lifecycle) section to get more details.
 
 Its purpose is to carrie all the relevent information about the request and to allow sharing informations between each step of the request lifecycle.
 

package/docs/handler.md

@@ -10,7 +10,7 @@ The handler should be declared as last argument of the [Route Definition](routes
 galbe.get('foo', schema, [hook1, hook2], ctx => {})
 ```
 
-Handler are called after the last hook call, or right after the request parsing if no hook is declared. To get a better understanding of the request lifecycle, you can refer to the [Lifecycle](lifecycle.md) section.
+Handler are called after the last hook call, or right after the request parsing if no hook is declared. To get a better understanding of the request lifecycle, you can refer to the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
 
 ## Handler definition
 

package/docs/hooks.md

@@ -35,7 +35,7 @@ Hooks should be declared just before the handler method in the [Route Definition
 galbe.get('foo', [ hook1, hook2, ... ], ctx => {})
 ```
 
-Hooks are called just before the [Handler](handler.md) in the order that they have been declared in the hook list of the [Route Definition](routes.md#route-defintion). To get a better understanding of hooks execution during the request lifecycle, you can refer to the [Lifecycle](lifecycle.md) section.
+Hooks are called just before the [Handler](handler.md) in the order that they have been declared in the hook list of the [Route Definition](routes.md#route-defintion). To get a better understanding of hooks execution during the request lifecycle, you can refer to the [Lifecycle](https://galbe.dev/documentation/lifecycle) section.
 
 ### Examples
 

package/docs/plugins.md

@@ -1 +1,124 @@
 # Plugins
+
+Galbe provides a powerful plugin system that allows developers to extend and customize the behavior of the framework. The plugin capabilities are centered around the [Request Lifecycle](https://galbe.dev/documentation/lifecycle).
+
+## Definition
+
+```ts
+type GalbePlugin = {
+  name: string
+  init?: (config: any, galbe: Galbe) => MaybePromise<void>
+  onFetch?: (context: Context) => MaybePromise<Response | void>
+  onRoute?: (context: Context) => MaybePromise<Response | void>
+  beforeHandle?: (context: Context) => MaybePromise<Response | void>
+  afterHandle?: (response: Response, context: Context) => MaybePromise<Response | void>
+}
+```
+
+**name**
+
+The name should be a Unique Plugin Identifier. It should be chosen to be unique to avoid conflicts with other potential plugins. For example, Galbe's official plugins names will always start with `dev.galbe.*`.
+
+**init**
+
+This method is called right after the server starts. It takes two arguments: a `config` and a `galbe` instance. The `config` holds the configuration for the specific scope of the current plugin (See [Configuration](getting-started.md#properties) `plugin` property for more details). The `galbe` argument is the instance of the current server; you can for instance retrieve the current routes definitions with `galbe.router.routes`.
+
+**onFetch**
+
+This method is called at the beginning of an incoming request. It takes a single `context` argument representing the current request [Context](context.md).
+
+It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
+
+**onRoute**
+
+This method is called after the router has found a matching route for the current request. Its takes a single `context` argument representing the current request [Context](context.md).
+
+It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
+
+**beforeHandle**
+
+This method is called after the request has been validated and before the route hooks and the handler are called. It takes a single `context` argument representing the current request [Context](context.md).
+
+It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
+
+**afterHandle**
+
+This method is called after the route handler has been called and before the response is sent. Its takes two arguments: a `response` object containing the [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) returned by the handler, and a `context` argument representing the current request [Context](context.md).
+
+It is preemptable, meaning that any returned value will be interpreted as a response to send back to the client. Therefore, the method should only return [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instances or nothing.
+
+## Registration
+
+To register a plugin with your Galbe server, you must use the `use` method from you galbe instance.
+
+```js
+const galbe = new Galbe()
+galbe.use(plugin)
+```
+
+## Example
+
+Here is an example of a plugin implementation that handles routes tagged with `@deprecated` metadata (See [Route files](routes.md#route-files) section about metadata).
+
+```ts
+// myPlugin.ts
+
+import { Galbe, type Context, type Route } from 'galbe'
+
+class MyPlugin {
+  name = 'dev.galbe.example'
+  deprecated: Record<string, string[]> = {}
+  /**
+   * Retrieve and store all route with a @deprecated flag metadata
+   */
+  init(config: any, galbe: Galbe) {
+    if (config?.enabled && galbe.meta) {
+      for (const f of galbe.meta) {
+        for (const [path, methods] of Object.entries(f.routes)) {
+          for (const [method, meta] of Object.entries(methods)) {
+            if (meta.deprecated) {
+              if (!this.deprecated?.[method]) this.deprecated[method] = []
+              this.deprecated[method].push(path)
+            }
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Check if the current route is deprecated, flags it as is and logs it
+   */
+  onRoute(context: Context) {
+    let route = context.route
+    if (this.deprecated?.[route.method]?.includes(route.path)) {
+      context.state[this.name] = { deprecated: true }
+      console.warn(`Call to deprecated route [${route.method}]${route.path}`)
+    }
+  }
+  /**
+   * Adds a header if the request has previously been flagged as deprecated
+   */
+  afterHandle(response: Response, context: Context) {
+    if (context.state?.[this.name]?.deprecated) {
+      response.headers.set('x-deprecated', 'true')
+    }
+  }
+}
+
+export default new MyPlugin()
+```
+
+```ts
+// index.ts
+
+import { Galbe } from 'galbe'
+import config from './galbe.config'
+import myPlugin from './myPlugin'
+
+const galbe = new Galbe(config)
+galbe.use(myPlugin)
+
+export default galbe
+```
+
+As you can see in this example, the [Context](context.md#definition) `state` property is used to persist information between plugins interceptor methods. It is a good practice to scope any information stored in the state with the plugin name, as it can also be used by other plugins and hooks to store data in the context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "galbe",
-  "version": "0.1.13",
+  "version": "0.2.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/server.ts

@@ -10,26 +10,11 @@ const handleInternalError = (error: any) => {
 }
 
 const setupPluginCallbacks = (galbe: Galbe) => ({
-  init: galbe.plugins.reduce((l: { name: string; cb: Function }[], p) => {
-    if (p.init) l.push({ name: p.name, cb: p.init })
-    return l
-  }, []),
-  onFetch: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.onFetch) l.push(p.onFetch)
-    return l
-  }, []),
-  onRoute: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.onRoute) l.push(p.onRoute)
-    return l
-  }, []),
-  beforeHandle: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.beforeHandle) l.push(p.beforeHandle)
-    return l
-  }, []),
-  afterHandle: galbe.plugins.reduce((l: Function[], p) => {
-    if (p.afterHandle) l.push(p.afterHandle)
-    return l
-  }, [])
+  init: galbe.plugins.filter(p => p.init),
+  onFetch: galbe.plugins.filter(p => p.onFetch),
+  onRoute: galbe.plugins.filter(p => p.onRoute),
+  beforeHandle: galbe.plugins.filter(p => p.beforeHandle),
+  afterHandle: galbe.plugins.filter(p => p.afterHandle)
 })
 
 export default async (galbe: Galbe, port?: number) => {
@@ -37,7 +22,8 @@ export default async (galbe: Galbe, port?: number) => {
   if (galbe?.config?.basePath && galbe?.config?.basePath[0] !== '/')
     galbe.config.basePath = `/${galbe?.config?.basePath}`
   let pluginsCb = setupPluginCallbacks(galbe)
-  for (const { name, cb } of pluginsCb.init) await cb(galbe?.config?.plugin?.[name], galbe)
+  //@ts-ignore
+  for (const p of pluginsCb.init) await p.init(galbe?.config?.plugin?.[p.name], galbe)
 
   return Bun.serve({
     port: port || galbe.config?.port || 3000,
@@ -51,8 +37,9 @@ export default async (galbe: Galbe, port?: number) => {
         body: {},
         state: {}
       }
-      for (const cb of pluginsCb.onFetch) {
-        const r = await cb(req)
+      for (const p of pluginsCb.onFetch) {
+        //@ts-ignore
+        const r = await p.onFetch(context)
         if (r) return r
       }
       const url = new URL(req.url)
@@ -66,9 +53,11 @@ export default async (galbe: Galbe, port?: number) => {
           if (error instanceof RequestError) throw error
           else throw handleInternalError(error)
         }
+        context.route = route
 
-        for (const cb of pluginsCb.onRoute) {
-          const r = await cb(route)
+        for (const p of pluginsCb.onRoute) {
+          //@ts-ignore
+          const r = await p.onRoute(context)
           if (r) return r
         }
 
@@ -113,8 +102,9 @@ export default async (galbe: Galbe, port?: number) => {
           throw new RequestError({ status: 400, payload: errors.reduce((acc, c) => ({ ...acc, ...c.payload }), {}) })
         }
 
-        for (const cb of pluginsCb.beforeHandle) {
-          const r = await cb(context)
+        for (const p of pluginsCb.beforeHandle) {
+          //@ts-ignore
+          const r = await p.beforeHandle(context)
           if (r) return r
         }
 
@@ -152,8 +142,9 @@ export default async (galbe: Galbe, port?: number) => {
 
         const parsedResponse = responseParser(response, context)
 
-        for (const cb of pluginsCb.afterHandle) {
-          const r = await cb(parsedResponse)
+        for (const p of pluginsCb.afterHandle) {
+          //@ts-ignore
+          const r = await p.afterHandle(parsedResponse, context)
           if (r) return r
         }
 

package/src/types.ts

@@ -124,6 +124,7 @@ export type Context<Path extends string = string, S extends RequestSchema = Requ
   query: Static<STObject<Exclude<S['query'], undefined>>>
   body: Static<Exclude<S['body'], undefined>>
   request: Request
+  route?: Route
   state: Record<string, any>
   set: {
     headers: {
@@ -259,8 +260,8 @@ export class InternalError extends RequestError {
 export type GalbePlugin = {
   name: string
   init?: (config: any, galbe: Galbe) => MaybePromise<void>
-  onFetch?: (request: Request) => MaybePromise<Response | void>
-  onRoute?: (route: Route) => MaybePromise<Response | void>
+  onFetch?: (context: Context) => MaybePromise<Response | void>
+  onRoute?: (context: Context) => MaybePromise<Response | void>
   beforeHandle?: (context: Context) => MaybePromise<Response | void>
-  afterHandle?: (response: Response) => MaybePromise<Response | void>
+  afterHandle?: (response: Response, context: Context) => MaybePromise<Response | void>
 }

package/test/plugins.test.ts

@@ -39,8 +39,8 @@ describe('plugins', async () => {
     let request: any = null
     const plugin: GalbePlugin = {
       name: 'dev.galbe.test.init',
-      onFetch: mock(req => {
-        request = req
+      onFetch: mock(ctx => {
+        request = ctx.request
       })
     }
 
@@ -86,7 +86,7 @@ describe('plugins', async () => {
     const plugin: GalbePlugin = {
       name: 'dev.galbe.test.init',
       onRoute: mock(r => {
-        route = r
+        route = r.route
       })
     }