@nice-code/common-errors 0.2.8 → 0.2.10

package/README.md

@@ -1,5 +1,106 @@
 # @nice-code/common-errors
 
-Shared error domains for Standard Schema validation errors and Hono middleware integration.
+Shared error domains for Standard Schema validation errors, with Hono middleware integration.
 
-See the [main README](../../README.md#nice-codecommon-errors) for full documentation and examples.
+## Install
+
+```bash
+bun add @nice-code/common-errors
+```
+
+Peer deps: `valibot` (or any Standard Schema library), `hono` (for `/hono` subpath).
+
+---
+
+## Validation error domain
+
+`err_validation` is a [`@nice-code/error`](../nice-error) domain for Standard Schema validation failures. Import it to match or inspect validation errors by domain.
+
+```ts
+import { err_validation, EValidator } from "@nice-code/common-errors";
+
+// Check if an error is a validation error
+if (err_validation.isExact(caught)) {
+  const hydrated = err_validation.hydrate(caught);
+  const { issues } = hydrated.getContext(EValidator.standard_schema);
+  // issues: readonly StandardSchemaV1.Issue[]
+}
+```
+
+The domain exposes one error id: `EValidator.standard_schema` with context `{ issues }`.
+
+---
+
+## Hono middleware
+
+Import from the `/hono` subpath:
+
+```ts
+import { niceSValidator, niceCatchSValidation } from "@nice-code/common-errors/hono";
+```
+
+### `niceSValidator(target, schema)`
+
+Drop-in replacement for `@hono/standard-validator`'s `sValidator` that throws a `NiceError` instead of returning a 400 response when validation fails.
+
+```ts
+import { niceSValidator } from "@nice-code/common-errors/hono";
+import * as v from "valibot";
+
+const CreateUserSchema = v.object({
+  name: v.string(),
+  email: v.pipe(v.string(), v.email()),
+});
+
+app.post("/users", niceSValidator("json", CreateUserSchema), async (c) => {
+  const body = c.req.valid("json"); // fully typed
+  // ...
+});
+```
+
+When validation fails, a `NiceError` from the `err_validation` domain is thrown. Use Hono's `onError` handler to convert it to a JSON response:
+
+```ts
+import { castNiceError } from "@nice-code/error";
+
+app.onError((err, c) => {
+  const niceError = castNiceError(err);
+  return c.json(niceError.toJsonObject(), niceError.httpStatusCode as any);
+});
+```
+
+### `niceCatchSValidation()`
+
+Middleware that intercepts raw `@hono/standard-validator` validation responses (the default `{ success: false, error: [...] }` shape) and converts them into `NiceError` JSON responses. Use this when you can't replace `sValidator` with `niceSValidator` directly.
+
+```ts
+app.use(niceCatchSValidation());
+
+// Existing sValidator usage is automatically intercepted
+app.post("/data", sValidator("json", MySchema), handler);
+```
+
+---
+
+## Full Hono example
+
+```ts
+import { Hono } from "hono";
+import { niceSValidator } from "@nice-code/common-errors/hono";
+import { castNiceError, EErrorPackType } from "@nice-code/error";
+import * as v from "valibot";
+
+const app = new Hono();
+
+app.onError((err, c) => {
+  const niceError = castNiceError(err);
+  return c.json(niceError.toJsonObject(), niceError.httpStatusCode as any);
+});
+
+const BodySchema = v.object({ message: v.string() });
+
+app.post("/echo", niceSValidator("json", BodySchema), async (c) => {
+  const { message } = c.req.valid("json");
+  return c.json({ echo: message });
+});
+```