@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.
Files changed (35) hide show
  1. package/LICENSE +22 -0
  2. package/README.md +246 -2
  3. package/dist/bin.d.ts +36 -0
  4. package/dist/bin.d.ts.map +1 -0
  5. package/dist/bin.js +127 -0
  6. package/dist/index.d.ts +23 -0
  7. package/dist/index.d.ts.map +1 -0
  8. package/dist/index.js +67 -0
  9. package/dist/installer.d.ts +36 -0
  10. package/dist/installer.d.ts.map +1 -0
  11. package/dist/installer.js +139 -0
  12. package/dist/types.d.ts +25 -0
  13. package/dist/types.d.ts.map +1 -0
  14. package/dist/types.js +2 -0
  15. package/package.json +101 -3
  16. package/plugin.json +11 -0
  17. package/skills/wthek-error-handling/SKILL.md +711 -0
  18. package/skills/wthek-error-handling/examples/express-zod.js +44 -0
  19. package/skills/wthek-error-handling/examples/express-zod.ts +51 -0
  20. package/skills/wthek-error-handling/examples/fastify-zod.js +40 -0
  21. package/skills/wthek-error-handling/examples/fastify-zod.ts +45 -0
  22. package/skills/wthek-error-handling/examples/hono-valibot.ts +42 -0
  23. package/skills/wthek-error-handling/examples/koa-typebox.ts +54 -0
  24. package/skills/wthek-error-handling/references/express.md +73 -0
  25. package/skills/wthek-error-handling/references/fastify.md +81 -0
  26. package/skills/wthek-error-handling/references/formatters.md +241 -0
  27. package/skills/wthek-error-handling/references/hono.md +151 -0
  28. package/skills/wthek-error-handling/references/koa.md +62 -0
  29. package/skills/wthek-error-handling/references/mcp.md +148 -0
  30. package/skills/wthek-error-handling/references/nestjs.md +84 -0
  31. package/skills/wthek-error-handling/references/restify.md +68 -0
  32. package/skills/wthek-error-handling/references/status-codes.md +181 -0
  33. package/skills/wthek-error-handling/references/typebox.md +74 -0
  34. package/skills/wthek-error-handling/references/valibot.md +202 -0
  35. 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
+