tessl/npm-ledgerhq--errors

Comprehensive error handling system for Ledger hardware wallet applications and libraries

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Error Utilities

Name: tessl/npm-ledgerhq--errors
Author: tessl

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

Capabilities

Create Custom Error Class

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

/**
 * Creates a custom error class with consistent naming and structure
 * @param name - The name of the custom error class
 * @returns CustomErrorFunc constructor function
 */
function createCustomErrorClass(name: string): CustomErrorFunc;

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

Usage Examples:

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");
const error2 = new MyCustomError("Custom message", { code: 500, context: "API" });

console.log(error1.name); // "MyCustomError"
console.log(error1.message); // "Something went wrong"
console.log(error2.code); // 500
console.log(error2.context); // "API"

Serialize Error

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

/**
 * Serializes an error object for cross-context communication
 * @param value - The error or value to serialize
 * @returns Serialized representation or the original value
 */
function serializeError(value: any): undefined | To | string;

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

Usage Examples:

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

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

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

// Handle non-error values
const serializedNull = serializeError(null); // null
const serializedString = serializeError("test"); // "test"

Deserialize Error

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

/**
 * Deserializes an error object from its serialized form
 * @param object - The serialized error object
 * @returns Reconstructed Error instance
 */
function deserializeError(object: any): Error;

Usage Examples:

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

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

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

// Deserialize from object
const errorData = {
  name: "TransportError",
  message: "USB connection lost",
  id: "USB_DISCONNECT"
};
const reconstructed = deserializeError(errorData);
console.log(reconstructed.message); // "USB connection lost"
console.log(reconstructed.id); // "USB_DISCONNECT"

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

Add Custom Error Deserializer

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

/**
 * Registers a custom deserializer for a specific error type
 * @param name - The error type name to register deserializer for
 * @param deserializer - Function to deserialize objects of this type
 */
function addCustomErrorDeserializer(
  name: string,
  deserializer: (obj: any) => any
): void;

Usage Examples:

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

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

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

const deserialized = deserializeError(complexErrorData);
console.log(deserialized.customProperty); // "value"
console.log(deserialized.timestamp instanceof Date); // true