@devua-lab/error-serialization 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# Error Serializer Library
+
+A lightweight, highly extensible TypeScript library for standardized error serialization. It provides a unified pipeline to transform any error—from Zod validation issues and Axios HTTP failures to native JavaScript errors and raw strings—into a consistent, strictly typed response format.
+
+---
+
+## 📑 Table of Contents
+
+1. [Features](#features)
+2. [Standardized Output Format](#standardized-output-format)
+3. [Out-of-the-Box Functionality](#out-of-the-box-functionality)
+    - [ZodErrorPlugin](#zoderrorplugin)
+    - [AxiosErrorPlugin](#axioserrorplugin)
+    - [StandardErrorPlugin](#standarderrorplugin)
+4. [Core Orchestration](#core-orchestration)
+    - [Priority System](#priority-system)
+    - [Subscription System (Callbacks)](#subscription-system-callbacks)
+5. [Advanced Usage](#advanced-usage)
+6. [Test Coverage & Reliability](#test-coverage--reliability)
+
+---
+
+## ✨ Features
+
+- **🎯 Universal Standardization**: Regardless of the error source, the output always follows the same predictable interface.
+- **🏗️ Structured Validation Mapping**: Advanced transformation of Zod issues into flat keys or deep object hierarchies.
+- **🌐 Generic API Extraction**: Smart parsing of backend error messages and codes from HTTP responses.
+- **🚀 Priority-Based Execution**: Automatically selects the most appropriate handler for any given error object.
+- **🔔 Real-time Subscriptions**: Lightweight callback system for global error monitoring and analytics.
+- **🛡️ Preservation of Context**: The original error object is always preserved, allowing access to low-level details (like Axios request configs).
+- **🔌 Plugin-Driven**: Easily register new handlers for custom application-specific error classes.
+
+---
+
+## 🏗 Standardized Output Format
+
+The serialization process produces an `AppErrorResponse` object:
+
+```typescript
+{
+  metadata: {
+    plugin: string;    // The plugin that successfully handled the error
+    priority: number;  // Priority level of the handling plugin
+  },
+  error: unknown;      // The ORIGINAL error object (preserved for logging/debugging)
+  global?: string;     // A primary human-readable error message
+  code?: string[];     // Standardized error identifiers (e.g., ["102", "CONFLICT"])
+  status?: number;     // Numeric status code (e.g., 422, 404, 500, or 0 for network issues)
+  validation?: {       // Detailed field-level errors (primarily for Zod)
+    [key: string]: any;
+  }
+}
+```
+
+---
+
+## 📦 Out-of-the-Box Functionality
+
+### ZodErrorPlugin
+Designed for `ZodError` instances. It translates complex validation issues into formats suitable for frontend state.
+- **Status Code**: Returns `422`.
+- **Default Code**: `["102"]`.
+- **Flexible Pathing**: Correctly handles array indices (e.g., `list.0.name`) and nested properties.
+- **Customizable**: Use `mapIssue` to dynamically rewrite messages or inject specific codes based on validation parameters.
+
+### AxiosErrorPlugin
+A generic handler for `AxiosError`. It is designed to work with virtually any backend error structure.
+- **Message Parsing**: Scans the response body for `message` or `error.message`.
+- **Code Parsing**: Extracts `code` or `errorCode` from response data.
+- **Network Awareness**: Provides fallback status `0` and generic codes (e.g., `HTTP_0`) when a server response is absent (Network Error).
+
+### StandardErrorPlugin
+The baseline handler for native `Error` objects, ensuring even basic exceptions are standardized.
+- **Code**: `["INTERNAL_ERROR"]`.
+- **Message**: Uses the native `error.message`.
+
+---
+
+## ⚙️ Core Orchestration
+
+### Priority System
+Plugins are ordered by priority. The `ErrorSerializer` iterates through them until it finds a match.
+
+| Plugin                  | Priority | Matching Criteria                      |
+|:------------------------|:---------|:---------------------------------------|
+| **ZodErrorPlugin**      | 2        | `instanceof ZodError`                  |
+| **AxiosErrorPlugin**    | 1        | `axios.isAxiosError(error)`            |
+| **StandardErrorPlugin** | 0        | `instanceof Error`                     |
+| **FallbackError**       | -1       | Fallback priority for unhandled errors |
+
+### Subscription System (Callbacks)
+Register callbacks to listen to every serialization event. Since the original error is preserved in the output, you can extract any context needed.
+
+```typescript
+serializer.subscribe((context) => {
+  // Access Axios config via the original error preservation
+  if (context.metadata.plugin === 'AxiosErrorPlugin') {
+    const originalAxiosError = context.error as AxiosError;
+    console.log('Request URL:', originalAxiosError.config?.url);
+  }
+  
+  // Log all critical status codes
+  if (context.status && context.status >= 500) {
+    MyMonitor.log(context.global);
+  }
+});
+```
+
+---
+
+## 🚀 Advanced Usage
+
+### Custom Zod Mapping
+```typescript
+const plugin = new ZodErrorPlugin({
+  mapIssue: (issue) => {
+    if (issue.params?.apiCode) {
+      return { code: issue.params.apiCode, message: issue.message };
+    }
+  }
+});
+```
+
+---
+
+## 🧪 Test Coverage & Reliability
+
+The library is fully verified with `vitest` against a wide range of scenarios:
+- **General Backend Errors**: Extraction of custom error codes and messages from various API response formats.
+- **Deeply Nested Validation**: Handling of paths like `['a', 0, 'b', 1, 'c']` in both flat and nested modes.
+- **Symbol Key Safety**: Automatic filtering of `Symbol` keys in Zod paths to prevent serialization issues.
+- **Boundary Inputs**: Graceful handling of `null`, `undefined`, and numeric inputs.
+- **Connectivity Issues**: Accurate serialization of Axios network-level failures.
+- **Subscription Integrity**: Confirmation that simplified callbacks receive the full `AppErrorResponse`.

package/dist/index.cjs

@@ -0,0 +1,303 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AxiosErrorPlugin: () => AxiosErrorPlugin,
+  ErrorSerializer: () => ErrorSerializer,
+  StandardErrorPlugin: () => StandardErrorPlugin,
+  ZodErrorPlugin: () => ZodErrorPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/contants.ts
+var ErrorPriority = {
+  /**
+   * Fallback priority for unhandled errors
+   */
+  FallbackError: -1,
+  /**
+   * Default priority for generic errors
+   */
+  StandardError: 0,
+  /**
+   * Priority for HTTP-related errors
+   */
+  AxiosError: 1,
+  /**
+   * High priority for validation-related errors
+   */
+  ZodError: 2
+};
+
+// src/ErrorSerializer.ts
+var ErrorSerializer = class {
+  /**
+   * List of registered serialization plugins.
+   */
+  plugins = [];
+  /**
+   * Registered callbacks triggered after serialization.
+   */
+  callbacks = [];
+  /**
+   * Registers a plugin and sorts the pipeline by priority.
+   */
+  register(plugin) {
+    this.plugins.push(plugin);
+    this.plugins.sort((a, b) => b.priority - a.priority);
+    return this;
+  }
+  /**
+   * Adds a global callback triggered for every processed error.
+   */
+  subscribe(callback) {
+    this.callbacks.push(callback);
+    return this;
+  }
+  /**
+   * Orchestrates the serialization process.
+   * Returns a standardized response even for primitive types or null.
+   */
+  process(error) {
+    let output = null;
+    for (const plugin of this.plugins) {
+      if (plugin.match(error)) {
+        output = plugin.serialize(error);
+        break;
+      }
+    }
+    if (!output) {
+      output = {
+        metadata: {
+          plugin: "ErrorSerializer",
+          priority: ErrorPriority.FallbackError
+        },
+        error,
+        global: String(error),
+        code: ["UNHANDLED_EXCEPTION"]
+      };
+    }
+    for (const callback of this.callbacks) {
+      callback(output);
+    }
+    return output;
+  }
+};
+
+// src/plugins/AxiosErrorPlugin.ts
+var import_axios = require("axios");
+
+// src/types.ts
+var ErrorPlugin = class {
+  /**
+   * @param priority - Determines execution order (higher values run first)
+   */
+  constructor(priority = ErrorPriority.StandardError) {
+    this.priority = priority;
+  }
+  /**
+   * Internal helper to maintain consistent metadata and structure.
+   */
+  createResponse(error, params) {
+    return {
+      metadata: {
+        plugin: this.name,
+        priority: this.priority
+      },
+      error,
+      ...params
+    };
+  }
+};
+
+// src/plugins/AxiosErrorPlugin.ts
+var AxiosErrorPlugin = class extends ErrorPlugin {
+  /**
+   * Plugin identifier
+   */
+  name = "AxiosErrorPlugin";
+  constructor() {
+    super(ErrorPriority.AxiosError);
+  }
+  /**
+   * Uses Axios type guard to match errors
+   */
+  match(error) {
+    return (0, import_axios.isAxiosError)(error);
+  }
+  /**
+   * Maps HTTP response details to the global schema
+   */
+  serialize(error) {
+    const responseData = error.response?.data;
+    const backendMessage = responseData?.message || responseData?.error?.message;
+    const backendCode = responseData?.code || responseData?.errorCode;
+    const finalMessage = backendMessage || error.message || "Network Error";
+    const finalCodes = backendCode ? Array.isArray(backendCode) ? backendCode : [String(backendCode)] : [`HTTP_${error.response?.status || 0}`];
+    return this.createResponse(error, {
+      global: finalMessage,
+      code: finalCodes,
+      status: error.response?.status || 0
+    });
+  }
+};
+
+// src/plugins/StandardErrorPlugin.ts
+var StandardErrorPlugin = class extends ErrorPlugin {
+  /**
+   * Plugin identifier
+   */
+  name = "StandardErrorPlugin";
+  constructor() {
+    super(ErrorPriority.StandardError);
+  }
+  /**
+   * Matches native Error class
+   */
+  match(error) {
+    return error instanceof Error;
+  }
+  /**
+   * Converts native Error to standardized response
+   */
+  serialize(error) {
+    return this.createResponse(error, {
+      global: error.message,
+      code: ["INTERNAL_ERROR"]
+    });
+  }
+};
+
+// src/plugins/ZodErrorPlugin.ts
+var import_zod = require("zod");
+var ZodErrorPlugin = class extends ErrorPlugin {
+  /**
+   * Plugin identifier
+   */
+  name = "ZodErrorPlugin";
+  /**
+   * Private storage for serialization settings.
+   */
+  options;
+  /**
+   * @param options - Customization for error path and message formatting
+   */
+  constructor(options = {}) {
+    super(ErrorPriority.ZodError);
+    this.options = {
+      structure: "flat",
+      messageFormat: "array",
+      keySeparator: "_",
+      ...options
+    };
+  }
+  /**
+   * Checks if the error is an instance of ZodError
+   */
+  match(error) {
+    return error instanceof import_zod.ZodError;
+  }
+  /**
+   * Serializes ZodError into the standardized format.
+   * Collects custom error codes if they are provided via mapIssue.
+   */
+  serialize(error) {
+    const codes = /* @__PURE__ */ new Set(["102"]);
+    const validation = this.formatIssues(error.issues, codes);
+    return this.createResponse(error, {
+      global: "Validation error",
+      code: Array.from(codes),
+      status: 422,
+      validation
+    });
+  }
+  /**
+   * Processes Zod issues into the final validation object.
+   */
+  formatIssues(issues, codes) {
+    const result = {};
+    for (const issue of issues) {
+      const path = issue.path.filter(
+        (k) => typeof k !== "symbol"
+      );
+      let message = issue.message;
+      if (this.options.mapIssue) {
+        const mapped = this.options.mapIssue(issue);
+        if (mapped) {
+          if (mapped.message) message = mapped.message;
+          if (mapped.code) codes.add(mapped.code);
+        }
+      }
+      if (this.options.structure === "nested") {
+        this.setNestedValue(result, path, message);
+      } else {
+        const key = path.join(this.options.keySeparator);
+        this.setFlatValue(result, key, message);
+      }
+    }
+    return result;
+  }
+  /**
+   * Handles flat object key generation
+   */
+  setFlatValue(obj, key, message) {
+    if (this.options.messageFormat === "array") {
+      if (!obj[key]) obj[key] = [];
+      obj[key].push(message);
+    } else {
+      if (!obj[key]) obj[key] = message;
+    }
+  }
+  /**
+   * Recursively builds nested object paths
+   */
+  setNestedValue(obj, path, message) {
+    let current = obj;
+    for (let i = 0; i < path.length; i++) {
+      const key = path[i];
+      const isLast = i === path.length - 1;
+      if (isLast) {
+        if (this.options.messageFormat === "array") {
+          if (!current[key]) current[key] = [];
+          if (Array.isArray(current[key])) {
+            current[key].push(message);
+          } else {
+            current[key] = [message];
+          }
+        } else {
+          current[key] = message;
+        }
+      } else {
+        if (!current[key] || typeof current[key] !== "object") {
+          current[key] = {};
+        }
+        current = current[key];
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AxiosErrorPlugin,
+  ErrorSerializer,
+  StandardErrorPlugin,
+  ZodErrorPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,232 @@
+import { AxiosError } from 'axios';
+import { ZodError } from 'zod';
+
+/**
+ * Priority levels for different error types.
+ * Plugins with higher priority are checked first in the pipeline.
+ */
+declare const ErrorPriority: {
+    /**
+     * Fallback priority for unhandled errors
+     */
+    readonly FallbackError: -1;
+    /**
+     * Default priority for generic errors
+     */
+    readonly StandardError: 0;
+    /**
+     * Priority for HTTP-related errors
+     */
+    readonly AxiosError: 1;
+    /**
+     * High priority for validation-related errors
+     */
+    readonly ZodError: 2;
+};
+
+/**
+ * Standardized error response structure used by all plugins.
+ */
+interface AppErrorResponse {
+    /**
+     * Metadata about the serialization process
+     */
+    metadata: {
+        /**
+         * Name of the plugin that handled the error
+         */
+        plugin: string;
+        /**
+         * Priority level of the handler
+         */
+        priority: number;
+    };
+    /**
+     * The original error object that was processed
+     */
+    error: unknown;
+    /**
+     * Global error message or description
+     */
+    global?: string;
+    /**
+     * List of specific error codes
+     */
+    code?: string[];
+    /**
+     * HTTP status code if applicable
+     */
+    status?: number;
+    /**
+     * Map of field-level validation errors
+     */
+    validation?: Record<string, ExpectedAny>;
+}
+/**
+ * Callback function triggered after error processing.
+ */
+type SerializationCallback = (context: AppErrorResponse) => void;
+/**
+ * Configuration options for Zod error serialization.
+ */
+interface ZodSerializationOptions {
+    /**
+     * Structure of the validation object:
+     * - 'flat': keys like "user_name"
+     * - 'nested': hierarchical objects
+     */
+    structure: "flat" | "nested";
+    /**
+     * Format of validation messages:
+     * - 'array': list of strings
+     * - 'string': first error message only
+     */
+    messageFormat: "array" | "string";
+    /**
+     * Separator for flat keys
+     */
+    keySeparator?: string;
+    /**
+     * Custom mapper to override message or code for specific Zod issues.
+     */
+    mapIssue?: (issue: ExpectedAny) => {
+        code?: string;
+        message?: string;
+    } | undefined;
+}
+/**
+ * Abstract base class for error plugins with unified response formatting.
+ */
+declare abstract class ErrorPlugin<T = unknown> {
+    priority: (typeof ErrorPriority)[keyof typeof ErrorPriority];
+    /**
+     * Unique identifier for the plugin
+     */
+    abstract readonly name: string;
+    /**
+     * @param priority - Determines execution order (higher values run first)
+     */
+    protected constructor(priority?: (typeof ErrorPriority)[keyof typeof ErrorPriority]);
+    /**
+     * Determines if the error is compatible with this plugin.
+     */
+    abstract match(error: unknown): error is T;
+    /**
+     * Transforms the error into the standardized AppErrorResponse.
+     */
+    abstract serialize(error: T): AppErrorResponse;
+    /**
+     * Internal helper to maintain consistent metadata and structure.
+     */
+    protected createResponse(error: T, params: Omit<AppErrorResponse, "metadata" | "error">): AppErrorResponse;
+}
+/**
+ * Type alias for any-type values in structured objects.
+ */
+type ExpectedAny = any;
+
+/**
+ * Core engine for error processing that manages plugin lifecycle and post-processing callbacks.
+ */
+declare class ErrorSerializer {
+    /**
+     * List of registered serialization plugins.
+     */
+    private plugins;
+    /**
+     * Registered callbacks triggered after serialization.
+     */
+    private callbacks;
+    /**
+     * Registers a plugin and sorts the pipeline by priority.
+     */
+    register(plugin: ErrorPlugin<ExpectedAny>): this;
+    /**
+     * Adds a global callback triggered for every processed error.
+     */
+    subscribe(callback: SerializationCallback): this;
+    /**
+     * Orchestrates the serialization process.
+     * Returns a standardized response even for primitive types or null.
+     */
+    process(error: unknown): AppErrorResponse;
+}
+
+/**
+ * Plugin for handling Axios errors and extracting server-side data.
+ */
+declare class AxiosErrorPlugin extends ErrorPlugin<AxiosError> {
+    /**
+     * Plugin identifier
+     */
+    readonly name = "AxiosErrorPlugin";
+    constructor();
+    /**
+     * Uses Axios type guard to match errors
+     */
+    match(error: unknown): error is AxiosError;
+    /**
+     * Maps HTTP response details to the global schema
+     */
+    serialize(error: AxiosError): AppErrorResponse;
+}
+
+/**
+ * Basic plugin for standard JavaScript Error objects.
+ */
+declare class StandardErrorPlugin extends ErrorPlugin<Error> {
+    /**
+     * Plugin identifier
+     */
+    readonly name = "StandardErrorPlugin";
+    constructor();
+    /**
+     * Matches native Error class
+     */
+    match(error: unknown): error is Error;
+    /**
+     * Converts native Error to standardized response
+     */
+    serialize(error: Error): AppErrorResponse;
+}
+
+/**
+ * Plugin specifically designed for Zod errors with advanced structural formatting.
+ */
+declare class ZodErrorPlugin extends ErrorPlugin<ZodError> {
+    /**
+     * Plugin identifier
+     */
+    readonly name = "ZodErrorPlugin";
+    /**
+     * Private storage for serialization settings.
+     */
+    private options;
+    /**
+     * @param options - Customization for error path and message formatting
+     */
+    constructor(options?: Partial<ZodSerializationOptions>);
+    /**
+     * Checks if the error is an instance of ZodError
+     */
+    match(error: unknown): error is ZodError;
+    /**
+     * Serializes ZodError into the standardized format.
+     * Collects custom error codes if they are provided via mapIssue.
+     */
+    serialize(error: ZodError): AppErrorResponse;
+    /**
+     * Processes Zod issues into the final validation object.
+     */
+    protected formatIssues(issues: ZodError["issues"], codes: Set<string>): Record<string, ExpectedAny>;
+    /**
+     * Handles flat object key generation
+     */
+    private setFlatValue;
+    /**
+     * Recursively builds nested object paths
+     */
+    private setNestedValue;
+}
+
+export { AxiosErrorPlugin, ErrorSerializer, StandardErrorPlugin, ZodErrorPlugin };

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { AxiosError } from 'axios';
+import { ZodError } from 'zod';
+
+/**
+ * Priority levels for different error types.
+ * Plugins with higher priority are checked first in the pipeline.
+ */
+declare const ErrorPriority: {
+    /**
+     * Fallback priority for unhandled errors
+     */
+    readonly FallbackError: -1;
+    /**
+     * Default priority for generic errors
+     */
+    readonly StandardError: 0;
+    /**
+     * Priority for HTTP-related errors
+     */
+    readonly AxiosError: 1;
+    /**
+     * High priority for validation-related errors
+     */
+    readonly ZodError: 2;
+};
+
+/**
+ * Standardized error response structure used by all plugins.
+ */
+interface AppErrorResponse {
+    /**
+     * Metadata about the serialization process
+     */
+    metadata: {
+        /**
+         * Name of the plugin that handled the error
+         */
+        plugin: string;
+        /**
+         * Priority level of the handler
+         */
+        priority: number;
+    };
+    /**
+     * The original error object that was processed
+     */
+    error: unknown;
+    /**
+     * Global error message or description
+     */
+    global?: string;
+    /**
+     * List of specific error codes
+     */
+    code?: string[];
+    /**
+     * HTTP status code if applicable
+     */
+    status?: number;
+    /**
+     * Map of field-level validation errors
+     */
+    validation?: Record<string, ExpectedAny>;
+}
+/**
+ * Callback function triggered after error processing.
+ */
+type SerializationCallback = (context: AppErrorResponse) => void;
+/**
+ * Configuration options for Zod error serialization.
+ */
+interface ZodSerializationOptions {
+    /**
+     * Structure of the validation object:
+     * - 'flat': keys like "user_name"
+     * - 'nested': hierarchical objects
+     */
+    structure: "flat" | "nested";
+    /**
+     * Format of validation messages:
+     * - 'array': list of strings
+     * - 'string': first error message only
+     */
+    messageFormat: "array" | "string";
+    /**
+     * Separator for flat keys
+     */
+    keySeparator?: string;
+    /**
+     * Custom mapper to override message or code for specific Zod issues.
+     */
+    mapIssue?: (issue: ExpectedAny) => {
+        code?: string;
+        message?: string;
+    } | undefined;
+}
+/**
+ * Abstract base class for error plugins with unified response formatting.
+ */
+declare abstract class ErrorPlugin<T = unknown> {
+    priority: (typeof ErrorPriority)[keyof typeof ErrorPriority];
+    /**
+     * Unique identifier for the plugin
+     */
+    abstract readonly name: string;
+    /**
+     * @param priority - Determines execution order (higher values run first)
+     */
+    protected constructor(priority?: (typeof ErrorPriority)[keyof typeof ErrorPriority]);
+    /**
+     * Determines if the error is compatible with this plugin.
+     */
+    abstract match(error: unknown): error is T;
+    /**
+     * Transforms the error into the standardized AppErrorResponse.
+     */
+    abstract serialize(error: T): AppErrorResponse;
+    /**
+     * Internal helper to maintain consistent metadata and structure.
+     */
+    protected createResponse(error: T, params: Omit<AppErrorResponse, "metadata" | "error">): AppErrorResponse;
+}
+/**
+ * Type alias for any-type values in structured objects.
+ */
+type ExpectedAny = any;
+
+/**
+ * Core engine for error processing that manages plugin lifecycle and post-processing callbacks.
+ */
+declare class ErrorSerializer {
+    /**
+     * List of registered serialization plugins.
+     */
+    private plugins;
+    /**
+     * Registered callbacks triggered after serialization.
+     */
+    private callbacks;
+    /**
+     * Registers a plugin and sorts the pipeline by priority.
+     */
+    register(plugin: ErrorPlugin<ExpectedAny>): this;
+    /**
+     * Adds a global callback triggered for every processed error.
+     */
+    subscribe(callback: SerializationCallback): this;
+    /**
+     * Orchestrates the serialization process.
+     * Returns a standardized response even for primitive types or null.
+     */
+    process(error: unknown): AppErrorResponse;
+}
+
+/**
+ * Plugin for handling Axios errors and extracting server-side data.
+ */
+declare class AxiosErrorPlugin extends ErrorPlugin<AxiosError> {
+    /**
+     * Plugin identifier
+     */
+    readonly name = "AxiosErrorPlugin";
+    constructor();
+    /**
+     * Uses Axios type guard to match errors
+     */
+    match(error: unknown): error is AxiosError;
+    /**
+     * Maps HTTP response details to the global schema
+     */
+    serialize(error: AxiosError): AppErrorResponse;
+}
+
+/**
+ * Basic plugin for standard JavaScript Error objects.
+ */
+declare class StandardErrorPlugin extends ErrorPlugin<Error> {
+    /**
+     * Plugin identifier
+     */
+    readonly name = "StandardErrorPlugin";
+    constructor();
+    /**
+     * Matches native Error class
+     */
+    match(error: unknown): error is Error;
+    /**
+     * Converts native Error to standardized response
+     */
+    serialize(error: Error): AppErrorResponse;
+}
+
+/**
+ * Plugin specifically designed for Zod errors with advanced structural formatting.
+ */
+declare class ZodErrorPlugin extends ErrorPlugin<ZodError> {
+    /**
+     * Plugin identifier
+     */
+    readonly name = "ZodErrorPlugin";
+    /**
+     * Private storage for serialization settings.
+     */
+    private options;
+    /**
+     * @param options - Customization for error path and message formatting
+     */
+    constructor(options?: Partial<ZodSerializationOptions>);
+    /**
+     * Checks if the error is an instance of ZodError
+     */
+    match(error: unknown): error is ZodError;
+    /**
+     * Serializes ZodError into the standardized format.
+     * Collects custom error codes if they are provided via mapIssue.
+     */
+    serialize(error: ZodError): AppErrorResponse;
+    /**
+     * Processes Zod issues into the final validation object.
+     */
+    protected formatIssues(issues: ZodError["issues"], codes: Set<string>): Record<string, ExpectedAny>;
+    /**
+     * Handles flat object key generation
+     */
+    private setFlatValue;
+    /**
+     * Recursively builds nested object paths
+     */
+    private setNestedValue;
+}
+
+export { AxiosErrorPlugin, ErrorSerializer, StandardErrorPlugin, ZodErrorPlugin };

package/dist/index.js

@@ -0,0 +1,273 @@
+// src/contants.ts
+var ErrorPriority = {
+  /**
+   * Fallback priority for unhandled errors
+   */
+  FallbackError: -1,
+  /**
+   * Default priority for generic errors
+   */
+  StandardError: 0,
+  /**
+   * Priority for HTTP-related errors
+   */
+  AxiosError: 1,
+  /**
+   * High priority for validation-related errors
+   */
+  ZodError: 2
+};
+
+// src/ErrorSerializer.ts
+var ErrorSerializer = class {
+  /**
+   * List of registered serialization plugins.
+   */
+  plugins = [];
+  /**
+   * Registered callbacks triggered after serialization.
+   */
+  callbacks = [];
+  /**
+   * Registers a plugin and sorts the pipeline by priority.
+   */
+  register(plugin) {
+    this.plugins.push(plugin);
+    this.plugins.sort((a, b) => b.priority - a.priority);
+    return this;
+  }
+  /**
+   * Adds a global callback triggered for every processed error.
+   */
+  subscribe(callback) {
+    this.callbacks.push(callback);
+    return this;
+  }
+  /**
+   * Orchestrates the serialization process.
+   * Returns a standardized response even for primitive types or null.
+   */
+  process(error) {
+    let output = null;
+    for (const plugin of this.plugins) {
+      if (plugin.match(error)) {
+        output = plugin.serialize(error);
+        break;
+      }
+    }
+    if (!output) {
+      output = {
+        metadata: {
+          plugin: "ErrorSerializer",
+          priority: ErrorPriority.FallbackError
+        },
+        error,
+        global: String(error),
+        code: ["UNHANDLED_EXCEPTION"]
+      };
+    }
+    for (const callback of this.callbacks) {
+      callback(output);
+    }
+    return output;
+  }
+};
+
+// src/plugins/AxiosErrorPlugin.ts
+import { isAxiosError } from "axios";
+
+// src/types.ts
+var ErrorPlugin = class {
+  /**
+   * @param priority - Determines execution order (higher values run first)
+   */
+  constructor(priority = ErrorPriority.StandardError) {
+    this.priority = priority;
+  }
+  /**
+   * Internal helper to maintain consistent metadata and structure.
+   */
+  createResponse(error, params) {
+    return {
+      metadata: {
+        plugin: this.name,
+        priority: this.priority
+      },
+      error,
+      ...params
+    };
+  }
+};
+
+// src/plugins/AxiosErrorPlugin.ts
+var AxiosErrorPlugin = class extends ErrorPlugin {
+  /**
+   * Plugin identifier
+   */
+  name = "AxiosErrorPlugin";
+  constructor() {
+    super(ErrorPriority.AxiosError);
+  }
+  /**
+   * Uses Axios type guard to match errors
+   */
+  match(error) {
+    return isAxiosError(error);
+  }
+  /**
+   * Maps HTTP response details to the global schema
+   */
+  serialize(error) {
+    const responseData = error.response?.data;
+    const backendMessage = responseData?.message || responseData?.error?.message;
+    const backendCode = responseData?.code || responseData?.errorCode;
+    const finalMessage = backendMessage || error.message || "Network Error";
+    const finalCodes = backendCode ? Array.isArray(backendCode) ? backendCode : [String(backendCode)] : [`HTTP_${error.response?.status || 0}`];
+    return this.createResponse(error, {
+      global: finalMessage,
+      code: finalCodes,
+      status: error.response?.status || 0
+    });
+  }
+};
+
+// src/plugins/StandardErrorPlugin.ts
+var StandardErrorPlugin = class extends ErrorPlugin {
+  /**
+   * Plugin identifier
+   */
+  name = "StandardErrorPlugin";
+  constructor() {
+    super(ErrorPriority.StandardError);
+  }
+  /**
+   * Matches native Error class
+   */
+  match(error) {
+    return error instanceof Error;
+  }
+  /**
+   * Converts native Error to standardized response
+   */
+  serialize(error) {
+    return this.createResponse(error, {
+      global: error.message,
+      code: ["INTERNAL_ERROR"]
+    });
+  }
+};
+
+// src/plugins/ZodErrorPlugin.ts
+import { ZodError } from "zod";
+var ZodErrorPlugin = class extends ErrorPlugin {
+  /**
+   * Plugin identifier
+   */
+  name = "ZodErrorPlugin";
+  /**
+   * Private storage for serialization settings.
+   */
+  options;
+  /**
+   * @param options - Customization for error path and message formatting
+   */
+  constructor(options = {}) {
+    super(ErrorPriority.ZodError);
+    this.options = {
+      structure: "flat",
+      messageFormat: "array",
+      keySeparator: "_",
+      ...options
+    };
+  }
+  /**
+   * Checks if the error is an instance of ZodError
+   */
+  match(error) {
+    return error instanceof ZodError;
+  }
+  /**
+   * Serializes ZodError into the standardized format.
+   * Collects custom error codes if they are provided via mapIssue.
+   */
+  serialize(error) {
+    const codes = /* @__PURE__ */ new Set(["102"]);
+    const validation = this.formatIssues(error.issues, codes);
+    return this.createResponse(error, {
+      global: "Validation error",
+      code: Array.from(codes),
+      status: 422,
+      validation
+    });
+  }
+  /**
+   * Processes Zod issues into the final validation object.
+   */
+  formatIssues(issues, codes) {
+    const result = {};
+    for (const issue of issues) {
+      const path = issue.path.filter(
+        (k) => typeof k !== "symbol"
+      );
+      let message = issue.message;
+      if (this.options.mapIssue) {
+        const mapped = this.options.mapIssue(issue);
+        if (mapped) {
+          if (mapped.message) message = mapped.message;
+          if (mapped.code) codes.add(mapped.code);
+        }
+      }
+      if (this.options.structure === "nested") {
+        this.setNestedValue(result, path, message);
+      } else {
+        const key = path.join(this.options.keySeparator);
+        this.setFlatValue(result, key, message);
+      }
+    }
+    return result;
+  }
+  /**
+   * Handles flat object key generation
+   */
+  setFlatValue(obj, key, message) {
+    if (this.options.messageFormat === "array") {
+      if (!obj[key]) obj[key] = [];
+      obj[key].push(message);
+    } else {
+      if (!obj[key]) obj[key] = message;
+    }
+  }
+  /**
+   * Recursively builds nested object paths
+   */
+  setNestedValue(obj, path, message) {
+    let current = obj;
+    for (let i = 0; i < path.length; i++) {
+      const key = path[i];
+      const isLast = i === path.length - 1;
+      if (isLast) {
+        if (this.options.messageFormat === "array") {
+          if (!current[key]) current[key] = [];
+          if (Array.isArray(current[key])) {
+            current[key].push(message);
+          } else {
+            current[key] = [message];
+          }
+        } else {
+          current[key] = message;
+        }
+      } else {
+        if (!current[key] || typeof current[key] !== "object") {
+          current[key] = {};
+        }
+        current = current[key];
+      }
+    }
+  }
+};
+export {
+  AxiosErrorPlugin,
+  ErrorSerializer,
+  StandardErrorPlugin,
+  ZodErrorPlugin
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@devua-lab/error-serialization",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		}
+	},
+	"scripts": {
+		"build": "tsup src/index.ts --format cjs,esm --dts --clean",
+		"dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+		"format": "biome format --write .",
+		"lint": "biome lint .",
+		"check": "biome check --write .",
+		"ci": "biome ci .",
+		"test": "vitest",
+		"test:run": "vitest run",
+		"test:cov": "vitest run --coverage"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.14",
+		"@types/node": "^25.2.2",
+		"axios": "^1.13.5",
+		"tsup": "^8.5.1",
+		"typescript": "^5.9.3",
+		"vite": "^7.3.1",
+		"vitest": "^4.0.18",
+		"zod": "^4.3.6"
+	},
+	"peerDependencies": {
+		"axios": ">=1.0.0",
+		"zod": ">=3.0.0"
+	},
+	"peerDependenciesMeta": {
+		"axios": {
+			"optional": true
+		},
+		"zod": {
+			"optional": true
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	]
+}