sleepy-serv 0.4.0 → 0.6.0

package/README.md

@@ -1,4 +1,4 @@
-# Sleepy Server
+# `sleepy-serv`
 
 A directory-driven web server designed for REST-ful applications
 
@@ -86,9 +86,9 @@ These functions take three parameters:
 - `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 `res` parameter might seem familiar if coming from ExpressJS, but this parameter has a different purpose. The `res` parameter is the "result" value handed to the current middleware. Middleware do not mutate it. Instead, whatever a middleware passes into `next(data)` becomes the `res` value the next middleware receives. This way, the `req` object stays as a lean `BunRequest`, and each middleware decides exactly what the next one sees.
 
-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`.
+The `next` parameter is a function that advances the chain. Whatever you pass to it becomes the next middleware's `res`. Calling `next()` with no argument sets the next `res` to `undefined`, so to forward the current result unchanged, return `next(res)`. 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.
 
@@ -99,11 +99,11 @@ As mentioned earlier, method definition files can also export an array of functi
 ```js
 export default [
   async (req, res, next) => {
-    res.body = await req.json()
-    return next() /* call the next middleware */
+    /* transform `res` into the parsed body for the next middleware */
+    return next(await req.json())
   },
   (req, res) => { /* notice that the last function doesn't take `next` */
-    console.log('JSON body:', res.body)
+    console.log('JSON body:', res)
 
     return new Response('Hello world')
   },
@@ -115,7 +115,7 @@ This is useful if you want to break common logic up into reusable functions. The
 #### 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()`
+- **Call `next(data)`**: Continue to the next middleware by returning `next(data)`, where `data` becomes that middleware's `res`. To forward the current result unchanged, return `next(res)`
 - **Return a Response**: End the chain (early) by returning a `BunResponse` object
 - **Throw an error**: Stop the chain and trigger error handling
 
