@nice-code/error 0.10.0 → 0.12.0

package/build/index.cjs

@@ -0,0 +1,1056 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let http_status_codes = require("http-status-codes");
+let tslog = require("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
+	};
+}
+//#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;
+};
+//#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;
+};
+//#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);
+};
+//#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;
+	}
+};
+//#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 ?? {};
+}
+//#endregion
+//#region src/internal/nice_core_errors.ts
+const err_nice = defineNiceError({
+	domain: "err_nice",
+	schema: {}
+});
+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: http_status_codes.StatusCodes.UNPROCESSABLE_ENTITY,
+	schema: {
+		["native_error"]: err({
+			context: { required: true },
+			message: ({ jsError }) => `A native JavaScript Error was encountered during casting: ${jsError.message}`,
+			httpStatusCode: http_status_codes.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: http_status_codes.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`;
+			}
+		})
+	}
+});
+const err_nice_handler = err_nice.createChildDomain({
+	domain: "err_nice_handler",
+	schema: {}
+});
+//#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);
+}
+function forId(domain, id, handler) {
+	return new NiceErrorHandler().forId(domain, id, handler);
+}
+function forIds(domain, ids, handler) {
+	return new NiceErrorHandler().forIds(domain, ids, handler);
+}
+//#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 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;
+}
+//#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";
+}
+//#endregion
+//#region src/utils/logger.ts
+const logger_NiceError = new tslog.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("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;
+}
+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
+	};
+};
+//#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 });
+	}
+};
+//#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;
+}
+//#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") return handler(error.getContext(id));
+	}
+	if (typeof handlers._ === "function") return handlers._();
+}
+//#endregion
+exports.EErrId_CastNotNice = EErrId_CastNotNice;
+exports.EErrorHandlerTargetType = EErrorHandlerTargetType;
+exports.EErrorPackType = EErrorPackType;
+exports.NiceError = NiceError;
+exports.NiceErrorDomain = NiceErrorDomain;
+exports.NiceErrorHandler = NiceErrorHandler;
+exports.NiceErrorHydrated = NiceErrorHydrated;
+exports.castAndHydrate = castAndHydrate;
+exports.castNiceError = castNiceError;
+exports.causePack = causePack;
+exports.defineNiceError = defineNiceError;
+exports.err = err;
+exports.err_cast_not_nice = err_cast_not_nice;
+exports.err_nice = err_nice;
+exports.err_nice_handler = err_nice_handler;
+exports.forDomain = forDomain;
+exports.forId = forId;
+exports.forIds = forIds;
+exports.isNiceErrorObject = isNiceErrorObject;
+exports.isRegularErrorJsonObject = isRegularErrorJsonObject;
+exports.matchFirst = matchFirst;
+exports.msgPack = msgPack;
+
+//# sourceMappingURL=index.cjs.map