@nice-code/error 0.8.0 → 0.9.0

package/build/index.js

@@ -1,963 +1,1034 @@
-// src/internal/nice_core_errors.ts
 import { StatusCodes } from "http-status-codes";
-
-// src/utils/jsErrorOrCastJsError.ts
+import { Logger } from "tslog";
+//#region 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
-  };
+	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;
+//#endregion
+//#region src/NiceError/nice_error.static.ts
+const DUR_OBJ_PACK_PREFIX = "NE_DUROBJ[[";
+const DUR_OBJ_PACK_SUFFIX = "]]NE_DUROBJ";
+//#endregion
+//#region src/utils/packError/packError.enums.ts
+let EErrorPackType = /* @__PURE__ */ function(EErrorPackType) {
+	EErrorPackType["no_pack"] = "no_pack";
+	EErrorPackType["msg_pack"] = "msg_pack";
+	EErrorPackType["cause_pack"] = "cause_pack";
+	return EErrorPackType;
+}({});
+//#endregion
+//#region src/utils/packError/causePack.ts
+const causePack = (error) => {
+	error._packedState = {
+		cause: error.cause,
+		packedAs: "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;
+//#endregion
+//#region src/utils/packError/msgPack.ts
+const msgPack = (error) => {
+	error._packedState = {
+		message: error.cleanMessage,
+		packedAs: "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);
+//#endregion
+//#region src/utils/packError/packError.ts
+const 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
-    };
-  }
-  toJSON() {
-    return this.toJsonObject();
-  }
-  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;
-    const err = this.createError({
-      def: this._buildDef(),
-      niceErrorDefined: this,
-      ids: [id],
-      errorData,
-      message: reconciledData.cleanMessage ?? reconciledData.message,
-      httpStatusCode: reconciledData.httpStatusCode
-    });
-    if (typeof Error.captureStackTrace === "function") {
-      Error.captureStackTrace(err, this.fromId);
-    }
-    return err;
-  }
-  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];
-    const err = this.createError({
-      def: this._buildDef(),
-      niceErrorDefined: this,
-      ids,
-      errorData,
-      message: errorData[primaryId].cleanMessage ?? errorData[primaryId].message,
-      httpStatusCode: errorData[primaryId].httpStatusCode
-    });
-    if (typeof Error.captureStackTrace === "function") {
-      Error.captureStackTrace(err, this.fromContext);
-    }
-    return err;
-  }
-  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 } : {}
-  });
+//#endregion
+//#region src/NiceError/NiceError.ts
+var NiceError = class extends Error {
+	name = "NiceError";
+	def;
+	/** Primary id is first entry in ids. */
+	ids;
+	wasntNice;
+	httpStatusCode;
+	timeCreated;
+	cleanMessage;
+	originError;
+	_packedState;
+	/** Internal: all active id → reconciled data pairs. */
+	_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();
+	}
+	/**
+	* Type guard: returns `true` if this error was created with (or contains) the
+	* given `id`. After the guard, `getContext(id)` will be strongly typed.
+	*/
+	hasId(id) {
+		return id in this._errorDataMap;
+	}
+	/**
+	* Returns `true` if this error contains **at least one** of the supplied ids.
+	* Narrows `ACTIVE_IDS` to the matching subset of `IDS`.
+	*/
+	hasOneOfIds(ids) {
+		return ids.some((id) => id in this._errorDataMap);
+	}
+	/** `true` when this error was created with more than one id (via `fromContext`). */
+	get hasMultiple() {
+		return Object.keys(this._errorDataMap).length > 1;
+	}
+	/** Returns all active error ids on this instance. */
+	getIds() {
+		return Object.keys(this._errorDataMap);
+	}
+	/**
+	* Returns the typed context value for the given error id.
+	*
+	* TypeScript will only allow you to call this with an id that is part of
+	* `ACTIVE_IDS` (i.e. an id confirmed via `hasId` / `hasOneOfIds`, or passed
+	* to `fromId` / `fromContext`).
+	*
+	* @throws If the context is in the `"unhydrated"` state — the error was
+	* reconstructed from a JSON payload and its context has a custom serializer
+	* that hasn't been run yet. Call `niceErrorDefined.hydrate(error)` first.
+	*/
+	getContext(id) {
+		const state = this._errorDataMap[id]?.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") this.cause = this.originError;
+		return this;
+	}
+	/**
+	* Returns `true` if `other` has the same domain and the exact same set of
+	* active error ids as this error (order-independent).
+	*
+	* Useful for deduplication, retry logic, and asserting that two errors
+	* represent the same "kind" of problem without comparing context values.
+	*
+	* ```ts
+	* const a = err_auth.fromId("invalid_credentials", { username: "alice" });
+	* const b = err_auth.fromId("invalid_credentials", { username: "bob" });
+	* a.matches(b); // true  — same domain + same id set
+	*
+	* const c = err_auth.fromId("account_locked");
+	* a.matches(c); // false — same domain, different id
+	* ```
+	*/
+	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
+		} : void 0;
+		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") contextState = {
+				kind: "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
+		};
+	}
+	toJSON() {
+		return this.toJsonObject();
+	}
+	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);
+	}
+	/**
+	* Iterates `cases` in order, finds the first whose domain matches this error
+	* (via `is()`), optionally further filters by active ids, hydrates the error,
+	* calls the handler, and returns `true`. Returns `false` if no case matched.
+	*
+	* Build cases with `forDomain` (any id in the domain) or `forIds` (specific
+	* id subset). Handlers are invoked synchronously — any returned Promise is
+	* not awaited. Use `handleWithAsync` when handlers are async.
+	*
+	* @example
+	* ```ts
+	* const handled = error.handleWith([
+	*   forIds(err_feature, ["not_found"], (h) => {
+	*     res.status(404).json({ missing: h.getContext("not_found").resource });
+	*   }),
+	*   forDomain(err_feature, (h) => {
+	*     matchFirst(h, {
+	*       forbidden: ({ userId }) => res.status(403).json({ userId }),
+	*       _: () => res.status(500).end(),
+	*     });
+	*   }),
+	*   forDomain(err_service, (h) => {
+	*     res.status(h.httpStatusCode).json({ error: h.message });
+	*   }),
+	* ]);
+	* if (!handled) next(error);
+	* ```
+	*/
+	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 ? void 0 : result.handlerResponse;
+			}
+		}
+		if (handlerOptions.throwOnUnhandled === true) throw this;
+	}
+	/**
+	* Same matching logic as `handleWith`, but `await`s the handler's returned
+	* Promise before resolving. Use this when your handlers perform async work
+	* (database writes, HTTP calls, etc.).
+	*
+	* @example
+	* ```ts
+	* const handled = await error.handleWithAsync([
+	*   forDomain(err_payments, async (h) => {
+	*     await db.logFailedPayment(h);
+	*     await notifyOps(h.message);
+	*   }),
+	* ]);
+	* ```
+	*/
+	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;
+	}
+	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") this.message = this._packedState.message;
+		if (this._packedState.packedAs === "cause_pack") this.cause = this._packedState.cause;
+		this._packedState = void 0;
+		delete this._packedState;
+		return this;
+	}
 };
