sleepy-serv 0.3.0 → 0.4.0

package/README.md

@@ -73,19 +73,23 @@ The route's logic is implemented in the route definition files. These must `expo
 Here's an example of a simple handler function:
 
 ```js
-export default function (req, res) {
+export default function (req, res, next) {
   console.log('res:', res)
+  console.log('next:', next) // null for route handlers
 
   return new Response('Hello world')
 }
 ```
 
-These functions take two parameters:
+These functions take three parameters:
 - `req`: a `BunRequest` object
 - `res`: a results object
+- `next`: a function to call the next middleware in the chain (or `null` for the final handler)
 
 The `res` parameter might seem familiar if coming from ExpressJS, but this parameter has a different purpose. The `res` parameter is meant to act as a dedicated, persistent object that middleware can write their results to. This way, the `req` object stays as a lean `BunRequest`.
 
+The `next` parameter is a function that allows middleware to pass control to the next function in the middleware chain. For route handlers (the final function in the chain), `next` will be `null`.
+
 These handlers can also be `async` functions and `sleepy-serv` will wait for them to finish before moving on.
 
 ### Middleware
@@ -94,10 +98,11 @@ As mentioned earlier, method definition files can also export an array of functi
 
 ```js
 export default [
-  async (req, res) => {
+  async (req, res, next) => {
     res.body = await req.json()
+    return next() /* call the next middleware */
   },
-  (req, res) => {
+  (req, res) => { /* notice that the last function doesn't take `next` */
     console.log('JSON body:', res.body)
 
     return new Response('Hello world')
@@ -105,9 +110,58 @@ export default [
 ]
 ```
 
-This is useful if you want to break common logic up into reusable functions. The functions in the array are called in-order, and are provided the same `req` object. If you'd like to cache results between middleware functions, you can simply attach them to the `req` object.
+This is useful if you want to break common logic up into reusable functions. The functions in the array are called in-order, and each receives three parameters: `req`, `res`, and `next`.
+
+#### Middleware Chain Behavior
+
+Each middleware function must do one of the following:
+- **Call `next()`**: Continue to the next middleware in the chain by returning `next()`
+- **Return a Response**: End the chain (early) by returning a `BunResponse` object
+- **Throw an error**: Stop the chain and trigger error handling
+
+The `next` parameter will be `null` for the final function in the chain (the route handler), indicating there are no more middleware functions to call.
+
+#### Example with Explicit `next()` Calls
+
+```js
+export default [
+  (req, res, next) => {
+    console.log('1st middleware')
+
+    if (req.headers.get('authorization')) {
+      return next() // continue to next middleware
+    } else {
+      return new Response('Unauthorized', { status: 401 }) // end chain early
+    }
+  },
+  (req, res, next) => {
+    console.log('2nd middleware')
+
+    res.user = {
+      id: 123,
+      name: 'John',
+    }
+
+    return next() // continue to route handler
+  },
+  (req, res) => {
+    console.log('Final, "route" handler')
+
+    return new Response(`Hello ${res.user.name}`)
+  },
+]
+```
+
+#### Middleware Execution Order
+
+Middleware functions are executed in the following order:
+1. **App-level middleware** (defined in `createApp()` options)
+2. **Directory-level middleware** (from `meta.js` files, from root to leaf)
+3. **Route-level middleware** (defined in the route file array)
 
-### Breaking the Middleware Chain - Responses
+Each middleware function receives the same `req` and `res` objects, allowing data to be passed between middleware functions through the `res` object.
+
+#### Breaking the Middleware Chain - Responses
 
 You might want to break the middleware chain with a response early.
 
@@ -115,27 +169,29 @@ Here's an example:
 
 ```js
 export default [
-  req => {
+  (req, res, next) => {
     if (req.params.userId === '123') {
       return new Response('Returned early')
+    } else {
+      return next() // continue to next middleware
     }
   },
-  req => {
+  (req, res) => {
     return new Response('End of chain')
   },
 ]
 ```
 
-The the case above, the 1st middleware function will return a `Response` object if the route param's `userId` is equal to a specific value. In those cases, the last function in the middleware chain will not execute for that request.
+In the case above, the 1st middleware function will return a `Response` object if the route param's `userId` is equal to a specific value. In those cases, the last function in the middleware chain will not execute for that request. If the condition is not met, `next()` is called to continue to the next middleware.
 
