@nice-code/error 0.2.8 → 0.2.10

package/README.md

@@ -1,5 +1,237 @@
-# @nice-code/error
-
-Typed, serializable errors with domain hierarchies, pattern matching, and safe transport across API boundaries.
-
-See the [main README](../../README.md) for full documentation and examples.
+# @nice-code/error
+
+Typed, serializable errors with domain hierarchies, pattern matching, and safe transport across API boundaries.
+
+## Install
+
+```bash
+bun add @nice-code/error
+```
+
+## Core concepts
+
+- **Domain** — a named group of related errors (`err_user_auth`, `err_payment`)
+- **Schema** — maps error id strings to message, HTTP status, and optional typed context
+- **Error id** — identifies what went wrong within a domain; multiple ids can be active on one error
+- **Context** — structured data attached to an id (e.g. `{ username: string }`)
+- **Hydration** — deserializing context from a JSON round-trip back to the original typed value
+
+---
+
+## Defining an error domain
+
+```ts
+import { defineNiceError, err } from "@nice-code/error";
+
+export const err_auth = defineNiceError({
+  domain: "err_auth",
+  schema: {
+    // No context — second arg to fromId is not accepted
+    account_locked: err({
+      message: "Account is locked",
+      httpStatusCode: 403,
+    }),
+
+    // Required context — second arg to fromId is required
+    invalid_credentials: err<{ username: string }>({
+      message: ({ username }) => `Invalid credentials for: ${username}`,
+      httpStatusCode: 401,
+      context: { required: true },
+    }),
+
+    // Optional context
+    rate_limited: err<{ retryAfter: number }>({
+      message: (ctx) => ctx ? `Retry after ${ctx.retryAfter}s` : "Rate limited",
+      httpStatusCode: 429,
+      context: {},
+    }),
+  },
+} as const);
+```
+
+### `err()` — schema entry helper
+
+| Schema entry | `fromId("id")` | `fromId("id", ctx)` |
+|---|---|---|
+| `err()` / `err({ message, httpStatusCode })` | ✓ | ✗ |
+| `err<C>({ context: {} })` | ✓ optional | ✓ optional |
+| `err<C>({ context: { required: true } })` | ✗ | ✓ required |
+
+### Custom serialization (non-JSON-safe context)
+
+```ts
+fs_error: err<{ cause: NodeJS.ErrnoException }>({
+  message: ({ cause }) => `FS error: ${cause.message}`,
+  context: {
+    required: true,
+    serialization: {
+      toJsonSerializable: ({ cause }) => ({ code: cause.code, message: cause.message }),
+      fromJsonSerializable: (obj) => ({ cause: Object.assign(new Error(obj.message), obj) }),
+    },
+  },
+}),
+```
+
+---
+
+## Creating errors
+
+```ts
+// Single id — context required per schema
+const err1 = err_auth.fromId("invalid_credentials", { username: "alice" });
+
+// Multi-id in one error
+const err2 = err_auth.fromContext({
+  invalid_credentials: { username: "bob" },
+  rate_limited: { retryAfter: 30 },
+});
+
+// Chain additional ids after construction
+const err3 = err_auth.fromId("account_locked").addId("rate_limited");
+```
+
+---
+
+## Reading errors
+
+```ts
+// Check and narrow type
+if (err1.hasId("invalid_credentials")) {
+  const { username } = err1.getContext("invalid_credentials"); // typed
+}
+
+// Check multiple ids at once
+if (err2.hasOneOfIds(["invalid_credentials", "rate_limited"])) {
+  // ACTIVE_IDS narrowed to that subset
+}
+
+// Pattern match — calls first matching handler, returns its result
+import { matchFirst } from "@nice-code/error";
+
+const message = matchFirst(err1, {
+  invalid_credentials: ({ username }) => `Wrong password for ${username}`,
+  account_locked: () => "Account locked",
+  _: () => "Unknown auth error",
+});
+```
+
+---
+
+## Domain hierarchies
+
+```ts
+const err_app = defineNiceError({ domain: "err_app", schema: {} } as const);
+
+const err_auth = err_app.createChildDomain({
+  domain: "err_auth",
+  schema: { /* ... */ },
+});
+
+const err_auth_registration = err_auth.createChildDomain({
+  domain: "err_auth_registration",
+  schema: { /* ... */ },
+});
+
+// Ancestry checks
+err_app.isParentOf(err_auth_registration);           // true
+err_auth.isParentOf(err_auth_registration);          // true
+err_auth_registration.isParentOf(err_auth);          // false
+
+// Type guard — exact domain match only
+err_auth.isExact(someError);         // true only for err_auth domain
+err_auth.isThisOrChild(someError);   // true for err_auth and all children
+```
+
+---
+
+## Serialization & transport
+
+```ts
+// Serialize to a plain JSON object (safe to send over HTTP)
+const json = error.toJsonObject();
+const str = error.toJsonString();
+const response = error.toHttpResponse(); // Response with correct HTTP status
+
+// On the receiving side — reconstruct from anything
+import { castNiceError } from "@nice-code/error";
+
+const caught = castNiceError(unknownValue); // always returns NiceError
+
+if (err_auth.isExact(caught)) {
+  const hydrated = err_auth.hydrate(caught); // deserializes context
+  const { username } = hydrated.getContext("invalid_credentials");
+}
+```
+
+`castNiceError` handles: `NiceError` instances, serialized JSON objects, native `Error`, error-like objects, nullish values, and primitives.
+
+---
+
+## Error handling with handlers
+
+### Functional style (composable)
+
+```ts
+import { forDomain, forId, forIds } from "@nice-code/error";
+
+const handled = error.handleWithSync([
+  forId(err_auth, "invalid_credentials", (h) => {
+    const { username } = h.getContext("invalid_credentials");
+    return res.status(401).json({ error: `Bad credentials for ${username}` });
+  }),
+  forIds(err_auth, ["account_locked", "rate_limited"], (h) => {
+    return res.status(h.httpStatusCode).json({ error: h.message });
+  }),
+  forDomain(err_payment, (h) => {
+    return res.status(500).json({ error: "Payment failed" });
+  }),
+]);
+
+// Async handlers
+await error.handleWithAsync([
+  forDomain(err_payment, async (h) => {
+    await db.logFailure(h.message);
+    await notify(h.toJsonObject());
+  }),
+]);
+```
+
+### Class-based style (reusable handler)
+
+```ts
+import { NiceErrorHandler } from "@nice-code/error";
+
+const handler = new NiceErrorHandler()
+  .forId(err_auth, "invalid_credentials", (h) => "unauthorized")
+  .forDomain(err_payment, (h) => "payment_error")
+  .setDefaultHandler((e) => "unknown_error");
+
+handler.handleErrorWithPromiseInspection(error);
+```
+
+---
+
+## Utility types
+
+```ts
+import type { InferNiceError, InferNiceErrorHydrated } from "@nice-code/error";
+
+type TAuthError = InferNiceError<typeof err_auth>;
+// → NiceError<{ domain: "err_auth"; ... }, keyof schema>
+
+type TAuthErrorHydrated = InferNiceErrorHydrated<typeof err_auth>;
+```
+
+---
+
+## Packing for transport
+
+Useful when errors must travel through systems that don't preserve custom properties (e.g. some RPC layers).
+
+```ts
+import { EErrorPackType } from "@nice-code/error";
+
+error.pack(EErrorPackType.msg_pack);   // embeds JSON in error.message
+error.pack(EErrorPackType.cause_pack); // embeds JSON in error.cause
+error.unpack();                        // restore original
+```