-
-// src/NiceErrorDefined/err.ts
+//#endregion
+//#region src/NiceError/NiceErrorHydrated.ts
+var NiceErrorHydrated = class NiceErrorHydrated extends NiceError {
+	def;
+	niceErrorDefined;
+	constructor(options) {
+		super(options);
+		this.def = options.def;
+		this.niceErrorDefined = options.niceErrorDefined;
+	}
+	/**
+	* Returns a **new** `NiceErrorHydrated` with additional id+context entries merged in.
+	* The returned error's `ACTIVE_IDS` is the union of the original ids and the
+	* newly supplied keys.
+	*
+	* ```ts
+	* const err = errDef.fromId("id_a", { a: 1 })
+	*   .addContext({ id_b: { b: "x" } });
+	* err.getIds(); // ["id_a", "id_b"]
+	* ```
+	*/
+	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
+		});
+	}
+	/**
+	* Returns a **new** `NiceErrorHydrated` with an additional error id (and its context,
+	* if the schema requires one). Equivalent to `addContext({ [id]: context })`
+	* but mirrors the `fromId` ergonomics for single-id additions.
+	*/
+	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
+		});
+	}
+};
+//#endregion
+//#region src/NiceErrorDefined/NiceErrorDefined.ts
+var NiceErrorDomain = class NiceErrorDomain {
+	domain;
+	allDomains;
+	defaultHttpStatusCode;
+	defaultMessage;
+	/** Kept for runtime use (message resolution, httpStatusCode, context serialization, etc.). */
+	_schema;
+	_definedChildNiceErrors = [];
+	_definedParentNiceError;
+	/** Set by `.packAs()` — explicit per-instance override, takes priority over `_packAsFn`. */
+	_setPack;
+	/** Set at definition time — called dynamically each time an error is created. */
+	_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;
+	}
+	/**
+	* Creates a child domain that inherits this domain in `allDomains`.
+	* The child has its own schema and its own domain string.
+	*/
+	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;
+	}
+	/**
+	* Promotes a plain `NiceError<ERR_DEF>` back into a `NiceErrorHydrated` so
+	* that builder methods (`addId`, `addContext`, etc.) are available again.
+	*
+	* For each active id, if the context is in the `"unhydrated"` state (i.e. the
+	* error was reconstructed from a JSON payload), `hydrate` calls
+	* `fromJsonSerializable` to reconstruct the typed value and advances the state
+	* to `"hydrated"`. Ids already in `"hydrated"` or `"raw_unset"` state
+	* are passed through unchanged.
+	*
+	* @throws If `error.def.domain` does not match this definition's domain. Use
+	* `niceErrorDefined.is(error)` before calling `hydrate` to ensure compatibility.
+	*
+	* ```ts
+	* const raw = castNiceError(apiResponseBody);
+	*
+	* if (err_user_auth.is(raw)) {
+	*   const hydrated = err_user_auth.hydrate(raw);
+	*   // hydrated.getContext("invalid_credentials") — fully typed, no throw
+	*   // hydrated.addId / addContext — available again
+	* }
+	* ```
+	*/
+	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 deserialize = this._schema[id]?.context?.serialization?.fromJsonSerializable;
+				if (deserialize != null) contextState = {
+					kind: "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
+		});
+	}
+	/**
+	* Creates a `NiceErrorHydrated` for a single error id.
+	*
+	* - `id` autocompletes to the schema keys.
+	* - The second argument `context` is required / optional / absent based on
+	*   whether the schema entry declares `context.required: true`.
+	* - The returned error has `ACTIVE_IDS` narrowed to exactly `K`, so
+	*   `getContext(id)` is immediately strongly typed.
+	*/
+	fromId(...args) {
+		const [id, context] = args;
+		const reconciledData = this.reconcileErrorDataForId(id, context);
+		const errorData = {};
+		errorData[id] = reconciledData;
+		const err = this.createError({
+			def: this._buildDef(),
+			niceErrorDefined: this,
+			ids: [id],
+			errorData,
+			message: reconciledData.cleanMessage ?? reconciledData.message,
+			httpStatusCode: reconciledData.httpStatusCode
+		});
+		if (typeof Error.captureStackTrace === "function") Error.captureStackTrace(err, this.fromId);
+		return err;
+	}
+	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];
+		const err = this.createError({
+			def: this._buildDef(),
+			niceErrorDefined: this,
+			ids,
+			errorData,
+			message: errorData[primaryId].cleanMessage ?? errorData[primaryId].message,
+			httpStatusCode: errorData[primaryId].httpStatusCode
+		});
+		if (typeof Error.captureStackTrace === "function") Error.captureStackTrace(err, this.fromContext);
+		return err;
+	}
+	/**
+	* Returns `true` if `error` is a `NiceError` whose `def.domain` exactly matches
+	* this definition's domain.
+	*
+	* Use this after `castNiceError` to narrow an unknown error to this specific
+	* domain before accessing its typed ids/context:
+	*
+	* ```ts
+	* const caught = castNiceError(e);
+	*
+	* if (err_user_auth.is(caught)) {
+	*   // caught is now NiceError<typeof err_user_auth's ERR_DEF>
+	*   const hydrated = err_user_auth.hydrate(caught);
+	*   const { username } = hydrated.getContext("invalid_credentials");
+	* }
+	* ```
+	*/
+	isExact(error) {
+		if (!(error instanceof NiceError)) return false;
+		return error.def.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);
+	}
+	/**
+	* Returns `true` if this domain appears anywhere in the target's ancestry
+	* chain (including an exact domain match).
+	*
+	* Accepts either a `NiceErrorDefined` (domain definition) or a `NiceError`
+	* instance (extracts the domain from its `def`).
+	*/
+	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) contextState = {
+			kind: "hydrated",
+			value: context,
+			serialized: entry.context.serialization.toJsonSerializable(context)
+		};
+		else contextState = {
+			kind: "serde_unset",
+			value: context
+		};
+		return {
+			contextState,
+			message,
+			httpStatusCode,
+			timeAdded: Date.now()
+		};
+	}
+};
+//#endregion
+//#region src/NiceErrorDefined/defineNiceError.ts
+const defineNiceError = (definition) => {
+	return new NiceErrorDomain({
+		domain: definition.domain,
+		allDomains: [definition.domain],
+		schema: definition.schema,
+		...definition.packAs != null ? { packAs: definition.packAs } : {}
+	});
+};
+//#endregion
+//#region src/NiceErrorDefined/err.ts
 function err(meta) {
-  return meta ?? {};
+	return meta ?? {};
 }
