@nice-code/error 0.0.20 → 0.1.0

package/README.md

@@ -1 +1,5 @@
 # @nice-code/error
+
+Typed, serializable errors with domain hierarchies, pattern matching, and safe transport across API boundaries.
+
+See the [main README](../../README.md) for full documentation and examples.

package/build/index.js

@@ -388,6 +388,7 @@ class NiceError extends Error {
   ids;
   wasntNice;
   httpStatusCode;
+  timeCreated;
   originError;
   _packedState;
   _errorDataMap;
@@ -401,6 +402,7 @@ class NiceError extends Error {
     if (options.originError != null) {
       this.originError = options.originError;
     }
+    this.timeCreated = options.timeCreated ?? Date.now();
   }
   hasId(id) {
     return id in this._errorDataMap;
@@ -478,7 +480,12 @@ class NiceError extends Error {
       } else {
         contextState = data.contextState;
       }
-      errorData[id] = { contextState, message: data.message, httpStatusCode: data.httpStatusCode };
+      errorData[id] = {
+        contextState,
+        message: data.message,
+        httpStatusCode: data.httpStatusCode,
+        timeAdded: data.timeAdded
+      };
     }
     return {
       name: "NiceError",
@@ -488,34 +495,49 @@ class NiceError extends Error {
       wasntNice: this.wasntNice,
       message: this.message,
       httpStatusCode: this.httpStatusCode,
+      timeCreated: this.timeCreated,
       ...this.stack != null ? { stack: this.stack } : {},
       originError
     };
   }
+  toJsonString() {
+    return JSON.stringify(this.toJsonObject());
+  }
+  toHttpResponse() {
+    return new Response(this.toJsonString(), {
+      status: this.httpStatusCode,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
   hydrate(definedNiceError) {
     return definedNiceError.hydrate(this);
   }
-  handleWith(cases) {
-    for (const c of cases) {
-      if (!c._domain.isExact(this))
-        continue;
-      if (c._ids != null && !this.hasOneOfIds(c._ids))
-        continue;
-      c._handler(c._domain.hydrate(this));
-      return true;
+  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;
+      }
     }
-    return false;
+    if (handlerOptions.throwOnUnhandled === true)
+      throw this;
+    return;
   }
-  async handleWithAsync(cases) {
-    for (const c of cases) {
-      if (!c._domain.isExact(this))
-        continue;
-      if (c._ids != null && !this.hasOneOfIds(c._ids))
-        continue;
-      await c._handler(c._domain.hydrate(this));
-      return true;
+  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;
+      }
     }
-    return false;
+    if (handlerOptions.throwOnUnhandled === true)
+      throw this;
+    return;
   }
   get isPacked() {
     return this._packedState != null;
@@ -595,7 +617,7 @@ class NiceErrorHydrated extends NiceError {
 }
 
 // src/NiceErrorDefined/NiceErrorDefined.ts
-class NiceErrorDefined {
+class NiceErrorDomain {
   domain;
   allDomains;
   defaultHttpStatusCode;
@@ -620,7 +642,7 @@ class NiceErrorDefined {
     }
   }
   createChildDomain(subErrorDef) {
-    const child = new NiceErrorDefined({
+    const child = new NiceErrorDomain({
       domain: subErrorDef.domain,
       allDomains: [subErrorDef.domain, ...this.allDomains],
       schema: subErrorDef.schema,
@@ -676,9 +698,10 @@ class NiceErrorDefined {
     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 error.getIds()) {
-      const existingData = error.getErrorDataForId(id);
+    for (const id of finalError.getIds()) {
+      const existingData = finalError.getErrorDataForId(id);
       if (existingData == null)
         continue;
       let contextState = existingData.contextState;
@@ -696,18 +719,20 @@ class NiceErrorDefined {
       reconciledErrorData[id] = {
         contextState,
         message: existingData.message,
-        httpStatusCode: existingData.httpStatusCode
+        httpStatusCode: existingData.httpStatusCode,
+        timeAdded: existingData.timeAdded
       };
     }
     return new NiceErrorHydrated({
       def: this._buildDef(),
       niceErrorDefined: this,
-      ids: error.ids,
+      ids: finalError.ids,
       errorData: reconciledErrorData,
-      message: error.message,
-      httpStatusCode: error.httpStatusCode,
-      wasntNice: error.wasntNice,
-      originError: error.originError
+      message: finalError.message,
+      httpStatusCode: finalError.httpStatusCode,
+      wasntNice: finalError.wasntNice,
+      originError: finalError.originError,
+      timeCreated: finalError.timeCreated
     });
   }
   fromId(...args) {
@@ -798,13 +823,13 @@ class NiceErrorDefined {
     } else {
       contextState = { kind: "serde_unset" /* serde_unset */, value: context };
     }
-    return { contextState, message, httpStatusCode };
+    return { contextState, message, httpStatusCode, timeAdded: Date.now() };
   }
 }
 
 // src/NiceErrorDefined/defineNiceError.ts
 var defineNiceError = (definition) => {
-  return new NiceErrorDefined({
+  return new NiceErrorDomain({
     domain: definition.domain,
     allDomains: [definition.domain],
     schema: definition.schema,
@@ -880,6 +905,124 @@ var err_cast_not_nice = err_nice.createChildDomain({
     })
   }
 });
+var err_nice_handler = err_nice.createChildDomain({
+  domain: "err_nice_handler",
+  schema: {}
+});
+// src/NiceErrorHandler/NiceErrorHandler.types.ts
+var EErrorHandlerTargetType;
+((EErrorHandlerTargetType2) => {
+  EErrorHandlerTargetType2["ids"] = "ids";
+  EErrorHandlerTargetType2["domain"] = "domain";
+  EErrorHandlerTargetType2["default"] = "default";
+})(EErrorHandlerTargetType ||= {});
+
+// src/NiceErrorHandler/NiceErrorHandler.ts
+class NiceErrorHandler {
+  handlerConfigs = [];
+  _defaultRequester;
+  handleErrorWithPromiseInspection(error, options) {
+    for (const handlerConfig of this.handlerConfigs) {
+      if (!handlerConfig._matcher(error))
+        continue;
+      const errorResult = handlerConfig._requester(error);
+      if (errorResult instanceof Promise) {
+        return {
+          isPromise: true,
+          matched: true,
+          target: handlerConfig.target,
+          handlerPromise: errorResult
+        };
+      }
+      return {
+        isPromise: false,
+        matched: true,
+        target: handlerConfig.target,
+        handlerResponse: errorResult
+      };
+    }
+    if (this._defaultRequester) {
+      const defaultResult = this._defaultRequester(error);
+      if (defaultResult instanceof Promise) {
+        return {
+          isPromise: true,
+          matched: true,
+          target: {
+            type: "default" /* default */,
+            identifier: "[matched:default]"
+          },
+          handlerPromise: defaultResult
+        };
+      }
+      return {
+        isPromise: false,
+        matched: true,
+        target: { type: "default" /* default */, identifier: "[matched:default]" },
+        handlerResponse: defaultResult
+      };
+    }
+    if (options?.throwOnUnhandled === true) {
+      throw error;
+    }
+    return {
+      matched: false,
+      attemptedTargets: this.handlerConfigs.map((config) => config.target)
+    };
+  }
+  forDomain(domain, handler) {
+    this.handlerConfigs.push({
+      target: {
+        type: "domain" /* domain */,
+        domain: domain.domain,
+        identifier: `[matched:domain:${domain.domain}]`
+      },
+      _matcher: (error) => domain.isExact(error),
+      _requester: (error) => handler(domain.hydrate(error))
+    });
+    return this;
+  }
+  forId(domain, id, handler) {
+    this.handlerConfigs.push({
+      target: {
+        type: "ids" /* ids */,
+        domain: domain.domain,
+        ids: [id],
+        identifier: `[matched:ids:${domain.domain}:${id}]`
+      },
+      _matcher: (error) => domain.isExact(error) && error.hasId(id),
+      _requester: (error) => handler(domain.hydrate(error))
+    });
+    return this;
+  }
+  forIds(domain, ids, handler) {
+    this.handlerConfigs.push({
+      target: {
+        type: "ids" /* ids */,
+        domain: domain.domain,
+        ids,
+        identifier: `[matched:ids:${domain.domain}:${ids.join(",")}]`
+      },
+      _matcher: (error) => domain.isExact(error) && ids.some((id) => error.hasId(id)),
+      _requester: (error) => handler(domain.hydrate(error))
+    });
+    return this;
+  }
+  setDefaultHandler(handler) {
+    this._defaultRequester = handler;
+    return this;
+  }
+}
+
+// src/NiceErrorHandler/handleWith.ts
+function forDomain(domain, handler) {
+  return new NiceErrorHandler().forDomain(domain, handler);
+}
+function forId(domain, id, handler) {
+  return new NiceErrorHandler().forId(domain, id, handler);
+}
+function forIds(domain, ids, handler) {
+  return new NiceErrorHandler().forIds(domain, ids, handler);
+}
 // src/utils/isNiceErrorObject.ts
 function isNiceErrorObject(obj) {
   if (typeof obj !== "object" || obj == null)
@@ -2704,13 +2847,6 @@ function castAndHydrate(value, niceErrorDefined) {
   }
   return casted;
 }
-// src/utils/handleWith.ts
-function forDomain(domain, handler) {
-  return { _domain: domain, _ids: undefined, _handler: handler };
-}
-function forIds(domain, ids, handler) {
-  return { _domain: domain, _ids: ids, _handler: handler };
-}
 // src/utils/matchFirst.ts
 function matchFirst(error, handlers) {
   for (const id of error.getIds()) {
@@ -2731,7 +2867,9 @@ export {
   isRegularErrorJsonObject,
   isNiceErrorObject,
   forIds,
+  forId,
   forDomain,
+  err_nice_handler,
   err_nice,
   err_cast_not_nice,
   err,
@@ -2740,8 +2878,10 @@ export {
   castNiceError,
   castAndHydrate,
   NiceErrorHydrated,
-  NiceErrorDefined,
+  NiceErrorHandler,
+  NiceErrorDomain,
   NiceError,
   EErrorPackType,
+  EErrorHandlerTargetType,
   EErrId_CastNotNice
 };

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

@@ -1,11 +1,12 @@
-import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
-import type { IErrorCase } from "../utils/handleWith";
+import type { NiceErrorDomain } from "../NiceErrorDefined/NiceErrorDefined";
+import type { NiceErrorHandler } from "../NiceErrorHandler/NiceErrorHandler";
+import type { IHandleErrorOptions } from "../NiceErrorHandler/NiceErrorHandler.types";
 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 INiceErrorDomainProps, type INiceErrorJsonObject, type IRegularErrorJsonObject, type TDomainNiceErrorId, 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"]> {
+export interface INiceErrorOptions<ERR_DEF extends INiceErrorDomainProps, ID extends TDomainNiceErrorId<ERR_DEF> = TDomainNiceErrorId<ERR_DEF>> {
     def: Omit<ERR_DEF, "schema">;
     /** Primary id is first entry in ids. */
     ids: ID[];
@@ -15,8 +16,9 @@ export interface INiceErrorOptions<ERR_DEF extends INiceErrorDefinedProps, ID ex
     wasntNice?: boolean;
     httpStatusCode?: number;
     originError?: IRegularErrorJsonObject | undefined;
+    timeCreated?: number;
 }
-export declare class NiceError<ERR_DEF extends INiceErrorDefinedProps = TUnknownNiceErrorDef, 
+export declare class NiceError<ERR_DEF extends INiceErrorDomainProps = TUnknownNiceErrorDef, 
 /**
  * Union of active error-id keys.
  * - After `fromId(id)`: exactly one key.
@@ -24,13 +26,14 @@ export declare class NiceError<ERR_DEF extends INiceErrorDefinedProps = TUnknown
  * - 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 {
+ACTIVE_IDS extends TDomainNiceErrorId<ERR_DEF> = TDomainNiceErrorId<ERR_DEF>> 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;
+    readonly timeCreated: number;
     originError?: IRegularErrorJsonObject;
     _packedState?: {
         packedAs: EErrorPackType.cause_pack;
@@ -88,7 +91,9 @@ ACTIVE_IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] &
      */
     matches(other: NiceError<any, any>): boolean;
     toJsonObject(): INiceErrorJsonObject<ERR_DEF>;
-    hydrate(definedNiceError: NiceErrorDefined<ERR_DEF>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS>;
+    toJsonString(): string;
+    toHttpResponse(): Response;
+    hydrate(definedNiceError: NiceErrorDomain<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,
@@ -117,7 +122,7 @@ ACTIVE_IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] &
      * if (!handled) next(error);
      * ```
      */
-    handleWith(cases: ReadonlyArray<IErrorCase<any, any>>): boolean;
+    handleWithSync<RD, R>(handlerInput: NiceErrorHandler<RD, R> | ReadonlyArray<NiceErrorHandler<RD, R>>, handlerOptions?: IHandleErrorOptions): R | RD | undefined;
     /**
      * Same matching logic as `handleWith`, but `await`s the handler's returned
      * Promise before resolving. Use this when your handlers perform async work
@@ -133,7 +138,7 @@ ACTIVE_IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] &
      * ]);
      * ```
      */
-    handleWithAsync(cases: ReadonlyArray<IErrorCase<any, any>>): Promise<boolean>;
+    handleWithAsync<RD, R>(handlerInput: NiceErrorHandler<RD, R> | ReadonlyArray<NiceErrorHandler<RD, R>>, handlerOptions?: IHandleErrorOptions): Promise<R | RD | undefined>;
     get isPacked(): boolean;
     pack(packType?: EErrorPackType): this;
     unpack(): this;

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

@@ -111,6 +111,7 @@ export type TErrorReconciledData<SCHEMA extends TNiceErrorSchema, K extends keyo
     contextState: TContextState<TExtractContextType<SCHEMA[K]>>;
     message: string;
     httpStatusCode: number;
+    timeAdded: number;
 };
 /**
  * Wire-safe reconciled data — uses `TSerializedContextState` (no `"hydrated"`).
@@ -118,24 +119,25 @@ export type TErrorReconciledData<SCHEMA extends TNiceErrorSchema, K extends keyo
  * 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> = {
+export type TSerializedErrorReconciledData<SCHEMA extends TNiceErrorSchema, K extends TSchemaNiceErrorId<SCHEMA>> = {
     contextState: TSerializedContextState<TExtractContextType<SCHEMA[K]>>;
     message: string;
     httpStatusCode: number;
+    timeAdded: number;
 };
-export type TErrorDataForIdMap<SCHEMA extends TNiceErrorSchema> = {
-    [K in keyof SCHEMA]?: TErrorReconciledData<SCHEMA, K>;
+export type TErrorDataForIdMap<SCHEMA extends TNiceErrorSchema, K extends TSchemaNiceErrorId<SCHEMA> = TSchemaNiceErrorId<SCHEMA>> = {
+    [key in K]?: TErrorReconciledData<SCHEMA, K>;
 };
 /** Wire-safe version of `TErrorDataForIdMap`. Used in `INiceErrorJsonObject`. */
 export type TSerializedErrorDataMap<SCHEMA extends TNiceErrorSchema> = {
-    [K in keyof SCHEMA]?: TSerializedErrorReconciledData<SCHEMA, K>;
+    [K in TSchemaNiceErrorId<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;
+    [K in TSchemaNiceErrorId<SCHEMA>]?: TExtractContextType<SCHEMA[K]> | undefined;
 };
 /**
  * Resolves the args tuple for `fromId` / `addId`:
@@ -144,7 +146,7 @@ export type TFromContextInput<SCHEMA extends TNiceErrorSchema> = {
  * - 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 type FromIdArgs<ERR_DEF extends INiceErrorDomainProps, K extends TDomainNiceErrorId<ERR_DEF>> = [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;
 }
@@ -158,7 +160,7 @@ export interface IDefineNewNiceErrorDomainOptions<ERR_DOMAIN extends string = st
     domain: ERR_DOMAIN;
     schema: SCHEMA;
 }
-export interface INiceErrorDefinedProps<ERR_DOMAINS extends string[] = string[], SCHEMA extends TNiceErrorSchema = TNiceErrorSchema> {
+export interface INiceErrorDomainProps<ERR_DOMAINS extends string[] = string[], SCHEMA extends TNiceErrorSchema = TNiceErrorSchema> {
     packAs?: () => EErrorPackType | void;
     defaultHttpStatusCode?: number;
     defaultMessage?: string;
@@ -166,7 +168,7 @@ export interface INiceErrorDefinedProps<ERR_DOMAINS extends string[] = string[],
     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> {
+export interface INiceErrorJsonObject<ERR_DEF extends INiceErrorDomainProps = INiceErrorDomainProps, ID extends TDomainNiceErrorId<ERR_DEF> = TDomainNiceErrorId<ERR_DEF>> {
     name: "NiceError";
     def: Omit<ERR_DEF, "schema">;
     ids: ID[];
@@ -179,7 +181,10 @@ export interface INiceErrorJsonObject<ERR_DEF extends INiceErrorDefinedProps = I
     stack?: string;
     cause?: unknown;
     originError?: IRegularErrorJsonObject | undefined;
+    timeCreated: number;
 }
+export type TSchemaNiceErrorId<SCHEMA extends TNiceErrorSchema> = keyof SCHEMA & string;
+export type TDomainNiceErrorId<ERR_DEF extends INiceErrorDomainProps> = TSchemaNiceErrorId<ERR_DEF["schema"]>;
 /**
  * The widest ERR_DEF used when creating a NiceError without a definition
  * (bare construction, castNiceError, etc.).
@@ -189,7 +194,7 @@ export interface INiceErrorJsonObject<ERR_DEF extends INiceErrorDefinedProps = I
  * correctly — `string & "specific_domain"` narrows to `"specific_domain"`
  * instead of collapsing the intersection to `never`.
  */
-export type TUnknownNiceErrorDef = INiceErrorDefinedProps;
+export type TUnknownNiceErrorDef = INiceErrorDomainProps;
 /**
  * Wide id type for bare / cast NiceErrors that have no schema.
  * Using `string` (rather than a literal `"unknown"`) ensures that

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

@@ -1,6 +1,6 @@
-import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
+import type { NiceErrorDomain } from "../NiceErrorDefined/NiceErrorDefined";
 import { type INiceErrorOptions, NiceError } from "./NiceError";
-import type { ExtractFromIdContextArg, INiceErrorDefinedProps, TFromContextInput, TUnknownNiceErrorDef } from "./NiceError.types";
+import type { ExtractFromIdContextArg, INiceErrorDomainProps, TDomainNiceErrorId, 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`.
@@ -9,13 +9,15 @@ import type { ExtractFromIdContextArg, INiceErrorDefinedProps, TFromContextInput
  * - 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]>];
+type AddIdArgs<ERR_DEF extends INiceErrorDomainProps, K extends TDomainNiceErrorId<ERR_DEF>> = [
+    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> {
+export interface INiceErrorHydratedOptions<ERR_DEF extends INiceErrorDomainProps, ID extends TDomainNiceErrorId<ERR_DEF>> extends INiceErrorOptions<ERR_DEF, ID> {
     def: ERR_DEF;
-    niceErrorDefined: NiceErrorDefined<ERR_DEF>;
+    niceErrorDefined: NiceErrorDomain<ERR_DEF>;
 }
-export declare class NiceErrorHydrated<ERR_DEF extends INiceErrorDefinedProps = TUnknownNiceErrorDef, 
+export declare class NiceErrorHydrated<ERR_DEF extends INiceErrorDomainProps = TUnknownNiceErrorDef, 
 /**
  * Union of active error-id keys.
  * - After `fromId(id)`: exactly one key.
@@ -23,7 +25,7 @@ export declare class NiceErrorHydrated<ERR_DEF extends INiceErrorDefinedProps =
  * - 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> {
+ACTIVE_IDS extends TDomainNiceErrorId<ERR_DEF> = TDomainNiceErrorId<ERR_DEF>> extends NiceError<ERR_DEF, ACTIVE_IDS> {
     readonly def: ERR_DEF;
     private readonly niceErrorDefined;
     constructor(options: INiceErrorHydratedOptions<ERR_DEF, ACTIVE_IDS>);
@@ -44,6 +46,6 @@ ACTIVE_IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] &
      * 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>;
+    addId<K extends TDomainNiceErrorId<ERR_DEF>>(...args: AddIdArgs<ERR_DEF, K>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS | K>;
 }
 export {};

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

@@ -1,8 +1,8 @@
 import { NiceError } from "../NiceError/NiceError";
-import { type FromIdArgs, type IDefineNewNiceErrorDomainOptions, type INiceErrorDefinedProps, type TErrorReconciledData, type TFromContextInput } from "../NiceError/NiceError.types";
+import { type FromIdArgs, type IDefineNewNiceErrorDomainOptions, type INiceErrorDomainProps, type INiceErrorJsonObject, type TDomainNiceErrorId, 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> = {
+type ChildDef<PARENT_DEF extends INiceErrorDomainProps, SUB extends IDefineNewNiceErrorDomainOptions> = {
     domain: SUB["domain"];
     allDomains: [SUB["domain"], ...PARENT_DEF["allDomains"]];
     schema: SUB["schema"];
@@ -25,7 +25,7 @@ type KeysOfContextInput<INPUT> = keyof INPUT & string;
  * // → 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;
+export type InferNiceError<T extends NiceErrorDomain<any>> = T extends NiceErrorDomain<infer ERR_DEF> ? NiceError<ERR_DEF, keyof ERR_DEF["schema"] & string> : never;
 /**
  * Infers the strongly-typed `NiceErrorHydrated` class type from a `NiceErrorDefined` instance.
  *
@@ -39,8 +39,8 @@ export type InferNiceError<T extends NiceErrorDefined<any>> = T extends NiceErro
  * // → 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> {
+export type InferNiceErrorHydrated<T extends NiceErrorDomain<any>> = T extends NiceErrorDomain<infer ERR_DEF> ? NiceErrorHydrated<ERR_DEF, keyof ERR_DEF["schema"] & string> : never;
+export declare class NiceErrorDomain<ERR_DEF extends INiceErrorDomainProps = INiceErrorDomainProps> {
     readonly domain: ERR_DEF["domain"];
     readonly allDomains: ERR_DEF["allDomains"];
     readonly defaultHttpStatusCode?: number;
@@ -60,9 +60,9 @@ export declare class NiceErrorDefined<ERR_DEF extends INiceErrorDefinedProps = I
      */
     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;
+    }): NiceErrorDomain<ChildDef<ERR_DEF, SUB>>;
+    protected addParentNiceErrorDefined<PARENT_DEF extends INiceErrorDomainProps>(parentError: NiceErrorDomain<PARENT_DEF>): void;
+    protected addChildNiceErrorDefined<CHILD_DEF extends INiceErrorDomainProps>(child: NiceErrorDomain<CHILD_DEF>): void;
     packAs(pack: EErrorPackType): this;
     private createError;
     /**
@@ -88,7 +88,7 @@ export declare class NiceErrorDefined<ERR_DEF extends INiceErrorDefinedProps = I
      * }
      * ```
      */
-    hydrate<ACTIVE_IDS extends keyof ERR_DEF["schema"] & string>(error: NiceError<ERR_DEF, ACTIVE_IDS>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS>;
+    hydrate<ACTIVE_IDS extends TDomainNiceErrorId<ERR_DEF> = TDomainNiceErrorId<ERR_DEF>>(error: NiceError<ERR_DEF, ACTIVE_IDS> | INiceErrorJsonObject<ERR_DEF, ACTIVE_IDS>): NiceErrorHydrated<ERR_DEF, ACTIVE_IDS>;
     /**
      * Creates a `NiceErrorHydrated` for a single error id.
      *
@@ -126,7 +126,7 @@ export declare class NiceErrorDefined<ERR_DEF extends INiceErrorDefinedProps = I
      * Accepts either a `NiceErrorDefined` (domain definition) or a `NiceError`
      * instance (extracts the domain from its `def`).
      */
-    isParentOf(target: NiceErrorDefined<any> | NiceError<any, any>): boolean;
+    isParentOf(target: NiceErrorDomain<any> | NiceError<any, any>): boolean;
     private _buildDef;
     private _resolveMessage;
     private _resolveHttpStatusCode;

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

@@ -1,6 +1,6 @@
 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<{
+import { NiceErrorDomain } from "./NiceErrorDefined";
+export declare const defineNiceError: <ERR_DOMAIN extends string, SCHEMA extends TNiceErrorSchema>(definition: IDefineNewNiceErrorDomainOptions<ERR_DOMAIN, SCHEMA>) => NiceErrorDomain<{
     domain: ERR_DOMAIN;
     allDomains: [ERR_DOMAIN];
     schema: SCHEMA;

package/build/types/NiceErrorHandler/NiceErrorHandler.d.ts

@@ -0,0 +1,23 @@
+import type { NiceError } from "../NiceError/NiceError";
+import type { INiceErrorDomainProps, TDomainNiceErrorId } from "../NiceError/NiceError.types";
+import type { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
+import type { NiceErrorDomain } from "../NiceErrorDefined/NiceErrorDefined";
+import { type IHandleErrorOptions, type MaybePromise, type THandleErrorWithPromiseInspection } from "./NiceErrorHandler.types";
+export declare class NiceErrorHandler<RES_DEF = never, RES = never> {
+    private handlerConfigs;
+    private _defaultRequester?;
+    handleErrorWithPromiseInspection(error: NiceError<any, any>, options?: IHandleErrorOptions): THandleErrorWithPromiseInspection<RES | RES_DEF>;
+    /**
+     * 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<DEF extends INiceErrorDomainProps, H_RES = void>(domain: NiceErrorDomain<DEF>, handler: (error: NiceErrorHydrated<DEF, TDomainNiceErrorId<DEF>>) => MaybePromise<H_RES>): NiceErrorHandler<RES_DEF, RES | H_RES>;
+    forId<DEF extends INiceErrorDomainProps, ID extends TDomainNiceErrorId<DEF>, H_RES = void>(domain: NiceErrorDomain<DEF>, id: ID, handler: (error: NiceErrorHydrated<DEF, ID>) => MaybePromise<H_RES>): NiceErrorHandler<RES_DEF, RES | H_RES>;
+    forIds<DEF extends INiceErrorDomainProps, IDS extends TDomainNiceErrorId<DEF>[], H_RES = void>(domain: NiceErrorDomain<DEF>, ids: IDS, handler: (error: NiceErrorHydrated<DEF, IDS[number]>) => MaybePromise<H_RES>): NiceErrorHandler<RES_DEF, RES | H_RES>;
+    /**
+     * 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<H_RES>(handler: (error: NiceError<any, any>) => MaybePromise<H_RES>): NiceErrorHandler<H_RES, RES>;
+}

package/build/types/NiceErrorHandler/NiceErrorHandler.types.d.ts

@@ -0,0 +1,82 @@
+import type { NiceError } from "../NiceError/NiceError";
+import type { INiceErrorDomainProps, TDomainNiceErrorId } from "../NiceError/NiceError.types";
+import type { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Broad handler signature used internally for storage and dispatch.
+ */
+export type TBroadErrorHandler<E extends NiceError = NiceError, RES = unknown> = (action: E) => MaybePromise<RES>;
+/**
+ * Handler registered via forDomain.
+ *
+ * `act.input` is typed as the union of input types for every action in `ACT_DOM`,
+ * and `act.coreAction` carries the matching schema — the same narrowing you get
+ * from `forActionIds` over all action IDs in the domain.
+ */
+export type TErrorHandlerForDomain<ERR_DOM extends INiceErrorDomainProps> = (error: NiceErrorHydrated<ERR_DOM>) => MaybePromise<unknown>;
+/**
+ * Handler registered via forActionId — receives a specific action ID, with
+ * the primed action's input narrowed to that ID's schema.
+ */
+export type TErrorIdHandlerForDomain<ERR_DOM extends INiceErrorDomainProps, ID extends TDomainNiceErrorId<ERR_DOM>> = (error: NiceErrorHydrated<ERR_DOM, ID>) => MaybePromise<unknown>;
+export declare enum EErrorHandlerTargetType {
+    ids = "ids",
+    domain = "domain",
+    default = "default"
+}
+export type TErrorHandlerTarget = ({
+    type: EErrorHandlerTargetType.ids;
+    domain: string;
+    ids: string[];
+} | {
+    type: EErrorHandlerTargetType.domain;
+    domain: string;
+} | {
+    type: EErrorHandlerTargetType.default;
+}) & {
+    identifier: string;
+};
+/**
+ * A single case in a `handleWith` / `handleWithAsync` call.
+ *
+ * Construct via `forDomain` or `forIds` — do not build this object directly.
+ */
+export interface IErrorHandlerConfig<ERR extends NiceError<any, any> = NiceError<any, any>, RES = unknown> {
+    readonly _matcher: (action: ERR) => boolean;
+    readonly _requester: TBroadErrorHandler<ERR, RES>;
+}
+export interface IErrorHandleAttempt_Success<RES = void> {
+    handled: true;
+    result: RES;
+    target: TErrorHandlerTarget;
+}
+export interface IErrorHandleAttempt_Failure {
+    handled: false;
+    result?: undefined;
+    targets: TErrorHandlerTarget[];
+}
+export type TErrorHandleAttempt<RES = void> = IErrorHandleAttempt_Success<RES> | IErrorHandleAttempt_Failure;
+export interface IHandleErrorOptions {
+    throwOnUnhandled?: boolean;
+}
+export type THandleErrorWithPromiseInspection<RES = void> = {
+    isPromise: false;
+    matched: true;
+    target: TErrorHandlerTarget;
+    handlerResponse: RES;
+} | {
+    isPromise: true;
+    matched: true;
+    target: TErrorHandlerTarget;
+    handlerPromise: Promise<RES>;
+} | {
+    matched: false;
+    attemptedTargets: TErrorHandlerTarget[];
+};
+export type THandleResponse<RES = unknown> = {
+    handled: false;
+} | {
+    handled: true;
+    isPromise: boolean;
+    response: RES;
+};

package/build/types/NiceErrorHandler/handleWith.d.ts

@@ -0,0 +1,8 @@
+import type { INiceErrorDomainProps, TDomainNiceErrorId } from "../NiceError/NiceError.types";
+import type { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
+import type { NiceErrorDomain } from "../NiceErrorDefined/NiceErrorDefined";
+import { NiceErrorHandler } from "./NiceErrorHandler";
+import type { MaybePromise } from "./NiceErrorHandler.types";
+export declare function forDomain<DEF extends INiceErrorDomainProps, H_RES = void>(domain: NiceErrorDomain<DEF>, handler: (error: NiceErrorHydrated<DEF, TDomainNiceErrorId<DEF>>) => MaybePromise<H_RES>): NiceErrorHandler<never, H_RES>;
+export declare function forId<DEF extends INiceErrorDomainProps, ID extends TDomainNiceErrorId<DEF>, H_RES = void>(domain: NiceErrorDomain<DEF>, id: ID, handler: (error: NiceErrorHydrated<DEF, ID>) => MaybePromise<H_RES>): NiceErrorHandler<never, H_RES>;
+export declare function forIds<DEF extends INiceErrorDomainProps, IDS extends TDomainNiceErrorId<DEF>[], H_RES = void>(domain: NiceErrorDomain<DEF>, ids: IDS, handler: (error: NiceErrorHydrated<DEF, IDS[number]>) => MaybePromise<H_RES>): NiceErrorHandler<never, H_RES>;

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

@@ -1,4 +1,4 @@
-export declare const err_example_app: import("..").NiceErrorDefined<{
+export declare const err_example_app: import("..").NiceErrorDomain<{
     domain: "err_example_app";
     allDomains: ["err_example_app"];
     schema: {};
@@ -7,7 +7,7 @@ export declare enum EErrId_UserAuth {
     invalid_credentials = "invalid_credentials",
     account_locked = "account_locked"
 }
-export declare const err_user_auth: import("..").NiceErrorDefined<{
+export declare const err_user_auth: import("..").NiceErrorDomain<{
     domain: string;
     allDomains: [string, "err_example_app"];
     schema: {
@@ -25,7 +25,7 @@ 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<{
+export declare const err_user_auth_registration: import("..").NiceErrorDomain<{
     domain: string;
     allDomains: [string, string, "err_example_app"];
     schema: {

package/build/types/index.d.ts

@@ -5,9 +5,11 @@ export * from "./NiceError/NiceErrorHydrated";
 export * from "./NiceErrorDefined/defineNiceError";
 export * from "./NiceErrorDefined/err";
 export * from "./NiceErrorDefined/NiceErrorDefined";
+export * from "./NiceErrorHandler/handleWith";
+export * from "./NiceErrorHandler/NiceErrorHandler";
+export * from "./NiceErrorHandler/NiceErrorHandler.types";
 export * from "./utils/castAndHydrate";
 export * from "./utils/castNiceError";
-export * from "./utils/handleWith";
 export * from "./utils/isNiceErrorObject";
 export * from "./utils/isRegularErrorObject";
 export * from "./utils/matchFirst";

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

@@ -1,5 +1,5 @@
 import type { IInspectErrorResult_JsError, IInspectErrorResult_JsErrorObject, IInspectErrorResult_JsOther, IInspectErrorResult_Nullish, TInspectErrorResult_JsDataType } from "../utils/inspectPotentialError/inspectPotentialError.types";
-export declare const err_nice: import("..").NiceErrorDefined<{
+export declare const err_nice: import("..").NiceErrorDomain<{
     domain: "err_nice";
     allDomains: ["err_nice"];
     schema: {};
@@ -11,7 +11,7 @@ export declare enum EErrId_CastNotNice {
     js_data_type = "js_data_type",
     js_other = "js_other"
 }
-export declare const err_cast_not_nice: import("..").NiceErrorDefined<{
+export declare const err_cast_not_nice: import("..").NiceErrorDomain<{
     domain: string;
     allDomains: [string, "err_nice"];
     schema: {
@@ -42,3 +42,8 @@ export declare const err_cast_not_nice: import("..").NiceErrorDefined<{
         };
     };
 }>;
+export declare const err_nice_handler: import("..").NiceErrorDomain<{
+    domain: string;
+    allDomains: [string, "err_nice"];
+    schema: {};
+}>;

package/build/types/test/helpers/nice_error_testing.static.d.ts

@@ -1,3 +1,3 @@
 import type { INiceErrorOptions } from "../../NiceError/NiceError";
-import type { INiceErrorDefinedProps } from "../../NiceError/NiceError.types";
-export declare const nice_error_test_options: INiceErrorOptions<INiceErrorDefinedProps, keyof INiceErrorDefinedProps["schema"]>;
+import type { INiceErrorDomainProps } from "../../NiceError/NiceError.types";
+export declare const nice_error_test_options: INiceErrorOptions<INiceErrorDomainProps, keyof INiceErrorDomainProps["schema"]>;

package/build/types/utils/castAndHydrate.d.ts

@@ -1,7 +1,7 @@
 import { NiceError } from "../NiceError/NiceError";
-import type { INiceErrorDefinedProps } from "../NiceError/NiceError.types";
+import type { INiceErrorDomainProps } from "../NiceError/NiceError.types";
 import { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
-import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
+import type { NiceErrorDomain } from "../NiceErrorDefined/NiceErrorDefined";
 /**
  * Combines `castNiceError`, `is()`, and `hydrate()` in a single call — the
  * idiomatic way to handle an unknown value arriving from a remote boundary
@@ -32,4 +32,4 @@ import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
  * });
  * ```
  */
-export declare function castAndHydrate<ERR_DEF extends INiceErrorDefinedProps>(value: unknown, niceErrorDefined: NiceErrorDefined<ERR_DEF>): NiceErrorHydrated<ERR_DEF, keyof ERR_DEF["schema"] & string> | NiceError;
+export declare function castAndHydrate<ERR_DEF extends INiceErrorDomainProps>(value: unknown, niceErrorDefined: NiceErrorDomain<ERR_DEF>): NiceErrorHydrated<ERR_DEF, keyof ERR_DEF["schema"] & string> | NiceError;

package/build/types/utils/matchFirst.d.ts

@@ -1,12 +1,12 @@
 import { NiceError } from "../NiceError/NiceError";
-import type { INiceErrorDefinedProps, TExtractContextType } from "../NiceError/NiceError.types";
+import type { INiceErrorDomainProps, TExtractContextType } from "../NiceError/NiceError.types";
 /**
  * Handler map for `matchFirst`. Each key is an error id (from `ACTIVE_IDS`) and
  * the value is a function that receives the typed context for that id.
  *
  * The `_` key is an optional fallback that runs when no id-specific handler matched.
  */
-export type TMatchFirstHandlers<ERR_DEF extends INiceErrorDefinedProps, ACTIVE_IDS extends keyof ERR_DEF["schema"] & string, RESULT> = {
+export type TMatchFirstHandlers<ERR_DEF extends INiceErrorDomainProps, ACTIVE_IDS extends keyof ERR_DEF["schema"] & string, RESULT> = {
     [K in ACTIVE_IDS]?: (context: TExtractContextType<ERR_DEF["schema"][K]>) => RESULT;
 } & {
     _?: () => RESULT;
@@ -32,4 +32,4 @@ export type TMatchFirstHandlers<ERR_DEF extends INiceErrorDefinedProps, ACTIVE_I
  * });
  * ```
  */
-export declare function matchFirst<ERR_DEF extends INiceErrorDefinedProps, ACTIVE_IDS extends keyof ERR_DEF["schema"] & string, RESULT>(error: NiceError<ERR_DEF, ACTIVE_IDS>, handlers: TMatchFirstHandlers<ERR_DEF, ACTIVE_IDS, RESULT>): RESULT | undefined;
+export declare function matchFirst<ERR_DEF extends INiceErrorDomainProps, ACTIVE_IDS extends keyof ERR_DEF["schema"] & string, RESULT>(error: NiceError<ERR_DEF, ACTIVE_IDS>, handlers: TMatchFirstHandlers<ERR_DEF, ACTIVE_IDS, RESULT>): RESULT | undefined;

package/package.json

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

package/build/types/utils/handleWith.d.ts

@@ -1,49 +0,0 @@
-import type { INiceErrorDefinedProps } from "../NiceError/NiceError.types";
-import type { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
-import type { NiceErrorDefined } from "../NiceErrorDefined/NiceErrorDefined";
-/**
- * A single case in a `handleWith` / `handleWithAsync` call.
- *
- * Construct via `forDomain` or `forIds` — do not build this object directly.
- */
-export interface IErrorCase<DEF extends INiceErrorDefinedProps, IDS extends keyof DEF["schema"] & string> {
-}
-/**
- * Builds a case that fires for any error whose domain exactly matches `domain`.
- * The handler receives the fully-hydrated error, narrowed to all schema ids.
- *
- * Use with `error.handleWith([...])` (sync) or `error.handleWithAsync([...])` (async).
- *
- * @example
- * ```ts
- * error.handleWith([
- *   forDomain(err_payments, (h) => {
- *     matchFirst(h, {
- *       payment_failed: ({ reason }) => res.status(402).json({ reason }),
- *       card_expired:   ()           => res.status(402).json({ expired: true }),
- *     });
- *   }),
- * ]);
- * ```
- */
-export declare function forDomain<DEF extends INiceErrorDefinedProps>(domain: NiceErrorDefined<DEF>, handler: (error: NiceErrorHydrated<DEF, keyof DEF["schema"] & string>) => void | Promise<void>): IErrorCase<DEF, keyof DEF["schema"] & string>;
-/**
- * Builds a case that fires only if the error's domain matches `domain` **and**
- * at least one of `ids` is active on the error.
- * The handler receives the fully-hydrated error, narrowed to `IDS[number]`.
- *
- * @example
- * ```ts
- * error.handleWith([
- *   forIds(err_feature, ["not_found", "forbidden"], (h) => {
- *     // h.getContext("not_found") and h.getContext("forbidden") are both available
- *     if (h.hasId("not_found")) res.status(404).json({ missing: h.getContext("not_found").resource });
- *     if (h.hasId("forbidden")) res.status(403).json({ denied: true });
- *   }),
- *
- *   // Fallback: any other err_feature error
- *   forDomain(err_feature, (h) => res.status(500).json({ error: h.message })),
- * ]);
- * ```
- */
-export declare function forIds<DEF extends INiceErrorDefinedProps, IDS extends ReadonlyArray<keyof DEF["schema"] & string>>(domain: NiceErrorDefined<DEF>, ids: IDS, handler: (error: NiceErrorHydrated<DEF, IDS[number]>) => void | Promise<void>): IErrorCase<DEF, IDS[number]>;