# strand-errors

[![CI](https://github.com/l1feai/strand-errors/actions/workflows/ci.yml/badge.svg)](https://github.com/l1feai/strand-errors/actions/workflows/ci.yml)

Standardized error types for the Strand ecosystem.

## Features

- Comprehensive error categories for all Strand operations
- Automatic conversion between error types
- JavaScript compatibility layer
- Error context support for better debugging
- Serialization support for network protocols
- Zero-cost abstractions

## Error Categories

- **StorageError**: I/O operations, block management, storage backends
- **CryptoError**: Signature verification, key operations, encryption/decryption
- **ProtocolError**: Network protocol issues, version mismatches, timeouts
- **OwnershipError**: DID validation, permissions, governance (L1feOS-specific)
- **ReplicationError**: Synchronization, peer connectivity, bandwidth
- **ValidationError**: Data integrity, checksums, schema validation

## Usage

```rust
use strand_errors::{Result, StrandError, StorageError, ErrorContext};

// Basic error creation
fn read_block(index: u64) -> Result<Vec<u8>> {
    Err(StorageError::BlockNotFound(index).into())
}

// With context
fn load_data() -> Result<Vec<u8>> {
    std::fs::read("data.bin")
        .map_err(StorageError::from)?
        .context("Failed to load data from disk")
}

// Ownership validation
fn check_permission(identity: &str) -> Result<()> {
    if !has_permission(identity) {
        return Err(OwnershipError::PermissionDenied {
            identity: identity.to_string(),
            permission: "write".to_string(),
        }
        .into());
    }
    Ok(())
}
```

## Error Codes

The library provides numeric error codes for external APIs:

```rust
let err = StrandError::Storage(StorageError::BlockNotFound(42));
let code = ErrorCode::from(&err); // ErrorCode::BlockNotFound (1002)
```

## JavaScript Compatibility

Errors can be mapped to JavaScript-compatible names:

```rust
let err = StrandError::Storage(StorageError::BlockNotFound(42));
assert_eq!(err.error_name(), "BLOCK_NOT_FOUND");
```

## Features

- `serde`: Enable serialization support for errors

## io::ErrorKind Mapping

The master error type provides a mapping to `std::io::ErrorKind` where appropriate, and can be converted into `std::io::Error`:

```rust
use std::io;
use strand_errors::{StrandError, StorageError, ToIoErrorKind};

let err: StrandError = StorageError::BlockNotFound(42).into();
assert_eq!(err.to_io_error_kind(), Some(io::ErrorKind::NotFound));

let io_err: io::Error = err.into();
assert_eq!(io_err.kind(), io::ErrorKind::NotFound);
```

## License

MIT OR Apache-2.0
