@odatnurd/cf-requests 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Terence Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# Simple CloudFlare Request Handlers
+
+`cf-requests` is a very 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.
+
+This is also intended to be used with
+[@axel669/joker](https://www.npmjs.com/package/@axel669/joker) as a schema
+validation library and
+[@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.
+
+
+## Installation
+
+Install `cf-requests` via `npm`, `pnpm`, and so on, in the usual way.
+
+```sh
+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.
+
+### Example
+
+Assuming a file named `test.joker.json` that contains the following Joker
+schema:
+
+```json
+{
+  "itemName": "body",
+  "root": {
+    "key1": "number",
+    "key2": "string",
+  }
+}
+```
+
+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.
+
+
+```js
+/******************************************************************************/
+
+
+import { validate, success, routeHandler } from '#lib/common';
+
+import * as testSchema from '#schemas/test';
+
+
+export const $post = routeHandler(
+  validate('json', testSchema),
+
+  async (ctx) => {
+    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
+    if (body.key1 != 69) {
+      throw new Error('key is not nice');
+    }
+
+    return success(ctx, 'request body validated', body);
+  },
+);
+
+```
+
+## Methods
+
+```js
+export function success(ctx, message, result, status) {}
+```
+
+Indicate a successful return in JSON with the given `HTTP` status code:
+
+```js
+{
+    "success": true,
+    message,
+    data: result
+}
+```
+
+`result` is optional and defaults to an empty array if not provided. Similarly
+`status` is option and defaults to `200` if not provided.
+
+---
+
+```js
+export function fail(ctx, message, status, result) {}
+```
+
+Indicates a failure return in JSON with the given `HTTP` status code.
+
+This follows 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
+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.
+
+---
+
+```js
+export function validate(dataType, schemaObj) {}
+```
+
+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.
+
+`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`.
+
+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
+`422` to signify the issue directly.
+
+Execute a fetch operation on the provided database, using the data in `sqlargs`
+to create the statement(s) to be executed, and return the result(s) of the
+query after logging statistics such as the rows read and written, which will be
+annotated with the action string provided to give context to the operation.
+
+The provided `sqlargs` is a variable length list of arguments that consists of
+strings to be compiled to SQL, previously compiled statements, and/or arrays of
+values to bind to statements.
+
+For the purposes of binding, arrays will bind to the most recently seen
+statement, allowing you to compile one statement and bind it multiple times if
+desired.
+
+When more than one statement is provided, all statements will be executed as a
+batch operation, which implicitly runs as a transaction.
+
+The return value is the direct result of executing the query or queries given
+in `sqlargs`; this is either a (potentially empty) array of result rows, or an
+array of such arrays (if a batch). As with `dbRawQuery`, the `meta` is stripped
+from the results, providing you just the actual query result.
+
+---
+
+```js
+export function body(handler) {}
+```
+
+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.
+
+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`.
+
+```js
+export const $post = [
+  validate('json', testSchema),
+
+  body(async (ctx) => {
+    const body = ctx.req.valid('json');
+
+    return success(ctx, 'code test worked', body);
+  }),
+];
+```
+
+---
+
+```js
+export class HttpError extends Error(message: string, status) {}
+```
+
+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.
+
+If `status` is not provided, it defaults to `500`.
+
+---
+
+```js
+export function routeHandler(...args) {}
+```
+
+This small helper makes it slightly cleaner to set up a route handler by taking
+any number of arguments and returning them back as an array.
+
+As a part of this operation, any `async` function that takes exactly one argument
+is implicitly wrapped in `body()`. This makes the resulting handler somewhat
+cleaner looking, while still allowing for arbitrary middleware
+
+```js
+export const $post = routeHandler(
+  validate('json', testSchema),
+
+  // More than one argument, so function is directly returned; no body() call.
+  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.
+  async (ctx) => {
+    const body = ctx.req.valid('json');
+
+    if (body.key1 != 69) {
+      throw new Error('key is not nice');
+    }
+
+    return success(ctx, 'code test worked', body);
+  },
+);
+```

package/lib/handlers.js

@@ -0,0 +1,128 @@
+/******************************************************************************/
+
+
+import { validator } from 'hono/validator';
+
+
+/******************************************************************************/
+
+
+/* Generate a standardized success response from an API call.
+ *
+ * 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) => {
+  status ??= 200;
+  result ??= [];
+
+  ctx.status(status);
+  return ctx.json({ success: true, message, data: result });
+}
+
+
+/******************************************************************************/
+
+
+/* Generate a standardized error response from an API call.
+ *
+ * This generates a JSON return value with the given HTTP status, with an
+ * error reason that is the reason specified. */
+export const fail = (ctx, message, status, result) => {
+  status ??= 400;
+
+  ctx.status(status);
+  return ctx.json({ success: false, message, data: result });
+}
+
+
+/******************************************************************************/
+
+
+/* Create a validator that will validate the type of request data provided
+ * against a specifically defined Joker schema object. The data is both
+ * validated against the schema as well as filtered so that non-schema
+ * properties of the data are discarded.
+ *
+ * This provides a middleware filter for use in Hono; it is expected to either
+ * trigger a failure, or return the data that is the validated and cleaned
+ * object from the request.
+ *
+ * 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) => {
+  // Joker returns true for valid data and an array of error objects on failure.
+  const result = await schemaObj.validate(value);
+  if (result === true) {
+    return schemaObj.mask(value);
+  }
+
+  return fail(ctx, `${dataType} data is not valid`, 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.
+ *
+ * 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';
+  }
+}
+
+/******************************************************************************/
+
+/* Create a request handler that will execute the provided handler function and
+ * catch any exceptions that it may raise, returning an appropriate error
+ * response back to the caller. */
+export function body(handler) {
+  return async (ctx) => {
+    try {
+      return await handler(ctx);
+    }
+    catch (err) {
+      if (err instanceof HttpError) {
+        return fail(ctx, err.message, err.status);
+      }
+
+      return fail(ctx, err.message, 500);
+    }
+  }
+}
+
+
+/******************************************************************************/
+
+/* 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.
+ *
+ * Any argument that is an async function with exactly one argument is wrapped
+ * in a call to body() directly, while all other values (including async
+ * functions that take more than one argument) are put into the array as-is.
+ *
+ * This allows for not only validations but also arbitrary middleware as well
+ * to be used. */
+ export function routeHandler(...args) {
+  return args.map(arg => {
+    // Any async functions that take exactly one argument are passed through the
+    // body wrapper to wrap them; everything else passes through as-is.
+    if (typeof arg === 'function' && arg.constructor.name === 'AsyncFunction' && arg.length === 1) {
+      return body(arg);
+    }
+    return arg;
+  });
+}
+
+/******************************************************************************/

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@odatnurd/cf-requests",
+  "version": "0.1.0",
+  "description": "Simple Cloudflare Hono request wrapper",
+  "author": "OdatNurd (https://odatnurd.net)",
+  "homepage": "https://github.com/OdatNurd/cf-requests",
+  "bugs": "https://github.com/OdatNurd/cf-requests/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OdatNurd/cf-requests"
+  },
+  "type": "module",
+  "main": "lib/handlers.js",
+  "exports": {
+    ".": "./lib/handlers.js"
+  },
+  "files": [
+    "lib/handlers.js"
+  ],
+  "keywords": [
+    "cloudflare",
+    "hono",
+    "routing"
+  ],
+  "peerDependencies": {
+    "hono": "^4.7.0"
+  },
+  "scripts": {
+    "test": "echo \"No tests specified\" && exit 0"
+  }
+}