-### Breaking the Middleware Chain - Errors
+#### Breaking the Middleware Chain - Errors
 
 It's also common to throw errors for things like request validation or when a desired resource is not found. `sleepy-serv` has defined custom `Error` types for every type of 4xx and 5xx error:
 
 ```js
 import { NotFoundError } from 'sleepy-serv'
 
-export default async function (req) {
+export default async function (req, res) {
   const users = await sql`
 SELECT * FROM Users
 WHERE userId=${req.params.userId}
@@ -156,7 +212,7 @@ If the user is found in the database, then the request will return with a succes
 Throwing generic errors also works too:
 
 ```js
-export default async function (req) {
+export default async function (req, res) {
   throw new Error('A problem occurred')
 }
 ```
@@ -167,7 +223,7 @@ export default async function (req) {
 
 It's also possible for resource directories to contain a `meta.js` file. These files can export various things that have some sort semantic relationship to the part of the route that they're defined in.
 
-### Directory-Level Middleware
+#### Directory-Level Middleware
 
 `meta.js` files can also export an array of middleware functions:
 
@@ -175,7 +231,10 @@ It's also possible for resource directories to contain a `meta.js` file. These f
 // meta.js
 
 export const middleware = [
-  req => { /* do middleware things */ },
+  (req, res, next) => {
+    /* do middleware things */
+    return next() // Continue to next middleware
+  },
 ]
 ```
 
@@ -223,25 +282,69 @@ The middleware defined in `/api/users/:userId/meta.js` will be applied the follo
 - `DELETE /users/:userId`
 - `PUT /users/:userId`
 
-### Future Use-Cases
+### Meta Files
 
-At the time of this writing, `meta.js` only exports middleware functions.
+At the time of this writing, `meta.js` only exports middleware functions, but it will eventually be able to provide additional configuration for the endpoint definitions within its scope.
 
-## Build-In Middleware
+## Built-In Middleware
 
 `sleepy-serv` also comes built-in with a few useful middleware functions that are commonly used.
 
-### parseJson(req, _res)
+### parseJson(req, res, next)
+
+This middleware parses the request's `body` property as a JSON string, and then stores the results in `res.body`. It calls `next()` if parsing succeeds, and throws a `BadRequestError` if parsing fails. Additional body parsers can be written in the future to accommodate other body encoding schemes (such as XML or protobuf).
 
-This middleware parses the request's `body` property as a JSON string, and then stores the results in `res.body`. Additional body parsers can be written in the future a accommodate other body encoding schemes.
+Example usage:
+
+```js
+import { middleware } from 'sleepy-serv'
+
+export default [
+  middleware.parseJson,
+  (req, res) => {
+    console.log('Parsed JSON:', res.body)
+
+    return new Response('JSON received')
+  },
+]
+```
 
 ### validateSchema(schemas)
 
-This function takes a `schemas` object. Each property is optional:
-- `headers`: takes a string formatter schema to evaulate `req.headers`
-- `params`: takes a string formatter schema to evaulate `req.params`
-- `query`: takes a string foramtter schema to evaulate `req.query`
-- `body`: takes a JSON validation schema to evaulate `res.body`
+This function returns a middleware function that validates request data against provided schemas. The returned middleware function has the signature `(req, res, next)` and automatically calls `next()` after successful validation.
+
+The `schemas` object can contain these optional properties:
+- `headers`: takes a string formatter schema to evaluate `req.headers`
+- `params`: takes a string formatter schema to evaluate `req.params`
+- `query`: takes a string formatter schema to evaluate `req.query`
+- `body`: takes a JSON validation schema to evaluate `res.body`
+
+Example usage:
+
+```js
+import { middleware } from 'sleepy-serv'
+
+export default [
+  middleware.parseJson,
+  middleware.validateSchema({
+    params: {
+      userId: { type: 'format', value: 'uuid' }
+    },
+    body: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' }
+      },
+      required: ['name', 'email']
+    }
+  }),
+  (req, res, next) => {
+    // Validation passed, process the request
+    return new Response('Data is valid')
+  },
+]
+```
 
 Here's an example of the schema in action:
 
@@ -295,6 +398,26 @@ Calling `setValidationFormats()` extends the possible values that can be passed
 
 ## `createApp()` Options
 
+### `middleware`
+
+You can define app-level middleware that will be applied to all routes:
+
+```js
+import { middleware } from 'sleepy-serv'
+
+const app = await createApp(PORT, import.meta.dirname, {
+  middleware: [
+    middleware.parseJson,
+    (req, res, next) => {
+      console.log(`${req.method} ${req.url}`)
+      return next()
+    },
+  ],
+})
+```
+
+App-level middleware is executed before any directory-level or route-level middleware.
+
 ### `hostname`
 
 The hostname can be customized like so:

package/package.json

@@ -2,7 +2,7 @@
   "name": "sleepy-serv",
   "description": "A more opinionated web server for building REST-ful applications",
   "author": "Travis J True",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "exports": "./src/index.js",
   "type": "module",
   "keywords": [

package/src/index.js

@@ -45,17 +45,18 @@ function methodNotAllowedHandler (_req) {
   throw new MethodNotAllowedError()
 }
 
+/* TODO: add whitelist support */
 function validateDirectoryIllegalFiles (targetPath, filenames) {
-  const hasInvalidFiles = filenames.some(filename =>
-    !ALLOWED_FILES_ALL.includes(filename)
-  )
-
-  if (hasInvalidFiles) {
-    throw new TypeError(`
-Directory contains illegal files:
-${targetPath}
-    `.trim())
-  }
+//   const hasInvalidFiles = filenames.some(filename =>
+//     !ALLOWED_FILES_ALL.includes(filename)
+//   )
+
+//   if (hasInvalidFiles) {
+//     throw new TypeError(`
+// Directory contains illegal files:
+// ${targetPath}
+//     `.trim())
+//   }
 }
 
 function validateLeafDirectory (targetPath, filenames, entries) {
@@ -191,13 +192,24 @@ ${route.modulePath}
 
     req.query = query ? querystring.parse(query) : {}
 
-    for (const fn of middlewareChain) {
-      const response = await fn(req, res)
+    const executeMiddleware = async (index) => {
+      const currentMiddleware = middlewareChain[index]
+      const isLastMiddleware = index === middlewareChain.length - 1
+
+      const next = !isLastMiddleware ?
+        () => executeMiddleware(index + 1)
+        : null
 
-      if (response) {
-        return response
+      const result = await currentMiddleware(req, res, next)
+
+      if (result instanceof Response) {
+        return result
+      } else {
+        throw new TypeError('Handler does not return a Response object')
       }
     }
+
+    return executeMiddleware(0)
   }
 
   return {

package/src/middleware.js

@@ -2,6 +2,7 @@ import Ajv from 'ajv'
 import addFormats from 'ajv-formats'
 
 import {
+  BadRequestError,
   UnsupportedMediaTypeError,
   UnprocessableContentError,
 } from './errors'
@@ -46,14 +47,26 @@ function buildFormatterSchema (schema) {
   }
 }
 
-export async function parseJson (req, res) {
+export async function parseJson (req, res, next) {
   const contentType = req.headers.get('content-type')
 
-  if (req.method !== 'GET' && contentType !== 'application/json') {
+  if (!contentType) {
+    return next()
+  }
+
+  if (contentType !== 'application/json') {
     throw new UnsupportedMediaTypeError('content-type')
   }
 
-  res.body = await req.json()
+  try {
+    res.body = await req.json()
+  } catch (err) {
+    console.error(err)
+
+    throw new BadRequestError('Body is invalid JSON')
+  }
+
+  return next()
 }
 
 export function setValidationFormats (formats) {
@@ -61,7 +74,7 @@ export function setValidationFormats (formats) {
 }
 
 export function validateSchema (schemas) {
-  return function (req, res) {
+  return function (req, res, next) {
     const formattedSchemas = {
       headers: buildFormatterSchema(schemas.headers),
       params: buildFormatterSchema(schemas.params),
@@ -97,5 +110,7 @@ export function validateSchema (schemas) {
     if (errors.length > 0) {
       throw new UnprocessableContentError(errors)
     }
+
+    return next()
   }
 }