@nice-code/error 0.0.15

package/build/types/NiceError/NiceError.d.ts

@@ -0,0 +1,141 @@
+import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
+import type { IErrorCase } from "../utils/handleWith";
+import { EErrorPackType } from "../utils/packError/packError.enums";
+import { type INiceErrorDefinedProps, type INiceErrorJsonObject, type IRegularErrorJsonObject, type TErrorDataForIdMap, type TErrorReconciledData, type TExtractContextType, type TNiceErrorSchema, type TUnknownNiceErrorDef } from "./NiceError.types";
+import type { NiceErrorHydrated } from "./NiceErrorHydrated";
+type ContextOf<S extends TNiceErrorSchema, K extends keyof S> = TExtractContextType<S[K]>;
+/** Full-featured construction from NiceErrorDefined.fromId / fromContext. */
+export interface INiceErrorOptions<ERR_DEF extends INiceErrorDefinedProps, ID extends keyof ERR_DEF["schema"]> {
+    def: Omit<ERR_DEF, "schema">;
+    /** Primary id is first entry in ids. */
+    ids: ID[];
+    /** All active ids with their messages, http status codes, and context state. */
+    errorData: TErrorDataForIdMap<ERR_DEF["schema"]>;
+    message: string;
+    wasntNice?: boolean;
+    httpStatusCode?: number;
+    originError?: IRegularErrorJsonObject | undefined;
+}
+export declare class NiceError<ERR_DEF extends INiceErrorDefinedProps = TUnknownNiceErrorDef, 
+/**
+ * Union of active error-id keys.
+ * - After `fromId(id)`: exactly one key.
+ * - After `fromContext({...})`: a union of all supplied keys.
+ * - After `hasOneOfIds([a,b])`: narrows to that subset.
+ * - Default (bare construction / castNiceError): `TUnknownNiceErrorId`.
+ */
+ACTIVE_IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> extends Error {
+    readonly name: "NiceError";
+    readonly def: Omit<ERR_DEF, "schema">;
+    /** Primary id is first entry in ids. */
+    readonly ids: ACTIVE_IDS[];
+    readonly wasntNice: boolean;
+    readonly httpStatusCode: number;
+    originError?: IRegularErrorJsonObject;
+    _packedState?: {
+        packedAs: EErrorPackType.cause_pack;
+        cause: unknown;
+    } | {
+        packedAs: EErrorPackType.msg_pack;
+        message: string;
+    } | undefined;
+    /** Internal: all active id → reconciled data pairs. */
+    protected readonly _errorDataMap: TErrorDataForIdMap<ERR_DEF["schema"]>;
+    constructor(options: INiceErrorOptions<ERR_DEF, ACTIVE_IDS>);
+    /**
+     * 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 extends keyof ERR_DEF["schema"] & string>(id: ID): this is NiceError<ERR_DEF, ID>;
+    /**
+     * Returns `true` if this error contains **at least one** of the supplied ids.
+     * Narrows `ACTIVE_IDS` to the matching subset of `IDS`.
+     */
+    hasOneOfIds<IDS extends ReadonlyArray<keyof ERR_DEF["schema"] & string>>(ids: IDS): this is NiceError<ERR_DEF, IDS[number]>;
+    /** `true` when this error was created with more than one id (via `fromContext`). */
+    get hasMultiple(): boolean;
+    /** Returns all active error ids on this instance. */
+    getIds(): Array<ACTIVE_IDS>;
+    /**
+     * 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 extends ACTIVE_IDS>(id: ID): ContextOf<ERR_DEF["schema"], ID>;
+    getErrorDataForId<ID extends ACTIVE_IDS>(id: ID): TErrorReconciledData<ERR_DEF["schema"], ID> | undefined;
+    withOriginError(error: unknown): 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: NiceError<any, any>): boolean;
+    toJsonObject(): INiceErrorJsonObject<ERR_DEF>;
+    hydrate(definedNiceError: NiceErrorDefined<ERR_DEF>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS>;
+    /**
+     * 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);
+     * ```
+     */
+    handleWith(cases: ReadonlyArray<IErrorCase<any, any>>): boolean;
+    /**
+     * 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);
+     *   }),
+     * ]);
+     * ```
+     */
+    handleWithAsync(cases: ReadonlyArray<IErrorCase<any, any>>): Promise<boolean>;
+    get isPacked(): boolean;
+    pack(packType?: EErrorPackType): this;
+    unpack(): this;
+}
+export {};

