hono-ban 0.2.0 → 0.2.4

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[];
 }