@odatnurd/cf-requests 0.1.1 → 0.1.3

package/README.md

@@ -78,17 +78,115 @@ 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.
+
+To use these utilities, you must install the required peer dependencies into
+your own project's `devDependencies` if you have not already done so.
+
+```sh
+pnpm add -D @odatnurd/d1-query @axel669/aegis miniflare fs-jetpack
+```
+
+> ℹ️ If you are actively using
+> [@odatnurd/d1-query](https://www.npmjs.com/package/@odatnurd/d1-query) in your
+> project, that library should be installed as a regular `dependency` and not a
+> `devDependency`
+
+The `@odatnurd/cf-requests` module exports the following functions:
+
+
+### Helper Functions
+
+```javascript
+export function initializeResponseChecks() {}
+```
+Registers all [custom checks](#custom-checks) with Aegis. This should be called
+once at the top of your `aegis.config.js` file.
+
+---
+
+```javascript
+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:
+
+ * `Valid Data`: An Object that represents the validated and masked data
+ * `Invalid Data`: A `Response` object that carries the error payload
+
+Using this, it is possible to validate that a schema works as expected without
+having to use it in the actual request first.
+
+> ℹ️ By default, the test will use the `validate` function to perform the data
+> validation. If desired, you can pass an optional `validator` function as the
+> final argument. This must take the same arguments as `validate` does, and
+> follow the same contract. This allows for testing of other schema libraries,
+> such as during migrations to this library.
+
+
+### 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
+the database first in order to set up testing.
+
+**Example `aegis.config.js`:**
+
+```js
+import { initializeCustomChecks, aegisSetup, aegisTeardown } from '@odatnurd/cf-aegis';
+import { initializeResponseChecks } from '@odatnurd/cf-requests/aegis';
+
+initializeCustomChecks();
+initializeResponseChecks()
+
+export const config = {
+    files: [
+        "test/**/*.test.js",
+    ],
+    hooks: {
+        async setup(ctx) {
+            await aegisSetup(ctx, 'test/setup.sql', 'DB');
+        },
+
+        async teardown(ctx) {
+            await aegisTeardown(ctx);
+        },
+    },
+    failAction: "afterSection",
+}
+```
+
+
+### Custom Checks
+
+The `initializeResponseChecks()` 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.
+* `.isResponseWithStatus($, count)`: Checks if an object is a `Response` with a
+  specific `status` code.
+
+
 ## Methods
 
 ```js
 export function success(ctx, message, result, status) {}
 ```
 
-Indicate a successful return in JSON with the given `HTTP` status code:
+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:
 
 ```js
 {
     "success": true,
+    status,
     message,
     data: result
 }

package/aegis/index.js

@@ -0,0 +1,121 @@
+/******************************************************************************/
+
+
+import { addCheck } from '@axel669/aegis';
+import { validate } from '../lib/handlers.js';
+
+
+/******************************************************************************/
+
+
+/*
+ * Initializes some custom Aegis checks that make testing of schema and data
+ * requests easier.
+ *
+ * This is entirely optional.
+ */
+export function initializeRequestChecks() {
+  // Check that a value is a response object from our middleware
+  addCheck.value.isResponse(
+    source => source instanceof Response
+  );
+
+  // Check that a value is NOT a response object
+  addCheck.value.isNotResponse(
+    source => (source instanceof Response) === false
+  );
+
+  addCheck.value.isResponseWithStatus(
+    (source, status) => source instanceof Response && source.status == status
+  );
+}
+
+
+/******************************************************************************/
+
+
+/* A helper function to be able to test the schema validation options in the
+ * library. This takes a schema object and data type such as you would pass to
+ * the validate() function, along with an input data object, and exercises that
+ * the schema works as expected.
+ *
+ * The result of the call is either a JSON object that represents the validated
+ * and masked input data if the schema validated the data, or a Response object
+ * that carries the failure of the validation. This would be a response of code
+ * 400 with a JSON body that carries the actual validation failure message
+ * within it. */
+export async function schemaTest(dataType, schema, data, validator) {
+  // If a validator is provided, use it; otherwise use ours. This requires that
+  // you provide a call-compatible validator. This is here only to support some
+  // migrations of old code that is using a different validator than the one
+  // this library currently uses.
+  validator = validator ??= validate;
+
+  // Use the Hono factory to create our middleware, just as a caller would.
+  // Create a middleware using the Hono factory method for this, using the
+  // schema object and data type provided.
+  const middleware = validator(dataType, schema);
+
+  // As a result of the middleware, we will either capture the validated (and
+  // masked) input JSON data, or we will capture an error response. As a part of
+  // this we also capture what the eventual status of the call would be if this
+  // generates a response, so that we can put it into the response object.
+  let validData = null;
+  let errorResponse = null;
+  let responseStatus = 200;
+
+  // A fake next to pass to the middleware when we execute it, so that it does
+  // not throw an error.
+  const next = () => {};
+
+  // In order to run the test we need to create a fake Hono context object to
+  // pass to the middleware; this mimics the smallest possible footprint of
+  // Hono context for our purposes.
+  const ctx = {
+    req: {
+      // These methods are used by the validator to pull the parsed data out of
+      // the request in order to validate it.
+      param: () => data,
+      json: async () => data,
+      query: () => data,
+
+      // The validator invokes this to get headers out of the request when the
+      // data type is JSON.
+      header: (name) => {
+        if (name.toLowerCase() === 'content-type' && dataType === 'json') {
+          return 'application/json';
+        }
+        return undefined;
+      },
+
+      // When validation succeeds, it invokes this to store the data back into
+      // the context.
+      addValidatedData: (target, data) => validData = data
+    },
+
+    // Used to capture a failure; the validator will invoke status to set the
+    // required HTTP response and then invoke the json() method to populate the
+    // error.
+    status: (inStatus) => { responseStatus = inStatus; },
+    json: (payload) => {
+      errorResponse = new Response(
+        JSON.stringify(payload), {
+          status: responseStatus,
+          statusText: "Bad Request",
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    },
+  };
+
+  // Run the middleware; we either capture a result in the error payload or the
+  // validation result.
+  await middleware(ctx, next);
+
+  // Return the error payload if validation failed, otherwise return the
+  // validated data from the success path.
+  return errorResponse ?? validData;
+};
+
+
+/******************************************************************************/

package/lib/handlers.js

@@ -16,7 +16,7 @@ export const success = (ctx, message, result, status) => {
   result ??= [];
 
   ctx.status(status);
-  return ctx.json({ success: true, message, data: result });
+  return ctx.json({ success: true, status, message, data: result });
 }
 
 
@@ -31,7 +31,7 @@ export const fail = (ctx, message, status, result) => {
   status ??= 400;
 
   ctx.status(status);
-  return ctx.json({ success: false, message, data: result });
+  return ctx.json({ success: false, status, message, data: result });
 }
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odatnurd/cf-requests",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Simple Cloudflare Hono request wrapper",
   "author": "OdatNurd (https://odatnurd.net)",
   "homepage": "https://github.com/OdatNurd/cf-requests",
@@ -13,15 +13,18 @@
   "type": "module",
   "main": "lib/handlers.js",
   "exports": {
-    ".": "./lib/handlers.js"
+    ".": "./lib/handlers.js",
+    "./aegis": "./aegis/index.js"
   },
   "files": [
-    "lib/handlers.js"
+    "lib",
+    "aegis"
   ],
   "keywords": [
     "cloudflare",
     "hono",
-    "routing"
+    "routing",
+    "aegis"
   ],
   "peerDependencies": {
     "hono": "^4.7.0"