@odatnurd/cf-requests 0.1.9 → 0.1.11

package/README.md

@@ -78,12 +78,13 @@ by the schema are present.
 ```js
 // Bring in the validation generator, the success response generator, and the
 // route handler generator.
-import { validate, success, routeHandler } from '@odatnurd/cf-requests';
+import { validate, verify, success, routeHandler } from '@odatnurd/cf-requests';
 
 // 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';
+import * as inputSchema from '#schemas/test_input';
+import * as outputSchema from '#schemas/test_output';
 
 // The hono-file-routes package defines routes in a file by exporting `$verb`
 // as routes. Here we are using the routeHandler() generator, which constructs
@@ -93,7 +94,10 @@ import * as testSchema from '#schemas/test';
 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),
+  validate('json', inputSchema),
+
+  // Verify that the resulting object, on success, follows the provided schema,
+  verify(outputSchema),
 
   // Async functions that take a single argument are route handlers; they will
   // be automatically guarded with a try/catch block
@@ -210,7 +214,7 @@ Aegis to simplify testing database-related logic.
 ## Library Methods
 
 ```js
-export function success(ctx, message, result=[], status=200) {}
+export async function success(ctx, message, result=[], status=200) {}
 ```
 
 Generate a successful return in JSON with the given `HTTP` status code; the
@@ -228,6 +232,15 @@ status code is used to construct the JSON as well as the response object:
 `result` is optional and defaults to an empty array if not provided. Similarly
 `status` is option and defaults to `200` if not provided.
 
+If the `verify()` function was used to set a schema, then this function will
+validate that the **entire returned body, including `result`** you provide
+matches the schema, and will also optionally mask it, if `verify()` was given
+a mask function.
+
+When using `verify()`, if the result body does not conform to the schema, a
+`SchemaError` exception will be thrown. This is automatically handled by
+`body()`, and will result in a `fail()` response instead of a `success()`.
+
 ---
 
 ```js
@@ -247,6 +260,10 @@ other meaningful result (which is the opposite of the `success` case).
 If `status` is not provided, it defaults to `400`, while if `result` is not
 provided, the `data` field will not be present in the result.
 
+Note that unlike `success()`, `fail()` will not honor the addition of an output
+validator via `verify()`, since it is usually expected that it will not provide
+a meaningful data result.
+
 ---
 
 ```js
@@ -279,6 +296,36 @@ validation of the schema, the `fail()` method is invoked on it with a status of
 
 ---
 
+```js
+export function verify({ validate, mask? }) {}
+```
+
+This function registers the provided validation/masking pair for the current
+route. This causes `success` to validate (and optionally mask) the resulting
+message body before finalizing the request and sending the data out.
+
+> ℹ️ The schema is run over the **entire returned body, not just the`result`**,
+> so in practice the schema needs to match what the `success()` function uses
+> as the final result.
+
+The 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.
+
+---
+
 ```js
 export function body(handler) {}
 ```
@@ -301,6 +348,12 @@ 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.
 
+> ℹ️ If the body catches a `SchemaError`, the `CF_REQUESTS_STACKTRACE` variable
+> will be ignored since in this case it is the data and not the code that was at
+> fail. In these cases, the result inside of the returned body will be the
+> validation error object instead.
+
+
 ```js
 export const $post = [
   validate('json', testSchema),
@@ -336,6 +389,17 @@ error with the same layout as any other exception class.
 
 ---
 
+```js
+export class SchemaError extends HttpError { constructor(message, status=500, result=undefined) {} }
+```
+
+This is a simple extension to HttpError and is thrown in cases where a schema
+validation error has occurred; it is handled by `body()` the same as `HttpError`
+is. If the exception has a `result`, it will be used in the call to `fail()` in
+this case, so that the result of the validation will be returned.
+
+---
+
 ```js
 export function routeHandler(...args) {}
 ```

package/lib/handlers.js

@@ -7,16 +7,86 @@ import { validator } from 'hono/validator';
 /******************************************************************************/
 
 
-/* Generate a standardized success response from an API call.
+/* A custom error base class that allows for route handlers to generate errors
+ * with a specific message and status code without having to have more explicit
+ * exception handling logic.
+ *
+ * When instances of this class are thrown by the code that is wrapped in a
+ * call to body(), the error response from that handler will follow a standard
+ * form and have a distinct HTTP error code.
+ *
+ * For simplicity, if the status code is not provided, 500 is assumed.
+ */
+export class HttpError extends Error {
+  constructor(message, status=500) {
+    super(message);
+    this.status = status;
+    this.name = 'HttpError';
+  }
+}
+
+
+/******************************************************************************/
+
+
+/* This custom error class works as HttpError does, but it is specificaly thrown
+ * to indicate that there was a schema validation error, either on input or on
+ * output.
+ *
+ * The result here is optional and if given is used as the result in the
+ * handler's fail() call; for schema errors this generally returns the object
+ * that the schema validator returns when it signals the error. */
+export class SchemaError extends HttpError {
+  constructor(message, status=500, result=undefined) {
+    super(message, status);
+    this.name = 'SchemaError';
+    this.result = result;
+  }
+}
+
+
+/******************************************************************************/
+
+
+/* Generate a standardized success response from an API call. If the provided
+ * context has a response guard attached to it, the result that is provided will
+ * be validated against it (and also masked, if a mask was provided) prior to
+ * being attached to the output and returned.
+ *
+ * If this results in an error, an exception is thrown to indicate this; the
+ * standard machinery will catch this and handle it as appropriate.
  *
- * This generates a JSON return value with the given HTTP status, with a
- * data section that contains the provided result, whatever it may be. */
-export const success = (ctx, message, result, status) => {
+ * On success (no validation, or validation passes), this generates a JSON
+ * return value with the given HTTP status, with a data section that contains
+ * the provided result, whatever it may be (and which could possibly have been
+ * masked). */
+export const success = async (ctx, message, result, status) => {
   status ??= 200;
   result ??= [];
 
+  // Construct the body that we will be returning back.
+  let body = { success: true, status, message, data: result };
+
+  // See if there is a validator attached to this; if so, we have more work to
+  // do; if not, we can skip.
+  const validator = ctx.get('__cf_requests_response_validator');
+  if (validator !== undefined) {
+    // Try to validate; if this does not return true, then the data is not valid
+    // and we should throw an error.
+    const valid = validator.validate(body);
+    if (valid !== true) {
+      throw new SchemaError('response data failed schema validation', 500, valid);
+    }
+
+    // If there is a mask function, then use it to set up the value of the
+    // result.
+    if (typeof validator.mask === 'function') {
+      body = validator.mask(body);
+    }
+  }
+
   ctx.status(status);
-  return ctx.json({ success: true, status, message, data: result });
+  return ctx.json(body);
 }
 
 
@@ -56,31 +126,32 @@ export const validate = (dataType, { validate, mask }) => validator(dataType, as
     return typeof mask === 'function' ? mask(value) : value;
   }
 
-  return fail(ctx, `${dataType} data is not valid`, 422, result);
+  // Fail with 422 to signal unprocessible entity.
+  return fail(ctx, `request ${dataType} data failed schema validation`, 422, result);
 });
 
 
 /******************************************************************************/
 
 
