@nice-code/error 0.2.9 → 0.2.11

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
+```

package/build/index.js

@@ -1,19 +1,952 @@
-// src/index.ts
-export * from "./internal";
-export * from "./NiceError/NiceError";
-export * from "./NiceError/NiceError.types";
-export * from "./NiceError/NiceErrorHydrated";
-export * from "./NiceErrorDefined/defineNiceError";
-export * from "./NiceErrorDefined/err";
-export * from "./NiceErrorDefined/NiceErrorDefined";
-export * from "./NiceErrorHandler/handleWith";
-export * from "./NiceErrorHandler/NiceErrorHandler";
-export * from "./NiceErrorHandler/NiceErrorHandler.types";
-export * from "./utils/castAndHydrate";
-export * from "./utils/castNiceError";
-export * from "./utils/isNiceErrorObject";
-export * from "./utils/isRegularErrorObject";
-export * from "./utils/matchFirst";
-export * from "./utils/packError/causePack";
-export * from "./utils/packError/msgPack";
-export * from "./utils/packError/packError.enums";
+// src/internal/nice_core_errors.ts
+import { StatusCodes } from "http-status-codes";
+
+// src/utils/jsErrorOrCastJsError.ts
+function jsErrorOrCastJsError(error, logMessage = true) {
+  if (error instanceof Error) {
+    return Object.assign(error, {
+      message: error.message
+    });
+  }
+  const message = error?.message ?? (typeof error === "string" ? error : "No error message found");
+  if (logMessage) {
+    console.error(`An unknown and unstructured error was thrown: ${message}`, error);
+  }
+  return {
+    ...new Error(message),
+    ...error
+  };
+}
+
+// src/NiceError/nice_error.static.ts
+var DUR_OBJ_PACK_PREFIX = "NE_DUROBJ[[";
+var DUR_OBJ_PACK_SUFFIX = "]]NE_DUROBJ";
+
+// src/utils/packError/packError.enums.ts
+var EErrorPackType;
+((EErrorPackType2) => {
+  EErrorPackType2["no_pack"] = "no_pack";
+  EErrorPackType2["msg_pack"] = "msg_pack";
+  EErrorPackType2["cause_pack"] = "cause_pack";
+})(EErrorPackType ||= {});
+
+// src/utils/packError/causePack.ts
+var causePack = (error) => {
+  error._packedState = { cause: error.cause, packedAs: "cause_pack" /* cause_pack */ };
+  error.cause = `${DUR_OBJ_PACK_PREFIX}${JSON.stringify(error.toJsonObject())}${DUR_OBJ_PACK_SUFFIX}`;
+  return error;
+};
+
+// src/utils/packError/msgPack.ts
+var msgPack = (error) => {
+  error._packedState = { message: error.cleanMessage, packedAs: "msg_pack" /* msg_pack */ };
+  error.message = `${DUR_OBJ_PACK_PREFIX}${JSON.stringify(error.toJsonObject())}${DUR_OBJ_PACK_SUFFIX}`;
+  return error;
+};
+
+// src/utils/packError/packError.ts
+var packError = (error, packType = "msg_pack") => {
+  if (packType === "no_pack") {
+    return error;
+  }
+  if (packType === "msg_pack") {
+    return msgPack(error);
+  }
+  return causePack(error);
+};
+
+// src/NiceError/NiceError.ts
+class NiceError extends Error {
+  name = "NiceError";
+  def;
+  ids;
+  wasntNice;
+  httpStatusCode;
+  timeCreated;
+  cleanMessage;
+  originError;
+  _packedState;
+  _errorDataMap;
+  constructor(options) {
+    const messagePure = options.message;
+    const prefixedMessage = `[${options.def.domain}](${options.ids.join(",")}) ${messagePure}`;
+    super(prefixedMessage);
+    this.cleanMessage = messagePure;
+    this.def = options.def;
+    this.ids = options.ids;
+    this._errorDataMap = options.errorData;
+    this.wasntNice = options.wasntNice ?? false;
+    this.httpStatusCode = options.httpStatusCode ?? 500;
+    if (options.originError != null) {
+      this.originError = options.originError;
+    }
+    this.timeCreated = options.timeCreated ?? Date.now();
+  }
+  hasId(id) {
+    return id in this._errorDataMap;
+  }
+  hasOneOfIds(ids) {
+    return ids.some((id) => (id in this._errorDataMap));
+  }
+  get hasMultiple() {
+    return Object.keys(this._errorDataMap).length > 1;
+  }
+  getIds() {
+    return Object.keys(this._errorDataMap);
+  }
+  getContext(id) {
+    const errorData = this._errorDataMap[id];
+    const state = errorData?.contextState;
+    if (state == null) {
+      return;
+    }
+    if (state.kind === "unhydrated") {
+      throw new Error(`[NiceError.getContext] Context for id "${String(id)}" is in the "unhydrated" state. ` + `The error was reconstructed from a serialized payload but has not been deserialized yet. ` + `Call \`niceErrorDefined.hydrate(error)\` to reconstruct the typed context.`);
+    }
+    return state.value;
+  }
+  getErrorDataForId(id) {
+    return this._errorDataMap[id];
+  }
+  withOriginError(error) {
+    this.originError = jsErrorOrCastJsError(error);
+    if (this._packedState?.packedAs !== "cause_pack" /* cause_pack */) {
+      this.cause = this.originError;
+    }
+    return this;
+  }
+  matches(other) {
+    const myDef = this.def;
+    const otherDef = other.def;
+    if (myDef.domain !== otherDef.domain)
+      return false;
+    const myIds = this.getIds().map(String).sort();
+    const otherIds = other.getIds().map(String).sort();
+    if (myIds.length !== otherIds.length)
+      return false;
+    return myIds.every((id, i) => id === otherIds[i]);
+  }
+  toJsonObject() {
+    const originError = this.originError ? {
+      name: this.originError.name,
+      message: this.originError.cleanMessage ?? this.originError.message,
+      stack: this.originError.stack,
+      cause: this.originError.cause
+    } : undefined;
+    const def = {
+      domain: this.def.domain,
+      allDomains: this.def.allDomains
+    };
+    if (this.def.defaultHttpStatusCode != null) {
+      def["defaultHttpStatusCode"] = this.def.defaultHttpStatusCode;
+    }
+    if (this.def.defaultMessage != null) {
+      def["defaultMessage"] = this.def.defaultMessage;
+    }
+    const errorData = {};
+    for (const rawId of Object.keys(this._errorDataMap)) {
+      const id = rawId;
+      const data = this._errorDataMap[id];
+      if (data == null)
+        continue;
+      let contextState;
+      if (data.contextState.kind === "hydrated" /* hydrated */) {
+        contextState = {
+          kind: "unhydrated" /* unhydrated */,
+          serialized: data.contextState.serialized
+        };
+      } else {
+        contextState = data.contextState;
+      }
+      errorData[id] = {
+        contextState,
+        message: data.cleanMessage ?? data.message,
+        httpStatusCode: data.httpStatusCode,
+        timeAdded: data.timeAdded
+      };
+    }
+    return {
+      name: "NiceError",
+      def,
+      ids: this.ids,
+      errorData,
+      wasntNice: this.wasntNice,
+      message: this.cleanMessage,
+      httpStatusCode: this.httpStatusCode,
+      timeCreated: this.timeCreated,
+      ...this.stack != null ? { stack: this.stack } : {},
+      originError
+    };
+  }
+  toJsonString() {
+    return JSON.stringify(this.toJsonObject());
+  }
+  toHttpResponse() {
+    return new Response(this.toJsonString(), {
+      status: this.httpStatusCode,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  hydrate(definedNiceError) {
+    return definedNiceError.hydrate(this);
+  }
+  handleWithSync(handlerInput, handlerOptions = {}) {
+    const handlersArray = Array.isArray(handlerInput) ? handlerInput : [handlerInput];
+    for (const handler of handlersArray) {
+      const result = handler.handleErrorWithPromiseInspection(this, handlerOptions);
+      if (result.matched) {
+        if (result.isPromise) {
+          console.warn(`[NiceError.handleWith] Handler ${result.target.identifier} returned a Promise but was called via \`handleWith\` (synchronous). ` + `The Promise will not be awaited. Use \`handleWithAsync\` for async handlers.`);
+        }
+        return result.isPromise ? undefined : result.handlerResponse;
+      }
+    }
+    if (handlerOptions.throwOnUnhandled === true)
+      throw this;
+    return;
+  }
+  async handleWithAsync(handlerInput, handlerOptions = {}) {
+    const handlersArray = Array.isArray(handlerInput) ? handlerInput : [handlerInput];
+    for (const handler of handlersArray) {
+      const result = handler.handleErrorWithPromiseInspection(this, handlerOptions);
+      if (result.matched) {
+        return result.isPromise ? await result.handlerPromise : result.handlerResponse;
+      }
+    }
+    if (handlerOptions.throwOnUnhandled === true)
+      throw this;
+    return;
+  }
+  get isPacked() {
+    return this._packedState != null;
+  }
+  pack(packType = "msg_pack") {
+    if (this.isPacked)
+      return this;
+    return packError(this, packType);
+  }
+  unpack() {
+    if (this._packedState == null)
+      return this;
+    if (this._packedState.packedAs === "msg_pack" /* msg_pack */) {
+      this.message = this._packedState.message;
+    }
+    if (this._packedState.packedAs === "cause_pack" /* cause_pack */) {
+      this.cause = this._packedState.cause;
+    }
+    this._packedState = undefined;
+    delete this._packedState;
+    return this;
+  }
+}
+
+// src/NiceError/NiceErrorHydrated.ts
+class NiceErrorHydrated extends NiceError {
+  def;
+  niceErrorDefined;
+  constructor(options) {
+    super(options);
+    this.def = options.def;
+    this.niceErrorDefined = options.niceErrorDefined;
+  }
+  addContext(context) {
+    const newIds = Object.keys(context);
+    const newErrorData = {};
+    for (const id of newIds) {
+      newErrorData[id] = this.niceErrorDefined.reconcileErrorDataForId(id, context[id]);
+    }
+    const mergedErrorData = {
+      ...this._errorDataMap,
+      ...newErrorData
+    };
+    const mergedIds = Array.from(new Set([...this.getIds(), ...Object.keys(context)]));
+    return new NiceErrorHydrated({
+      def: this.def,
+      niceErrorDefined: this.niceErrorDefined,
+      ids: mergedIds,
+      errorData: mergedErrorData,
+      message: this.cleanMessage,
+      wasntNice: this.wasntNice,
+      httpStatusCode: this.httpStatusCode,
+      originError: this.originError
+    });
+  }
+  addId(...args) {
+    const [id, context] = args;
+    const reconciledData = this.niceErrorDefined.reconcileErrorDataForId(id, context);
+    const errorDataMap = {};
+    errorDataMap[id] = reconciledData;
+    const mergedContexts = {
+      ...this._errorDataMap,
+      ...errorDataMap
+    };
+    const mergedIds = Array.from(new Set([...this.getIds(), id]));
+    return new NiceErrorHydrated({
+      def: this.def,
+      niceErrorDefined: this.niceErrorDefined,
+      ids: mergedIds,
+      errorData: mergedContexts,
+      message: this.cleanMessage,
+      wasntNice: this.wasntNice,
+      httpStatusCode: this.httpStatusCode,
+      originError: this.originError
+    });
+  }
+}
+
+// src/NiceErrorDefined/NiceErrorDefined.ts
+class NiceErrorDomain {
+  domain;
+  allDomains;
+  defaultHttpStatusCode;
+  defaultMessage;
+  _schema;
+  _definedChildNiceErrors = [];
+  _definedParentNiceError;
+  _setPack;
+  _packAsFn;
+  constructor(definition) {
+    this.domain = definition.domain;
+    this.allDomains = definition.allDomains;
+    this._schema = definition.schema;
+    if (definition.packAs != null) {
+      this._packAsFn = definition.packAs;
+    }
+    if (definition.defaultHttpStatusCode != null) {
+      this.defaultHttpStatusCode = definition.defaultHttpStatusCode;
+    }
+    if (definition.defaultMessage != null) {
+      this.defaultMessage = definition.defaultMessage;
+    }
+  }
+  createChildDomain(subErrorDef) {
+    const child = new NiceErrorDomain({
+      domain: subErrorDef.domain,
+      allDomains: [subErrorDef.domain, ...this.allDomains],
+      schema: subErrorDef.schema,
+      defaultHttpStatusCode: subErrorDef.defaultHttpStatusCode,
+      defaultMessage: subErrorDef.defaultMessage
+    });
+    this.addChildNiceErrorDefined(child);
+    child.addParentNiceErrorDefined(this);
+    if (subErrorDef.packAs != null) {
+      child._packAsFn = subErrorDef.packAs;
+    } else if (this._setPack) {
+      child.packAs(this._setPack);
+    } else if (this._packAsFn) {
+      child._packAsFn = this._packAsFn;
+    }
+    return child;
+  }
+  addParentNiceErrorDefined(parentError) {
+    if (this._definedParentNiceError?.domain === parentError.domain) {
+      return;
+    }
+    this._definedParentNiceError = {
+      domain: parentError.domain,
+      definedError: parentError
+    };
+  }
+  addChildNiceErrorDefined(child) {
+    if (this._definedChildNiceErrors.some((linked) => linked.domain === child.domain)) {
+      return;
+    }
+    this._definedChildNiceErrors.push({
+      domain: child.domain,
+      definedError: child
+    });
+    if (this._definedParentNiceError) {
+      this._definedParentNiceError.definedError.addChildNiceErrorDefined(child);
+    }
+  }
+  packAs(pack) {
+    this._setPack = pack;
+    return this;
+  }
+  createError(input) {
+    const err = new NiceErrorHydrated(input);
+    const packType = this._setPack ?? this._packAsFn?.();
+    if (packType != null && packType !== "no_pack") {
+      return err.pack(packType);
+    }
+    return err;
+  }
+  hydrate(error) {
+    const errDef = error.def;
+    if (errDef.domain !== this.domain) {
+      throw new Error(`[NiceErrorDefined.hydrate] Domain mismatch: this definition is "${this.domain}" ` + `but the error belongs to "${errDef.domain}". ` + `Call \`niceErrorDefined.is(error)\` before hydrating to ensure compatibility.`);
+    }
+    const finalError = error instanceof NiceError ? error : new NiceError(error);
+    const reconciledErrorData = {};
+    for (const id of finalError.getIds()) {
+      const existingData = finalError.getErrorDataForId(id);
+      if (existingData == null)
+        continue;
+      let contextState = existingData.contextState;
+      if (contextState.kind === "unhydrated") {
+        const entry = this._schema[id];
+        const deserialize = entry?.context?.serialization?.fromJsonSerializable;
+        if (deserialize != null) {
+          contextState = {
+            kind: "hydrated" /* hydrated */,
+            value: deserialize(contextState.serialized),
+            serialized: contextState.serialized
+          };
+        }
+      }
+      reconciledErrorData[id] = {
+        contextState,
+        message: existingData.cleanMessage ?? existingData.message,
+        httpStatusCode: existingData.httpStatusCode,
+        timeAdded: existingData.timeAdded
+      };
+    }
+    return new NiceErrorHydrated({
+      def: this._buildDef(),
+      niceErrorDefined: this,
+      ids: finalError.ids,
+      errorData: reconciledErrorData,
+      message: finalError.cleanMessage ?? finalError.message,
+      httpStatusCode: finalError.httpStatusCode,
+      wasntNice: finalError.wasntNice,
+      originError: finalError.originError,
+      timeCreated: finalError.timeCreated
+    });
+  }
+  fromId(...args) {
+    const [id, context] = args;
+    const reconciledData = this.reconcileErrorDataForId(id, context);
+    const errorData = {};
+    errorData[id] = reconciledData;
+    return this.createError({
+      def: this._buildDef(),
+      niceErrorDefined: this,
+      ids: [id],
+      errorData,
+      message: reconciledData.cleanMessage ?? reconciledData.message,
+      httpStatusCode: reconciledData.httpStatusCode
+    });
+  }
+  fromContext(context) {
+    const ids = Object.keys(context);
+    if (ids.length === 0) {
+      throw new Error("[NiceErrorDefined.fromContext] context object must contain at least one error id.");
+    }
+    const errorData = {};
+    for (const id of ids) {
+      errorData[id] = this.reconcileErrorDataForId(id, context[id]);
+    }
+    const primaryId = ids[0];
+    return this.createError({
+      def: this._buildDef(),
+      niceErrorDefined: this,
+      ids,
+      errorData,
+      message: errorData[primaryId].cleanMessage ?? errorData[primaryId].message,
+      httpStatusCode: errorData[primaryId].httpStatusCode
+    });
+  }
+  isExact(error) {
+    if (!(error instanceof NiceError))
+      return false;
+    const errDef = error.def;
+    return errDef.domain === this.domain;
+  }
+  isThisOrChild(error) {
+    if (!(error instanceof NiceError))
+      return false;
+    const errDef = error.def;
+    return errDef.domain === this.domain || this.allDomains.includes(errDef.domain);
+  }
+  isParentOf(target) {
+    const allDomains = target instanceof NiceError ? target.def.allDomains : target.allDomains;
+    return Array.isArray(allDomains) && allDomains.includes(this.domain);
+  }
+  _buildDef() {
+    return {
+      domain: this.domain,
+      allDomains: this.allDomains,
+      schema: this._schema
+    };
+  }
+  _resolveMessage(id, context) {
+    const entry = this._schema[id];
+    if (typeof entry?.message === "function") {
+      return entry.message(context);
+    }
+    if (typeof entry?.message === "string") {
+      return entry.message;
+    }
+    return this.defaultMessage ?? `[${this.domain}::${id}] An error occurred.`;
+  }
+  _resolveHttpStatusCode(id, context) {
+    const entry = this._schema[id];
+    let httpStatusCode;
+    if (typeof entry?.httpStatusCode === "function") {
+      httpStatusCode = entry.httpStatusCode(context);
+    }
+    if (typeof entry?.httpStatusCode === "number") {
+      httpStatusCode = entry.httpStatusCode;
+    }
+    return typeof httpStatusCode === "number" ? httpStatusCode : this.defaultHttpStatusCode ?? 500;
+  }
+  reconcileErrorDataForId(id, context) {
+    const message = this._resolveMessage(id, context);
+    const httpStatusCode = this._resolveHttpStatusCode(id, context);
+    const entry = this._schema[id];
+    let contextState;
+    if (context != null && entry?.context?.serialization != null) {
+      const serialized = entry.context.serialization.toJsonSerializable(context);
+      contextState = { kind: "hydrated" /* hydrated */, value: context, serialized };
+    } else {
+      contextState = { kind: "serde_unset" /* serde_unset */, value: context };
+    }
+    return { contextState, message, httpStatusCode, timeAdded: Date.now() };
+  }
+}
+
+// src/NiceErrorDefined/defineNiceError.ts
+var defineNiceError = (definition) => {
+  return new NiceErrorDomain({
+    domain: definition.domain,
+    allDomains: [definition.domain],
+    schema: definition.schema,
+    ...definition.packAs != null ? { packAs: definition.packAs } : {}
+  });
+};
+
+// src/NiceErrorDefined/err.ts
+function err(meta) {
+  return meta ?? {};
+}
+
+// src/internal/nice_core_errors.ts
+var err_nice = defineNiceError({
+  domain: "err_nice",
+  schema: {}
+});
+var EErrId_CastNotNice;
+((EErrId_CastNotNice2) => {
+  EErrId_CastNotNice2["js_error"] = "native_error";
+  EErrId_CastNotNice2["js_error_like_object"] = "js_error_like_object";
+  EErrId_CastNotNice2["nullish_value"] = "nullish_value";
+  EErrId_CastNotNice2["js_data_type"] = "js_data_type";
+  EErrId_CastNotNice2["js_other"] = "js_other";
+})(EErrId_CastNotNice ||= {});
+var err_cast_not_nice = err_nice.createChildDomain({
+  domain: "err_cast_not_nice",
+  defaultHttpStatusCode: StatusCodes.UNPROCESSABLE_ENTITY,
+  schema: {
+    ["native_error" /* js_error */]: err({
+      context: {
+        required: true
+      },
+      message: ({ jsError }) => `A native JavaScript Error was encountered during casting: ${jsError.message}`,
+      httpStatusCode: StatusCodes.INTERNAL_SERVER_ERROR
+    }),
+    ["js_error_like_object" /* js_error_like_object */]: err({
+      context: {
+        required: true
+      },
+      message: ({ jsErrorObject }) => `An object resembling a JavaScript Error was encountered during casting: [${jsErrorObject.name}] ${jsErrorObject.message}`,
+      httpStatusCode: StatusCodes.INTERNAL_SERVER_ERROR
+    }),
+    ["nullish_value" /* nullish_value */]: err({
+      context: {
+        required: true
+      },
+      message: ({ value }) => `A nullish value [${value === null ? "null" : "undefined"}] was encountered during casting`
+    }),
+    ["js_data_type" /* js_data_type */]: err({
+      context: {
+        required: true
+      },
+      message: ({ jsDataType, jsDataValue }) => {
+        let inspectedValue;
+        try {
+          inspectedValue = JSON.stringify(jsDataValue);
+        } catch {}
+        return `A value of type [${jsDataType}] with value [${inspectedValue ?? "UNSERIALIZABLE"}] was encountered during casting, which is not a valid error type`;
+      }
+    }),
+    ["js_other" /* js_other */]: err({
+      context: {
+        required: true
+      },
+      message: ({ jsDataValue }) => {
+        let inspectedValue;
+        try {
+          inspectedValue = JSON.stringify(jsDataValue);
+        } catch {}
+        return `An unhandled type [${typeof jsDataValue}] with value [${inspectedValue ?? "UNSERIALIZABLE"}] was encountered during casting, which is not a valid error type`;
+      }
+    })
+  }
+});
+var err_nice_handler = err_nice.createChildDomain({
+  domain: "err_nice_handler",
+  schema: {}
+});
+// src/NiceErrorHandler/NiceErrorHandler.types.ts
+var EErrorHandlerTargetType;
+((EErrorHandlerTargetType2) => {
+  EErrorHandlerTargetType2["ids"] = "ids";
+  EErrorHandlerTargetType2["domain"] = "domain";
+  EErrorHandlerTargetType2["default"] = "default";
+})(EErrorHandlerTargetType ||= {});
+
+// src/NiceErrorHandler/NiceErrorHandler.ts
+class NiceErrorHandler {
+  handlerConfigs = [];
+  _defaultRequester;
+  handleErrorWithPromiseInspection(error, options) {
+    for (const handlerConfig of this.handlerConfigs) {
+      if (!handlerConfig._matcher(error))
+        continue;
+      const errorResult = handlerConfig._requester(error);
+      if (errorResult instanceof Promise) {
+        return {
+          isPromise: true,
+          matched: true,
+          target: handlerConfig.target,
+          handlerPromise: errorResult
+        };
+      }
+      return {
+        isPromise: false,
+        matched: true,
+        target: handlerConfig.target,
+        handlerResponse: errorResult
+      };
+    }
+    if (this._defaultRequester) {
+      const defaultResult = this._defaultRequester(error);
+      if (defaultResult instanceof Promise) {
+        return {
+          isPromise: true,
+          matched: true,
+          target: {
+            type: "default" /* default */,
+            identifier: "[matched:default]"
+          },
+          handlerPromise: defaultResult
+        };
+      }
+      return {
+        isPromise: false,
+        matched: true,
+        target: { type: "default" /* default */, identifier: "[matched:default]" },
+        handlerResponse: defaultResult
+      };
+    }
+    if (options?.throwOnUnhandled === true) {
+      throw error;
+    }
+    return {
+      matched: false,
+      attemptedTargets: this.handlerConfigs.map((config) => config.target)
+    };
+  }
+  forDomain(domain, handler) {
+    this.handlerConfigs.push({
+      target: {
+        type: "domain" /* domain */,
+        domain: domain.domain,
+        identifier: `[matched:domain:${domain.domain}]`
+      },
+      _matcher: (error) => domain.isExact(error),
+      _requester: (error) => handler(domain.hydrate(error))
+    });
+    return this;
+  }
+  forId(domain, id, handler) {
+    this.handlerConfigs.push({
+      target: {
+        type: "ids" /* ids */,
+        domain: domain.domain,
+        ids: [id],
+        identifier: `[matched:ids:${domain.domain}:${id}]`
+      },
+      _matcher: (error) => domain.isExact(error) && error.hasId(id),
+      _requester: (error) => handler(domain.hydrate(error))
+    });
+    return this;
+  }
+  forIds(domain, ids, handler) {
+    this.handlerConfigs.push({
+      target: {
+        type: "ids" /* ids */,
+        domain: domain.domain,
+        ids,
+        identifier: `[matched:ids:${domain.domain}:${ids.join(",")}]`
+      },
+      _matcher: (error) => domain.isExact(error) && ids.some((id) => error.hasId(id)),
+      _requester: (error) => handler(domain.hydrate(error))
+    });
+    return this;
+  }
+  setDefaultHandler(handler) {
+    this._defaultRequester = handler;
+    return this;
+  }
+}
+
+// src/NiceErrorHandler/handleWith.ts
+function forDomain(domain, handler) {
+  return new NiceErrorHandler().forDomain(domain, handler);
+}
+function forId(domain, id, handler) {
+  return new NiceErrorHandler().forId(domain, id, handler);
+}
+function forIds(domain, ids, handler) {
+  return new NiceErrorHandler().forIds(domain, ids, handler);
+}
+// src/utils/isNiceErrorObject.ts
+function isNiceErrorObject(obj) {
+  if (typeof obj !== "object" || obj == null)
+    return false;
+  const o = obj;
+  if (o["name"] !== "NiceError" || typeof o["message"] !== "string" || typeof o["wasntNice"] !== "boolean" || typeof o["httpStatusCode"] !== "number") {
+    return false;
+  }
+  const def = o["def"];
+  if (typeof def !== "object" || def == null)
+    return false;
+  const d = def;
+  if (typeof d["domain"] !== "string" || !Array.isArray(d["allDomains"]))
+    return false;
+  const errorData = o["errorData"];
+  if (errorData != null) {
+    if (typeof errorData !== "object")
+      return false;
+    for (const entry of Object.values(errorData)) {
+      if (entry == null)
+        continue;
+      if (typeof entry !== "object")
+        return false;
+      const e = entry;
+      const state = e["contextState"];
+      if (state == null || typeof state !== "object")
+        return false;
+      const kind = state["kind"];
+      if (kind !== "serde_unset" /* serde_unset */ && kind !== "unhydrated" /* unhydrated */)
+        return false;
+    }
+  }
+  return true;
+}
+
+// src/utils/isRegularErrorObject.ts
+function isRegularErrorJsonObject(obj) {
+  if (typeof obj !== "object" || obj == null)
+    return false;
+  const o = obj;
+  return typeof o["name"] === "string" && typeof o["message"] === "string";
+}
+
+// src/utils/logger.ts
+import { Logger } from "tslog";
+var logger_NiceError = new Logger({
+  name: "NiceErrorLogger"
+});
+var logger_NiceError_testing = logger_NiceError.getSubLogger({
+  name: "NiceErrorTestingLogger"
+});
+
+// src/utils/inspectPotentialError/inspectPotentialError.ts
+function interpretMessagePackedError(parsedError) {
+  let packedErrorStr;
+  if (typeof parsedError.message === "string" && parsedError.message.includes(DUR_OBJ_PACK_PREFIX) && parsedError.message.includes(DUR_OBJ_PACK_SUFFIX)) {
+    packedErrorStr = parsedError.message;
+  }
+  if (typeof parsedError.cause === "string" && parsedError.cause.includes(DUR_OBJ_PACK_PREFIX) && parsedError.cause.includes(DUR_OBJ_PACK_SUFFIX)) {
+    packedErrorStr = parsedError.cause;
+  }
+  if (packedErrorStr != null) {
+    const jsonStr = packedErrorStr.split(DUR_OBJ_PACK_PREFIX)[1].split(DUR_OBJ_PACK_SUFFIX)[0];
+    try {
+      const errorObj = JSON.parse(jsonStr);
+      if (isNiceErrorObject(errorObj)) {
+        return {
+          type: "niceErrorObject" /* niceErrorObject */,
+          niceErrorObject: errorObj
+        };
+      }
+    } catch {}
+  }
+  return null;
+}
+var inspectPotentialError = (potentialError) => {
+  if (potentialError == null) {
+    return {
+      type: "nullish" /* nullish */,
+      value: potentialError
+    };
+  }
+  if (typeof potentialError === "number") {
+    return {
+      type: "jsDataType" /* jsDataType */,
+      jsDataType: "number",
+      jsDataValue: potentialError
+    };
+  }
+  if (typeof potentialError === "boolean") {
+    return {
+      type: "jsDataType" /* jsDataType */,
+      jsDataType: "boolean",
+      jsDataValue: potentialError
+    };
+  }
+  let parsedError = potentialError;
+  if (typeof potentialError === "string") {
+    if (potentialError.includes("{") && potentialError.includes("name")) {
+      try {
+        parsedError = JSON.parse(potentialError);
+      } catch {
+        return {
+          type: "jsDataType" /* jsDataType */,
+          jsDataType: "string",
+          jsDataValue: potentialError
+        };
+      }
+    } else {
+      return {
+        type: "jsDataType" /* jsDataType */,
+        jsDataType: "string",
+        jsDataValue: potentialError
+      };
+    }
+  }
+  if (typeof parsedError !== "object" || parsedError == null) {
+    logger_NiceError.warn({
+      message: "Received a potential error that is a primitive data type other than string, number, or boolean. This is unexpected and may indicate an issue with error handling in the code.",
+      potentialError
+    });
+    return {
+      jsDataValue: potentialError,
+      type: "jsOther" /* jsOther */
+    };
+  }
+  if (parsedError instanceof NiceError) {
+    return {
+      type: "niceError" /* niceError */,
+      niceError: parsedError
+    };
+  }
+  if (isNiceErrorObject(parsedError)) {
+    return {
+      type: "niceErrorObject" /* niceErrorObject */,
+      niceErrorObject: parsedError
+    };
+  }
+  if (parsedError instanceof Error) {
+    const durObjResult = interpretMessagePackedError(parsedError);
+    if (durObjResult != null) {
+      return durObjResult;
+    }
+    return {
+      type: "jsError" /* jsError */,
+      jsError: parsedError
+    };
+  }
+  if (isRegularErrorJsonObject(parsedError)) {
+    const durObjResult = interpretMessagePackedError(parsedError);
+    if (durObjResult != null) {
+      return durObjResult;
+    }
+    return {
+      type: "jsErrorObject" /* jsErrorObject */,
+      jsErrorObject: parsedError
+    };
+  }
+  return {
+    type: "jsDataType" /* jsDataType */,
+    jsDataType: "object",
+    jsDataValue: parsedError
+  };
+};
+
+// src/utils/castNiceError.ts
+var castNiceError = (error) => {
+  const inspected = inspectPotentialError(error);
+  switch (inspected.type) {
+    case "niceError" /* niceError */:
+      return inspected.niceError;
+    case "niceErrorObject" /* niceErrorObject */: {
+      const obj = inspected.niceErrorObject;
+      return new NiceError(obj);
+    }
+    case "jsError" /* jsError */: {
+      return err_cast_not_nice.fromContext({
+        ["native_error" /* js_error */]: inspected
+      }).withOriginError(inspected.jsError);
+    }
+    case "jsErrorObject" /* jsErrorObject */: {
+      const err2 = err_cast_not_nice.fromContext({
+        ["js_error_like_object" /* js_error_like_object */]: inspected
+      });
+      err2.cause = inspected.jsErrorObject;
+      return err2;
+    }
+    case "nullish" /* nullish */:
+      return err_cast_not_nice.fromContext({
+        ["nullish_value" /* nullish_value */]: inspected
+      });
+    case "jsDataType" /* jsDataType */: {
+      return err_cast_not_nice.fromContext({
+        ["js_data_type" /* js_data_type */]: inspected
+      });
+    }
+    default:
+      return err_cast_not_nice.fromContext({
+        ["js_other" /* js_other */]: inspected
+      });
+  }
+};
+
+// src/utils/castAndHydrate.ts
+function castAndHydrate(value, niceErrorDefined) {
+  const casted = castNiceError(value);
+  if (niceErrorDefined.isExact(casted)) {
+    return niceErrorDefined.hydrate(casted);
+  }
+  return casted;
+}
+// src/utils/matchFirst.ts
+function matchFirst(error, handlers) {
+  for (const id of error.getIds()) {
+    const handler = handlers[id];
+    if (typeof handler === "function") {
+      const context = error.getContext(id);
+      return handler(context);
+    }
+  }
+  if (typeof handlers._ === "function") {
+    return handlers._();
+  }
+  return;
+}
+export {
+  msgPack,
+  matchFirst,
+  isRegularErrorJsonObject,
+  isNiceErrorObject,
+  forIds,
+  forId,
+  forDomain,
+  err_nice_handler,
+  err_nice,
+  err_cast_not_nice,
+  err,
+  defineNiceError,
+  causePack,
+  castNiceError,
+  castAndHydrate,
+  NiceErrorHydrated,
+  NiceErrorHandler,
+  NiceErrorDomain,
+  NiceError,
+  EErrorPackType,
+  EErrorHandlerTargetType,
+  EErrId_CastNotNice
+};

package/package.json

@@ -4,7 +4,7 @@
   "module": "build/index.js",
   "types": "build/types/index.d.ts",
   "type": "module",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "exports": {
     ".": {
       "types": "./build/types/index.d.ts",