-
-// src/internal/nice_core_errors.ts
-var err_nice = defineNiceError({
-  domain: "err_nice",
-  schema: {}
+//#endregion
+//#region src/internal/nice_core_errors.ts
+const 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`;
-      }
-    })
-  }
+let EErrId_CastNotNice = /* @__PURE__ */ function(EErrId_CastNotNice) {
+	EErrId_CastNotNice["js_error"] = "native_error";
+	EErrId_CastNotNice["js_error_like_object"] = "js_error_like_object";
+	EErrId_CastNotNice["nullish_value"] = "nullish_value";
+	EErrId_CastNotNice["js_data_type"] = "js_data_type";
+	EErrId_CastNotNice["js_other"] = "js_other";
+	return EErrId_CastNotNice;
+}({});
+const err_cast_not_nice = err_nice.createChildDomain({
+	domain: "err_cast_not_nice",
+	defaultHttpStatusCode: StatusCodes.UNPROCESSABLE_ENTITY,
+	schema: {
+		["native_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"]: 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"]: err({
+			context: { required: true },
+			message: ({ value }) => `A nullish value [${value === null ? "null" : "undefined"}] was encountered during casting`
+		}),
+		["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"]: 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: {}
+const 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
+//#endregion
+//#region src/NiceErrorHandler/NiceErrorHandler.types.ts
+let EErrorHandlerTargetType = /* @__PURE__ */ function(EErrorHandlerTargetType) {
+	EErrorHandlerTargetType["ids"] = "ids";
+	EErrorHandlerTargetType["domain"] = "domain";
+	EErrorHandlerTargetType["default"] = "default";
+	return EErrorHandlerTargetType;
+}({});
+//#endregion
+//#region src/NiceErrorHandler/NiceErrorHandler.ts
+var NiceErrorHandler = class {
+	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",
+					identifier: "[matched:default]"
+				},
+				handlerPromise: defaultResult
+			};
+			return {
+				isPromise: false,
+				matched: true,
+				target: {
+					type: "default",
+					identifier: "[matched:default]"
+				},
+				handlerResponse: defaultResult
+			};
+		}
+		if (options?.throwOnUnhandled === true) throw error;
+		return {
+			matched: false,
+			attemptedTargets: this.handlerConfigs.map((config) => config.target)
+		};
+	}
+	/**
+	* Register a handler that fires for **any** error whose domain matches `domain`.
+	* The handler receives a fully hydrated error — `getContext`, `addId`, and `addContext`
+	* are all available. First matching case wins.
+	*/
+	forDomain(domain, handler) {
+		this.handlerConfigs.push({
+			target: {
+				type: "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",
+				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",
+				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;
+	}
+	/**
+	* Register a fallback handler that fires when no other case matches.
+	* Only one default handler can be registered — calling this twice replaces the previous one.
+	*/
+	setDefaultHandler(handler) {
+		this._defaultRequester = handler;
+		return this;
+	}
+};
+//#endregion
+//#region src/NiceErrorHandler/handleWith.ts
 function forDomain(domain, handler) {
-  return new NiceErrorHandler().forDomain(domain, handler);
+	return new NiceErrorHandler().forDomain(domain, handler);
 }
 function forId(domain, id, handler) {
-  return new NiceErrorHandler().forId(domain, id, handler);
+	return new NiceErrorHandler().forId(domain, id, handler);
 }
 function forIds(domain, ids, handler) {
-  return new NiceErrorHandler().forIds(domain, ids, handler);
+	return new NiceErrorHandler().forIds(domain, ids, handler);
 }
-// src/utils/isNiceErrorObject.ts
+//#endregion
+//#region src/utils/isNiceErrorObject.ts
+/**
+* Returns `true` if `obj` is a JSON-serialised `NiceError` object matching the
+* current wire format (contextState-based errorData entries).
+*
+* Validates:
+* - Top-level shape (`name`, `message`, `wasntNice`, `httpStatusCode`, `def`)
+* - Each `errorData` entry has a `contextState` with a valid `kind` discriminant
+*   (`"no_serialization"` or `"unhydrated"`) — rejecting payloads in the old
+*   format (`context` / `serialized` fields) to prevent silent data corruption.
+*/
 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;
+	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 state = entry["contextState"];
+			if (state == null || typeof state !== "object") return false;
+			const kind = state["kind"];
+			if (kind !== "serde_unset" && kind !== "unhydrated") return false;
+		}
+	}
+	return true;
 }
-
-// src/utils/isRegularErrorObject.ts
+//#endregion
+//#region 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";
+	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
+//#endregion
+//#region src/utils/logger.ts
+const logger_NiceError = new Logger({ name: "NiceErrorLogger" });
+logger_NiceError.getSubLogger({ name: "NiceErrorTestingLogger" });
+//#endregion
+//#region 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;
+	let packedErrorStr;
+	if (typeof parsedError.message === "string" && parsedError.message.includes("NE_DUROBJ[[") && parsedError.message.includes("]]NE_DUROBJ")) packedErrorStr = parsedError.message;
+	if (typeof parsedError.cause === "string" && parsedError.cause.includes("NE_DUROBJ[[") && parsedError.cause.includes("]]NE_DUROBJ")) 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: 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
-  };
+const inspectPotentialError = (potentialError) => {
+	if (potentialError == null) return {
+		type: "nullish",
+		value: potentialError
+	};
+	if (typeof potentialError === "number") return {
+		type: "jsDataType",
+		jsDataType: "number",
+		jsDataValue: potentialError
+	};
+	if (typeof potentialError === "boolean") return {
+		type: "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: "string",
+			jsDataValue: potentialError
+		};
+	}
+	else return {
+		type: "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"
+		};
+	}
+	if (parsedError instanceof NiceError) return {
+		type: "niceError",
+		niceError: parsedError
+	};
+	if (isNiceErrorObject(parsedError)) return {
+		type: "niceErrorObject",
+		niceErrorObject: parsedError
+	};
+	if (parsedError instanceof Error) {
+		const durObjResult = interpretMessagePackedError(parsedError);
+		if (durObjResult != null) return durObjResult;
+		return {
+			type: "jsError",
+			jsError: parsedError
+		};
+	}
+	if (isRegularErrorJsonObject(parsedError)) {
+		const durObjResult = interpretMessagePackedError(parsedError);
+		if (durObjResult != null) return durObjResult;
+		return {
+			type: "jsErrorObject",
+			jsErrorObject: parsedError
+		};
+	}
+	return {
+		type: "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
-      });
-  }
+//#endregion
+//#region src/utils/castNiceError.ts
+/**
+* Casts any unknown value into a `NiceError`.
+*
+* - If the value is already a `NiceError` instance, it is returned as-is.
+* - If the value is a plain `Error`, it is wrapped with the original as `originError`.
+* - If the value is a JSON-serialised `NiceError` object (e.g. from an API
+*   response), a best-effort `NiceError` is re-created from it.
+* - For all other values, a generic `NiceError` is created with a descriptive
+*   message.
+*
+* After casting, use `NiceErrorDefined.is(error)` to narrow the error to a
+* specific domain and access its strongly-typed ids and context.
+*/
+const castNiceError = (error) => {
+	const inspected = inspectPotentialError(error);
+	switch (inspected.type) {
+		case "niceError": return inspected.niceError;
+		case "niceErrorObject": {
+			const obj = inspected.niceErrorObject;
+			return new NiceError(obj);
+		}
+		case "jsError": return err_cast_not_nice.fromContext({ ["native_error"]: inspected }).withOriginError(inspected.jsError);
+		case "jsErrorObject": {
+			const err = err_cast_not_nice.fromContext({ ["js_error_like_object"]: inspected });
+			err.cause = inspected.jsErrorObject;
+			return err;
+		}
+		case "nullish": return err_cast_not_nice.fromContext({ ["nullish_value"]: inspected });
+		case "jsDataType": return err_cast_not_nice.fromContext({ ["js_data_type"]: inspected });
+		default: return err_cast_not_nice.fromContext({ ["js_other"]: inspected });
+	}
 };
-
-// src/utils/castAndHydrate.ts
+//#endregion
+//#region src/utils/castAndHydrate.ts
+/**
+* Combines `castNiceError`, `is()`, and `hydrate()` in a single call — the
+* idiomatic way to handle an unknown value arriving from a remote boundary
+* (API response, message queue, IPC, etc.) when you have a specific domain in mind.
+*
+* - Casts `value` to a `NiceError` using `castNiceError`.
+* - If the result belongs to `niceErrorDefined`'s domain (`is()` returns `true`),
+*   hydrates it and returns a fully-typed `NiceErrorHydrated`.
+* - Otherwise returns the raw cast `NiceError` (which may be a `wasntNice` error
+*   if `value` was not a NiceError at all).
+*
+* @example
+* ```ts
+* // In an Express error handler:
+* app.use((err, req, res, next) => {
+*   const error = castAndHydrate(err, err_user_auth);
+*
+*   if (err_user_auth.is(error)) {
+*     // error is NiceErrorHydrated — getContext / addId available
+*     const result = matchFirst(error, {
+*       invalid_credentials: ({ username }) => res.status(401).json({ username }),
+*       account_locked:      ()             => res.status(403).json({ locked: true }),
+*     });
+*     if (result) return;
+*   }
+*
+*   next(err);
+* });
+* ```
+*/
 function castAndHydrate(value, niceErrorDefined) {
-  const casted = castNiceError(value);
-  if (niceErrorDefined.isExact(casted)) {
-    return niceErrorDefined.hydrate(casted);
-  }
-  return casted;
+	const casted = castNiceError(value);
+	if (niceErrorDefined.isExact(casted)) return niceErrorDefined.hydrate(casted);
+	return casted;
 }
-// src/utils/matchFirst.ts
+//#endregion
+//#region src/utils/matchFirst.ts
+/**
+* Pattern-matches an error against a map of id → handler functions, returning the
+* result of the first handler whose id is active on the error.
+*
+* - Ids are tested in the order returned by `error.getIds()`.
+* - If no id-specific handler matched and `_` is provided, the fallback is called.
+* - Returns `undefined` when neither any id handler nor the fallback fires.
+*
+* **Requires hydrated context.** If any matched id is in the `"unhydrated"` state,
+* `getContext` will throw. Call `niceErrorDefined.hydrate(error)` beforehand when
+* working with errors deserialized from a JSON payload.
+*
+* @example
+* ```ts
+* const result = matchFirst(error, {
+*   invalid_credentials: ({ username }) => `Wrong password for ${username}`,
+*   account_locked:      ()             => "Account is locked",
+*   _:                   ()             => "Unknown auth error",
+* });
+* ```
+*/
 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;
+	for (const id of error.getIds()) {
+		const handler = handlers[id];
+		if (typeof handler === "function") return handler(error.getContext(id));
+	}
+	if (typeof handlers._ === "function") return handlers._();
 }
-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
-};
+//#endregion
+export { EErrId_CastNotNice, EErrorHandlerTargetType, EErrorPackType, NiceError, NiceErrorDomain, NiceErrorHandler, NiceErrorHydrated, castAndHydrate, castNiceError, causePack, defineNiceError, err, err_cast_not_nice, err_nice, err_nice_handler, forDomain, forId, forIds, isNiceErrorObject, isRegularErrorJsonObject, matchFirst, msgPack };
+
+//# sourceMappingURL=index.js.map