@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 CHANGED
@@ -9,12 +9,13 @@ _Built for projects using [`http-error-kit`][http-error-kit], this utility trans
9
9
  ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/skillnter/wthek-typebox-transformer/main.yml)
10
10
  [![npm version](https://img.shields.io/npm/v/%40wthek%2Ftypebox-transformer?color=brightgreen)](https://www.npmjs.com/package/@wthek/typebox-transformer)
11
11
  [![GitHub license](https://img.shields.io/github/license/skillnter/wthek-typebox-transformer?color=brightgreen)](LICENSE)
12
+ ![NPM Type Definitions](https://img.shields.io/npm/types/%40wthek%2Ftypebox-transformer)
12
13
  [![GitHub Issues](https://img.shields.io/github/issues/Skillnter/wthek-typebox-transformer)](https://github.com/Skillnter/wthek-typebox-transformer/issues)
13
14
  ![npm](https://img.shields.io/npm/dy/%40wthek%2Ftypebox-transformer)
14
15
  [![Bundle Size](https://img.shields.io/bundlephobia/minzip/%40wthek%2Ftypebox-transformer)](https://bundlephobia.com/package/%40wthek%2Ftypebox-transformer)
15
16
  [![Codacy Badge](https://app.codacy.com/project/badge/Grade/256715e97d954a5cb5afd9cca3039419)](https://app.codacy.com/gh/Skillnter/wthek-typebox-transformer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
16
17
  [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/256715e97d954a5cb5afd9cca3039419)](https://app.codacy.com/gh/Skillnter/wthek-typebox-transformer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
17
- [![Socket Badge](https://socket.dev/api/badge/npm/package/@wthek/typebox-transformer/1.0.0)](https://socket.dev/npm/package/@wthek/typebox-transformer/overview/1.0.0)
18
+ [![Socket Badge](https://socket.dev/api/badge/npm/package/@wthek/typebox-transformer/)](https://socket.dev/npm/package/@wthek/typebox-transformer/overview/)
18
19
  [![Github Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-30363D?&logo=GitHub-Sponsors&logoColor=EA4AAA)](https://github.com/sponsors/Skillnter)
19
20
  [![Open Collective](https://img.shields.io/badge/Open%20Collective-3385FF?logo=open-collective&logoColor=white)](https://opencollective.com/skillnter)
20
21
  [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?&logo=buy-me-a-coffee&logoColor=black)](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.0.0",
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.2.0",
55
- "http-response-status-code": "^1.8.0"
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": [