hono-ban 0.2.4 → 0.2.6

package/src/factories/server-errors.ts

@@ -1,230 +0,0 @@
-/**
- * Server error factory functions (5xx)
- * @module hono-ban/factories/server-errors
- */
-
-import type { BanError, BanOptions, ErrorStatusCode } from "../types";
-import { createError } from "../core";
-
-/**
- * Helper function to reduce duplication
- * @param statusCode - HTTP status code
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-function createErrorWithStatus<T>(
-  statusCode: ErrorStatusCode,
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  if (typeof messageOrOptions === "string") {
-    return createError<T>({
-      ...options,
-      statusCode,
-      message: messageOrOptions,
-    });
-  }
-  return createError<T>({ ...messageOrOptions, ...options, statusCode });
-}
-
-/**
- * Create a 500 Internal Server Error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function internal<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    500 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 501 Not Implemented error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function notImplemented<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    501 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 502 Bad Gateway error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function badGateway<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    502 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 503 Service Unavailable error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function serverUnavailable<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    503 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 504 Gateway Timeout error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function gatewayTimeout<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    504 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 505 HTTP Version Not Supported error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function httpVersionNotSupported<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    505 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 506 Variant Also Negotiates error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function variantAlsoNegotiates<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    506 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 507 Insufficient Storage error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function insufficientStorage<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    507 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 508 Loop Detected error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function loopDetected<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    508 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 510 Not Extended error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function notExtended<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    510 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 511 Network Authentication Required error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function networkAuthRequired<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  return createErrorWithStatus(
-    511 as ErrorStatusCode,
-    messageOrOptions,
-    options
-  );
-}
-
-/**
- * Create a 500 Internal Server Error marked as a developer error
- * @param messageOrOptions - Error message or options
- * @param options - Additional options
- */
-export function badImplementation<T = unknown>(
-  messageOrOptions?: string | Partial<BanOptions<T>>,
-  options?: Partial<BanOptions<T>>
-): BanError<T> {
-  const mergedOptions =
-    typeof messageOrOptions === "string"
-      ? { ...options, message: messageOrOptions }
-      : { ...messageOrOptions, ...options };
-
-  const mergedData = {
-    isDeveloperError: true,
-    ...((mergedOptions.data as Record<string, unknown>) || {}),
-  } as unknown as T;
-
-  return createError<T>({
-    ...mergedOptions,
-    statusCode: 500 as ErrorStatusCode,
-    data: mergedData,
-  });
-}

package/src/formatters/default/index.ts

@@ -1,72 +0,0 @@
-/**
- * Default error formatter implementation
- * @module hono-ban/formatters/default
- */
-
-import { STATUS_CODES } from "../../constants";
-import type { BanError, DefaultErrorOutput, Headers } from "../../types";
-import { sanitizeObject } from "../../utils";
-
-/**
- * Default JSON formatter maintaining backward compatibility
- */
-export const defaultFormatter = {
-  contentType: "application/json",
-
-  /**
-   * Format an error into a standardized output structure
-   * @param error - Error to format
-   * @param headers - Headers for HTTP response (not included in response body)
-   * @param sanitize - Fields to remove from output
-   * @param includeStackTrace - Whether to include stack traces
-   */
-  format(
-    error: BanError,
-    headers: Headers = {}, // Headers are used for HTTP headers, not included in response body
-    sanitize: readonly string[] = [],
-    includeStackTrace = false
-  ): DefaultErrorOutput {
-    const { status, message, data } = error;
-
-    // Build base payload
-    const payload: DefaultErrorOutput["payload"] = {
-      statusCode: status,
-      error: STATUS_CODES[status] || "Unknown Error",
-    };
-
-    // Add optional fields
-    if (typeof message === "string") {
-      payload.message = message;
-    }
-
-    const isDeveloperError =
-      data &&
-      typeof data === "object" &&
-      "isDeveloperError" in data &&
-      data.isDeveloperError === true;
-
-    if (includeStackTrace || isDeveloperError) {
-      if (error.stack) {
-        payload.stack = error.stack;
-      }
-      if (error.causeStack) {
-        payload.causeStack = error.causeStack;
-      }
-    }
-
-    if (data !== undefined) {
-      payload.data = data;
-    }
-
-    // Create output structure
-    const output: DefaultErrorOutput = {
-      statusCode: status,
-      payload: sanitizeObject(
-        payload,
-        sanitize
-      ) as DefaultErrorOutput["payload"],
-    };
-
-    return output;
-  },
-};

package/src/formatters/index.ts

@@ -1,13 +0,0 @@
-/**
- * Formatters exports
- * @module hono-ban/formatters
- */
-
-// Export formatter interfaces
-export * from "./interfaces";
-
-// Export default formatter
-export * from "./default";
-
-// Export RFC7807 formatter
-export * from "./rfc7807";

package/src/formatters/interfaces.ts

@@ -1,7 +0,0 @@
-/**
- * Formatter interfaces
- * @module hono-ban/formatters/interfaces
- */
-
-// Re-export formatter interfaces from types
-export { ErrorFormatter, DefaultErrorOutput } from "../types";

package/src/formatters/rfc7807/formatter.ts