package/build/types/NiceError/NiceError.enums.d.ts

@@ -0,0 +1,5 @@
+export declare enum EContextSerializedState {
+    serde_unset = "serde_unset",
+    unhydrated = "unhydrated",
+    hydrated = "hydrated"
+}

package/build/types/NiceError/NiceError.types.d.ts

@@ -0,0 +1,199 @@
+import type { EErrorPackType } from "../utils/packError/packError.enums";
+import type { EContextSerializedState } from "./NiceError.enums";
+export interface IRegularErrorJsonObject extends Omit<Error, "stack"> {
+    name: string;
+    message: string;
+    stack?: string | undefined;
+    cause?: unknown;
+}
+export type JSONSerializableValue = string | number | boolean | null | {
+    [key: string]: JSONSerializableValue;
+} | JSONSerializableValue[];
+interface ISerializationDefinition<C, D extends JSONSerializableValue> {
+    toJsonSerializable: (context: C) => D;
+    fromJsonSerializable: (obj: D) => C;
+}
+/** Describes the context attached to a single error id. */
+export interface INiceErrorContextDefinition<C, D extends JSONSerializableValue = JSONSerializableValue> {
+    required?: boolean;
+    serialization?: ISerializationDefinition<C, D>;
+}
+/**
+ * A single entry in a NiceErrorDefined schema.
+ * `C` is the context value type (defaults to `never` = no context).
+ */
+export interface INiceErrorIdMetadata<C = never, D extends JSONSerializableValue = JSONSerializableValue> {
+    context?: [C] extends [never] ? never : INiceErrorContextDefinition<C, D>;
+    /** Static message string OR a function that receives the context value and returns a string. */
+    message?: [C] extends [never] ? string : string | ((context: C) => string);
+    httpStatusCode?: [C] extends [never] ? number : number | ((context: C) => number);
+}
+/** A record mapping error-id string keys to their metadata. */
+export type TNiceErrorSchema = Record<string, INiceErrorIdMetadata<any>>;
+/** Extracts the raw context value type `C` from a single schema entry. */
+export type TExtractContextType<M> = M extends INiceErrorIdMetadata<infer C> ? C : never;
+/**
+ * Given a schema entry M, returns the context argument type expected by `fromId`:
+ *
+ * - `C = never`                     → `undefined`  (no context field on this id)
+ * - `C` defined, `required: true`   → `C`          (context is a required argument)
+ * - `C` defined, `required` absent/false → `C | undefined` (context is optional)
+ *
+ * Note: `required: true` must be a literal `true` for TypeScript to narrow correctly.
+ * Use the `err()` helper (which preserves literal types) rather than writing schema
+ * entries inline without `as const`.
+ */
+export type ExtractFromIdContextArg<M> = M extends INiceErrorIdMetadata<infer C> ? [C] extends [never] ? undefined : M extends {
+    context: {
+        required: true;
+    };
+} ? C : C | undefined : undefined;
+/**
+ * No custom serializer is defined for this error id's context.
+ * `value` holds the typed context directly (plain JSON-safe value, or `undefined`
+ * if the context was optional and not provided).
+ *
+ * This state is safe across a JSON round-trip because no type information is lost.
+ */
+export type TContextStateNoSerialization<C> = {
+    kind: EContextSerializedState.serde_unset;
+    /** The typed context value (or `undefined` if optional and not provided). */
+    value: C | undefined;
+};
+/**
+ * A custom serializer is defined, but the context has **not** been deserialized
+ * from its JSON-wire form yet.
+ *
+ * This state occurs after `castNiceError` reconstructs an error from a serialized
+ * payload. `value` is absent — the raw serialized representation is in `serialized`.
+ *
+ * Call `niceErrorDefined.hydrate(error)` to reconstruct the typed context via
+ * `fromJsonSerializable` and advance to the `"hydrated"` state.
+ */
+export type TContextStateUnhydrated = {
+    kind: EContextSerializedState.unhydrated;
+    /** The JSON-serializable representation of the original context. */
+    serialized: JSONSerializableValue;
+};
+/**
+ * A custom serializer is defined, and the context is fully deserialized to its
+ * original typed value.
+ *
+ * This state is set when the error is first created via `fromId`/`fromContext`,
+ * or after `niceErrorDefined.hydrate(error)` reconstructs it.
+ *
+ * Note: `toJsonObject()` intentionally downgrades this to `"unhydrated"` on
+ * output so the flag cannot survive a JSON round-trip as a false positive.
+ */
+export type TContextStateHydrated<C> = {
+    kind: EContextSerializedState.hydrated;
+    /** The typed context value — the original value as provided at error creation. */
+    value: C;
+    /** The JSON-serializable representation (produced by `toJsonSerializable`). */
+    serialized: JSONSerializableValue;
+};
+/**
+ * Runtime context state — union of all three lifecycle states.
+ * Stored in `_errorDataMap` on a live `NiceError` instance.
+ */
+export type TContextState<C> = TContextStateNoSerialization<C> | TContextStateUnhydrated | TContextStateHydrated<C>;
+/**
+ * Wire-safe context state — excludes `"hydrated"` because `toJsonObject()` downgrades
+ * it to `"unhydrated"` before serialization. This is the only state that appears in
+ * `INiceErrorJsonObject` and on errors reconstructed via `castNiceError`.
+ */
+export type TSerializedContextState<C> = TContextStateNoSerialization<C> | TContextStateUnhydrated;
+/**
+ * Runtime reconciled data for a single error id, stored in `_errorDataMap`.
+ * Uses the full `TContextState` union (including `"hydrated"`).
+ */
+export type TErrorReconciledData<SCHEMA extends TNiceErrorSchema, K extends keyof SCHEMA> = {
+    contextState: TContextState<TExtractContextType<SCHEMA[K]>>;
+    message: string;
+    httpStatusCode: number;
+};
+/**
+ * Wire-safe reconciled data — uses `TSerializedContextState` (no `"hydrated"`).
+ * This is the shape stored in `INiceErrorJsonObject.errorData` and transmitted
+ * over the wire. `"hydrated"` is excluded so that the serialization state can
+ * never be trusted after a JSON round-trip.
+ */
+export type TSerializedErrorReconciledData<SCHEMA extends TNiceErrorSchema, K extends keyof SCHEMA> = {
+    contextState: TSerializedContextState<TExtractContextType<SCHEMA[K]>>;
+    message: string;
+    httpStatusCode: number;
+};
+export type TErrorDataForIdMap<SCHEMA extends TNiceErrorSchema> = {
+    [K in keyof SCHEMA]?: TErrorReconciledData<SCHEMA, K>;
+};
+/** Wire-safe version of `TErrorDataForIdMap`. Used in `INiceErrorJsonObject`. */
+export type TSerializedErrorDataMap<SCHEMA extends TNiceErrorSchema> = {
+    [K in keyof SCHEMA]?: TSerializedErrorReconciledData<SCHEMA, K>;
+};
+/**
+ * The Partial record that `fromContext` accepts: callers supply one or more
+ * { [errorId]: contextValue } entries and NiceError stores them all.
+ */
+export type TFromContextInput<SCHEMA extends TNiceErrorSchema> = {
+    [K in keyof SCHEMA]?: TExtractContextType<SCHEMA[K]> | undefined;
+};
+/**
+ * Resolves the args tuple for `fromId` / `addId`:
+ *
+ * - No context on this id                  → `[id]`
+ * - Context defined, `required: true`      → `[id, context]`
+ * - Context defined, `required` absent/false → `[id] | [id, context]`
+ */
+export type FromIdArgs<ERR_DEF extends INiceErrorDefinedProps, K extends keyof ERR_DEF["schema"]> = [ExtractFromIdContextArg<ERR_DEF["schema"][K]>] extends [undefined] ? [id: K] : [undefined] extends [ExtractFromIdContextArg<ERR_DEF["schema"][K]>] ? [id: K] | [id: K, context: NonNullable<ExtractFromIdContextArg<ERR_DEF["schema"][K]>>] : [id: K, context: ExtractFromIdContextArg<ERR_DEF["schema"][K]>];
+export interface IPackErrorAs_Base {
+    packAs: EErrorPackType;
+}
+export interface IPackErrorAs_MatchEnvVar extends IPackErrorAs_Base {
+    matchEnvVar: string;
+}
+export interface IDefineNewNiceErrorDomainOptions<ERR_DOMAIN extends string = string, SCHEMA extends TNiceErrorSchema = TNiceErrorSchema> {
+    defaultHttpStatusCode?: number;
+    defaultMessage?: string;
+    packAs?: () => EErrorPackType | void;
+    domain: ERR_DOMAIN;
+    schema: SCHEMA;
+}
+export interface INiceErrorDefinedProps<ERR_DOMAINS extends string[] = string[], SCHEMA extends TNiceErrorSchema = TNiceErrorSchema> {
+    packAs?: () => EErrorPackType | void;
+    defaultHttpStatusCode?: number;
+    defaultMessage?: string;
+    domain: ERR_DOMAINS[number];
+    allDomains: ERR_DOMAINS;
+    schema: SCHEMA;
+}
+export interface INiceErrorJsonObject<ERR_DEF extends INiceErrorDefinedProps = INiceErrorDefinedProps, ID extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> {
+    name: "NiceError";
+    def: Omit<ERR_DEF, "schema">;
+    ids: ID[];
+    /** Wire-safe error data — context is in `"raw_unset"` or `"unhydrated"` state only. */
+    errorData: TSerializedErrorDataMap<ERR_DEF["schema"]>;
+    wasntNice: boolean;
+    message: string;
+    httpStatusCode: number;
+    /** The stack trace of the NiceError at the point it was created. */
+    stack?: string;
+    cause?: unknown;
+    originError?: IRegularErrorJsonObject | undefined;
+}
+/**
+ * The widest ERR_DEF used when creating a NiceError without a definition
+ * (bare construction, castNiceError, etc.).
+ *
+ * Uses the base `INiceErrorDefinedProps` defaults (`string[]` domains,
+ * `TNiceErrorSchema` schema) so that type-guard narrowing via `is()` works
+ * correctly — `string & "specific_domain"` narrows to `"specific_domain"`
+ * instead of collapsing the intersection to `never`.
+ */
+export type TUnknownNiceErrorDef = INiceErrorDefinedProps;
+/**
+ * Wide id type for bare / cast NiceErrors that have no schema.
+ * Using `string` (rather than a literal `"unknown"`) ensures that
+ * `is()` type-guard intersections narrow cleanly: `string & K` = `K`.
+ */
+export type TUnknownNiceErrorId = string;
+export {};

