Core Utilities

/**
 * Serializes error objects to JSON-safe format, handling circular references
 * @param value - Error object or any value to serialize
 * @returns Serialized error object, string, or undefined
 */
function serializeError(value: any): undefined | To | string;

interface To {
  name?: string;
  message?: string;
  stack?: string;
}

import { serializeError, TransportError } from "@ledgerhq/errors";

// Serialize a transport error
const error = new TransportError("Connection failed", "USB_001");
const serialized = serializeError(error);
console.log(JSON.stringify(serialized));
// {"name":"TransportError","message":"Connection failed","id":"USB_001","stack":"..."}

// Serialize any error
const genericError = new Error("Something went wrong");
const serializedGeneric = serializeError(genericError);
console.log(JSON.stringify(serializedGeneric));
// {"name":"Error","message":"Something went wrong","stack":"..."}

// Handle circular references
const circularError = new Error("Circular");
circularError.self = circularError;
const serializedCircular = serializeError(circularError);
// Circular references are replaced with "[Circular]"

/**
 * Deserializes JSON error objects back to Error instances
 * @param object - Serialized error object to deserialize
 * @returns Reconstructed Error instance with proper prototype chain
 */
function deserializeError(object: any): Error;

import { deserializeError, serializeError, TransportError } from "@ledgerhq/errors";

// Deserialize a transport error
const error = new TransportError("Connection failed", "USB_001");
const serialized = serializeError(error);
const deserialized = deserializeError(serialized);

console.log(deserialized instanceof TransportError); // true
console.log(deserialized.message); // "Connection failed"
console.log(deserialized.id); // "USB_001"

// Deserialize from JSON string
const jsonError = '{"name":"UserRefusedOnDevice","message":"User refused"}';
const parsedError = deserializeError(JSON.parse(jsonError));
console.log(parsedError.name); // "UserRefusedOnDevice"

// Handle unknown error classes
const unknownError = { name: "CustomError", message: "Unknown error type" };
const deserialized = deserializeError(unknownError);
// Creates a new custom error class if not found in registry

/**
 * Creates a custom error class constructor function
 * @param name - Name of the error class
 * @returns Constructor function for the custom error class
 */
function createCustomErrorClass(name: string): CustomErrorFunc;

type CustomErrorFunc = (
  message?: string,
  fields?: { [key: string]: any }
) => void;

import { createCustomErrorClass } from "@ledgerhq/errors";

// Create a custom error class
const MyCustomError = createCustomErrorClass("MyCustomError");

// Use the custom error class
const error1 = new MyCustomError("Something went wrong");
console.log(error1.name); // "MyCustomError"
console.log(error1.message); // "Something went wrong"

// With additional fields
const error2 = new MyCustomError("Database error", { 
  code: "DB_001", 
  severity: "high" 
});
console.log(error2.code); // "DB_001"
console.log(error2.severity); // "high"

// instanceof checks work
console.log(error1 instanceof MyCustomError); // true
console.log(error1 instanceof Error); // true

/**
 * Registers a custom deserializer for specific error types
 * @param name - Name of the error class
 * @param deserializer - Function to deserialize the error object
 */
function addCustomErrorDeserializer(
  name: string,
  deserializer: (obj: any) => any
): void;

import { addCustomErrorDeserializer, deserializeError } from "@ledgerhq/errors";

// Register a custom deserializer
addCustomErrorDeserializer("MySpecialError", (obj) => {
  const error = new Error(obj.message);
  error.name = "MySpecialError";
  error.customProperty = obj.customProperty;
  error.timestamp = new Date(obj.timestamp);
  return error;
});

// Now deserialization will use the custom deserializer
const serializedSpecialError = {
  name: "MySpecialError",
  message: "Special error occurred",
  customProperty: "special value",
  timestamp: "2023-01-01T00:00:00.000Z"
};

const deserialized = deserializeError(serializedSpecialError);
console.log(deserialized.name); // "MySpecialError"
console.log(deserialized.customProperty); // "special value"
console.log(deserialized.timestamp instanceof Date); // true

interface To {
  name?: string;
  message?: string;
  stack?: string;
}

type CustomErrorFunc = (
  message?: string,
  fields?: { [key: string]: any }
) => void;