-/* A custom error base class that allows for route handlers to generate errors
- * with a specific message and status code without having to have more explicit
- * exception handling logic.
+/* Register a post-validator that will be used by any success() calls within the
+ * route handler to verify that the data being put into the returned result to
+ * the client conforms to the scheme presented.
  *
- * When instances of this class are thrown by the code that is wrapped in a
- * call to body(), the error response from that handler will follow a standard
- * form and have a distinct HTTP error code.
+ * The validator provided is the same as that for validate(); an object that
+ * has a 'validate' key to validate the data and an optional 'mask' key to mask
+ * the result.
  *
- * For simplicity, if the status code is not provided, 500 is assumed.
- */
-export class HttpError extends Error {
-  constructor(message, status=500) {
-    super(message);
-    this.status = status;
-    this.name = 'HttpError';
-  }
+ * Internally, this just stores the guard into the context for later usage and
+ * continues on its merry way. */
+export const verify = (validator) => async (ctx, next) => {
+  // Due to my excessive amount of paranoia, this is namespaced with the package
+  // name to slightly reduce the possibility of a name conflict.
+  ctx.set('__cf_requests_response_validator', validator);
+  await next();
 }
 
+
 /******************************************************************************/
 
 /* Create a request handler that will execute the provided handler function and
@@ -92,29 +163,40 @@ 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;
-          });
+      // By default, the result has no data attached.
+      let errorData = undefined;
+
+      // If the exception is a schema validation error, then the exception will
+      // carry what we want to use for the result, since that tells us how the
+      // validation failed.
+      if (err instanceof SchemaError) {
+        errorData = err.result;
+      } else {
+        // This is not a schema validation; check to see if we should be adding
+        // a stack trace as the data instead.
+        const generateTrace = ['true', 'yes'].includes(ctx.env.CF_REQUESTS_STACKTRACE);
+
+        // 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') {
+          errorData = 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, trace);
-      }
+      // If the error was an HttpError or a SchemaError, then use its status as
+      // the status; otherwise default to 500.
+      const status = (err instanceof HttpError) ? err.status : 500;
 
-      return fail(ctx, err.message, 500, trace);
+      return fail(ctx, err.message, status, errorData);
     }
   }
 }
@@ -122,6 +204,7 @@ export function body(handler) {
 
 /******************************************************************************/
 
+
 /* This is a utility wrapper function that simplifies the creation of a Hono
  * route handler; it accepts any number of arguments and returns back a prepared
  * array of items for use as a route handler.
@@ -143,4 +226,5 @@ export function body(handler) {
   });
 }
 
+
 /******************************************************************************/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odatnurd/cf-requests",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Simple Cloudflare Hono request wrapper",
   "author": "OdatNurd (https://odatnurd.net)",
   "homepage": "https://github.com/OdatNurd/cf-requests",