hono-ban 0.2.0 → 0.2.3

package/README.md

@@ -17,6 +17,7 @@ HTTP-friendly error objects for [Hono](https://hono.dev), inspired by [Boom](htt
   - [Custom Error Data](#custom-error-data)
   - [Error Conversion](#error-conversion)
   - [Error Formatting](#error-formatting)
+  - [OpenAPI Integration](#openapi-integration)
 - [Formatters](#formatters)
   - [Default Formatter](#default-formatter)
   - [RFC7807 (Problem Details) Formatter](#rfc7807-problem-details-formatter)
@@ -55,7 +56,14 @@ hono-ban provides a comprehensive error handling solution for Hono.js applicatio
 ### Basic Usage
 
 ```typescript
-import { notFound, badRequest } from "hono-ban";
+import { Hono } from "hono";
+import ban, { notFound, badRequest } from "hono-ban";
+
+// Create a Hono app
+const app = new Hono();
+
+// IMPORTANT: Add the ban middleware for error handling to work
+app.use(ban());
 
 // Create a 404 Not Found error
 const error = notFound("User not found");
@@ -66,10 +74,20 @@ const validationError = badRequest("Invalid input", {
     invalidFields: ["email", "password"],
   },
 });
+
+// Example route that throws an error
+app.get("/users/:id", (c) => {
+  // The thrown error will be caught and formatted by the ban middleware
+  throw notFound(`User with ID ${c.req.param("id")} not found`);
+});
 ```
 
+> **Note**: The ban middleware is required for errors to be automatically caught and formatted. Without it, thrown errors won't be properly handled.
+
 ### Error Middleware
 
+The ban middleware is **required** to catch and format errors thrown in your routes. Without this middleware, errors will not be properly handled.
+
 #### Basic Usage
 
 ```typescript
@@ -80,6 +98,7 @@ import { notFound } from "hono-ban";
 const app = new Hono();
 
 // Add the error handling middleware with default options
+// This is REQUIRED for error handling to work
 app.use(ban());
 
 // Routes can throw errors that will be handled automatically
@@ -189,6 +208,96 @@ const formatted = formatError(banError, myFormatter, {
 const response = createErrorResponse(banError, formatted);
 ```
 
+### OpenAPI Integration
+
+hono-ban integrates seamlessly with [@hono/zod-openapi](https://github.com/honojs/middleware/tree/main/packages/zod-openapi) to provide standardized error handling for OpenAPI-validated routes.
+
+```typescript
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { ban, createRFC7807Formatter, rfc7807Hook } from "hono-ban";
+import { RFC7807DetailsSchema } from "hono-ban/formatters/rfc7807";
+import { createRoute, z } from "@hono/zod-openapi";
+import type { Context } from "hono";
+import type { Env } from "./config/env";
+
+// Create an OpenAPIHono instance with the RFC7807 hook for validation errors
+const app = new OpenAPIHono<Env>({ defaultHook: rfc7807Hook });
+
+// IMPORTANT: Add the ban middleware with RFC7807 formatter
+app.use(
+  ban({
+    formatter: createRFC7807Formatter({
+      baseUrl: "https://api.example.com/errors",
+    }),
+  })
+);
+
+// Define a schema for your data
+const NoteSchema = z.object({
+  name: z.string().max(10),
+});
+
+// Create an OpenAPI route with error handling
+const route = createRoute({
+  method: "post",
+  path: "/notes",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: NoteSchema,
+        },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      description: "Successfully created note",
+      content: {
+        "application/json": {
+          schema: z.object({
+            data: z.object({
+              id: z.string(),
+              type: z.string(),
+              attributes: NoteSchema,
+            }),
+          }),
+        },
+      },
+    },
+    400: {
+      description: "Validation error",
+      content: {
+        "application/json": {
+          schema: RFC7807DetailsSchema, // Use the RFC7807 schema for errors
+        },
+      },
+    },
+  },
+});
+
+// Register the route
+app.openapi(route, async (c) => {
+  // Handle the request
+  // Any validation errors will be automatically formatted using RFC7807
+  return c.json({
+    data: {
+      /* response data */
+    },
+  });
+});
+```
+
+#### Key Benefits
+
+1. **Automatic Validation Error Handling**: The `rfc7807Hook` automatically converts Zod validation errors to RFC7807 format.
+2. **Standardized Error Responses**: All errors follow the RFC7807 specification.
+3. **OpenAPI Documentation**: Error schemas are properly documented in your OpenAPI specification.
+4. **Type Safety**: Full TypeScript support for request and response validation.
+
+> **Note**: The ban middleware is still required when using OpenAPI integration. The `rfc7807Hook` handles validation errors, but the middleware is needed to catch and format other errors.
+
 ## Formatters
 
 hono-ban includes several built-in formatters for common error response formats.
@@ -274,21 +383,7 @@ The RFC7807 formatter provides several helper functions:
 - `createValidationError(params)`: Create validation error data
 - `createZodValidationError(error)`: Convert Zod validation errors to RFC7807 format
 - `createConstraintViolation(name, reason, resource, constraint)`: Create constraint violation data
-- `createRFC7807Hook(options)`: Create a Hono hook for Zod OpenAPI validation
-
-```typescript
-import { createRFC7807Hook } from "hono-ban/formatters/rfc7807";
-import { OpenAPIHono } from "@hono/zod-openapi";
-
-const app = new OpenAPIHono();
-
-// Add the RFC7807 hook for validation errors
-app.openapi(
-  createRFC7807Hook({
-    baseUrl: "https://api.example.com/problems",
-  })
-);
-```
+- `createRFC7807Hook(options)`: Create a Hono hook for Zod OpenAPI validation (see [OpenAPI Integration](#openapi-integration) for usage)
 
 ## API Reference
 

package/dist/cjs/index.js

@@ -69,13 +69,13 @@ __export(exports_src, {
   entityTooLarge: () => entityTooLarge,
   defaultFormatter: () => defaultFormatter,
   default: () => src_default,
-  createZodValidationError: () => createZodValidationError,
-  createValidationError: () => createValidationError,
+  createRFC7807ZodValidationError: () => createRFC7807ZodValidationError,
+  createRFC7807ValidationError: () => createRFC7807ValidationError,
   createRFC7807Hook: () => createRFC7807Hook,
   createRFC7807Formatter: () => createRFC7807Formatter,
+  createRFC7807ConstraintViolation: () => createRFC7807ConstraintViolation,
   createErrorResponse: () => createErrorResponse,
   createError: () => createError,
-  createConstraintViolation: () => createConstraintViolation,
   convertToBanError: () => convertToBanError,
   conflict: () => conflict,
   clientTimeout: () => clientTimeout,
@@ -83,11 +83,11 @@ __export(exports_src, {
   badImplementation: () => badImplementation,
   badGateway: () => badGateway,
   badData: () => badData,
-  ValidationParamSchema: () => ValidationParamSchema,
   STATUS_CODES: () => STATUS_CODES,
-  ProblemErrorDataSchema: () => ProblemErrorDataSchema,
-  ProblemDetailsSchema: () => ProblemDetailsSchema,
-  ConstraintViolationSchema: () => ConstraintViolationSchema
+  RFC7807ValidationParamSchema: () => RFC7807ValidationParamSchema,
+  RFC7807ErrorDataSchema: () => RFC7807ErrorDataSchema,
+  RFC7807DetailsSchema: () => RFC7807DetailsSchema,
+  RFC7807ConstraintViolationSchema: () => RFC7807ConstraintViolationSchema
 });
 module.exports = __toCommonJS(exports_src);
 
@@ -282,28 +282,64 @@ var defaultFormatter = {
 
 // src/formatters/rfc7807/schemas.ts
 var import_zod_openapi = require("@hono/zod-openapi");
-var ValidationParamSchema = import_zod_openapi.z.object({
-  name: import_zod_openapi.z.string(),
-  reason: import_zod_openapi.z.string()
-}).openapi("ValidationParam");
-var ConstraintViolationSchema = import_zod_openapi.z.object({
-  name: import_zod_openapi.z.string(),
-  reason: import_zod_openapi.z.string(),
-  resource: import_zod_openapi.z.string(),
-  constraint: import_zod_openapi.z.string()
-}).openapi("ConstraintViolation");
-var ProblemErrorDataSchema = import_zod_openapi.z.object({
-  "invalid-params": import_zod_openapi.z.array(ValidationParamSchema).optional(),
-  violations: import_zod_openapi.z.array(ConstraintViolationSchema).optional()
+var RFC7807ValidationParamSchema = import_zod_openapi.z.object({
+  name: import_zod_openapi.z.string().openapi({
+    example: "username",
+    description: "The field name that failed validation"
+  }),
+  reason: import_zod_openapi.z.string().openapi({
+    example: "String must contain at least 3 character(s)",
+    description: "The reason for validation failure"
+  })
 });
-var ProblemDetailsSchema = import_zod_openapi.z.object({
-  type: import_zod_openapi.z.string().url(),
-  title: import_zod_openapi.z.string(),
-  status: import_zod_openapi.z.number().int().min(400).max(599),
-  detail: import_zod_openapi.z.string(),
-  instance: import_zod_openapi.z.string(),
-  timestamp: import_zod_openapi.z.string().datetime()
-}).merge(ProblemErrorDataSchema).openapi("ProblemDetails");
+var RFC7807ConstraintViolationSchema = import_zod_openapi.z.object({
+  name: import_zod_openapi.z.string().openapi({
+    example: "email",
+    description: "The field name that violated a constraint"
+  }),
+  reason: import_zod_openapi.z.string().openapi({
+    example: "Email already exists",
+    description: "The reason for the constraint violation"
+  }),
+  resource: import_zod_openapi.z.string().openapi({
+    example: "user",
+    description: "The resource type that contains the constraint"
+  }),
+  constraint: import_zod_openapi.z.string().openapi({
+    example: "unique",
+    description: "The type of constraint that was violated"
+  })
+});
+var RFC7807ErrorDataSchema = import_zod_openapi.z.object({
+  "invalid-params": import_zod_openapi.z.array(RFC7807ValidationParamSchema).optional(),
+  violations: import_zod_openapi.z.array(RFC7807ConstraintViolationSchema).optional()
+});
+var RFC7807DetailsSchema = import_zod_openapi.z.object({
+  type: import_zod_openapi.z.string().url().openapi({
+    example: "https://api.example.com/problems/validation-error",
+    description: "A URI reference that identifies the problem type"
+  }),
+  title: import_zod_openapi.z.string().openapi({
+    example: "Validation Failed",
+    description: "A short, human-readable summary of the problem type"
+  }),
+  status: import_zod_openapi.z.number().int().min(400).max(599).openapi({
+    example: 400,
+    description: "The HTTP status code"
+  }),
+  detail: import_zod_openapi.z.string().optional().openapi({
+    example: "The request contains invalid fields",
+    description: "A human-readable explanation specific to this occurrence of the problem"
+  }),
+  instance: import_zod_openapi.z.string().url().optional().openapi({
+    example: "urn:uuid:6b56944d-5e89-4b4d-9ca7-c1be3d1f0e3f",
+    description: "A URI reference that identifies the specific occurrence of the problem"
+  }),
+  timestamp: import_zod_openapi.z.string().datetime().optional().openapi({
+    example: "2025-02-26T12:34:56.789Z",
+    description: "When the error occurred"
+  })
+}).merge(RFC7807ErrorDataSchema);
 
 // src/formatters/rfc7807/formatter.ts
 function createRFC7807Formatter(options = {}) {
@@ -320,37 +356,37 @@ function createRFC7807Formatter(options = {}) {
         timestamp: new Date().toISOString()
       };
       if (error.data?.["invalid-params"]) {
-        return ProblemDetailsSchema.parse({
+        return RFC7807DetailsSchema.parse({
           ...base,
           "invalid-params": error.data["invalid-params"]
         });
       }
       if (error.data?.violations) {
-        return ProblemDetailsSchema.parse({
+        return RFC7807DetailsSchema.parse({
           ...base,
           violations: error.data.violations
         });
       }
-      return ProblemDetailsSchema.parse(base);
+      return RFC7807DetailsSchema.parse(base);
     }
   };
 }
-function createValidationError(params) {
+function createRFC7807ValidationError(params) {
   return {
-    "invalid-params": ValidationParamSchema.array().parse(params)
+    "invalid-params": RFC7807ValidationParamSchema.array().parse(params)
   };
 }
-function createZodValidationError(error) {
+function createRFC7807ZodValidationError(error) {
   return {
-    "invalid-params": ValidationParamSchema.array().parse(error.errors.map((e) => ({
+    "invalid-params": RFC7807ValidationParamSchema.array().parse(error.errors.map((e) => ({
       name: e.path.join("."),
       reason: e.message
     })))
   };
 }
-function createConstraintViolation(name, reason, resource, constraint = "unique") {
+function createRFC7807ConstraintViolation(name, reason, resource, constraint = "unique") {
   return {
-    violations: ConstraintViolationSchema.array().parse([
+    violations: RFC7807ConstraintViolationSchema.array().parse([
       {
         name,
         reason,
@@ -4353,14 +4389,17 @@ function badImplementation(messageOrOptions, options) {
 
 // src/formatters/rfc7807/hooks.ts
 function createRFC7807Hook(options) {
-  const formatter = createRFC7807Formatter(options);
   return (result, c) => {
     if (!result.success && "error" in result && result.error instanceof ZodError) {
-      const error = badRequest("Validation Error", {
-        data: createZodValidationError(result.error)
+      const validationData = createRFC7807ZodValidationError(result.error);
+      throw badRequest({
+        message: options?.message || "Validation Error",
+        data: validationData,
+        formatter: options?.formatter,
+        headers: options?.headers,
+        sanitize: options?.sanitize,
+        includeStackTrace: options?.includeStackTrace
       });
-      const formatted = formatError(error, formatter);
-      return createErrorResponse(error, formatted);
     }
   };
 }

package/dist/esm/index.js

@@ -189,28 +189,64 @@ var defaultFormatter = {
 
 // src/formatters/rfc7807/schemas.ts
 import { z } from "@hono/zod-openapi";
-var ValidationParamSchema = z.object({
-  name: z.string(),
-  reason: z.string()
-}).openapi("ValidationParam");
-var ConstraintViolationSchema = z.object({
-  name: z.string(),
-  reason: z.string(),
-  resource: z.string(),
-  constraint: z.string()
-}).openapi("ConstraintViolation");
-var ProblemErrorDataSchema = z.object({
-  "invalid-params": z.array(ValidationParamSchema).optional(),
-  violations: z.array(ConstraintViolationSchema).optional()
+var RFC7807ValidationParamSchema = z.object({
+  name: z.string().openapi({
+    example: "username",
+    description: "The field name that failed validation"
+  }),
+  reason: z.string().openapi({
+    example: "String must contain at least 3 character(s)",
+    description: "The reason for validation failure"
+  })
 });
-var ProblemDetailsSchema = z.object({
-  type: z.string().url(),
-  title: z.string(),
-  status: z.number().int().min(400).max(599),
-  detail: z.string(),
-  instance: z.string(),
-  timestamp: z.string().datetime()
-}).merge(ProblemErrorDataSchema).openapi("ProblemDetails");
+var RFC7807ConstraintViolationSchema = z.object({
+  name: z.string().openapi({
+    example: "email",
+    description: "The field name that violated a constraint"
+  }),
+  reason: z.string().openapi({
+    example: "Email already exists",
+    description: "The reason for the constraint violation"
+  }),
+  resource: z.string().openapi({
+    example: "user",
+    description: "The resource type that contains the constraint"
+  }),
+  constraint: z.string().openapi({
+    example: "unique",
+    description: "The type of constraint that was violated"
+  })
+});
+var RFC7807ErrorDataSchema = z.object({
+  "invalid-params": z.array(RFC7807ValidationParamSchema).optional(),
+  violations: z.array(RFC7807ConstraintViolationSchema).optional()
+});
+var RFC7807DetailsSchema = z.object({
+  type: z.string().url().openapi({
+    example: "https://api.example.com/problems/validation-error",
+    description: "A URI reference that identifies the problem type"
+  }),
+  title: z.string().openapi({
+    example: "Validation Failed",
+    description: "A short, human-readable summary of the problem type"
+  }),
+  status: z.number().int().min(400).max(599).openapi({
+    example: 400,
+    description: "The HTTP status code"
+  }),
+  detail: z.string().optional().openapi({
+    example: "The request contains invalid fields",
+    description: "A human-readable explanation specific to this occurrence of the problem"
+  }),
+  instance: z.string().url().optional().openapi({
+    example: "urn:uuid:6b56944d-5e89-4b4d-9ca7-c1be3d1f0e3f",
+    description: "A URI reference that identifies the specific occurrence of the problem"
+  }),
+  timestamp: z.string().datetime().optional().openapi({
+    example: "2025-02-26T12:34:56.789Z",
+    description: "When the error occurred"
+  })
+}).merge(RFC7807ErrorDataSchema);
 
 // src/formatters/rfc7807/formatter.ts
 function createRFC7807Formatter(options = {}) {
@@ -227,37 +263,37 @@ function createRFC7807Formatter(options = {}) {
         timestamp: new Date().toISOString()
       };
       if (error.data?.["invalid-params"]) {
-        return ProblemDetailsSchema.parse({
+        return RFC7807DetailsSchema.parse({
           ...base,
           "invalid-params": error.data["invalid-params"]
         });
       }
       if (error.data?.violations) {
-        return ProblemDetailsSchema.parse({
+        return RFC7807DetailsSchema.parse({
           ...base,
           violations: error.data.violations
         });
       }
-      return ProblemDetailsSchema.parse(base);
+      return RFC7807DetailsSchema.parse(base);
     }
   };
 }
-function createValidationError(params) {
+function createRFC7807ValidationError(params) {
   return {
-    "invalid-params": ValidationParamSchema.array().parse(params)
+    "invalid-params": RFC7807ValidationParamSchema.array().parse(params)
   };
 }
-function createZodValidationError(error) {
+function createRFC7807ZodValidationError(error) {
   return {
-    "invalid-params": ValidationParamSchema.array().parse(error.errors.map((e) => ({
+    "invalid-params": RFC7807ValidationParamSchema.array().parse(error.errors.map((e) => ({
       name: e.path.join("."),
       reason: e.message
     })))
   };
 }
-function createConstraintViolation(name, reason, resource, constraint = "unique") {
+function createRFC7807ConstraintViolation(name, reason, resource, constraint = "unique") {
   return {
-    violations: ConstraintViolationSchema.array().parse([
+    violations: RFC7807ConstraintViolationSchema.array().parse([
       {
         name,
         reason,
@@ -4260,14 +4296,17 @@ function badImplementation(messageOrOptions, options) {
 
 // src/formatters/rfc7807/hooks.ts
 function createRFC7807Hook(options) {
-  const formatter = createRFC7807Formatter(options);
   return (result, c) => {
     if (!result.success && "error" in result && result.error instanceof ZodError) {
-      const error = badRequest("Validation Error", {
-        data: createZodValidationError(result.error)
+      const validationData = createRFC7807ZodValidationError(result.error);
+      throw badRequest({
+        message: options?.message || "Validation Error",
+        data: validationData,
+        formatter: options?.formatter,
+        headers: options?.headers,
+        sanitize: options?.sanitize,
+        includeStackTrace: options?.includeStackTrace
       });
-      const formatted = formatError(error, formatter);
-      return createErrorResponse(error, formatted);
     }
   };
 }
@@ -4353,13 +4392,13 @@ export {
   entityTooLarge,
   defaultFormatter,
   src_default as default,
-  createZodValidationError,
-  createValidationError,
+  createRFC7807ZodValidationError,
+  createRFC7807ValidationError,
   createRFC7807Hook,
   createRFC7807Formatter,
+  createRFC7807ConstraintViolation,
   createErrorResponse,
   createError,
-  createConstraintViolation,
   convertToBanError,
   conflict,
   clientTimeout,
@@ -4367,9 +4406,9 @@ export {
   badImplementation,
   badGateway,
   badData,
-  ValidationParamSchema,
   STATUS_CODES,
-  ProblemErrorDataSchema,
-  ProblemDetailsSchema,
-  ConstraintViolationSchema
+  RFC7807ValidationParamSchema,
+  RFC7807ErrorDataSchema,
+  RFC7807DetailsSchema,
+  RFC7807ConstraintViolationSchema
 };

package/dist/types/formatters/rfc7807/formatter.d.ts

@@ -4,7 +4,7 @@
  */
 import { z } from "@hono/zod-openapi";
 import type { ErrorFormatter } from "../../types";
-import type { ValidationParam, RFC7807FormatterOptions as RFC7807Options } from "../../types";
+import type { RFC7807ValidationParam, RFC7807FormatterOptions as RFC7807Options } from "../../types";
 /**
  * Create an RFC 7807 Problem Details formatter
  */
@@ -12,7 +12,7 @@ export declare function createRFC7807Formatter(options?: RFC7807Options): ErrorF
 /**
  * Create validation error data in RFC 7807 format
  */
-export declare function createValidationError(params: ValidationParam[]): {
+export declare function createRFC7807ValidationError(params: RFC7807ValidationParam[]): {
     "invalid-params": {
         name: string;
         reason: string;
@@ -21,7 +21,7 @@ export declare function createValidationError(params: ValidationParam[]): {
 /**
  * Convert Zod validation errors to RFC 7807 format
  */
-export declare function createZodValidationError(error: z.ZodError): {
+export declare function createRFC7807ZodValidationError(error: z.ZodError): {
     "invalid-params": {
         name: string;
         reason: string;
@@ -30,7 +30,7 @@ export declare function createZodValidationError(error: z.ZodError): {
 /**
  * Create constraint violation data in RFC 7807 format
  */
-export declare function createConstraintViolation(name: string, reason: string, resource: string, constraint?: string): {
+export declare function createRFC7807ConstraintViolation(name: string, reason: string, resource: string, constraint?: string): {
     violations: {
         name: string;
         reason: string;

package/dist/types/formatters/rfc7807/hooks.d.ts

@@ -4,12 +4,37 @@
  */
 import { Hook } from "@hono/zod-openapi";
 import { Env } from "hono";
-import type { RFC7807FormatterOptions as RFC7807Options } from "../../types";
+import type { RFC7807FormatterOptions as RFC7807Options, BanOptions } from "../../types";
 /**
  * Create a Hono hook that formats validation errors using RFC 7807
+ *
+ * This hook throws a badRequest error that will be caught and processed by the ban middleware.
+ * You can provide options to override the default behavior of the middleware.
+ *
+ * @example
+ * // Basic usage - inherits all settings from middleware
+ * app.openapi(route, handler, { onError: createRFC7807Hook() });
+ *
+ * @example
+ * // With custom message
+ * app.openapi(route, handler, {
+ *   onError: createRFC7807Hook({ message: "Custom validation error" })
+ * });
+ *
+ * @example
+ * // With custom formatter and sanitization
+ * app.openapi(route, handler, {
+ *   onError: createRFC7807Hook({
+ *     formatter: customFormatter,
+ *     sanitize: ['password', 'token']
+ *   })
+ * });
  */
-export declare function createRFC7807Hook(options?: RFC7807Options): Hook<any, Env, any, any>;
+export declare function createRFC7807Hook<E extends Env = Env>(options?: RFC7807Options & Partial<BanOptions>): Hook<any, E, any, any>;
 /**
  * Pre-configured RFC 7807 hook with default options
+ *
+ * This is a convenience export that uses the default options.
+ * It will throw a badRequest error that will be caught and processed by the ban middleware.
  */
 export declare const rfc7807Hook: Hook<any, Env, any, any>;

package/dist/types/formatters/rfc7807/index.d.ts

@@ -2,6 +2,6 @@
  * RFC 7807 Problem Details implementation for Hono Ban
  * @module hono-ban/formatters/rfc7807
  */
-export { createRFC7807Formatter, createValidationError, createZodValidationError, createConstraintViolation, } from "./formatter";
+export { createRFC7807Formatter, createRFC7807ValidationError, createRFC7807ZodValidationError, createRFC7807ConstraintViolation, } from "./formatter";
 export { createRFC7807Hook, rfc7807Hook } from "./hooks";
-export { ValidationParamSchema, ConstraintViolationSchema, ProblemErrorDataSchema, ProblemDetailsSchema, } from "./schemas";
+export { RFC7807ValidationParamSchema, RFC7807ConstraintViolationSchema, RFC7807ErrorDataSchema, RFC7807DetailsSchema, } from "./schemas";

package/dist/types/formatters/rfc7807/schemas.d.ts

@@ -4,9 +4,9 @@
  */
 import { z } from "@hono/zod-openapi";
 /**
- * Schema for validation error parameters
+ * Schema for RFC 7807 validation error parameters
  */
-export declare const ValidationParamSchema: z.ZodObject<{
+export declare const RFC7807ValidationParamSchema: z.ZodObject<{
     name: z.ZodString;
     reason: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -17,9 +17,9 @@ export declare const ValidationParamSchema: z.ZodObject<{
     reason: string;
 }>;
 /**
- * Schema for constraint violations
+ * Schema for RFC 7807 constraint violations
  */
-export declare const ConstraintViolationSchema: z.ZodObject<{
+export declare const RFC7807ConstraintViolationSchema: z.ZodObject<{
     name: z.ZodString;
     reason: z.ZodString;
     resource: z.ZodString;
@@ -36,9 +36,9 @@ export declare const ConstraintViolationSchema: z.ZodObject<{
     constraint: string;
 }>;
 /**
- * Schema for additional error data in problem details
+ * Schema for additional error data in RFC 7807 problem details
  */
-export declare const ProblemErrorDataSchema: z.ZodObject<{
+export declare const RFC7807ErrorDataSchema: z.ZodObject<{
     "invalid-params": z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         reason: z.ZodString;
@@ -91,13 +91,13 @@ export declare const ProblemErrorDataSchema: z.ZodObject<{
 /**
  * Schema for complete RFC 7807 problem details
  */
-export declare const ProblemDetailsSchema: z.ZodObject<z.objectUtil.extendShape<{
+export declare const RFC7807DetailsSchema: z.ZodObject<z.objectUtil.extendShape<{
     type: z.ZodString;
     title: z.ZodString;
     status: z.ZodNumber;
-    detail: z.ZodString;
-    instance: z.ZodString;
-    timestamp: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    instance: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodOptional<z.ZodString>;
 }, {
     "invalid-params": z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -129,9 +129,6 @@ export declare const ProblemDetailsSchema: z.ZodObject<z.objectUtil.extendShape<
     type: string;
     title: string;
     status: number;
-    detail: string;
-    instance: string;
-    timestamp: string;
     "invalid-params"?: {
         name: string;
         reason: string;
@@ -142,13 +139,13 @@ export declare const ProblemDetailsSchema: z.ZodObject<z.objectUtil.extendShape<
         resource: string;
         constraint: string;
     }[] | undefined;
+    detail?: string | undefined;
+    instance?: string | undefined;
+    timestamp?: string | undefined;
 }, {
     type: string;
     title: string;
     status: number;
-    detail: string;
-    instance: string;
-    timestamp: string;
     "invalid-params"?: {
         name: string;
         reason: string;
@@ -159,4 +156,7 @@ export declare const ProblemDetailsSchema: z.ZodObject<z.objectUtil.extendShape<
         resource: string;
         constraint: string;
     }[] | undefined;
+    detail?: string | undefined;
+    instance?: string | undefined;
+    timestamp?: string | undefined;
 }>;

package/dist/types/types/rfc7807.d.ts

@@ -8,87 +8,70 @@
  * @module hono-ban/types/rfc7807
  * @see {@link https://datatracker.ietf.org/doc/html/rfc7807} RFC 7807 Problem Details
  */
+import { z } from "@hono/zod-openapi";
+import { RFC7807ValidationParamSchema, RFC7807ConstraintViolationSchema, RFC7807ErrorDataSchema, RFC7807DetailsSchema } from "../formatters/rfc7807/schemas";
 /**
  * Represents a validation error parameter in an RFC 7807 problem details object.
  * Used to indicate specific validation failures in request parameters.
  *
- * @interface ValidationParam
+ * @type RFC7807ValidationParam
  * @property {string} name - The name of the parameter that failed validation
  * @property {string} reason - The reason why the parameter failed validation
  */
-export interface ValidationParam {
-    name: string;
-    reason: string;
-}
+export type RFC7807ValidationParam = z.infer<typeof RFC7807ValidationParamSchema>;
 /**
  * Represents a constraint violation in an RFC 7807 problem details object.
  * Used to indicate violations of business rules or data constraints.
  *
- * @interface ConstraintViolation
+ * @type RFC7807ConstraintViolation
  * @property {string} name - The name of the violated constraint
  * @property {string} reason - The reason why the constraint was violated
  * @property {string} resource - The resource or entity where the violation occurred
  * @property {string} constraint - The specific constraint that was violated
  */
-export interface ConstraintViolation {
-    name: string;
-    reason: string;
-    resource: string;
-    constraint: string;
-}
+export type RFC7807ConstraintViolation = z.infer<typeof RFC7807ConstraintViolationSchema>;
 /**
  * Additional error data that can be included in an RFC 7807 problem details object.
  * This interface extends the standard problem details with validation and constraint information.
  *
- * @interface ProblemErrorData
- * @property {ValidationParam[]} [invalid-params] - Array of validation errors
- * @property {ConstraintViolation[]} [violations] - Array of constraint violations
+ * @type RFC7807ErrorData
+ * @property {RFC7807ValidationParam[]} [invalid-params] - Array of validation errors
+ * @property {RFC7807ConstraintViolation[]} [violations] - Array of constraint violations
  */
-export interface ProblemErrorData {
-    "invalid-params"?: ValidationParam[];
-    violations?: ConstraintViolation[];
-}
+export type RFC7807ErrorData = z.infer<typeof RFC7807ErrorDataSchema>;
 /**
  * Complete RFC 7807 problem details object structure.
  * This interface represents the full problem details format as defined in RFC 7807,
  * with additional properties for validation and constraint violation data.
  *
- * @interface ProblemDetails
- * @extends ProblemErrorData
+ * @type RFC7807Details
  * @property {string} type - URI reference that identifies the problem type
  * @property {string} title - Short, human-readable summary of the problem
  * @property {number} status - HTTP status code (400-599)
- * @property {string} detail - Human-readable explanation specific to this occurrence
- * @property {string} instance - URI reference that identifies the specific occurrence
- * @property {string} timestamp - ISO 8601 datetime when the error occurred
+ * @property {string} [detail] - Human-readable explanation specific to this occurrence
+ * @property {string} [instance] - URI reference that identifies the specific occurrence
+ * @property {string} [timestamp] - ISO 8601 datetime when the error occurred
  */
-export interface ProblemDetails extends ProblemErrorData {
-    type: string;
-    title: string;
-    status: number;
-    detail: string;
-    instance: string;
-    timestamp: string;
-}
+export type RFC7807Details = z.infer<typeof RFC7807DetailsSchema>;
 /**
  * Hook function for customizing RFC 7807 problem details before formatting.
  * This type represents a function that can modify the problem details object
  * before it is serialized into the final response.
  *
- * @callback ProblemDetailsHook
- * @param {ProblemDetails} details - The problem details object to modify
- * @returns {ProblemDetails} The modified problem details object
+ * @callback RFC7807DetailsHook
+ * @param {RFC7807Details} details - The problem details object to modify
+ * @returns {RFC7807Details} The modified problem details object
  */
-export type ProblemDetailsHook = (details: ProblemDetails) => ProblemDetails;
+export type RFC7807DetailsHook = (details: RFC7807Details) => RFC7807Details;
 /**
  * Configuration options for the RFC 7807 formatter.
  * These options control how problem details are generated and formatted.
  *
  * @interface RFC7807FormatterOptions
  * @property {string} [baseUrl="https://api.example.com/problems"] - Base URL for problem type URIs
- * @property {ProblemDetailsHook[]} [hooks=[]] - Array of hooks for customizing problem details
+ * @property {RFC7807DetailsHook[]} [hooks=[]] - Array of hooks for customizing problem details
  */
 export interface RFC7807FormatterOptions {
     baseUrl?: string;
-    hooks?: ProblemDetailsHook[];
+    hooks?: RFC7807DetailsHook[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-ban",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "HTTP-friendly error objects for Hono, inspired by Boom",
   "type": "module",
   "main": "dist/cjs/index.js",

package/src/formatters/rfc7807/formatter.ts

@@ -7,15 +7,15 @@ import { z } from "@hono/zod-openapi";
 import { STATUS_CODES } from "../../constants";
 import type { BanError, ErrorFormatter } from "../../types";
 import type {
-  ProblemDetails,
-  ProblemErrorData,
-  ValidationParam,
+  RFC7807Details,
+  RFC7807ErrorData,
+  RFC7807ValidationParam,
   RFC7807FormatterOptions as RFC7807Options,
 } from "../../types";
 import {
-  ConstraintViolationSchema,
-  ProblemDetailsSchema,
-  ValidationParamSchema,
+  RFC7807ConstraintViolationSchema,
+  RFC7807DetailsSchema,
+  RFC7807ValidationParamSchema,
 } from "./schemas";
 
 /**
@@ -29,7 +29,7 @@ export function createRFC7807Formatter(
   return {
     contentType: "application/problem+json",
 
-    format<T extends ProblemErrorData>(error: BanError<T>): ProblemDetails {
+    format<T extends RFC7807ErrorData>(error: BanError<T>): RFC7807Details {
       const base = {
         type: `${baseUrl}/${error.status}`,
         title: STATUS_CODES[error.status] || "Unknown Error",
@@ -41,7 +41,7 @@ export function createRFC7807Formatter(
 
       // Handle validation errors
       if (error.data?.["invalid-params"]) {
-        return ProblemDetailsSchema.parse({
+        return RFC7807DetailsSchema.parse({
           ...base,
           "invalid-params": error.data["invalid-params"],
         });
@@ -49,13 +49,13 @@ export function createRFC7807Formatter(
 
       // Handle constraint violations
       if (error.data?.violations) {
-        return ProblemDetailsSchema.parse({
+        return RFC7807DetailsSchema.parse({
           ...base,
           violations: error.data.violations,
         });
       }
 
-      return ProblemDetailsSchema.parse(base);
+      return RFC7807DetailsSchema.parse(base);
     },
   };
 }
@@ -63,18 +63,18 @@ export function createRFC7807Formatter(
 /**
  * Create validation error data in RFC 7807 format
  */
-export function createValidationError(params: ValidationParam[]) {
+export function createRFC7807ValidationError(params: RFC7807ValidationParam[]) {
   return {
-    "invalid-params": ValidationParamSchema.array().parse(params),
+    "invalid-params": RFC7807ValidationParamSchema.array().parse(params),
   };
 }
 
 /**
  * Convert Zod validation errors to RFC 7807 format
  */
-export function createZodValidationError(error: z.ZodError) {
+export function createRFC7807ZodValidationError(error: z.ZodError) {
   return {
-    "invalid-params": ValidationParamSchema.array().parse(
+    "invalid-params": RFC7807ValidationParamSchema.array().parse(
       error.errors.map((e) => ({
         name: e.path.join("."),
         reason: e.message,
@@ -86,14 +86,14 @@ export function createZodValidationError(error: z.ZodError) {
 /**
  * Create constraint violation data in RFC 7807 format
  */
-export function createConstraintViolation(
+export function createRFC7807ConstraintViolation(
   name: string,
   reason: string,
   resource: string,
   constraint: string = "unique"
 ) {
   return {
-    violations: ConstraintViolationSchema.array().parse([
+    violations: RFC7807ConstraintViolationSchema.array().parse([
       {
         name,
         reason,

package/src/formatters/rfc7807/hooks.ts

@@ -7,41 +7,67 @@ import { ZodError } from "zod";
 import { Hook } from "@hono/zod-openapi";
 import { Env } from "hono";
 import { badRequest } from "../../factories";
-import { formatError, createErrorResponse } from "../../core";
-import type { RFC7807FormatterOptions as RFC7807Options } from "../../types";
-
-import { createRFC7807Formatter } from "./formatter";
-import { createZodValidationError } from "./formatter";
+import type {
+  RFC7807FormatterOptions as RFC7807Options,
+  BanOptions,
+} from "../../types";
+import { createRFC7807ZodValidationError } from "./formatter";
 
 /**
  * Create a Hono hook that formats validation errors using RFC 7807
+ *
+ * This hook throws a badRequest error that will be caught and processed by the ban middleware.
+ * You can provide options to override the default behavior of the middleware.
+ *
+ * @example
+ * // Basic usage - inherits all settings from middleware
+ * app.openapi(route, handler, { onError: createRFC7807Hook() });
+ *
+ * @example
+ * // With custom message
+ * app.openapi(route, handler, {
+ *   onError: createRFC7807Hook({ message: "Custom validation error" })
+ * });
+ *
+ * @example
+ * // With custom formatter and sanitization
+ * app.openapi(route, handler, {
+ *   onError: createRFC7807Hook({
+ *     formatter: customFormatter,
+ *     sanitize: ['password', 'token']
+ *   })
+ * });
  */
-export function createRFC7807Hook(
-  options?: RFC7807Options
-): Hook<any, Env, any, any> {
-  const formatter = createRFC7807Formatter(options);
-
+export function createRFC7807Hook<E extends Env = Env>(
+  options?: RFC7807Options & Partial<BanOptions>
+): Hook<any, E, any, any> {
   return (result, c) => {
     if (
       !result.success &&
       "error" in result &&
       result.error instanceof ZodError
     ) {
-      // Create the error
-      const error = badRequest("Validation Error", {
-        data: createZodValidationError(result.error),
-      });
+      // Create the validation error data
+      const validationData = createRFC7807ZodValidationError(result.error);
 
-      // Format the error using RFC7807
-      const formatted = formatError(error, formatter);
-
-      // Create and return the response
-      return createErrorResponse(error, formatted);
+      // Throw badRequest with both the validation data and any override options
+      throw badRequest({
+        message: options?.message || "Validation Error",
+        data: validationData,
+        // Pass through any override options
+        formatter: options?.formatter,
+        headers: options?.headers,
+        sanitize: options?.sanitize,
+        includeStackTrace: options?.includeStackTrace,
+      });
     }
   };
 }
 
 /**
  * Pre-configured RFC 7807 hook with default options
+ *
+ * This is a convenience export that uses the default options.
+ * It will throw a badRequest error that will be caught and processed by the ban middleware.
  */
-export const rfc7807Hook = createRFC7807Hook();
+export const rfc7807Hook = createRFC7807Hook<Env>();

package/src/formatters/rfc7807/index.ts

@@ -5,16 +5,16 @@
 
 export {
   createRFC7807Formatter,
-  createValidationError,
-  createZodValidationError,
-  createConstraintViolation,
+  createRFC7807ValidationError,
+  createRFC7807ZodValidationError,
+  createRFC7807ConstraintViolation,
 } from "./formatter";
 
 export { createRFC7807Hook, rfc7807Hook } from "./hooks";
 
 export {
-  ValidationParamSchema,
-  ConstraintViolationSchema,
-  ProblemErrorDataSchema,
-  ProblemDetailsSchema,
+  RFC7807ValidationParamSchema,
+  RFC7807ConstraintViolationSchema,
+  RFC7807ErrorDataSchema,
+  RFC7807DetailsSchema,
 } from "./schemas";

package/src/formatters/rfc7807/schemas.ts

@@ -4,54 +4,85 @@
  */
 
 import { z } from "@hono/zod-openapi";
-import type {
-  ValidationParam,
-  ConstraintViolation,
-  ProblemDetails,
-  ProblemErrorData,
-} from "../../types";
 
 /**
- * Schema for validation error parameters
+ * Schema for RFC 7807 validation error parameters
  */
-export const ValidationParamSchema = z
-  .object({
-    name: z.string(),
-    reason: z.string(),
-  })
-  .openapi("ValidationParam");
+export const RFC7807ValidationParamSchema = z.object({
+  name: z.string().openapi({
+    example: "username",
+    description: "The field name that failed validation",
+  }),
+  reason: z.string().openapi({
+    example: "String must contain at least 3 character(s)",
+    description: "The reason for validation failure",
+  }),
+});
 
 /**
- * Schema for constraint violations
+ * Schema for RFC 7807 constraint violations
  */
-export const ConstraintViolationSchema = z
-  .object({
-    name: z.string(),
-    reason: z.string(),
-    resource: z.string(),
-    constraint: z.string(),
-  })
-  .openapi("ConstraintViolation");
+export const RFC7807ConstraintViolationSchema = z.object({
+  name: z.string().openapi({
+    example: "email",
+    description: "The field name that violated a constraint",
+  }),
+  reason: z.string().openapi({
+    example: "Email already exists",
+    description: "The reason for the constraint violation",
+  }),
+  resource: z.string().openapi({
+    example: "user",
+    description: "The resource type that contains the constraint",
+  }),
+  constraint: z.string().openapi({
+    example: "unique",
+    description: "The type of constraint that was violated",
+  }),
+});
 
 /**
- * Schema for additional error data in problem details
+ * Schema for additional error data in RFC 7807 problem details
  */
-export const ProblemErrorDataSchema = z.object({
-  "invalid-params": z.array(ValidationParamSchema).optional(),
-  violations: z.array(ConstraintViolationSchema).optional(),
+export const RFC7807ErrorDataSchema = z.object({
+  "invalid-params": z.array(RFC7807ValidationParamSchema).optional(),
+  violations: z.array(RFC7807ConstraintViolationSchema).optional(),
 });
 
 /**
  * Schema for complete RFC 7807 problem details
  */
-export const ProblemDetailsSchema = z
+export const RFC7807DetailsSchema = z
   .object({
-    type: z.string().url(),
-    title: z.string(),
-    status: z.number().int().min(400).max(599),
-    detail: z.string(),
-    instance: z.string(),
-    timestamp: z.string().datetime(),
+    type: z.string().url().openapi({
+      example: "https://api.example.com/problems/validation-error",
+      description: "A URI reference that identifies the problem type",
+    }),
+    title: z.string().openapi({
+      example: "Validation Failed",
+      description: "A short, human-readable summary of the problem type",
+    }),
+    status: z.number().int().min(400).max(599).openapi({
+      example: 400,
+      description: "The HTTP status code",
+    }),
+
+    // Optional fields per RFC7807
+    detail: z.string().optional().openapi({
+      example: "The request contains invalid fields",
+      description:
+        "A human-readable explanation specific to this occurrence of the problem",
+    }),
+    instance: z.string().url().optional().openapi({
+      example: "urn:uuid:6b56944d-5e89-4b4d-9ca7-c1be3d1f0e3f",
+      description:
+        "A URI reference that identifies the specific occurrence of the problem",
+    }),
+
+    // Extensions for validation errors
+    timestamp: z.string().datetime().optional().openapi({
+      example: "2025-02-26T12:34:56.789Z",
+      description: "When the error occurred",
+    }),
   })
-  .merge(ProblemErrorDataSchema)
-  .openapi("ProblemDetails");
+  .merge(RFC7807ErrorDataSchema);

package/src/types/rfc7807.ts

@@ -9,82 +9,75 @@
  * @see {@link https://datatracker.ietf.org/doc/html/rfc7807} RFC 7807 Problem Details
  */
 
+import { z } from "@hono/zod-openapi";
+import {
+  RFC7807ValidationParamSchema,
+  RFC7807ConstraintViolationSchema,
+  RFC7807ErrorDataSchema,
+  RFC7807DetailsSchema,
+} from "../formatters/rfc7807/schemas";
+
 /**
  * Represents a validation error parameter in an RFC 7807 problem details object.
  * Used to indicate specific validation failures in request parameters.
  *
- * @interface ValidationParam
+ * @type RFC7807ValidationParam
  * @property {string} name - The name of the parameter that failed validation
  * @property {string} reason - The reason why the parameter failed validation
  */
-export interface ValidationParam {
-  name: string;
-  reason: string;
-}
+export type RFC7807ValidationParam = z.infer<
+  typeof RFC7807ValidationParamSchema
+>;
 
 /**
  * Represents a constraint violation in an RFC 7807 problem details object.
  * Used to indicate violations of business rules or data constraints.
  *
- * @interface ConstraintViolation
+ * @type RFC7807ConstraintViolation
  * @property {string} name - The name of the violated constraint
  * @property {string} reason - The reason why the constraint was violated
  * @property {string} resource - The resource or entity where the violation occurred
  * @property {string} constraint - The specific constraint that was violated
  */
-export interface ConstraintViolation {
-  name: string;
-  reason: string;
-  resource: string;
-  constraint: string;
-}
+export type RFC7807ConstraintViolation = z.infer<
+  typeof RFC7807ConstraintViolationSchema
+>;
 
 /**
  * Additional error data that can be included in an RFC 7807 problem details object.
  * This interface extends the standard problem details with validation and constraint information.
  *
- * @interface ProblemErrorData
- * @property {ValidationParam[]} [invalid-params] - Array of validation errors
- * @property {ConstraintViolation[]} [violations] - Array of constraint violations
+ * @type RFC7807ErrorData
+ * @property {RFC7807ValidationParam[]} [invalid-params] - Array of validation errors
+ * @property {RFC7807ConstraintViolation[]} [violations] - Array of constraint violations
  */
-export interface ProblemErrorData {
-  "invalid-params"?: ValidationParam[];
-  violations?: ConstraintViolation[];
-}
+export type RFC7807ErrorData = z.infer<typeof RFC7807ErrorDataSchema>;
 
 /**
  * Complete RFC 7807 problem details object structure.
  * This interface represents the full problem details format as defined in RFC 7807,
  * with additional properties for validation and constraint violation data.
  *
- * @interface ProblemDetails
- * @extends ProblemErrorData
+ * @type RFC7807Details
  * @property {string} type - URI reference that identifies the problem type
  * @property {string} title - Short, human-readable summary of the problem
  * @property {number} status - HTTP status code (400-599)
- * @property {string} detail - Human-readable explanation specific to this occurrence
- * @property {string} instance - URI reference that identifies the specific occurrence
- * @property {string} timestamp - ISO 8601 datetime when the error occurred
+ * @property {string} [detail] - Human-readable explanation specific to this occurrence
+ * @property {string} [instance] - URI reference that identifies the specific occurrence
+ * @property {string} [timestamp] - ISO 8601 datetime when the error occurred
  */
-export interface ProblemDetails extends ProblemErrorData {
-  type: string;
-  title: string;
-  status: number;
-  detail: string;
-  instance: string;
-  timestamp: string;
-}
+export type RFC7807Details = z.infer<typeof RFC7807DetailsSchema>;
 
 /**
  * Hook function for customizing RFC 7807 problem details before formatting.
  * This type represents a function that can modify the problem details object
  * before it is serialized into the final response.
  *
- * @callback ProblemDetailsHook
- * @param {ProblemDetails} details - The problem details object to modify
- * @returns {ProblemDetails} The modified problem details object
+ * @callback RFC7807DetailsHook
+ * @param {RFC7807Details} details - The problem details object to modify
+ * @returns {RFC7807Details} The modified problem details object
  */
-export type ProblemDetailsHook = (details: ProblemDetails) => ProblemDetails;
+export type RFC7807DetailsHook = (details: RFC7807Details) => RFC7807Details;
 
 /**
  * Configuration options for the RFC 7807 formatter.
@@ -92,9 +85,9 @@ export type ProblemDetailsHook = (details: ProblemDetails) => ProblemDetails;
  *
  * @interface RFC7807FormatterOptions
  * @property {string} [baseUrl="https://api.example.com/problems"] - Base URL for problem type URIs
- * @property {ProblemDetailsHook[]} [hooks=[]] - Array of hooks for customizing problem details
+ * @property {RFC7807DetailsHook[]} [hooks=[]] - Array of hooks for customizing problem details
  */
 export interface RFC7807FormatterOptions {
   baseUrl?: string;
-  hooks?: ProblemDetailsHook[];
+  hooks?: RFC7807DetailsHook[];
 }