0
# Error Utilities
1

2
Core utilities for creating custom error classes and handling error serialization across different contexts in the Ledger ecosystem.
3

4
## Capabilities
5

6
### Create Custom Error Class
7

8
Factory function to create custom error classes with consistent behavior and structure.
9

10
```typescript { .api }
11
/**
12
 * Creates a custom error class with consistent naming and structure
13
 * @param name - The name of the custom error class
14
 * @returns CustomErrorFunc constructor function
15
 */
16
function createCustomErrorClass(name: string): CustomErrorFunc;
17

18
type CustomErrorFunc = (
19
  message?: string,
20
  fields?: { [key: string]: any }
21
) => void;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { createCustomErrorClass } from "@ledgerhq/errors";
28

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

32
// Use the custom error class
33
const error1 = new MyCustomError("Something went wrong");
34
const error2 = new MyCustomError("Custom message", { code: 500, context: "API" });
35

36
console.log(error1.name); // "MyCustomError"
37
console.log(error1.message); // "Something went wrong"
38
console.log(error2.code); // 500
39
console.log(error2.context); // "API"
40
```
41

42
### Serialize Error
43

44
Serializes error objects for cross-context communication, handling circular references and maintaining essential error information.
45

46
```typescript { .api }
47
/**
48
 * Serializes an error object for cross-context communication
49
 * @param value - The error or value to serialize
50
 * @returns Serialized representation or the original value
51
 */
52
function serializeError(value: any): undefined | To | string;
53

54
interface To {
55
  name?: string;
56
  message?: string;
57
  stack?: string;
58
}
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
import { serializeError, DeviceNotGenuineError } from "@ledgerhq/errors";
65

66
// Serialize a standard error
67
const error = new Error("Connection failed");
68
const serialized = serializeError(error);
69
console.log(serialized);
70
// { name: "Error", message: "Connection failed", stack: "..." }
71

72
// Serialize a custom Ledger error
73
const deviceError = new DeviceNotGenuineError("Device verification failed");
74
const serializedDevice = serializeError(deviceError);
75
console.log(serializedDevice);
76
// { name: "DeviceNotGenuine", message: "Device verification failed", stack: "..." }
77

78
// Handle non-error values
79
const serializedNull = serializeError(null); // null
80
const serializedString = serializeError("test"); // "test"
81
```
82

83
### Deserialize Error
84

85
Deserializes error objects from their serialized form, reconstructing the original error type and properties.
86

87
```typescript { .api }
88
/**
89
 * Deserializes an error object from its serialized form
90
 * @param object - The serialized error object
91
 * @returns Reconstructed Error instance
92
 */
93
function deserializeError(object: any): Error;
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import { deserializeError, serializeError, DeviceNotGenuineError } from "@ledgerhq/errors";
100

101
// Round-trip serialization
102
const originalError = new DeviceNotGenuineError("Authentication failed");
103
const serialized = serializeError(originalError);
104
const deserialized = deserializeError(serialized);
105

106
console.log(deserialized instanceof Error); // true
107
console.log(deserialized.name); // "DeviceNotGenuine"
108
console.log(deserialized.message); // "Authentication failed"
109

110
// Deserialize from object
111
const errorData = {
112
  name: "TransportError",
113
  message: "USB connection lost",
114
  id: "USB_DISCONNECT"
115
};
116
const reconstructed = deserializeError(errorData);
117
console.log(reconstructed.message); // "USB connection lost"
118
console.log(reconstructed.id); // "USB_DISCONNECT"
119

120
// Handle unknown error types
121
const unknownError = { name: "CustomError", message: "Unknown error" };
122
const deserialized = deserializeError(unknownError);
123
// Creates new error class automatically and logs warning
124
```
125

126
### Add Custom Error Deserializer
127

128
Registers custom deserializer functions for specific error types, enabling proper reconstruction of complex error objects.
129

130
```typescript { .api }
131
/**
132
 * Registers a custom deserializer for a specific error type
133
 * @param name - The error type name to register deserializer for
134
 * @param deserializer - Function to deserialize objects of this type
135
 */
136
function addCustomErrorDeserializer(
137
  name: string,
138
  deserializer: (obj: any) => any
139
): void;
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { addCustomErrorDeserializer, deserializeError } from "@ledgerhq/errors";
146

147
// Register custom deserializer for complex error
148
addCustomErrorDeserializer("ComplexError", (obj) => {
149
  const error = new Error(obj.message);
150
  error.name = "ComplexError";
151
  error.customProperty = obj.customProperty;
152
  error.timestamp = new Date(obj.timestamp);
153
  return error;
154
});
155

156
// Now deserializeError can properly handle ComplexError objects
157
const complexErrorData = {
158
  name: "ComplexError",
159
  message: "Complex operation failed",
160
  customProperty: "value",
161
  timestamp: "2023-01-01T00:00:00.000Z"
162
};
163

164
const deserialized = deserializeError(complexErrorData);
165
console.log(deserialized.customProperty); // "value"
166
console.log(deserialized.timestamp instanceof Date); // true
167
```