@wthek/hono-middleware 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,12 +9,13 @@ _Built for applications powered by [http-error-kit][http-error-kit], this middle
9
9
  ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/skillnter/wthek-hono-middleware/main.yml)
10
10
  [![npm version](https://img.shields.io/npm/v/%40wthek%2Fhono-middleware?color=brightgreen)](https://www.npmjs.com/package/@wthek/hono-middleware)
11
11
  [![GitHub license](https://img.shields.io/github/license/skillnter/wthek-hono-middleware?color=brightgreen)](LICENSE)
12
+ ![NPM Type Definitions](https://img.shields.io/npm/types/%40wthek%2Fhono-middleware)
12
13
  [![GitHub Issues](https://img.shields.io/github/issues/Skillnter/wthek-hono-middleware)](https://github.com/Skillnter/wthek-hono-middleware/issues)
13
14
  ![npm](https://img.shields.io/npm/dy/%40wthek%2Fhono-middleware)
14
15
  [![Bundle Size](https://img.shields.io/bundlephobia/minzip/%40wthek%2Fhono-middleware)](https://bundlephobia.com/package/%40wthek%2Fhono-middleware)
15
16
  [![Codacy Badge](https://app.codacy.com/project/badge/Grade/453f3cdfa02749c9b4c506dbbf5e103a)](https://app.codacy.com/gh/Skillnter/wthek-hono-middleware/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
16
17
  [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/453f3cdfa02749c9b4c506dbbf5e103a)](https://app.codacy.com/gh/Skillnter/wthek-hono-middleware/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
17
- [![Socket Badge](https://socket.dev/api/badge/npm/package/@wthek/hono-middleware/1.0.0)](https://socket.dev/npm/package/@wthek/hono-middleware/overview/1.0.0)
18
+ [![Socket Badge](https://socket.dev/api/badge/npm/package/@wthek/hono-middleware/)](https://socket.dev/npm/package/@wthek/hono-middleware/overview/)
18
19
  [![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-121013?logo=github&logoColor=white)](https://skillnter.github.io/wthek-hono-middleware/)
19
20
  [![Github Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-30363D?&logo=GitHub-Sponsors&logoColor=EA4AAA)](https://github.com/sponsors/Skillnter)
20
21
  [![Open Collective](https://img.shields.io/badge/Open%20Collective-3385FF?logo=open-collective&logoColor=white)](https://opencollective.com/skillnter)
@@ -37,6 +38,7 @@ _Built for applications powered by [http-error-kit][http-error-kit], this middle
37
38
  - [Installation](#installation)
38
39
  - [Usage](#usage)
39
40
  - [Options](#options)
41
+ - [AI Agent Integration](#ai-agent-integration)
40
42
  - [Explore More WTHek Extensions](#explore-more-wthek-extensions)
41
43
  - [People](#people)
42
44
  - [Donations](#donations)
@@ -111,6 +113,17 @@ KitHttpErrorConfig.configureFormatter(
111
113
  );
112
114
  ```
113
115
 
116
+ ## AI Agent Integration
117
+
118
+ When building with AI coding assistants (Claude Code, Cursor, GitHub Copilot, Antigravity, Devin), add the following directive to your project's `.cursorrules`, `.github/copilot-instructions.md`, or system prompt:
119
+
120
+ ```markdown
121
+ ### Hono Error Handling Rule
122
+ - Always throw semantic error classes from `http-error-kit` (e.g., `BadRequestError`, `NotFoundError`, `UnauthorizedError`) inside Hono route handlers.
123
+ - In Hono setup, register `@wthek/hono-middleware`: `KitHonoMiddleware(app, { handleUnknownErrors: true })`.
124
+ - For scoped sub-routers or custom onError flows, use `app.onError(KitHonoErrorHandler({ handleUnknownErrors: true }))`.
125
+ ```
126
+
114
127
  ## Explore More WTHek Extensions
115
128
 
116
129
  The WTHek ecosystem continues to grow with new extensions to simplify error handling across various frameworks and libraries. Stay updated with the latest tools that integrate seamlessly with `http-error-kit`.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,14 @@
1
1
  import type { Context, ErrorHandler, Hono } from "hono";
2
2
  /**
3
3
  * Configuration options for KitHonoMiddleware and KitHonoErrorHandler.
4
+ *
5
+ * @example
6
+ * ```typescript
7
+ * const options: IKitHonoMiddlewareOptions = {
8
+ * log: true,
9
+ * handleUnknownErrors: true,
10
+ * };
11
+ * ```
4
12
  */
5
13
  export interface IKitHonoMiddlewareOptions {
6
14
  /**
package/llms.txt ADDED
@@ -0,0 +1,64 @@
1
+ # @wthek/hono-middleware
2
+
3
+ > Production-safe Hono error-handling middleware for `http-error-kit`.
4
+
5
+ ## Overview
6
+ `@wthek/hono-middleware` catches `KitHttpError` and `KitGeneralError` instances thrown in Hono routes and automatically responds with the matching HTTP status code and structured JSON error payload. It integrates with Hono's `app.onError()`, supports custom logging functions, and provides optional fallback handling for unknown exceptions.
7
+
8
+ ## Installation
9
+ ```bash
10
+ npm install @wthek/hono-middleware http-error-kit http-response-status-code
11
+ ```
12
+
13
+ ## Quick Start
14
+ ```typescript
15
+ import { Hono } from "hono";
16
+ import { KitHonoMiddleware } from "@wthek/hono-middleware";
17
+ import { BadRequestError, NotFoundError } from "http-error-kit";
18
+
19
+ const app = new Hono();
20
+
21
+ // Register global error handling middleware
22
+ KitHonoMiddleware(app, { log: true, handleUnknownErrors: true });
23
+
24
+ app.get("/api/users/:id", (c) => {
25
+ const id = c.req.param("id");
26
+ if (!id) {
27
+ throw new BadRequestError("User ID is required");
28
+ }
29
+ throw new NotFoundError("User not found");
30
+ });
31
+
32
+ export default app;
33
+ ```
34
+
35
+ ## Scoped Error Handler (`KitHonoErrorHandler`)
36
+ ```typescript
37
+ import { Hono } from "hono";
38
+ import { KitHonoErrorHandler } from "@wthek/hono-middleware";
39
+
40
+ const app = new Hono();
41
+
42
+ // Register directly via app.onError
43
+ app.onError(KitHonoErrorHandler({ log: true, handleUnknownErrors: true }));
44
+ ```
45
+
46
+ ## API Reference
47
+
48
+ ### `KitHonoMiddleware(app: Hono, options?: IKitHonoMiddlewareOptions)`
49
+ Registers `KitHonoErrorHandler` on the given Hono instance via `app.onError()`.
50
+
51
+ ### `KitHonoErrorHandler(options?: IKitHonoMiddlewareOptions)`
52
+ Returns a Hono-compatible error handler function: `(error: unknown, c: Context) => Response | Promise<Response>`.
53
+
54
+ #### Options (`IKitHonoMiddlewareOptions`)
55
+ - `log` (`boolean | ((error: unknown, c: Context) => void)`, default: `false`):
56
+ When `true`, logs via `console.error`. When a function is provided, calls custom logger callback.
57
+ - `handleUnknownErrors` (`boolean`, default: `false`):
58
+ When `true`, catches non-Kit errors and returns a structured 500 JSON response instead of plain text error message.
59
+
60
+ ## Safety Rules for AI Agents
61
+ 1. Register `KitHonoMiddleware(app)` during application setup before defining execution exports.
62
+ 2. Throw errors directly from `http-error-kit` (e.g., `throw new NotFoundError(...)`) inside route handlers.
63
+ 3. Hono automatically catches synchronous throws and rejected promises inside handlers and directs them to `onError`.
64
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
- {
1
+ {
2
2
  "name": "@wthek/hono-middleware",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Production-safe Hono error-handling middleware for http-error-kit. Maps KitHttpError instances to structured JSON responses with correct HTTP status codes and optional logging.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -37,6 +37,15 @@
37
37
  "status-codes",
38
38
  "api-error",
39
39
  "json-error",
40
+ "rfc-7807",
41
+ "rfc-9457",
42
+ "structured-errors",
43
+ "api-error-response",
44
+ "ai-agent",
45
+ "agent-skill",
46
+ "antigravity",
47
+ "cursor",
48
+ "copilot",
40
49
  "typescript",
41
50
  "middleware",
42
51
  "wthek",
@@ -52,8 +61,8 @@
52
61
  },
53
62
  "homepage": "https://github.com/Skillnter/wthek-hono-middleware#readme",
54
63
  "dependencies": {
55
- "http-error-kit": "^1.2.0",
56
- "http-response-status-code": "^1.8.0"
64
+ "http-error-kit": "^1.5.0",
65
+ "http-response-status-code": "^1.9.0"
57
66
  },
58
67
  "peerDependencies": {
59
68
  "hono": "^4.0.0"
@@ -77,6 +86,7 @@
77
86
  "files": [
78
87
  "dist/index.js",
79
88
  "dist/index.d.ts",
89
+ "llms.txt",
80
90
  "LICENSE"
81
91
  ],
82
92
  "funding": [