@@ -137,12 +137,13 @@ export default [
   (req, res, next) => {
     console.log('2nd middleware')
 
-    res.user = {
-      id: 123,
-      name: 'John',
-    }
-
-    return next() // continue to route handler
+    return next({ // continue to route handler
+      ...res,
+      user: {
+        id: 123,
+        name: 'John',
+      },
+    })
   },
   (req, res) => {
     console.log('Final, "route" handler')
@@ -159,7 +160,7 @@ Middleware functions are executed in the following order:
 2. **Directory-level middleware** (from `meta.js` files, from root to leaf)
 3. **Route-level middleware** (defined in the route file array)
 
-Each middleware function receives the same `req` and `res` objects, allowing data to be passed between middleware functions through the `res` object.
+Each middleware function receives the same `req` object. The `res` value, by contrast, is whatever the previous middleware passed into `next(data)`, allowing data to be transformed or accumulated as it flows through the chain.
 
 #### Breaking the Middleware Chain - Responses
 
@@ -233,7 +234,7 @@ It's also possible for resource directories to contain a `meta.js` file. These f
 export const middleware = [
   (req, res, next) => {
     /* do middleware things */
-    return next() // Continue to next middleware
+    return next(res) // Continue to next middleware, forwarding `res`
   },
 ]
 ```
@@ -290,43 +291,45 @@ At the time of this writing, `meta.js` only exports middleware functions, but it
 
 `sleepy-serv` also comes built-in with a few useful middleware functions that are commonly used.
 
-### parseJson(req, res, next)
+### parseJsonBody()
 
-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 function returns a middleware that parses the request's body as a JSON string and forwards the parsed value as the next middleware's `res` via `next(body)`. The returned middleware throws a `BadRequestError` if parsing fails, and forwards `res` unchanged (`next(res)`) when there is no `content-type`. Additional body parsers can be written in the future to accommodate other body encoding schemes (such as XML or protobuf).
 
 Example usage:
 
 ```js
-import { middleware } from 'sleepy-serv'
+import { parseJsonBody } from 'sleepy-serv'
 
 export default [
-  middleware.parseJson,
+  parseJsonBody(),
   (req, res) => {
-    console.log('Parsed JSON:', res.body)
+    console.log('Parsed JSON:', res)
 
     return new Response('JSON received')
   },
 ]
 ```
 
-### validateSchema(schemas)
+### validateSchemas(schemas)
 
-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.
+This function returns a middleware function that validates request data against provided schemas. The returned middleware function has the signature `(req, res, next)` and forwards `res` via `next(res)` 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`
+- `body`: takes a JSON validation schema to evaluate `res` (the body value passed in via `next`)
+
+Only the keys you pass are validated. Any key you omit is skipped entirely, and `res` is forwarded unchanged via `next(res)`; there is no implicit default schema for a missing `body`.
 
 Example usage:
 
 ```js
-import { middleware } from 'sleepy-serv'
+import { parseJsonBody, validateSchemas } from 'sleepy-serv'
 
 export default [
-  middleware.parseJson,
-  middleware.validateSchema({
+  parseJsonBody(),
+  validateSchemas({
     params: {
       userId: { type: 'format', value: 'uuid' }
     },
@@ -363,7 +366,7 @@ PUT /contacts/123/addresses
 ***
 TODO: add JSON schema example.
 
-Please take a look at the `lib/src/middleware.test.js` test file for a far a comprehensive set of examples on how to use this middleware.
+Please take a look at the `packages/server/src/middleware.test.js` test file for a far a comprehensive set of examples on how to use this middleware.
 ***
 
 The `headers`, `params`, and `query` (querystrings) can only be strings, so they're evaulated using a simplified _string format schema_ instead of a full JSON schema.
@@ -388,13 +391,15 @@ This determines how to evaulate the string based on the `type` parameter. If `ty
 Custom formats can also be provided by using the `setValidationFormats()` during app initialization. Here's an example:
 
 ```javascript
-middleware.setValidationFormats({
+import { setValidationFormats } from 'sleepy-serv'
+
+setValidationFormats({
   phone: /^\d{10}$/, /* 10-digit, numeric string */
   postalCode: /^\d{5}$/, /* 5-digit, numeric string */
 })
 ```
 
-Calling `setValidationFormats()` extends the possible values that can be passed to the `value` property when evaulating strings in either the string formatter schema, or the `res.body`'s JSON schema.
+Calling `setValidationFormats()` extends the possible values that can be passed to the `value` property when evaulating strings in either the string formatter schema, or the body's JSON schema.
 
 ## `createApp()` Options
 
@@ -403,11 +408,11 @@ Calling `setValidationFormats()` extends the possible values that can be passed
 You can define app-level middleware that will be applied to all routes:
 
 ```js
-import { middleware } from 'sleepy-serv'
+import { parseJsonBody } from 'sleepy-serv'
 
 const app = await createApp(PORT, import.meta.dirname, {
   middleware: [
-    middleware.parseJson,
+    parseJsonBody(),
     (req, res, next) => {
       console.log(`${req.method} ${req.url}`)
       return next()
@@ -418,6 +423,8 @@ const app = await createApp(PORT, import.meta.dirname, {
 
 App-level middleware is executed before any directory-level or route-level middleware.
 
+Note that the reserved `/ws` handshake routes are folded into these same chains, so app-level middleware runs against them too. A catch-all validator (for example a `validateSchemas` that requires a JSON body or a specific header on every request) will therefore also run against the body-less `/ws` handshake requests and reject them. Scope such validators below the reserved paths rather than applying them app-wide.
+
 ### `hostname`
 
 The hostname can be customized like so:
@@ -465,19 +472,3 @@ const app = await createApp(PORT, import.meta.dirname, {
   onClose: () => console.info('closing down...'),
 })
 ```
-
-## Running the Local Example App
-
-1. Install [`bun.sh`](https://bun.sh)
-1. Link the library package:
-    - `$ cd lib`
-    - `$ bun link`
-1. Link the library to the project
-    - `$ cd ../example`
-    - `$ npm link sleepy-serv`
-1. Finally, run the app: `$ bun --watch run start`
-
-## Running Tests
-
-- Use `bun`'s built-in test runner
-- Run tests from the `./lib` directory

package/package.json

@@ -2,9 +2,14 @@
   "name": "sleepy-serv",
   "description": "A more opinionated web server for building REST-ful applications",
   "author": "Travis J True",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "exports": "./src/index.js",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/travistrue2008/sleepy-serv.git",
+    "directory": "packages/server"
+  },
   "keywords": [
     "rest",
     "serv",
@@ -12,15 +17,9 @@
     "web server",
     "www"
   ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "devDependencies": {
-    "axios": "^1.7.9",
-    "eslint": "9.20.1"
-  },
+  "scripts": {},
   "dependencies": {
-    "ajv": "^8.17.1",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   }
 }

package/src/errors.js

@@ -1,4 +1,12 @@
-class RequestError extends Error {
+export class RequestError extends Error {
+  static get status () {
+    throw new Error('Unimplemented')
+  }
+
+  get output () {
+    return this.message ? { message: this.message } : null
+  }
+
   constructor (message) {
     super(message)
 
@@ -9,7 +17,7 @@ class RequestError extends Error {
 // 4xx - Client Errors
 
 export class BadRequestError extends RequestError {
-  static get statusCode () { return 400 }
+  static get status () { return 400 }
 
   constructor (message) {
     super(message)
@@ -19,7 +27,7 @@ export class BadRequestError extends RequestError {
 }
 
 export class UnauthorizedError extends RequestError {
-  static get statusCode () { return 401 }
+  static get status () { return 401 }
 
   constructor (message) {
     super(message)
@@ -29,7 +37,7 @@ export class UnauthorizedError extends RequestError {
 }
 
 export class PaymentRequiredError extends RequestError {
-  static get statusCode () { return 402 }
+  static get status () { return 402 }
 
   constructor (message) {
     super(message)
@@ -39,7 +47,7 @@ export class PaymentRequiredError extends RequestError {
 }
 
 export class ForbiddenError extends RequestError {
-  static get statusCode () { return 403 }
+  static get status () { return 403 }
 
   constructor (message) {
     super(message)
@@ -49,7 +57,7 @@ export class ForbiddenError extends RequestError {
 }
 
 export class NotFoundError extends RequestError {
-  static get statusCode () { return 404 }
+  static get status () { return 404 }
 
   constructor () {
     super('')
@@ -59,7 +67,7 @@ export class NotFoundError extends RequestError {
 }
 
 export class MethodNotAllowedError extends RequestError {
-  static get statusCode () { return 405 }
+  static get status () { return 405 }
 
   constructor () {
     super('')
@@ -69,7 +77,7 @@ export class MethodNotAllowedError extends RequestError {
 }
 
 export class NotAcceptableError extends RequestError {
-  static get statusCode () { return 406 }
+  static get status () { return 406 }
 
   constructor (message) {
     super(message)
@@ -79,7 +87,7 @@ export class NotAcceptableError extends RequestError {
 }
 
 export class ProxyAuthenticationRequiredError extends RequestError {
-  static get statusCode () { return 407 }
+  static get status () { return 407 }
 
   constructor (message) {
     super(message)
@@ -89,7 +97,7 @@ export class ProxyAuthenticationRequiredError extends RequestError {
 }
 
 export class RequestTimeoutError extends RequestError {
-  static get statusCode () { return 408 }
+  static get status () { return 408 }
 
   constructor (message) {
     super(message)
@@ -99,7 +107,7 @@ export class RequestTimeoutError extends RequestError {
 }
 
 export class ConflictError extends RequestError {
-  static get statusCode () { return 409 }
+  static get status () { return 409 }
 
   constructor (message) {
     super(message)
@@ -109,7 +117,7 @@ export class ConflictError extends RequestError {
 }
 
 export class GoneError extends RequestError {
-  static get statusCode () { return 410 }
+  static get status () { return 410 }
 
   constructor (message) {
     super(message)
@@ -119,7 +127,7 @@ export class GoneError extends RequestError {
 }
 
 export class LengthRequiredError extends RequestError {
-  static get statusCode () { return 411 }
+  static get status () { return 411 }
 
   constructor (message) {
     super(message)
@@ -129,7 +137,7 @@ export class LengthRequiredError extends RequestError {
 }
 
 export class PreconditionFailedError extends RequestError {
-  static get statusCode () { return 412 }
+  static get status () { return 412 }
 
   constructor (message) {
     super(message)
@@ -139,7 +147,7 @@ export class PreconditionFailedError extends RequestError {
 }
 
 export class PayloadTooLargeError extends RequestError {
-  static get statusCode () { return 413 }
+  static get status () { return 413 }
 
   constructor (message) {
     super(message)
@@ -149,7 +157,7 @@ export class PayloadTooLargeError extends RequestError {
 }
 
 export class UriTooLongError extends RequestError {
-  static get statusCode () { return 414 }
+  static get status () { return 414 }
 
   constructor (message) {
     super(message)
@@ -159,7 +167,7 @@ export class UriTooLongError extends RequestError {
 }
 
 export class UnsupportedMediaTypeError extends RequestError {
-  static get statusCode () { return 415 }
+  static get status () { return 415 }
 
   constructor (subject) {
     super(`Unsupported ${subject}`)
@@ -169,7 +177,7 @@ export class UnsupportedMediaTypeError extends RequestError {
 }
 
 export class RangeNotSatisfiableError extends RequestError {
-  static get statusCode () { return 416 }
+  static get status () { return 416 }
 
   constructor (message) {
     super(message)
@@ -179,7 +187,7 @@ export class RangeNotSatisfiableError extends RequestError {
 }
 
 export class ExpectationFailedError extends RequestError {
-  static get statusCode () { return 417 }
+  static get status () { return 417 }
 
   constructor (message) {
     super(message)
@@ -189,7 +197,7 @@ export class ExpectationFailedError extends RequestError {
 }
 
 export class ImATeapotError extends RequestError {
-  static get statusCode () { return 418 }
+  static get status () { return 418 }
 
   constructor (message) {
     super(message)
@@ -199,7 +207,7 @@ export class ImATeapotError extends RequestError {
 }
 
 export class MisdirectedRequestError extends RequestError {
-  static get statusCode () { return 421 }
+  static get status () { return 421 }
 
   constructor (message) {
     super(message)
@@ -209,7 +217,11 @@ export class MisdirectedRequestError extends RequestError {
 }
 
 export class UnprocessableContentError extends RequestError {
-  static get statusCode () { return 422 }
+  static get status () { return 422 }
+
+  get output () {
+    return JSON.parse(this.message)
+  }
 
   constructor (errors) {
     super(JSON.stringify(errors))
@@ -219,7 +231,7 @@ export class UnprocessableContentError extends RequestError {
 }
 
 export class LockedError extends RequestError {
-  static get statusCode () { return 423 }
+  static get status () { return 423 }
 
   constructor (message) {
     super(message)
@@ -229,7 +241,7 @@ export class LockedError extends RequestError {
 }
 
 export class FailedDependencyError extends RequestError {
-  static get statusCode () { return 424 }
+  static get status () { return 424 }
 
   constructor (message) {
     super(message)
@@ -239,7 +251,7 @@ export class FailedDependencyError extends RequestError {
 }
 
 export class TooEarlyError extends RequestError {
-  static get statusCode () { return 425 }
+  static get status () { return 425 }
 
   constructor (message) {
     super(message)
@@ -249,7 +261,7 @@ export class TooEarlyError extends RequestError {
 }
 
 export class UpgradeRequiredError extends RequestError {
-  static get statusCode () { return 426 }
+  static get status () { return 426 }
 
   constructor (message) {
     super(message)
@@ -259,7 +271,7 @@ export class UpgradeRequiredError extends RequestError {
 }
 
 export class PreconditionRequiredError extends RequestError {
-  static get statusCode () { return 428 }
+  static get status () { return 428 }
 
   constructor (message) {
     super(message)
@@ -269,7 +281,7 @@ export class PreconditionRequiredError extends RequestError {
 }
 
 export class TooManyRequestsError extends RequestError {
-  static get statusCode () { return 429 }
+  static get status () { return 429 }
 
   constructor (message) {
     super(message)
@@ -279,7 +291,7 @@ export class TooManyRequestsError extends RequestError {
 }
 
 export class RequestHeaderFieldsTooLargeError extends RequestError {
-  static get statusCode () { return 431 }
+  static get status () { return 431 }
 
   constructor (message) {
     super(message)
@@ -289,7 +301,7 @@ export class RequestHeaderFieldsTooLargeError extends RequestError {
 }
 
 export class UnavailableForLegalReasonsError extends RequestError {
-  static get statusCode () { return 451 }
+  static get status () { return 451 }
 
   constructor (message) {
     super(message)
@@ -301,7 +313,7 @@ export class UnavailableForLegalReasonsError extends RequestError {
 // 5xx - Server Errors
 
 export class InternalServerError extends RequestError {
-  static get statusCode () { return 500 }
+  static get status () { return 500 }
 
   constructor (message, ctx) {
     super(message)
@@ -312,7 +324,7 @@ export class InternalServerError extends RequestError {
 }
 
 export class NotImplementedError extends RequestError {
-  static get statusCode () { return 501 }
+  static get status () { return 501 }
 
   constructor () {
     super('')
@@ -322,7 +334,7 @@ export class NotImplementedError extends RequestError {
 }
 
 export class BadGatewayError extends RequestError {
-  static get statusCode () { return 502 }
+  static get status () { return 502 }
 
   constructor (message) {
     super(message)
@@ -332,7 +344,7 @@ export class BadGatewayError extends RequestError {
 }
 
 export class ServiceUnavailableError extends RequestError {
-  static get statusCode () { return 503 }
+  static get status () { return 503 }
 
   constructor (message) {
     super(message)
@@ -342,7 +354,7 @@ export class ServiceUnavailableError extends RequestError {
 }
 
 export class GatewayTimeoutError extends RequestError {
-  static get statusCode () { return 504 }
+  static get status () { return 504 }
 
   constructor () {
     super('')
@@ -352,7 +364,7 @@ export class GatewayTimeoutError extends RequestError {
 }
 
 export class HTTPVersionNotSupportedError extends RequestError {
-  static get statusCode () { return 505 }
+  static get status () { return 505 }
 
   constructor (message) {
     super(message)
@@ -362,7 +374,7 @@ export class HTTPVersionNotSupportedError extends RequestError {
 }
 
 export class VariantAlsoNegotiatesError extends RequestError {
-  static get statusCode () { return 506 }
+  static get status () { return 506 }
 
   constructor (message) {
     super(message)
@@ -372,7 +384,7 @@ export class VariantAlsoNegotiatesError extends RequestError {
 }
 
 export class InsufficientStorageError extends RequestError {
-  static get statusCode () { return 507 }
+  static get status () { return 507 }
 
   constructor (message) {
     super(message)
@@ -382,7 +394,7 @@ export class InsufficientStorageError extends RequestError {
 }
 
 export class LoopDetectedError extends RequestError {
-  static get statusCode () { return 508 }
+  static get status () { return 508 }
 
   constructor (message) {
     super(message)
@@ -392,7 +404,7 @@ export class LoopDetectedError extends RequestError {
 }
 
 export class NotExtendedError extends RequestError {
-  static get statusCode () { return 510 }
+  static get status () { return 510 }
 
   constructor (message) {
     super(message)
@@ -402,7 +414,7 @@ export class NotExtendedError extends RequestError {
 }
 
 export class NetworkAuthenticationRequiredError extends RequestError {
-  static get statusCode () { return 511 }
+  static get status () { return 511 }
 
   constructor (message) {
     super(message)