@@ -1,105 +0,0 @@
-/**
- * RFC 7807 Problem Details formatter implementation
- * @module hono-ban/formatters/rfc7807/formatter
- */
-
-import { z } from "@hono/zod-openapi";
-import { STATUS_CODES } from "../../constants";
-import type { BanError, ErrorFormatter } from "../../types";
-import type {
-  RFC7807Details,
-  RFC7807ErrorData,
-  RFC7807ValidationParam,
-  RFC7807FormatterOptions as RFC7807Options,
-} from "../../types";
-import {
-  RFC7807ConstraintViolationSchema,
-  RFC7807DetailsSchema,
-  RFC7807ValidationParamSchema,
-} from "./schemas";
-
-/**
- * Create an RFC 7807 Problem Details formatter
- */
-export function createRFC7807Formatter(
-  options: RFC7807Options = {}
-): ErrorFormatter {
-  const baseUrl = options.baseUrl || "https://api.example.com/problems";
-
-  return {
-    contentType: "application/problem+json",
-
-    format<T extends RFC7807ErrorData>(error: BanError<T>): RFC7807Details {
-      const base = {
-        type: `${baseUrl}/${error.status}`,
-        title: STATUS_CODES[error.status] || "Unknown Error",
-        status: error.status,
-        detail: error.message,
-        instance: `urn:uuid:${crypto.randomUUID()}`,
-        timestamp: new Date().toISOString(),
-      };
-
-      // Handle validation errors
-      if (error.data?.["invalid-params"]) {
-        return RFC7807DetailsSchema.parse({
-          ...base,
-          "invalid-params": error.data["invalid-params"],
-        });
-      }
-
-      // Handle constraint violations
-      if (error.data?.violations) {
-        return RFC7807DetailsSchema.parse({
-          ...base,
-          violations: error.data.violations,
-        });
-      }
-
-      return RFC7807DetailsSchema.parse(base);
-    },
-  };
-}
-
-/**
- * Create validation error data in RFC 7807 format
- */
-export function createRFC7807ValidationError(params: RFC7807ValidationParam[]) {
-  return {
-    "invalid-params": RFC7807ValidationParamSchema.array().parse(params),
-  };
-}
-
-/**
- * Convert Zod validation errors to RFC 7807 format
- */
-export function createRFC7807ZodValidationError(error: z.ZodError) {
-  return {
-    "invalid-params": RFC7807ValidationParamSchema.array().parse(
-      error.errors.map((e) => ({
-        name: e.path.join("."),
-        reason: e.message,
-      }))
-    ),
-  };
-}
-
-/**
- * Create constraint violation data in RFC 7807 format
- */
-export function createRFC7807ConstraintViolation(
-  name: string,
-  reason: string,
-  resource: string,
-  constraint: string = "unique"
-) {
-  return {
-    violations: RFC7807ConstraintViolationSchema.array().parse([
-      {
-        name,
-        reason,
-        resource,
-        constraint,
-      },
-    ]),
-  };
-}

package/src/formatters/rfc7807/hooks.ts

@@ -1,73 +0,0 @@
-/**
- * RFC 7807 Problem Details hooks for Hono applications
- * @module hono-ban/formatters/rfc7807/hooks
- */
-
-import { ZodError } from "zod";
-import { Hook } from "@hono/zod-openapi";
-import { Env } from "hono";
-import { badRequest } from "../../factories";
-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<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 validation error data
-      const validationData = createRFC7807ZodValidationError(result.error);
-
-      // 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<Env>();

package/src/formatters/rfc7807/index.ts

@@ -1,20 +0,0 @@
-/**
- * RFC 7807 Problem Details implementation for Hono Ban
- * @module hono-ban/formatters/rfc7807
- */
-
-export {
-  createRFC7807Formatter,
-  createRFC7807ValidationError,
-  createRFC7807ZodValidationError,
-  createRFC7807ConstraintViolation,
-} from "./formatter";
-
-export { createRFC7807Hook, rfc7807Hook } from "./hooks";
-
-export {
-  RFC7807ValidationParamSchema,
-  RFC7807ConstraintViolationSchema,
-  RFC7807ErrorDataSchema,
-  RFC7807DetailsSchema,
-} from "./schemas";

package/src/formatters/rfc7807/schemas.ts

@@ -1,88 +0,0 @@
-/**
- * Zod schemas for RFC 7807 Problem Details
- * @module hono-ban/formatters/rfc7807/schemas
- */
-
-import { z } from "@hono/zod-openapi";
-
-/**
- * Schema for RFC 7807 validation error parameters
- */
-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 RFC 7807 constraint violations
- */
-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 RFC 7807 problem details
- */
-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 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",
-    }),
-
-    // 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(RFC7807ErrorDataSchema);

package/src/index.ts

@@ -1,23 +0,0 @@
-/**
- * Main entry point for hono-ban
- * @module hono-ban
- */
-
-// Export core functionality
-export * from "./core";
-
-// Export formatters
-export * from "./formatters";
-
-// Export error factories
-export * from "./factories";
-
-// Export constants
-export * from "./constants";
-
-// Export types
-export * from "./types";
-
-// Export middleware as default
-import { ban } from "./middleware";
-export default ban;