package/build/types/NiceError/NiceErrorHydrated.d.ts

@@ -0,0 +1,49 @@
+import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
+import { type INiceErrorOptions, NiceError } from "./NiceError";
+import type { ExtractFromIdContextArg, INiceErrorDefinedProps, TFromContextInput, TUnknownNiceErrorDef } from "./NiceError.types";
+/**
+ * Resolves the args tuple for `addId` — mirrors `FromIdArgs` exactly so that
+ * optional vs required context is consistent across both `fromId` and `addId`.
+ *
+ * - No context on this id                   → `[id]`
+ * - Context defined, `required: true`       → `[id, context]`
+ * - Context defined, `required` absent/false → `[id] | [id, context]`
+ */
+type AddIdArgs<ERR_DEF extends INiceErrorDefinedProps, K extends keyof ERR_DEF["schema"] & string> = [ExtractFromIdContextArg<ERR_DEF["schema"][K]>] extends [undefined] ? [id: K] : [undefined] extends [ExtractFromIdContextArg<ERR_DEF["schema"][K]>] ? [id: K] | [id: K, context: NonNullable<ExtractFromIdContextArg<ERR_DEF["schema"][K]>>] : [id: K, context: ExtractFromIdContextArg<ERR_DEF["schema"][K]>];
+/** Full-featured construction from NiceErrorDefined.fromId / fromContext. */
+export interface INiceErrorHydratedOptions<ERR_DEF extends INiceErrorDefinedProps, ID extends keyof ERR_DEF["schema"] & string> extends INiceErrorOptions<ERR_DEF, ID> {
+    def: ERR_DEF;
+    niceErrorDefined: NiceErrorDefined<ERR_DEF>;
+}
+export declare class NiceErrorHydrated<ERR_DEF extends INiceErrorDefinedProps = TUnknownNiceErrorDef, 
+/**
+ * Union of active error-id keys.
+ * - After `fromId(id)`: exactly one key.
+ * - After `fromContext({...})`: a union of all supplied keys.
+ * - After `hasOneOfIds([a,b])`: narrows to that subset.
+ * - Default (bare construction / castNiceError): `TUnknownNiceErrorId`.
+ */
+ACTIVE_IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> extends NiceError<ERR_DEF, ACTIVE_IDS> {
+    readonly def: ERR_DEF;
+    private readonly niceErrorDefined;
+    constructor(options: INiceErrorHydratedOptions<ERR_DEF, ACTIVE_IDS>);
+    /**
+     * 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<INPUT extends TFromContextInput<ERR_DEF["schema"]>>(context: INPUT & Record<Exclude<keyof INPUT, keyof ERR_DEF["schema"] & string>, never>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS | (keyof INPUT & string)>;
+    /**
+     * 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<K extends keyof ERR_DEF["schema"] & string>(...args: AddIdArgs<ERR_DEF, K>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS | K>;
+}
+export {};

package/build/types/NiceError/nice_error.static.d.ts

@@ -0,0 +1,2 @@
+export declare const DUR_OBJ_PACK_PREFIX = "NE_DUROBJ[[";
+export declare const DUR_OBJ_PACK_SUFFIX = "]]NE_DUROBJ";

package/build/types/NiceErrorDefined/NiceErrorDefined.d.ts

@@ -0,0 +1,135 @@
+import { NiceError } from "../NiceError/NiceError";
+import { type FromIdArgs, type IDefineNewNiceErrorDomainOptions, type INiceErrorDefinedProps, type TErrorReconciledData, type TFromContextInput } from "../NiceError/NiceError.types";
+import { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
+import { type EErrorPackType } from "../utils/packError/packError.enums";
+type ChildDef<PARENT_DEF extends INiceErrorDefinedProps, SUB extends IDefineNewNiceErrorDomainOptions> = {
+    domain: SUB["domain"];
+    allDomains: [SUB["domain"], ...PARENT_DEF["allDomains"]];
+    schema: SUB["schema"];
+};
+/**
+ * Extracts the union of keys present in a `TFromContextInput` object.
+ * e.g. `{ invalid_credentials: {...} }` → `"invalid_credentials"`
+ */
+type KeysOfContextInput<INPUT> = keyof INPUT & string;
+/**
+ * Infers the strongly-typed `NiceError` class type from a `NiceErrorDefined` instance.
+ *
+ * `ACTIVE_IDS` is set to the full union of all schema keys. Use `hasId` /
+ * `hasOneOfIds` to narrow further at the call site.
+ *
+ * @example
+ * ```ts
+ * const err_user_auth = defineNiceError({ domain: "err_user_auth", schema: { ... } });
+ * type TUserAuthError = InferNiceError<typeof err_user_auth>;
+ * // → NiceError<{ domain: "err_user_auth"; ... }, keyof schema>
+ * ```
+ */
+export type InferNiceError<T extends NiceErrorDefined<any>> = T extends NiceErrorDefined<infer ERR_DEF> ? NiceError<ERR_DEF, keyof ERR_DEF["schema"] & string> : never;
+/**
+ * Infers the strongly-typed `NiceErrorHydrated` class type from a `NiceErrorDefined` instance.
+ *
+ * Use this when you need the builder methods (`addId`, `addContext`) as part of
+ * the inferred type — e.g. for function return types or variable annotations.
+ *
+ * @example
+ * ```ts
+ * const err_user_auth = defineNiceError({ domain: "err_user_auth", schema: { ... } });
+ * type TUserAuthErrorHydrated = InferNiceErrorHydrated<typeof err_user_auth>;
+ * // → NiceErrorHydrated<{ domain: "err_user_auth"; ... }, keyof schema>
+ * ```
+ */
+export type InferNiceErrorHydrated<T extends NiceErrorDefined<any>> = T extends NiceErrorDefined<infer ERR_DEF> ? NiceErrorHydrated<ERR_DEF, keyof ERR_DEF["schema"] & string> : never;
+export declare class NiceErrorDefined<ERR_DEF extends INiceErrorDefinedProps = INiceErrorDefinedProps> {
+    readonly domain: ERR_DEF["domain"];
+    readonly allDomains: ERR_DEF["allDomains"];
+    readonly defaultHttpStatusCode?: number;
+    readonly defaultMessage?: string;
+    /** Kept for runtime use (message resolution, httpStatusCode, context serialization, etc.). */
+    private readonly _schema;
+    private _definedChildNiceErrors;
+    private _definedParentNiceError?;
+    /** Set by `.packAs()` — explicit per-instance override, takes priority over `_packAsFn`. */
+    private _setPack?;
+    /** Set at definition time — called dynamically each time an error is created. */
+    private _packAsFn?;
+    constructor(definition: ERR_DEF);
+    /**
+     * Creates a child domain that inherits this domain in `allDomains`.
+     * The child has its own schema and its own domain string.
+     */
+    createChildDomain<SUB extends IDefineNewNiceErrorDomainOptions>(subErrorDef: SUB & {
+        [K in Exclude<keyof SUB, keyof IDefineNewNiceErrorDomainOptions>]: never;
+    }): NiceErrorDefined<ChildDef<ERR_DEF, SUB>>;
+    protected addParentNiceErrorDefined<PARENT_DEF extends INiceErrorDefinedProps>(parentError: NiceErrorDefined<PARENT_DEF>): void;
+    protected addChildNiceErrorDefined<CHILD_DEF extends INiceErrorDefinedProps>(child: NiceErrorDefined<CHILD_DEF>): void;
+    packAs(pack: EErrorPackType): this;
+    private createError;
+    /**
+     * 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<ACTIVE_IDS extends keyof ERR_DEF["schema"] & string>(error: NiceError<ERR_DEF, ACTIVE_IDS>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS>;
+    /**
+     * 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<K extends keyof ERR_DEF["schema"] & string>(...args: FromIdArgs<ERR_DEF, K>): NiceErrorHydrated<ERR_DEF, K>;
+    fromContext<INPUT extends TFromContextInput<ERR_DEF["schema"]>>(context: INPUT & Record<Exclude<keyof INPUT, keyof ERR_DEF["schema"]>, never>): NiceErrorHydrated<ERR_DEF, KeysOfContextInput<INPUT>>;
+    /**
+     * 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: unknown): error is NiceError<ERR_DEF, keyof ERR_DEF["schema"] & string>;
+    isThisOrChild(error: unknown): boolean;
+    /**
+     * 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: NiceErrorDefined<any> | NiceError<any, any>): boolean;
+    private _buildDef;
+    private _resolveMessage;
+    private _resolveHttpStatusCode;
+    reconcileErrorDataForId(id: keyof ERR_DEF["schema"] & string, context: TFromContextInput<ERR_DEF["schema"]>[typeof id]): TErrorReconciledData<ERR_DEF["schema"], typeof id>;
+}
+export {};

package/build/types/NiceErrorDefined/defineNiceError.d.ts

@@ -0,0 +1,7 @@
+import type { IDefineNewNiceErrorDomainOptions, TNiceErrorSchema } from "../NiceError/NiceError.types";
+import { NiceErrorDefined } from "./NiceErrorDefined";
+export declare const defineNiceError: <ERR_DOMAIN extends string, SCHEMA extends TNiceErrorSchema>(definition: IDefineNewNiceErrorDomainOptions<ERR_DOMAIN, SCHEMA>) => NiceErrorDefined<{
+    domain: ERR_DOMAIN;
+    allDomains: [ERR_DOMAIN];
+    schema: SCHEMA;
+}>;

package/build/types/NiceErrorDefined/err.d.ts

@@ -0,0 +1,59 @@
+import type { INiceErrorContextDefinition, INiceErrorIdMetadata, JSONSerializableValue } from "../NiceError/NiceError.types";
+/**
+ * Schema entry factory — the idiomatic way to define a single error id in a
+ * `NiceErrorDefined` schema.
+ *
+ * Using `err()` instead of writing schema entries as plain object literals
+ * ensures TypeScript resolves the context argument as **required** vs **optional**
+ * correctly in `fromId` / `addId` call sites.
+ *
+ * How `required` affects the call site:
+ *
+ * | Schema entry                       | `fromId("id")` | `fromId("id", ctx)` |
+ * |------------------------------------|----------------|---------------------|
+ * | `err()`  /  `err({ ... })`         | ✓              | ✗ (no context)      |
+ * | `err<C>({ context: {} })`          | ✓              | ✓ (optional ctx)    |
+ * | `err<C>({ context: { required: true } })` | ✗     | ✓ (required ctx)    |
+ *
+ * @example
+ * ```ts
+ * // No context — `fromId("not_found")` takes no second argument.
+ * not_found: err({ message: "Resource not found", httpStatusCode: 404 }),
+ *
+ * // Optional context — second arg accepted but not required.
+ * rate_limited: err<{ retryAfter: number }>({
+ *   message: (ctx) => ctx ? `Retry after ${ctx.retryAfter}s` : "Rate limited",
+ *   httpStatusCode: 429,
+ *   context: {},
+ * }),
+ *
+ * // Required context — `fromId("invalid_input", { field: "email" })` (second arg is required).
+ * invalid_input: err<{ field: string }>({
+ *   message: ({ field }) => `Invalid value for field: ${field}`,
+ *   httpStatusCode: 422,
+ *   context: { required: true },
+ * }),
+ *
+ * // Required context with custom serialization (for non-JSON-safe context values).
+ * fs_error: err<{ cause: NodeJS.ErrnoException }>({
+ *   message: ({ cause }) => `File system error: ${cause.message}`,
+ *   context: {
+ *     required: true,
+ *     serialization: {
+ *       toJsonSerializable: ({ cause }) => ({ code: cause.code, message: cause.message }),
+ *       fromJsonSerializable: (obj) => ({ cause: Object.assign(new Error(obj.message), obj) }),
+ *     },
+ *   },
+ * }),
+ * ```
+ */
+export declare function err<C, D extends JSONSerializableValue = Record<string, any>>(meta: INiceErrorIdMetadata<C, D> & {
+    context: INiceErrorContextDefinition<C, D> & {
+        required: true;
+    };
+}): INiceErrorIdMetadata<C> & {
+    context: {
+        required: true;
+    };
+};
+export declare function err<C = never>(meta?: INiceErrorIdMetadata<C>): INiceErrorIdMetadata<C>;

package/build/types/example/error_usage_example.d.ts

@@ -0,0 +1,41 @@
+export declare const err_example_app: import("..").NiceErrorDefined<{
+    domain: "err_example_app";
+    allDomains: ["err_example_app"];
+    schema: {};
+}>;
+export declare enum EErrId_UserAuth {
+    invalid_credentials = "invalid_credentials",
+    account_locked = "account_locked"
+}
+export declare const err_user_auth: import("..").NiceErrorDefined<{
+    domain: string;
+    allDomains: [string, "err_example_app"];
+    schema: {
+        invalid_credentials: import("..").INiceErrorIdMetadata<{
+            username: string;
+        }, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+        account_locked: import("..").INiceErrorIdMetadata<any, import("..").JSONSerializableValue>;
+    };
+}>;
+export declare enum EErrId_UserAuth_Registration {
+    password_error = "password_error",
+    password_too_short = "password_too_short"
+}
+export declare const err_user_auth_registration: import("..").NiceErrorDefined<{
+    domain: string;
+    allDomains: [string, string, "err_example_app"];
+    schema: {
+        password_too_short: import("..").INiceErrorIdMetadata<{
+            minLength: number;
+        }, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+        password_error: import("..").INiceErrorIdMetadata<any, import("..").JSONSerializableValue>;
+    };
+}>;

package/build/types/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./internal";
+export * from "./NiceError/NiceError";
+export * from "./NiceError/NiceError.types";
+export * from "./NiceError/NiceErrorHydrated";
+export * from "./NiceErrorDefined/defineNiceError";
+export * from "./NiceErrorDefined/err";
+export * from "./NiceErrorDefined/NiceErrorDefined";
+export * from "./utils/castAndHydrate";
+export * from "./utils/castNiceError";
+export * from "./utils/handleWith";
+export * from "./utils/isNiceErrorObject";
+export * from "./utils/isRegularErrorObject";
+export * from "./utils/matchFirst";
+export * from "./utils/packError/causePack";
+export * from "./utils/packError/msgPack";
+export * from "./utils/packError/packError.enums";

package/build/types/internal/index.d.ts

@@ -0,0 +1 @@
+export * from "./nice_core_errors";