@wthek/koa-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 +14 -1
- package/dist/index.d.ts +9 -0
- package/llms.txt +56 -0
- package/package.json +13 -3
package/README.md
CHANGED
|
@@ -9,12 +9,13 @@ _Built for applications powered by [http-error-kit][http-error-kit], this middle
|
|
|
9
9
|

|
|
10
10
|
[](https://www.npmjs.com/package/@wthek/koa-middleware)
|
|
11
11
|
[](LICENSE)
|
|
12
|
+

|
|
12
13
|
[](https://github.com/Skillnter/wthek-koa-middleware/issues)
|
|
13
14
|

|
|
14
15
|
[](https://bundlephobia.com/package/%40wthek%2Fkoa-middleware)
|
|
15
16
|
[](https://app.codacy.com/gh/Skillnter/wthek-koa-middleware/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
|
|
16
17
|
[](https://app.codacy.com/gh/Skillnter/wthek-koa-middleware/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
|
|
17
|
-
[](https://socket.dev/npm/package/@wthek/koa-middleware/overview/)
|
|
18
19
|
[](https://github.com/sponsors/Skillnter)
|
|
19
20
|
[](https://opencollective.com/skillnter)
|
|
20
21
|
[](https://www.buymeacoffee.com/skillnter)
|
|
@@ -37,6 +38,7 @@ _Built for applications powered by [http-error-kit][http-error-kit], this middle
|
|
|
37
38
|
- [Usage](#usage)
|
|
38
39
|
- [Options](#options)
|
|
39
40
|
- [Custom Formatting with KitHttpErrorConfig](#custom-formatting-with-kithttperrorconfig)
|
|
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)
|
|
@@ -142,6 +144,17 @@ KitHttpErrorConfig.configureFormatter(
|
|
|
142
144
|
);
|
|
143
145
|
```
|
|
144
146
|
|
|
147
|
+
## AI Agent Integration
|
|
148
|
+
|
|
149
|
+
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:
|
|
150
|
+
|
|
151
|
+
```markdown
|
|
152
|
+
### Koa Error Handling Rule
|
|
153
|
+
- Always throw semantic error classes from `http-error-kit` (e.g., `BadRequestError`, `NotFoundError`, `UnauthorizedError`) inside downstream Koa middleware and routes.
|
|
154
|
+
- In Koa bootstrap, register `@wthek/koa-middleware` at the top of the middleware stack: `KitKoaMiddleware(app, { handleUnknownErrors: true })`.
|
|
155
|
+
- If using centralized monitoring (Sentry, Datadog), enable `emitAppError: true` so `app.on("error")` continues to receive errors.
|
|
156
|
+
```
|
|
157
|
+
|
|
145
158
|
## Explore More WTHek Extensions
|
|
146
159
|
|
|
147
160
|
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,15 @@
|
|
|
1
1
|
import type { Context, default as Koa, Middleware } from "koa";
|
|
2
2
|
/**
|
|
3
3
|
* Configuration options for KitKoaMiddleware.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```typescript
|
|
7
|
+
* const options: IKitKoaMiddlewareOptions = {
|
|
8
|
+
* log: true,
|
|
9
|
+
* handleUnknownErrors: true,
|
|
10
|
+
* emitAppError: true,
|
|
11
|
+
* };
|
|
12
|
+
* ```
|
|
4
13
|
*/
|
|
5
14
|
export interface IKitKoaMiddlewareOptions {
|
|
6
15
|
/**
|
package/llms.txt
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# @wthek/koa-middleware
|
|
2
|
+
|
|
3
|
+
> Production-safe Koa error-handling middleware for `http-error-kit`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
`@wthek/koa-middleware` catches `KitHttpError` and `KitGeneralError` instances thrown in Koa downstream middleware and routes, automatically setting the HTTP status code and serializing the error into a structured JSON payload. It respects Koa's onion architecture, guards against header-sent errors (`ctx.headerSent`), provides configurable logging, optionally emits Koa `error` events for central telemetry, and handles unknown exceptions.
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
```bash
|
|
10
|
+
npm install @wthek/koa-middleware http-error-kit http-response-status-code
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
```typescript
|
|
15
|
+
import Koa from "koa";
|
|
16
|
+
import { KitKoaMiddleware } from "@wthek/koa-middleware";
|
|
17
|
+
import { BadRequestError, NotFoundError } from "http-error-kit";
|
|
18
|
+
|
|
19
|
+
const app = new Koa();
|
|
20
|
+
|
|
21
|
+
// Pattern 1: Direct registration (app passed as first argument)
|
|
22
|
+
KitKoaMiddleware(app, { log: true, handleUnknownErrors: true, emitAppError: true });
|
|
23
|
+
|
|
24
|
+
// Pattern 2: Standard Koa app.use()
|
|
25
|
+
// app.use(KitKoaMiddleware({ log: true, handleUnknownErrors: true }));
|
|
26
|
+
|
|
27
|
+
app.use(async (ctx) => {
|
|
28
|
+
if (ctx.path === "/api/users") {
|
|
29
|
+
throw new BadRequestError("Query parameter missing");
|
|
30
|
+
}
|
|
31
|
+
throw new NotFoundError("Route not found");
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
app.listen(3000);
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## API Reference
|
|
38
|
+
|
|
39
|
+
### `KitKoaMiddleware(appOrOptions?: Koa | IKitKoaMiddlewareOptions, options?: IKitKoaMiddlewareOptions)`
|
|
40
|
+
Returns or registers a Koa middleware: `(ctx: Context, next: Next) => Promise<void>`.
|
|
41
|
+
- If a Koa app is passed as the first parameter, it calls `app.use()` automatically.
|
|
42
|
+
- Otherwise, returns standard middleware for `app.use(KitKoaMiddleware(options))`.
|
|
43
|
+
|
|
44
|
+
#### Options (`IKitKoaMiddlewareOptions`)
|
|
45
|
+
- `log` (`boolean | ((error: unknown, ctx: Context) => void)`, default: `false`):
|
|
46
|
+
When `true`, logs via `console.error`. When a function is provided, calls custom logger.
|
|
47
|
+
- `handleUnknownErrors` (`boolean`, default: `false`):
|
|
48
|
+
When `true`, catches non-Kit errors and assigns a structured 500 JSON response instead of re-throwing downstream.
|
|
49
|
+
- `emitAppError` (`boolean`, default: `false`):
|
|
50
|
+
When `true`, emits `ctx.app.emit("error", error, ctx)` for central error listeners (Sentry, Datadog).
|
|
51
|
+
|
|
52
|
+
## Safety Rules for AI Agents
|
|
53
|
+
1. Place `app.use(KitKoaMiddleware(...))` at the very beginning of the middleware pipeline to wrap all downstream handlers.
|
|
54
|
+
2. Throw errors directly from `http-error-kit` (e.g., `throw new NotFoundError(...)`) inside downstream handlers.
|
|
55
|
+
3. Koa async functions automatically catch thrown errors and return control up the onion stack.
|
|
56
|
+
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wthek/koa-middleware",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Production-safe Koa 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",
|
|
@@ -38,6 +38,15 @@
|
|
|
38
38
|
"status-codes",
|
|
39
39
|
"api-error",
|
|
40
40
|
"json-error",
|
|
41
|
+
"rfc-7807",
|
|
42
|
+
"rfc-9457",
|
|
43
|
+
"structured-errors",
|
|
44
|
+
"api-error-response",
|
|
45
|
+
"ai-agent",
|
|
46
|
+
"agent-skill",
|
|
47
|
+
"antigravity",
|
|
48
|
+
"cursor",
|
|
49
|
+
"copilot",
|
|
41
50
|
"typescript",
|
|
42
51
|
"middleware",
|
|
43
52
|
"wthek",
|
|
@@ -53,8 +62,8 @@
|
|
|
53
62
|
},
|
|
54
63
|
"homepage": "https://github.com/Skillnter/wthek-koa-middleware#readme",
|
|
55
64
|
"dependencies": {
|
|
56
|
-
"http-error-kit": "^1.
|
|
57
|
-
"http-response-status-code": "^1.
|
|
65
|
+
"http-error-kit": "^1.5.0",
|
|
66
|
+
"http-response-status-code": "^1.9.0"
|
|
58
67
|
},
|
|
59
68
|
"peerDependencies": {
|
|
60
69
|
"koa": "^2.0.0 || ^3.0.0"
|
|
@@ -81,6 +90,7 @@
|
|
|
81
90
|
"files": [
|
|
82
91
|
"dist/index.js",
|
|
83
92
|
"dist/index.d.ts",
|
|
93
|
+
"llms.txt",
|
|
84
94
|
"LICENSE"
|
|
85
95
|
],
|
|
86
96
|
"funding": [
|