@odatnurd/cf-requests 0.1.7 → 0.1.9

package/README.md

@@ -1,23 +1,28 @@
 # Simple CloudFlare Request Handlers
 
-`cf-requests` is a very simple set of wrapper functions that allow for working
-with requests in a
+`cf-requests` is a simple set of wrapper functions that allow for working with
+requests in a
 [Cloudflare Worker](https://developers.cloudflare.com/workers/) or in
 [Cloudflare Pages](https://developers.cloudflare.com/pages/) using
-[Hono](https://hono.dev/) as a route handler, with a focus on API routes,
-though this is not strictly required.
+[Hono](https://hono.dev/) as a route handler.
 
-This is also intended to be used with
-[@axel669/joker](https://www.npmjs.com/package/@axel669/joker) as a schema
-validation library and
+The focus is to allow for more easy creation of robust `API` routes, providing
+a standard `JSON` response format on both success and failure.
+
+The request validation functionality is intended to be used alongside the
+[@axel669/joker](https://www.npmjs.com/package/@axel669/joker) schema
+validation library. However this is not strictly required, and the validation
+wrapper can be used with any validator with some simple wrapper code; see below
+for more details.
+
+The examples seen here utilize
 [@axel669/hono-file-routes](https://www.npmjs.com/package/@axel669/hono-file-routes),
-which collectively allow for fast and easy schema validation and data masking
-and allowing file based in Cloudflare Workers, where that is not directly
-possible. This again is not strictly required, but examples below assume that
-this is the case.
+which allows for file based routing in a Cloudflare worker. This is also not
+strictly required.
 
-> ℹ️ Technically, the validation wrapper will accept any validator (e.g. zod) as
-> long as the object passed in conforms to the validation contract; see below.
+Finally, there are some routines here that can be used with the
+[@axel669/aegis](https://www.npmjs.com/package/@axel669/aegis) test runner
+library, which is also documented below.
 
 
 ## Installation
@@ -30,17 +35,27 @@ npm install @odatnurd/cf-requests
 
 ## Usage
 
-The library provides all of the pieces needed to validate incoming requests
-based on an appropriate schema and return a JSON result that has a consistent
-field layout. In addition, request handlers are wrapped such that any
-exceptions that propagate out of the handler function are handled as errors
-with an appropriate return, making the actual handler code more straight
-forward.
+The library provides all of the pieces needed to:
+
+- validate incoming requests based on a schema (applied to the `json` body, path
+  parameters, query parameters, etc).
+- return a consistently structured `json` result in both `success` and `failure`
+  conditions
+- wrap a request handler with exception handling to remove boilerplate and help
+  enforce consistency in results.
+- compose all of the above into a single, cohesive handler for a route.
+
 
 ### Example
 
-Assuming a file named `test.joker.json` that contains the following Joker
-schema, and and you are using the Joker Rollup plugin:
+This example presumes that the
+[@axel669/joker](https://www.npmjs.com/package/@axel669/joker) library is being
+used to implement schema validation, and that routes are defined via the
+[@axel669/hono-file-routes](https://www.npmjs.com/package/@axel669/hono-file-routes)
+package.
+
+The contents of the `test.joker.json` file looks like the following, defining
+that the body of the request contain `key1` and `key2`, each of specific types:
 
 ```json
 {
@@ -52,27 +67,43 @@ schema, and and you are using the Joker Rollup plugin:
 }
 ```
 
-The following is a minimal route handler that validates the JSON body against
-the schema and returning it back. The request will result in a `422` error if
-the data is not valid, and the JSON body is masked to ensure that only the
-fields declared by the schema are present.
+Given this, the following is a minimal route handler that validates the JSON
+body against the schema.
+
+The request will result in a `422 Unprocessible Entity` error if the data is
+not valid, and the JSON body is masked to ensure that only the fields declared
+by the schema are present.
 
 
 ```js
-import { validate, success, routeHandler } from '#lib/common';
+// Bring in the validation generator, the success response generator, and the
+// route handler generator.
+import { validate, success, routeHandler } from '@odatnurd/cf-requests';
 
-// Use the Joker rollup plugin to obtain the object we require
+// Using the Joker rollup plugin, this will result in a testSchema object with a
+// `validate()` and `mask()` function within it, which verify that the result is
+// correct and mask away any fields not defined by the schema, respectively.
 import * as testSchema from '#schemas/test';
 
-
+// The hono-file-routes package defines routes in a file by exporting `$verb`
+// as routes. Here we are using the routeHandler() generator, which constructs
+// an appropriate route array based on its arguments.
+//
+// This value could also be used in a standard Hono app.
 export const $post = routeHandler(
+  // Generate a validator using the standard Hono mechanism; this will ensure
+  // that the JSON in the body fits the schema, and will mask extraneous fields.
   validate('json', testSchema),
 
+  // Async functions that take a single argument are route handlers; they will
+  // be automatically guarded with a try/catch block
   async (ctx) => {
+    // PUll out the validated JSON body.
     const body = ctx.req.valid('json');
 
-    // Generic errors show up as a 500 server error; throwing HTTPError allows
-    // for a specific error code to be returned instead
+    // Thrown exceptions inside the handler cause a fail() call to occur; the
+    // status is 500 for generic errors, but you can throw HTTPError instances
+    // to get a specific result as desired.
     if (body.key1 != 69) {
       throw new Error('key is not nice');
     }
@@ -86,8 +117,10 @@ export const $post = routeHandler(
 ## Testing Utilities (Optional)
 
 This package includes an optional set of helpers to facilitate testing your own
-projects with the [Aegis](https://www.npmjs.com/package/@axel669/aegis) test
-runner.
+projects with the [@axel669/aegis](https://www.npmjs.com/package/@axel669/aegis)
+test runner and the
+[@odatnurd/cf-aegis](https://www.npmjs.com/package/@odatnurd/cf-aegis) helper
+libraries.
 
 To use these utilities, you must install the required peer dependencies into
 your own project's `devDependencies` if you have not already done so.
@@ -96,16 +129,17 @@ your own project's `devDependencies` if you have not already done so.
 pnpm add -D @axel669/aegis @axel669/joker @odatnurd/cf-aegis miniflare
 ```
 
-The `@odatnurd/cf-requests/aegis` module exports the following functions:
+The `@odatnurd/cf-requests/aegis` module exports the following functions to
+aid in setting up tests:
 
 
-### Helper Functions
+### Aegis Helper Functions
 
 ```javascript
-export function initializeResponseChecks() {}
+export function initializeRequestChecks() {}
 ```
-Registers all [custom checks](#custom-checks) with Aegis. This should be called
-once at the top of your `aegis.config.js` file.
+Registers all [custom checks](#custom-checks) with `Aegis`. This should be
+called once at the top of your `aegis.config.js` file.
 
 ---
 
@@ -113,8 +147,8 @@ once at the top of your `aegis.config.js` file.
 export async function schemaTest(dataType, schema, data, validator = undefined) {}
 ```
 Takes a `dataType` and `schema` as would be provided to the `validate` function
-and runs the validation to see what the result is. The function will return
-either:
+and runs the validation against `data` to see what the result is. The function
+will return either:
 
  * `Valid Data`: An Object that represents the validated and masked data
  * `Invalid Data`: A `Response` object that carries the error payload
@@ -129,7 +163,7 @@ having to use it in the actual request first.
 > such as during migrations to this library.
 
 
-### Configuration
+### Aegis Test Configuration
 
 You can import the helper functions into your `aegis.config.js` file to easily
 set up a test environment, optionally also populating one or more SQL files into
@@ -139,10 +173,10 @@ the database first in order to set up testing.
 
 ```js
 import { initializeCustomChecks, aegisSetup, aegisTeardown } from '@odatnurd/cf-aegis';
-import { initializeResponseChecks } from '@odatnurd/cf-requests/aegis';
+import { initializeRequestChecks } from '@odatnurd/cf-requests/aegis';
 
 initializeCustomChecks();
-initializeResponseChecks()
+initializeRequestChecks()
 
 export const config = {
     files: [
@@ -164,8 +198,8 @@ export const config = {
 
 ### Custom Checks
 
-The `initializeResponseChecks()` function registers several custom checks with Aegis
-to simplify testing database-related logic.
+The `initializeRequestChecks()` function registers several custom checks with
+Aegis to simplify testing database-related logic.
 
 * `.isResponse($)`: Checks if a value is a `Response` object.
 * `.isNotResponse($)`: Checks if a value is not a `Response` object.
@@ -173,14 +207,14 @@ to simplify testing database-related logic.
   specific `status` code.
 
 
-## Methods
+## Library Methods
 
 ```js
-export function success(ctx, message, result, status) {}
+export function success(ctx, message, result=[], status=200) {}
 ```
 
-Indicate a successful return in JSON with the given `HTTP` status code; the
-status code is used to construct the JSON as well as the response:
+Generate a successful return in JSON with the given `HTTP` status code; the
+status code is used to construct the JSON as well as the response object:
 
 ```js
 {
@@ -197,13 +231,14 @@ status code is used to construct the JSON as well as the response:
 ---
 
 ```js
-export function fail(ctx, message, status, result) {}
+export function fail(ctx, message, status=400, result=undefined) {}
 ```
 
-Indicates a failure return in JSON with the given `HTTP` status code.
+Generate a failure return in JSON with the given `HTTP` status code; the status
+code is used to construct the JSON as well as the response object:
 
-This follows a similar form to `success`, though the `success` field is `false`
-instead of `true`.
+This results in JSON in a similar form to `success`, though the `success` field
+is `false` instead of `true`.
 
 Note that the order of the last two arguments is different because generally
 one wants to specify the status of an error but it usually does not return any
@@ -215,19 +250,28 @@ provided, the `data` field will not be present in the result.
 ---
 
 ```js
-export function validate(dataType, schemaObj) {}
+export function validate(dataType, { validate, mask? }) {}
 ```
 
 This function uses the [Hono validator()](https://hono.dev/docs/guides/validation)
 function to create a validator that will validate the data of the provided type
-using the provided `Joker` schema.
+using the provided validation object.
 
-`schemaObj` is an object that contains a `validate` and `mask` member that can
-validate data and store it into the `Hono` context, masking away all fields that
-are not present in the schema; this is intended to be used with
-[@axel669/joker](https://www.npmjs.com/package/@axel669/joker), though you are
-free to use any other validation schema so long as the call signatures match
-that of `joker`.
+The second parameter should be an object that contains a `validate` and an
+(optional) `mask` member:
+
+- `validate` takes the item to validate, and returns `true` when the data given
+  is valid. Any other return value is considered to be an error.
+- `mask` takes as an input the same item passed to `validate`, and returns a
+  masked version of the data that strips fields from the object that do not
+  appear in the schema.
+
+If `mask` is not provided, then the data will be validated but not masked.
+
+This method is intended to be used with the
+[@axel669/joker](https://www.npmjs.com/package/@axel669/joker) library (and
+in particular it's rollup plugin), though you are free to use any other
+validation schema so long as the call signatures are as defined above.
 
 On success, the data is placed in the context. If the data does not pass the
 validation of the schema, the `fail()` method is invoked on it with a status of
@@ -243,12 +287,20 @@ This is a simple wrapper which returns a function that wraps the provided
 handler function in a `try-catch` block, so that any uncaught exceptions can
 gracefully return a `fail()` result.
 
-The wrapper returned by this function will itself return either the result of
-the provided handler, so long as no exceptions are raised.
+The wrapper returned by this function will itself return the result of the
+provided handler, so long as no exceptions are raised.
+
+When an exception is caught, the `fail()` function is used to generate and
+return a response; this will contain as a message the text of the exception
+that was caught.
 
 Exceptions of type `HttpError` carry a specific `HTTP` status code, which will
 be used in the call to `fail()`; all other exceptions use a status of `500`.
 
+For debugging, if your worker has the  `CF_REQUESTS_STACKTRACE` environment
+variable set to either `true` or `yes`, the `fail()` response will include in
+its data field the stack trace as an array of strings that represent the trace.
+
 ```js
 export const $post = [
   validate('json', testSchema),
@@ -258,6 +310,9 @@ export const $post = [
 
     if (body.key1 != 69) {
       throw new Error('key is not nice');
+
+      // The above throw is the same as:
+      // return fail(ctx, 'key is not nice', 500)
     }
 
     return success(ctx, 'code test worked', body);
@@ -268,16 +323,16 @@ export const $post = [
 ---
 
 ```js
-export class HttpError extends Error(message: string, status) {}
+export class HttpError extends Error { constructor(message, status=500) {} }
 ```
 
 This is a simple exception class that wraps a textual message and a status code.
 
-When `body()` catches an exception of this type, it directly returns an error
-JSON containing the provided message and uses the status code as the `HTTP`
-status of the return.
+When `body()` catches an exception of this type, the `fail()` call it makes
+will use the status provided here as the `HTTP` status of the return.
 
-If `status` is not provided, it defaults to `500`.
+If `status` is not provided, it defaults to `500`, making this class generate an
+error with the same layout as any other exception class.
 
 ---
 
@@ -296,14 +351,15 @@ cleaner looking, while still allowing for arbitrary middleware
 export const $post = routeHandler(
   validate('json', testSchema),
 
-  // More than one argument, so function is directly returned; no body() call.
+  // More than one argument, so function is directly returned; no body() call
+  // wrapper here.
   async (ctx, next) => {
     console.log('Async middleware is running!');
     await next();
   },
 
   // Single argument async functions are wrapped in body(), so exceptions raised
-  // are handled appropriately.
+  // are handled consistently.
   async (ctx) => {
     const body = ctx.req.valid('json');
 

package/lib/handlers.js

@@ -49,11 +49,11 @@ export const fail = (ctx, message, status, result) => {
  *
  * When using this filter, underlying requests can fetch the validated data
  * via the ctx.req.valid() function, e.g. ctx.req.valid('json'). */
-export const validate = (dataType, schemaObj) => validator(dataType, async (value, ctx) => {
+export const validate = (dataType, { validate, mask }) => validator(dataType, async (value, ctx) => {
   // Joker returns true for valid data and an array of error objects on failure.
-  const result = await schemaObj.validate(value);
+  const result = await validate(value);
   if (result === true) {
-    return schemaObj.mask(value);
+    return typeof mask === 'function' ? mask(value) : value;
   }
 
   return fail(ctx, `${dataType} data is not valid`, 422, result);
@@ -92,11 +92,29 @@ export function body(handler) {
       return await handler(ctx);
     }
     catch (err) {
+      const generateTrace = ['true', 'yes'].includes(ctx.env.CF_REQUESTS_STACKTRACE);
+      let trace = undefined;
+
+      // If we should generate the stack trace and the error that we got
+      // actually has a trace in it, then generate a trace array by converting
+      // the stack into an array of locations for better readability.
+      //
+      // This elides the start line, since we capture the message already below,
+      // and removes the `at` prefix since that is redundant.
+      if (generateTrace === true && typeof err.stack === 'string') {
+        trace = err.stack.split('\n')
+          .slice(1)
+          .map(line => {
+            const trimmedLine = line.trim();
+            return trimmedLine.startsWith('at ') ? trimmedLine.substring(3) : trimmedLine;
+          });
+      }
+
       if (err instanceof HttpError) {
-        return fail(ctx, err.message, err.status);
+        return fail(ctx, err.message, err.status, trace);
       }
 
-      return fail(ctx, err.message, 500);
+      return fail(ctx, err.message, 500, trace);
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odatnurd/cf-requests",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Simple Cloudflare Hono request wrapper",
   "author": "OdatNurd (https://odatnurd.net)",
   "homepage": "https://github.com/OdatNurd/cf-requests",
@@ -29,15 +29,19 @@
   "devDependencies": {
     "@axel669/aegis": "^0.3.1",
     "@axel669/joker": "^0.3.5",
-    "@odatnurd/cf-aegis": "^0.1.2",
-    "miniflare": "^4.20250813.0"
+    "@odatnurd/cf-aegis": "^0.1.4",
+    "json5": "^2.2.3",
+    "miniflare": "^4.20250923.0",
+    "smol-toml": "^1.4.2"
   },
   "peerDependencies": {
     "@axel669/aegis": "^0.3.1",
     "@axel669/joker": "^0.3.5",
-    "@odatnurd/cf-aegis": "^0.1.2",
+    "@odatnurd/cf-aegis": "^0.1.4",
     "hono": "^4.7.0",
-    "miniflare": "^4.20250813.0"
+    "json5": "^2.2.3",
+    "miniflare": "^4.20250923.0",
+    "smol-toml": "^1.4.2"
   },
   "peerDependenciesMeta": {
     "@axel669/aegis": {
@@ -50,6 +54,9 @@
       "optional": true
     },
     "miniflare": {
+      "smol-toml": true
+    },
+    "json5": {
       "optional": true
     }
   },