@nice-code/error 0.0.15

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

@@ -0,0 +1,44 @@
+import type { IInspectErrorResult_JsError, IInspectErrorResult_JsErrorObject, IInspectErrorResult_JsOther, IInspectErrorResult_Nullish, TInspectErrorResult_JsDataType } from "../utils/inspectPotentialError/inspectPotentialError.types";
+export declare const err_nice: import("..").NiceErrorDefined<{
+    domain: "err_nice";
+    allDomains: ["err_nice"];
+    schema: {};
+}>;
+export declare enum EErrId_CastNotNice {
+    js_error = "native_error",
+    js_error_like_object = "js_error_like_object",
+    nullish_value = "nullish_value",
+    js_data_type = "js_data_type",
+    js_other = "js_other"
+}
+export declare const err_cast_not_nice: import("..").NiceErrorDefined<{
+    domain: string;
+    allDomains: [string, "err_nice"];
+    schema: {
+        native_error: import("..").INiceErrorIdMetadata<IInspectErrorResult_JsError, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+        js_error_like_object: import("..").INiceErrorIdMetadata<IInspectErrorResult_JsErrorObject, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+        nullish_value: import("..").INiceErrorIdMetadata<IInspectErrorResult_Nullish, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+        js_data_type: import("..").INiceErrorIdMetadata<TInspectErrorResult_JsDataType, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+        js_other: import("..").INiceErrorIdMetadata<IInspectErrorResult_JsOther, import("..").JSONSerializableValue> & {
+            context: {
+                required: true;
+            };
+        };
+    };
+}>;

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

@@ -0,0 +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"]>;

package/build/types/test/helpers/test_utils.d.ts

@@ -0,0 +1 @@
+export declare const isVal: <T>(input: unknown, val: T) => input is T;

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

@@ -0,0 +1,35 @@
+import { NiceError } from "../NiceError/NiceError";
+import type { INiceErrorDefinedProps } from "../NiceError/NiceError.types";
+import { NiceErrorHydrated } from "../NiceError/NiceErrorHydrated";
+import type { NiceErrorDefined } 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
+ * (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);
+ * });
+ * ```
+ */
+export declare function castAndHydrate<ERR_DEF extends INiceErrorDefinedProps>(value: unknown, niceErrorDefined: NiceErrorDefined<ERR_DEF>): NiceErrorHydrated<ERR_DEF, keyof ERR_DEF["schema"] & string> | NiceError;

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

@@ -0,0 +1,15 @@
+import { NiceError } from "../NiceError/NiceError";
+/**
+ * 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.
+ */
+export declare const castNiceError: (error: unknown) => NiceError;

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

@@ -0,0 +1,49 @@
+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]>;

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

@@ -0,0 +1,2 @@
+import { type TInspectErrorResult } from "./inspectPotentialError.types";
+export declare const inspectPotentialError: (potentialError: unknown) => TInspectErrorResult;

package/build/types/utils/inspectPotentialError/inspectPotentialError.enums.d.ts

@@ -0,0 +1,9 @@
+export declare enum EInspectErrorResultType {
+    nullish = "nullish",
+    niceErrorObject = "niceErrorObject",
+    niceError = "niceError",
+    jsError = "jsError",
+    jsErrorObject = "jsErrorObject",
+    jsDataType = "jsDataType",
+    jsOther = "jsOther"
+}

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

@@ -0,0 +1,51 @@
+import type { NiceError } from "../../NiceError/NiceError";
+import type { INiceErrorJsonObject, IRegularErrorJsonObject } from "../../NiceError/NiceError.types";
+import type { EInspectErrorResultType } from "./inspectPotentialError.enums";
+export interface IInspectErrorResult_Base<T extends EInspectErrorResultType> {
+    type: T;
+}
+export interface IInspectErrorResult_Nullish extends IInspectErrorResult_Base<EInspectErrorResultType.nullish> {
+    value: null | undefined;
+}
+export interface IInspectErrorResult_NiceErrorObject extends IInspectErrorResult_Base<EInspectErrorResultType.niceErrorObject> {
+    niceErrorObject: INiceErrorJsonObject;
+}
+export interface IInspectErrorResult_NiceError extends IInspectErrorResult_Base<EInspectErrorResultType.niceError> {
+    niceError: NiceError;
+}
+export interface IInspectErrorResult_JsError extends IInspectErrorResult_Base<EInspectErrorResultType.jsError> {
+    jsError: Error;
+}
+export interface IInspectErrorResult_JsErrorObject extends IInspectErrorResult_Base<EInspectErrorResultType.jsErrorObject> {
+    jsErrorObject: IRegularErrorJsonObject;
+}
+/**
+ * JS DATA TYPES
+ */
+export interface IInspectErrorResult_JsDataType_String extends IInspectErrorResult_Base<EInspectErrorResultType.jsDataType> {
+    jsDataType: "string";
+    jsDataValue: string;
+}
+export interface IInspectErrorResult_JsDataType_Number extends IInspectErrorResult_Base<EInspectErrorResultType.jsDataType> {
+    jsDataType: "number";
+    jsDataValue: number;
+}
+export interface IInspectErrorResult_JsDataType_Boolean extends IInspectErrorResult_Base<EInspectErrorResultType.jsDataType> {
+    jsDataType: "boolean";
+    jsDataValue: boolean;
+}
+export interface IInspectErrorResult_JsDataType_Object extends IInspectErrorResult_Base<EInspectErrorResultType.jsDataType> {
+    jsDataType: "object";
+    jsDataValue: object;
+}
+export type TInspectErrorResult_JsDataType = IInspectErrorResult_JsDataType_String | IInspectErrorResult_JsDataType_Number | IInspectErrorResult_JsDataType_Boolean | IInspectErrorResult_JsDataType_Object;
+/**
+ * Catch-all for any other JS data type that doesn't fit the above categories (e.g. symbol, bigint, function, etc.)
+ */
+export interface IInspectErrorResult_JsOther extends IInspectErrorResult_Base<EInspectErrorResultType.jsOther> {
+    jsDataValue: unknown;
+}
+/**
+ * Union of all possible results from inspectPotentialError
+ */
+export type TInspectErrorResult = IInspectErrorResult_Nullish | IInspectErrorResult_NiceErrorObject | IInspectErrorResult_NiceError | IInspectErrorResult_JsError | IInspectErrorResult_JsErrorObject | TInspectErrorResult_JsDataType | IInspectErrorResult_JsOther;

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

@@ -0,0 +1,12 @@
+import { type INiceErrorJsonObject } from "../NiceError/NiceError.types";
+/**
+ * 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.
+ */
+export declare function isNiceErrorObject(obj: unknown): obj is INiceErrorJsonObject;

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

@@ -0,0 +1,2 @@
+import type { IRegularErrorJsonObject } from "../NiceError/NiceError.types";
+export declare function isRegularErrorJsonObject(obj: unknown): obj is IRegularErrorJsonObject;

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

@@ -0,0 +1 @@
+export declare function jsErrorOrCastJsError(error: unknown, logMessage?: boolean): Error;

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

@@ -0,0 +1,3 @@
+import { Logger } from "tslog";
+export declare const logger_NiceError: Logger<unknown>;
+export declare const logger_NiceError_testing: Logger<unknown>;

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

@@ -0,0 +1,35 @@
+import { NiceError } from "../NiceError/NiceError";
+import type { INiceErrorDefinedProps, 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> = {
+    [K in ACTIVE_IDS]?: (context: TExtractContextType<ERR_DEF["schema"][K]>) => RESULT;
+} & {
+    _?: () => RESULT;
+};
+/**
+ * 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",
+ * });
+ * ```
+ */
+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;

