@wthek/error-handling 0.0.0-stage → 1.0.0-beta.2
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/LICENSE +22 -0
- package/README.md +246 -2
- package/dist/bin.d.ts +36 -0
- package/dist/bin.d.ts.map +1 -0
- package/dist/bin.js +127 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +67 -0
- package/dist/installer.d.ts +36 -0
- package/dist/installer.d.ts.map +1 -0
- package/dist/installer.js +139 -0
- package/dist/types.d.ts +25 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/package.json +101 -3
- package/plugin.json +11 -0
- package/skills/wthek-error-handling/SKILL.md +711 -0
- package/skills/wthek-error-handling/examples/express-zod.js +44 -0
- package/skills/wthek-error-handling/examples/express-zod.ts +51 -0
- package/skills/wthek-error-handling/examples/fastify-zod.js +40 -0
- package/skills/wthek-error-handling/examples/fastify-zod.ts +45 -0
- package/skills/wthek-error-handling/examples/hono-valibot.ts +42 -0
- package/skills/wthek-error-handling/examples/koa-typebox.ts +54 -0
- package/skills/wthek-error-handling/references/express.md +73 -0
- package/skills/wthek-error-handling/references/fastify.md +81 -0
- package/skills/wthek-error-handling/references/formatters.md +241 -0
- package/skills/wthek-error-handling/references/hono.md +151 -0
- package/skills/wthek-error-handling/references/koa.md +62 -0
- package/skills/wthek-error-handling/references/mcp.md +148 -0
- package/skills/wthek-error-handling/references/nestjs.md +84 -0
- package/skills/wthek-error-handling/references/restify.md +68 -0
- package/skills/wthek-error-handling/references/status-codes.md +181 -0
- package/skills/wthek-error-handling/references/typebox.md +74 -0
- package/skills/wthek-error-handling/references/valibot.md +202 -0
- package/skills/wthek-error-handling/references/zod.md +113 -0
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# TypeBox Error Transformation with @wthek
|
|
2
|
+
|
|
3
|
+
Guide for implementing `@wthek/typebox-transformer`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @wthek/typebox-transformer @sinclair/typebox http-error-kit http-response-status-code
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 1. Throwing Pattern (`KitTypeBoxTransformer`)
|
|
16
|
+
|
|
17
|
+
Transforms any TypeBox validation error into a `KitHttpError` and throws it. If the error is not a TypeBox error, it is re-thrown unchanged:
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { Type } from "@sinclair/typebox";
|
|
21
|
+
import { Value } from "@sinclair/typebox/value";
|
|
22
|
+
import { KitTypeBoxTransformer } from "@wthek/typebox-transformer";
|
|
23
|
+
|
|
24
|
+
const UserSchema = Type.Object({
|
|
25
|
+
name: Type.String(),
|
|
26
|
+
age: Type.Number({ minimum: 18 }),
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
try {
|
|
30
|
+
Value.Assert(UserSchema, { name: "Himanshu", age: 14 });
|
|
31
|
+
} catch (err: unknown) {
|
|
32
|
+
KitTypeBoxTransformer(err); // Throws KitHttpError with status 400 and issues
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 2. Non-Throwing Pattern (`fromTypeBoxError`)
|
|
39
|
+
|
|
40
|
+
Converts a TypeBox validation error into a `KitHttpError` instance or returns `null` if the error is not a recognized TypeBox error:
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
import { Type } from "@sinclair/typebox";
|
|
44
|
+
import { Value } from "@sinclair/typebox/value";
|
|
45
|
+
import { fromTypeBoxError } from "@wthek/typebox-transformer";
|
|
46
|
+
|
|
47
|
+
const errors = [...Value.Errors(UserSchema, payload)];
|
|
48
|
+
const kitError = fromTypeBoxError(errors);
|
|
49
|
+
|
|
50
|
+
if (kitError) {
|
|
51
|
+
// Pass to framework error handler or send response
|
|
52
|
+
return res.status(kitError.statusCode).json(kitError.toJSON());
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 3. Supported Input Shapes
|
|
59
|
+
|
|
60
|
+
`fromTypeBoxError` and `KitTypeBoxTransformer` seamlessly accept:
|
|
61
|
+
- `TypeBoxError` instances (including `AssertError` from `Value.Assert`)
|
|
62
|
+
- `ValueError[]` arrays (e.g. `[...Value.Errors(schema, data)]`)
|
|
63
|
+
- `ValueErrorIterator` iterators directly (e.g. `Value.Errors(schema, data)`)
|
|
64
|
+
- Single `ValueError` objects
|
|
65
|
+
- Objects with an `.errors` property containing `ValueError[]`
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 4. Configuration Options
|
|
70
|
+
|
|
71
|
+
| Option | Type | Default | Description |
|
|
72
|
+
| :--- | :--- | :--- | :--- |
|
|
73
|
+
| `message` | `string` | `"TypeBox Validation Failed"` | Custom error message for the transformed error. |
|
|
74
|
+
| `statusCode` | `number` | `400` | Custom HTTP status code to assign to the validation error. |
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Valibot Validation Integration with @wthek
|
|
2
|
+
|
|
3
|
+
Guide for `@wthek/valibot-transformer`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @wthek/valibot-transformer http-error-kit http-response-status-code
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
**Peer dependencies:** `valibot >= 1.0.0`, `http-error-kit >= 1.2.0`
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Dual Conversion APIs
|
|
18
|
+
|
|
19
|
+
### 1. `fromValiError(error, options?)` — Non-Throwing
|
|
20
|
+
|
|
21
|
+
Converts a `ValiError` into a `KitHttpError` instance or returns `null` if the error is not a `ValiError`:
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
import * as v from "valibot";
|
|
25
|
+
import { fromValiError } from "@wthek/valibot-transformer";
|
|
26
|
+
|
|
27
|
+
try {
|
|
28
|
+
v.parse(schema, input);
|
|
29
|
+
} catch (err: unknown) {
|
|
30
|
+
const kitError = fromValiError(err, {
|
|
31
|
+
message: "Invalid form input",
|
|
32
|
+
statusCode: 422,
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
if (kitError) {
|
|
36
|
+
return c.json(kitError, kitError.statusCode ?? 400);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
throw err;
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### 2. `KitValibotTransformer(error, options?)` — Throwing
|
|
44
|
+
|
|
45
|
+
Transforms any `ValiError` into a `KitHttpError` and throws it. Non-ValiErrors are re-thrown unchanged. Return type is `never`.
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
import * as v from "valibot";
|
|
49
|
+
import { KitValibotTransformer } from "@wthek/valibot-transformer";
|
|
50
|
+
import { UNPROCESSABLE_ENTITY } from "http-response-status-code";
|
|
51
|
+
|
|
52
|
+
try {
|
|
53
|
+
v.parse(schema, input);
|
|
54
|
+
} catch (err) {
|
|
55
|
+
KitValibotTransformer(err, {
|
|
56
|
+
message: "Validation failed",
|
|
57
|
+
statusCode: UNPROCESSABLE_ENTITY,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Options Reference
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
interface IKitValibotTransformerOptions {
|
|
68
|
+
message?: string; // Default: "Valibot Validation Failed"
|
|
69
|
+
statusCode?: number; // Default: 400
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Error Payload Structure
|
|
76
|
+
|
|
77
|
+
Valibot issues are preserved in `error.details.issues`:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"statusCode": 400,
|
|
82
|
+
"message": "Valibot Validation Failed",
|
|
83
|
+
"details": {
|
|
84
|
+
"issues": [
|
|
85
|
+
{
|
|
86
|
+
"kind": "validation",
|
|
87
|
+
"type": "min_value",
|
|
88
|
+
"input": 14,
|
|
89
|
+
"expected": ">=18",
|
|
90
|
+
"received": "14",
|
|
91
|
+
"message": "Invalid value: Expected >=18 but received 14",
|
|
92
|
+
"path": [{ "type": "object", "origin": "value", "key": "age", "value": 14 }]
|
|
93
|
+
}
|
|
94
|
+
]
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Framework Integration Examples
|
|
102
|
+
|
|
103
|
+
### Express
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
import express from "express";
|
|
107
|
+
import { KitExpressMiddleware } from "@wthek/express-middleware";
|
|
108
|
+
import { KitValibotTransformer } from "@wthek/valibot-transformer";
|
|
109
|
+
import * as v from "valibot";
|
|
110
|
+
|
|
111
|
+
const app = express();
|
|
112
|
+
app.use(express.json());
|
|
113
|
+
|
|
114
|
+
app.post("/users", (req, res) => {
|
|
115
|
+
try {
|
|
116
|
+
const user = v.parse(UserSchema, req.body);
|
|
117
|
+
res.status(201).json(user);
|
|
118
|
+
} catch (err) {
|
|
119
|
+
KitValibotTransformer(err);
|
|
120
|
+
}
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
app.use(KitExpressMiddleware({ handleUnknownErrors: true }));
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Fastify
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
import Fastify from "fastify";
|
|
130
|
+
import { KitFastifyMiddleware } from "@wthek/fastify-middleware";
|
|
131
|
+
import { KitValibotTransformer } from "@wthek/valibot-transformer";
|
|
132
|
+
|
|
133
|
+
const app = Fastify({ logger: true });
|
|
134
|
+
KitFastifyMiddleware(app, { log: true, handleUnknownErrors: true });
|
|
135
|
+
|
|
136
|
+
app.post("/users", async (request) => {
|
|
137
|
+
try {
|
|
138
|
+
return v.parse(UserSchema, request.body);
|
|
139
|
+
} catch (err) {
|
|
140
|
+
KitValibotTransformer(err);
|
|
141
|
+
}
|
|
142
|
+
});
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Hono
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
import { Hono } from "hono";
|
|
149
|
+
import { KitHonoMiddleware } from "@wthek/hono-middleware";
|
|
150
|
+
import { fromValiError } from "@wthek/valibot-transformer";
|
|
151
|
+
|
|
152
|
+
const app = new Hono();
|
|
153
|
+
KitHonoMiddleware(app, { handleUnknownErrors: true });
|
|
154
|
+
|
|
155
|
+
app.post("/users", async (c) => {
|
|
156
|
+
const body = await c.req.json();
|
|
157
|
+
try {
|
|
158
|
+
const user = v.parse(UserSchema, body);
|
|
159
|
+
return c.json(user, 201);
|
|
160
|
+
} catch (err) {
|
|
161
|
+
const kitError = fromValiError(err);
|
|
162
|
+
if (kitError) throw kitError;
|
|
163
|
+
throw err;
|
|
164
|
+
}
|
|
165
|
+
});
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Koa
|
|
169
|
+
|
|
170
|
+
```typescript
|
|
171
|
+
import Koa from "koa";
|
|
172
|
+
import { KitKoaMiddleware } from "@wthek/koa-middleware";
|
|
173
|
+
import { KitValibotTransformer } from "@wthek/valibot-transformer";
|
|
174
|
+
|
|
175
|
+
const app = new Koa();
|
|
176
|
+
KitKoaMiddleware(app, { handleUnknownErrors: true });
|
|
177
|
+
|
|
178
|
+
app.use(async (ctx) => {
|
|
179
|
+
try {
|
|
180
|
+
const user = v.parse(UserSchema, ctx.request.body);
|
|
181
|
+
ctx.status = 201;
|
|
182
|
+
ctx.body = user;
|
|
183
|
+
} catch (err) {
|
|
184
|
+
KitValibotTransformer(err);
|
|
185
|
+
}
|
|
186
|
+
});
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Valibot vs Zod vs TypeBox Transformer Comparison
|
|
192
|
+
|
|
193
|
+
| Feature | Zod | Valibot | TypeBox |
|
|
194
|
+
| :--- | :--- | :--- | :--- |
|
|
195
|
+
| **Package** | `@wthek/zod-transformer` | `@wthek/valibot-transformer` | `@wthek/typebox-transformer` |
|
|
196
|
+
| **Throwing fn** | `KitZodTransformer` | `KitValibotTransformer` | `KitTypeBoxTransformer` |
|
|
197
|
+
| **Non-throwing fn** | `fromZodError` | `fromValiError` | `fromTypeBoxError` |
|
|
198
|
+
| **Default message** | `"Zod Validation Failed"` | `"Valibot Validation Failed"` | `"TypeBox Validation Failed"` |
|
|
199
|
+
| **Issues location** | `details.issues` | `details.issues` | `details.issues` |
|
|
200
|
+
| **Detection** | `instanceof ZodError` | `isValiError()` | `instanceof TypeBoxError` + shape checks |
|
|
201
|
+
| **Express interceptor** | ✅ `@wthek/zod-express-interceptor` | ❌ Manual only | ❌ Manual only |
|
|
202
|
+
| **Input formats** | `ZodError` only | `ValiError` only | Multiple: `TypeBoxError`, `ValueError[]`, iterators, single `ValueError` |
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Zod Validation Integration with @wthek
|
|
2
|
+
|
|
3
|
+
Guide for `@wthek/zod-transformer` and `@wthek/zod-express-interceptor`.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. When to Use Which Package
|
|
8
|
+
|
|
9
|
+
- **Express.js Applications:** Use `@wthek/zod-express-interceptor`. It automatically intercepts uncaught `ZodError`s thrown by route handlers and transforms them before reaching the error middleware.
|
|
10
|
+
- **Fastify, NestJS, Restify, or Custom Handlers:** Use `@wthek/zod-transformer`. It provides both throwing and non-throwing conversion functions.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 2. Express Interceptor (`@wthek/zod-express-interceptor`)
|
|
15
|
+
|
|
16
|
+
Mount the interceptor **after** route declarations and **before** your final error handler:
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import express from "express";
|
|
20
|
+
import { z } from "zod";
|
|
21
|
+
import { KitZodExpressInterceptor } from "@wthek/zod-express-interceptor";
|
|
22
|
+
import { KitExpressMiddleware } from "@wthek/express-middleware";
|
|
23
|
+
|
|
24
|
+
const app = express();
|
|
25
|
+
app.use(express.json());
|
|
26
|
+
|
|
27
|
+
// 1. Routes (can throw raw ZodError)
|
|
28
|
+
app.post("/submit", (req, res) => {
|
|
29
|
+
const schema = z.object({ title: z.string().min(3) });
|
|
30
|
+
const data = schema.parse(req.body); // Throws ZodError on failure
|
|
31
|
+
res.json({ success: true, data });
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
// 2. Intercept Zod errors (must be AFTER routes)
|
|
35
|
+
app.use(KitZodExpressInterceptor({
|
|
36
|
+
message: "Validation failed on payload",
|
|
37
|
+
statusCode: 422, // e.g. Unprocessable Entity
|
|
38
|
+
}));
|
|
39
|
+
|
|
40
|
+
// 3. Final Error Middleware
|
|
41
|
+
app.use(KitExpressMiddleware());
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 3. Framework-Agnostic Transformer (`@wthek/zod-transformer`)
|
|
47
|
+
|
|
48
|
+
The transformer exports two functions:
|
|
49
|
+
|
|
50
|
+
### A. `fromZodError(error, options?)` — Non-Throwing (Preferred)
|
|
51
|
+
Returns a `KitHttpError` if the input is a `ZodError`, or `null` if it is not:
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
import { fromZodError } from "@wthek/zod-transformer";
|
|
55
|
+
|
|
56
|
+
try {
|
|
57
|
+
schema.parse(input);
|
|
58
|
+
} catch (err: unknown) {
|
|
59
|
+
const kitError = fromZodError(err, {
|
|
60
|
+
message: "Invalid form input",
|
|
61
|
+
statusCode: 422,
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
if (kitError) {
|
|
65
|
+
// Handled as KitHttpError
|
|
66
|
+
reply.status(kitError.statusCode ?? 400).send(kitError);
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// Not a ZodError - rethrow or pass along
|
|
71
|
+
throw err;
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### B. `KitZodTransformer(error, options?)` — Throwing
|
|
76
|
+
Converts a `ZodError` to a `KitHttpError` and throws it. If the error is not a `ZodError`, it re-throws the error unchanged:
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { KitZodTransformer } from "@wthek/zod-transformer";
|
|
80
|
+
|
|
81
|
+
try {
|
|
82
|
+
schema.parse(input);
|
|
83
|
+
} catch (err) {
|
|
84
|
+
KitZodTransformer(err, { statusCode: 400 });
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 4. Error Payload Structure
|
|
91
|
+
|
|
92
|
+
Both packages attach the native Zod issues array directly to `error.details.issues`:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"code": 400,
|
|
97
|
+
"msg": "Zod Validation Failed",
|
|
98
|
+
"extra": {
|
|
99
|
+
"issues": [
|
|
100
|
+
{
|
|
101
|
+
"code": "too_small",
|
|
102
|
+
"minimum": 18,
|
|
103
|
+
"type": "number",
|
|
104
|
+
"inclusive": true,
|
|
105
|
+
"exact": false,
|
|
106
|
+
"message": "Number must be greater than or equal to 18",
|
|
107
|
+
"path": ["age"]
|
|
108
|
+
}
|
|
109
|
+
]
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|