@wthek/typebox-transformer 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 +16 -0
- package/llms.txt +67 -0
- package/package.json +13 -3
package/README.md
CHANGED
|
@@ -9,12 +9,13 @@ _Built for projects using [`http-error-kit`][http-error-kit], this utility trans
|
|
|
9
9
|

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

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

|
|
14
15
|
[](https://bundlephobia.com/package/%40wthek%2Ftypebox-transformer)
|
|
15
16
|
[](https://app.codacy.com/gh/Skillnter/wthek-typebox-transformer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
|
|
16
17
|
[](https://app.codacy.com/gh/Skillnter/wthek-typebox-transformer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
|
|
17
|
-
[](https://socket.dev/npm/package/@wthek/typebox-transformer/overview/)
|
|
18
19
|
[](https://github.com/sponsors/Skillnter)
|
|
19
20
|
[](https://opencollective.com/skillnter)
|
|
20
21
|
[](https://www.buymeacoffee.com/skillnter)
|
|
@@ -137,6 +138,18 @@ KitHttpErrorConfig.configureFormatter(
|
|
|
137
138
|
);
|
|
138
139
|
```
|
|
139
140
|
|
|
141
|
+
## AI Agent Integration
|
|
142
|
+
|
|
143
|
+
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:
|
|
144
|
+
|
|
145
|
+
```markdown
|
|
146
|
+
### TypeBox Validation Error Rule
|
|
147
|
+
- When validating input with TypeBox, transform validation failures into `http-error-kit` errors using `@wthek/typebox-transformer`.
|
|
148
|
+
- For synchronous schema assertions: wrap in `try ... catch (err)` and invoke `KitTypeBoxTransformer(err)`.
|
|
149
|
+
- For `Value.Errors()` flows: convert directly with `fromTypeBoxError([...Value.Errors(schema, data)])`.
|
|
150
|
+
- Pair with `@wthek/*-middleware` to automatically serialize validation issues into structured HTTP responses.
|
|
151
|
+
```
|
|
152
|
+
|
|
140
153
|
## Explore More WTHek Extensions
|
|
141
154
|
|
|
142
155
|
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
|
@@ -3,6 +3,22 @@ import { KitHttpError } from "http-error-kit";
|
|
|
3
3
|
* Configuration options for KitTypeBoxTransformer and fromTypeBoxError.
|
|
4
4
|
*
|
|
5
5
|
* @interface IKitTypeBoxTransformerOptions
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { KitTypeBoxTransformer } from "@wthek/typebox-transformer";
|
|
10
|
+
*
|
|
11
|
+
* const options: IKitTypeBoxTransformerOptions = {
|
|
12
|
+
* message: "Invalid payload provided",
|
|
13
|
+
* statusCode: 422,
|
|
14
|
+
* };
|
|
15
|
+
*
|
|
16
|
+
* try {
|
|
17
|
+
* Value.Assert(UserSchema, data);
|
|
18
|
+
* } catch (err) {
|
|
19
|
+
* KitTypeBoxTransformer(err, options);
|
|
20
|
+
* }
|
|
21
|
+
* ```
|
|
6
22
|
*/
|
|
7
23
|
export interface IKitTypeBoxTransformerOptions {
|
|
8
24
|
/**
|
package/llms.txt
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# @wthek/typebox-transformer
|
|
2
|
+
|
|
3
|
+
> Framework-agnostic TypeBox error transformer for `http-error-kit`.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
`@wthek/typebox-transformer` transforms TypeBox validation errors into structured `KitHttpError` objects (defaulting to 400 Bad Request) with complete issue details attached under `issues`. Supports all TypeBox error formats: `TypeBoxError` instances (like `AssertError`), `ValueError[]` arrays, single `ValueError` objects, `Value.Errors()` iterators, and object wrappers with `{ errors: ValueError[] }`. Works seamlessly across Express, Fastify, Hono, Koa, NestJS, and Restify applications.
|
|
7
|
+
|
|
8
|
+
## Installation
|
|
9
|
+
```bash
|
|
10
|
+
npm install @wthek/typebox-transformer @sinclair/typebox http-error-kit http-response-status-code
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
|
|
15
|
+
### Throwing Transformed Errors (`KitTypeBoxTransformer`)
|
|
16
|
+
```typescript
|
|
17
|
+
import { Type } from "@sinclair/typebox";
|
|
18
|
+
import { Value } from "@sinclair/typebox/value";
|
|
19
|
+
import { KitTypeBoxTransformer } from "@wthek/typebox-transformer";
|
|
20
|
+
|
|
21
|
+
const UserSchema = Type.Object({
|
|
22
|
+
name: Type.String(),
|
|
23
|
+
age: Type.Number({ minimum: 18 }),
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
try {
|
|
27
|
+
Value.Assert(UserSchema, { name: "Hek", age: 14 });
|
|
28
|
+
} catch (err) {
|
|
29
|
+
// Throws KitHttpError with status 400 and validation issues attached
|
|
30
|
+
KitTypeBoxTransformer(err);
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Safe Conversion Without Throwing (`fromTypeBoxError`)
|
|
35
|
+
```typescript
|
|
36
|
+
import { Type } from "@sinclair/typebox";
|
|
37
|
+
import { Value } from "@sinclair/typebox/value";
|
|
38
|
+
import { fromTypeBoxError } from "@wthek/typebox-transformer";
|
|
39
|
+
|
|
40
|
+
const errors = [...Value.Errors(UserSchema, data)];
|
|
41
|
+
const kitError = fromTypeBoxError(errors, {
|
|
42
|
+
message: "Invalid Input",
|
|
43
|
+
statusCode: 422,
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
if (kitError) {
|
|
47
|
+
return res.status(kitError.statusCode).json(kitError.toJSON());
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## API Reference
|
|
52
|
+
|
|
53
|
+
### `fromTypeBoxError(error: unknown, options?: IKitTypeBoxTransformerOptions): KitHttpError | null`
|
|
54
|
+
Converts a TypeBox validation error into a `KitHttpError` without throwing. Returns `null` if the provided value is not a recognized TypeBox error.
|
|
55
|
+
|
|
56
|
+
### `KitTypeBoxTransformer(error: unknown, options?: IKitTypeBoxTransformerOptions): never`
|
|
57
|
+
Transforms a TypeBox validation error into a `KitHttpError` and throws it. If the value is not a TypeBox error, throws it unchanged.
|
|
58
|
+
|
|
59
|
+
#### Options (`IKitTypeBoxTransformerOptions`)
|
|
60
|
+
- `message` (`string`, default: `"TypeBox Validation Failed"`): Custom error message.
|
|
61
|
+
- `statusCode` (`number`, default: `400`): Custom HTTP status code.
|
|
62
|
+
|
|
63
|
+
## Safety Rules for AI Agents
|
|
64
|
+
1. Wrap `Value.Assert()` calls in `try ... catch` and pass caught errors to `KitTypeBoxTransformer(err)`.
|
|
65
|
+
2. When collecting errors with `Value.Errors()`, spread into an array and convert with `fromTypeBoxError([...errors])`.
|
|
66
|
+
3. Non-TypeBox errors passed to `KitTypeBoxTransformer(err)` are rethrown unchanged, preventing swallowed runtime errors.
|
|
67
|
+
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wthek/typebox-transformer",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Framework-agnostic utility that transforms TypeBox validation errors into structured http-error-kit errors. Preserves error issues and integrates cleanly with custom formatters.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
@@ -41,6 +41,15 @@
|
|
|
41
41
|
"error",
|
|
42
42
|
"kit",
|
|
43
43
|
"http-errors",
|
|
44
|
+
"rfc-7807",
|
|
45
|
+
"rfc-9457",
|
|
46
|
+
"structured-errors",
|
|
47
|
+
"api-error-response",
|
|
48
|
+
"ai-agent",
|
|
49
|
+
"agent-skill",
|
|
50
|
+
"antigravity",
|
|
51
|
+
"cursor",
|
|
52
|
+
"copilot",
|
|
44
53
|
"wthek",
|
|
45
54
|
"skillnter"
|
|
46
55
|
],
|
|
@@ -51,8 +60,8 @@
|
|
|
51
60
|
},
|
|
52
61
|
"homepage": "https://github.com/Skillnter/wthek-typebox-transformer#readme",
|
|
53
62
|
"dependencies": {
|
|
54
|
-
"http-error-kit": "^1.
|
|
55
|
-
"http-response-status-code": "^1.
|
|
63
|
+
"http-error-kit": "^1.5.0",
|
|
64
|
+
"http-response-status-code": "^1.9.0"
|
|
56
65
|
},
|
|
57
66
|
"peerDependencies": {
|
|
58
67
|
"@sinclair/typebox": "^0.32.0 || ^0.33.0 || ^0.34.0"
|
|
@@ -76,6 +85,7 @@
|
|
|
76
85
|
"files": [
|
|
77
86
|
"dist/index.js",
|
|
78
87
|
"dist/index.d.ts",
|
|
88
|
+
"llms.txt",
|
|
79
89
|
"LICENSE"
|
|
80
90
|
],
|
|
81
91
|
"funding": [
|