# 🔥 StoneError - 10 Billion Times Error Handling!

The most scientifically precise error library from the Kingdom of Science!

[![Kingdom of Science Approved](https://img.shields.io/badge/Approved%20By-Kingdom%20of%20Science-blueviolet)]()
[![SO BADASS](https://img.shields.io/badge/Science-SO_BADASS!-blueviolet)]()
[![10 BILLION](https://img.shields.io/badge/10_Billion%25-Reliable-blueviolet)]()

## 🚀 Why StoneError?

- Dr.Stone-themed error handling that would make Senku proud
- Dramatic error traces worthy of a laboratory explosion
- Scientific metadata attached to every error case
- 10 billion percent more organized than standard errors

## 💥 Installation

```bash
go get gitstormr.dev/stone-utils/stoneerror@latest
```

## ⚡ Basic Usage

```go
package main

import (
	"errors"
	"fmt"
	"gitstormr.dev/stone-utils/stoneerror"
)

func main() {
	// Create new scientific error
	err := stoneerror.New(4001, "Invalid chemical formula").
	    WithMetadata("element", "H2O2").
	    WithMetadata("expected", "H2O")

	// Wrap existing errors with scientific precision
	dbErr := errors.New("connection timeout")
	wrappedErr := stoneerror.Wrap(dbErr, 5001, "Database experiment failed").
	    WithMetadata("query", "SELECT * FROM chemical_elements")
}
```

## 🔬 Error Output Format

```text
StoneError [4001]
├─ Message: Invalid chemical formula
├─ Time: 2023-07-15T14:30:45Z
├─ Metadata:
│  ├─ element: H2O2
│  ├─ expected: H2O
└─ Caused by:
    StoneError [5001]
    ├─ Message: Database experiment failed
    ├─ Time: 2023-07-15T14:30:45Z
    ├─ Metadata:
    │  ├─ query: SELECT * FROM chemical_elements
    └─ Caused by:
        connection timeout
```

## 🧪 Core Features

### Scientific Error Codes

```go
const (
	LAB_FAILURE    = 5000 // Critical experiment failure
	BAD_CHEMISTRY  = 4001 // Invalid formula or mixture
	EQUIPMENT_FAIL = 5002 // Tools malfunction
)
```

### Advanced Error Wrapping

```go
// Wrap any error with scientific context
result := performExperiment()
if err != nil {
	return stoneerror.Wrap(err, LAB_FAILURE, "Voltaic pile test failed")
		.WithMetadata("voltage", "3.7V")
		.WithMetadata("materials", []string{"zinc", "copper"})
}
```

### JSON Output

```go
jsonError := err.ToJSON()
// {
//   "code": 4001,
//   "message": "Invalid chemical formula",
//   "time": "2023-07-15T14:30:45Z",
//   "metadata": {
//     "element": "H2O2",
//     "expected": "H2O"
//   }
// }
```

```go
stonelog.InitStoneLab(stonelog.STONE_DEBUG, true, false) // true = JSON, false = Keep suffixes
// Output: {"time":"2023-07-15T12:00:00Z","level":"OBSERVATION","message":"✅ Experiment successful: System ready","caller":"main.go:15"}
```

## ⚗️ Scientific Best Practices

1. Always use specific error codes - Each experiment needs proper labeling!
2. Attach relevant metadata - A good scientist documents everything
3. Wrap underlying errors - Trace the full chain of causality
4. Combine related failures - Multiple data points lead to better conclusions

**Join the Scientific Revolution!**

> "With StoneError, we're 10 billion percent prepared for any failure!" - Senku Ishigami

Kingdom of Science Approved

(Now with 100% more Chrome screaming "SO BADASS!")