package/build/types/utils/packError/causePack.d.ts

@@ -0,0 +1,2 @@
+import type { NiceError } from "../../NiceError/NiceError";
+export declare const causePack: <E extends NiceError<any, any>>(error: E) => E;

package/build/types/utils/packError/msgPack.d.ts

@@ -0,0 +1,2 @@
+import type { NiceError } from "../../NiceError/NiceError";
+export declare const msgPack: <E extends NiceError<any, any>>(error: E) => E;

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

@@ -0,0 +1,3 @@
+import type { NiceError } from "../../NiceError/NiceError";
+import type { EErrorPackType } from "./packError.enums";
+export declare const packError: <E extends NiceError<any, any>>(error: E, packType?: EErrorPackType) => E;

package/build/types/utils/packError/packError.enums.d.ts

@@ -0,0 +1,5 @@
+export declare enum EErrorPackType {
+    no_pack = "no_pack",
+    msg_pack = "msg_pack",
+    cause_pack = "cause_pack"
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nice-code/error",
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/types/index.d.ts",
+  "type": "module",
+  "version": "0.0.15",
+  "exports": {
+    ".": {
+      "types": "./build/types/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "bunx tsc --noEmit",
+    "type-check-watch": "bunx tsc --noEmit --watch",
+    "vitest": "vitest --typecheck",
+    "vitest-agent": "vitest --typecheck --reporter=agent",
+    "clean-build": "bunx rimraf build",
+    "build": "bun run clean-build && bun run build.ts && bun run build-types",
+    "build-types": "tsc --project tsconfig.build.json",
+    "example": "bun run ./src/example/error_usage_example.ts"
+  },
+  "dependencies": {
+    "http-status-codes": "^2.3.0",
+    "valibot": "1.3.1",
+    "tslog": "^4.10.2"
+  }
+}