# Practical Boxes Proposals - 20 Essential Runtime Libraries

**Generated by**: Task Agent 3 (Practical Libraries Analysis)
**Date**: 2025-10-12
**Philosophy**: Everything is Box, prefer plugins over built-ins

---

## 📊 Priority Matrix

| Priority | Category | Count | Examples |
|----------|----------|-------|----------|
| **Phase 1** | Essential | 5 | HTTPClient, YAML, CSV, Logger, Validation |
| **Phase 2** | Common | 7 | JSON (enhance), DateTime, Path, Process, Environment, Template, Testing |
| **Phase 3** | Advanced | 8 | Crypto, Compression, Database, Cache, Queue, WebSocket, Email, CLI |

---

## 🚀 Phase 1: Essential Boxes (Week 1-2)

### 1. **HTTPClientBox** ⭐ HIGHEST PRIORITY
**Impact**: Web development essential (axios/requests equivalent)
**Implementation**: Plugin (network I/O)

```hakorune
// API Design
using http as HTTPClientBox

static box Main {
    main() {
        local client = new HTTPClientBox()

        // GET request
        local response = client.get("https://api.example.com/users")
        print(response.status)  // 200
        print(response.body)    // JSON string

        // POST request
        local data = new MapBox()
        data.set("name", "Alice")
        data.set("email", "alice@example.com")

        local response2 = client.post("https://api.example.com/users", data)
        print(response2.status)

        // With headers
        local headers = new MapBox()
        headers.set("Authorization", "Bearer token123")
        headers.set("Content-Type", "application/json")

        local response3 = client.get("https://api.example.com/protected", headers)

        return 0
    }
}
```

**API Specification**:
```hakorune
box HTTPClientBox {
    // GET request
    get(url: StringBox) -> HTTPResponseBox
    get(url: StringBox, headers: MapBox) -> HTTPResponseBox

    // POST request
    post(url: StringBox, body: MapBox) -> HTTPResponseBox
    post(url: StringBox, body: StringBox, headers: MapBox) -> HTTPResponseBox

    // PUT, DELETE, PATCH
    put(url: StringBox, body: MapBox) -> HTTPResponseBox
    delete(url: StringBox) -> HTTPResponseBox
    patch(url: StringBox, body: MapBox) -> HTTPResponseBox

    // Advanced
    set_timeout(ms: IntegerBox) -> HTTPClientBox
    set_retry(count: IntegerBox) -> HTTPClientBox
}

box HTTPResponseBox {
    status: IntegerBox       // HTTP status code
    headers: MapBox          // Response headers
    body: StringBox          // Response body

    json() -> MapBox         // Parse body as JSON
    text() -> StringBox      // Get body as string
    is_ok() -> BoolBox       // status >= 200 && status < 300
    is_error() -> BoolBox    // status >= 400
}
```

**Implementation notes**:
- Backend: libcurl (Rust: reqwest crate)
- Async: Use nowait/await for non-blocking I/O
- Error handling: Return ResultBox<HTTPResponseBox, ErrorBox>

---

### 2. **YAMLBox** ⭐ Configuration Essential
**Impact**: Config file support (ubiquitous in DevOps)
**Implementation**: Plugin (parser)

```hakorune
// API Design
using yaml as YAMLBox

static box Main {
    main() {
        // Parse YAML string
        local yaml_str = r#"
name: MyApp
version: 1.0.0
dependencies:
  - hakorune: ">=0.1"
  - http: "^1.0"
settings:
  debug: true
  port: 8080
"#

        local config = YAMLBox.parse(yaml_str)
        print(config.get("name"))         // "MyApp"
        print(config.get("version"))      // "1.0.0"

        local settings = config.get("settings")
        print(settings.get("port"))       // 8080

        // Load from file
        local file_config = YAMLBox.load("config.yaml")

        // Serialize to YAML
        local data = new MapBox()
        data.set("key", "value")
        data.set("number", 42)

        local yaml_output = YAMLBox.dump(data)
        print(yaml_output)
        // Output:
        // key: value
        // number: 42

        return 0
    }
}
```

**API Specification**:
```hakorune
static box YAMLBox {
    // Parse YAML string to MapBox/ArrayBox
    parse(yaml_str: StringBox) -> MapBox

    // Load YAML from file
    load(file_path: StringBox) -> MapBox

    // Serialize MapBox/ArrayBox to YAML string
    dump(data: MapBox) -> StringBox

    // Save MapBox/ArrayBox to YAML file
    save(data: MapBox, file_path: StringBox) -> BoolBox
}
```

**Implementation notes**:
- Backend: yaml-rust or serde_yaml
- Support multi-document YAML (multiple `---` sections)
- Handle anchors and aliases (`&anchor`, `*alias`)

---

### 3. **CSVBox** ⭐ Data Processing Essential
**Impact**: Data science/ETL workflows
**Implementation**: Plugin (parser)

```hakorune
// API Design
using csv as CSVBox

static box Main {
    main() {
        // Read CSV file
        local csv = new CSVBox()
        local rows = csv.read("data.csv")

        // Iterate rows
        local iter = rows.iterator()
        loop(iter.has_next()) {
            local row = iter.next()
            print(row.get("name") + ": " + row.get("score"))
        }

        // Write CSV file
        local output = new CSVBox()
        local data = new ArrayBox()

        local row1 = new MapBox()
        row1.set("name", "Alice")
        row1.set("score", "95")
        data.push(row1)

        local row2 = new MapBox()
        row2.set("name", "Bob")
        row2.set("score", "87")
        data.push(row2)

        output.write("output.csv", data)

        return 0
    }
}
```

**API Specification**:
```hakorune
box CSVBox {
    // Read CSV file into ArrayBox<MapBox>
    read(file_path: StringBox) -> ArrayBox

    // Read with custom delimiter
    read_with_delimiter(file_path: StringBox, delimiter: StringBox) -> ArrayBox

    // Write ArrayBox<MapBox> to CSV file
    write(file_path: StringBox, data: ArrayBox) -> BoolBox

    // Write with custom delimiter
    write_with_delimiter(file_path: StringBox, data: ArrayBox, delimiter: StringBox) -> BoolBox

    // Configure
    set_has_headers(value: BoolBox) -> CSVBox
    set_quote_char(char: StringBox) -> CSVBox
}
```

**Implementation notes**:
- Backend: csv crate (Rust)
- Support quoted fields with commas
- Handle different line endings (CRLF, LF)

---

### 4. **LoggerBox** ⭐ Debugging Essential
**Impact**: Structured logging for production systems
**Implementation**: Plugin (I/O)

```hakorune
// API Design
using logger as LoggerBox

static box Main {
    main() {
        local log = LoggerBox.new("MyApp")

        // Log levels
        log.debug("Debug message")
        log.info("Application started")
        log.warn("Configuration file missing, using defaults")
        log.error("Failed to connect to database")

        // Structured logging
        local context = new MapBox()
        context.set("user_id", 123)
        context.set("action", "login")
        log.info("User logged in", context)

        // Output:
        // [2025-10-12 12:34:56] INFO [MyApp] User logged in {user_id: 123, action: "login"}

        // Configure output
        log.set_level("INFO")        // Only INFO and above
        log.set_file("app.log")      // Write to file
        log.set_format("json")       // JSON format

        return 0
    }
}
```

**API Specification**:
```hakorune
box LoggerBox {
    birth(name: StringBox)

    // Log methods
    debug(message: StringBox)
    debug(message: StringBox, context: MapBox)

    info(message: StringBox)
    info(message: StringBox, context: MapBox)

    warn(message: StringBox)
    warn(message: StringBox, context: MapBox)

    error(message: StringBox)
    error(message: StringBox, context: MapBox)

    // Configuration
    set_level(level: StringBox) -> LoggerBox  // "DEBUG", "INFO", "WARN", "ERROR"
    set_file(file_path: StringBox) -> LoggerBox
    set_format(format: StringBox) -> LoggerBox  // "text", "json"
}

static box LoggerBox {
    new(name: StringBox) -> LoggerBox
    get_logger(name: StringBox) -> LoggerBox  // Get or create logger
}
```

**Implementation notes**:
- Backend: env_logger or log crate (Rust)
- Support log rotation (size-based, time-based)
- Thread-safe for concurrent logging

---

### 5. **ValidationBox** ⭐ Input Safety Essential
**Impact**: Prevent bad data from entering system
**Implementation**: Plugin (pure logic)

```hakorune
// API Design
using validation as ValidationBox

static box Main {
    main() {
        local validator = new ValidationBox()

        // String validation
        local email = "user@example.com"
        if !validator.is_email(email) {
            print("Invalid email")
        }

        // Number validation
        local age = 25
        if !validator.is_in_range(age, 0, 120) {
            print("Invalid age")
        }

        // Required field validation
        local name = ""
        if !validator.is_not_empty(name) {
            print("Name is required")
        }

        // URL validation
        local url = "https://example.com"
        if !validator.is_url(url) {
            print("Invalid URL")
        }

        // Custom regex validation
        local phone = "123-456-7890"
        if !validator.matches(phone, r"\d{3}-\d{3}-\d{4}") {
            print("Invalid phone format")
        }

        return 0
    }
}
```

**API Specification**:
```hakorune
box ValidationBox {
    // String validators
    is_email(value: StringBox) -> BoolBox
    is_url(value: StringBox) -> BoolBox
    is_not_empty(value: StringBox) -> BoolBox
    is_alpha(value: StringBox) -> BoolBox
    is_alphanumeric(value: StringBox) -> BoolBox
    is_numeric(value: StringBox) -> BoolBox

    // Length validators
    is_min_length(value: StringBox, min: IntegerBox) -> BoolBox
    is_max_length(value: StringBox, max: IntegerBox) -> BoolBox
    is_length(value: StringBox, len: IntegerBox) -> BoolBox

    // Number validators
    is_in_range(value: IntegerBox, min: IntegerBox, max: IntegerBox) -> BoolBox
    is_positive(value: IntegerBox) -> BoolBox
    is_negative(value: IntegerBox) -> BoolBox

    // Pattern matching
    matches(value: StringBox, pattern: StringBox) -> BoolBox

    // Advanced
    validate_all(data: MapBox, rules: MapBox) -> ResultBox
}
```

**Implementation notes**:
- Backend: regex crate (Rust)
- Support common patterns (email, URL, phone, credit card)
- Return detailed error messages with field names

---

## 💡 Phase 2: Common Boxes (Week 3-4)

### 6. **JSONBox Enhancement** (Already exists, enhance)
**Impact**: Better JSON manipulation
**Current**: Basic parse/stringify
**Enhancement**: JsonPath queries, schema validation

```hakorune
// Enhanced API
local json = JSONBox.parse(r#"{"users":[{"name":"Alice","age":30}]}"#)

// JsonPath query
local names = json.query("$.users[*].name")  // ["Alice"]

// Schema validation
local schema = JSONBox.parse(r#"{"type":"object","required":["name"]}"#)
local valid = json.validate(schema)
```

---

### 7. **DateTimeBox**
**Impact**: Time manipulation (current TimeBox is limited)
**Enhancement**: Formatting, parsing, arithmetic

```hakorune
local now = DateTimeBox.now()
print(now.format("%Y-%m-%d %H:%M:%S"))  // "2025-10-12 12:34:56"

local future = now.add_days(7)
local diff = future.diff(now)  // DurationBox

local parsed = DateTimeBox.parse("2025-10-12", "%Y-%m-%d")
```

---

### 8. **PathBox**
**Impact**: File path manipulation (safer than string concat)

```hakorune
local path = new PathBox("/home/user/documents")
path = path.join("project").join("src").join("main.hako")
print(path.to_string())  // "/home/user/documents/project/src/main.hako"

print(path.filename())   // "main.hako"
print(path.extension())  // "hako"
print(path.parent())     // "/home/user/documents/project/src"

if path.exists() {
    print("File exists")
}
```

---

### 9. **ProcessBox**
**Impact**: Spawn external processes

```hakorune
local proc = new ProcessBox("ls", ["-la", "/tmp"])
local result = proc.run()
print(result.stdout)
print(result.exit_code)

// Async execution
nowait future = proc.spawn()
local result2 = await future
```

---

### 10. **EnvironmentBox**
**Impact**: Environment variable access

```hakorune
local env = EnvironmentBox.get("PATH")
EnvironmentBox.set("MY_VAR", "value")

local all_vars = EnvironmentBox.all()  // MapBox
```

---

### 11. **TemplateEngineBox**
**Impact**: String template rendering

```hakorune
local template = r"Hello, {{name}}! You have {{count}} messages."
local vars = new MapBox()
vars.set("name", "Alice")
vars.set("count", 5)

local result = TemplateEngineBox.render(template, vars)
print(result)  // "Hello, Alice! You have 5 messages."
```

---

### 12. **TestingBox** (Integrate with @test macro)
**Impact**: Test framework utilities

```hakorune
local suite = new TestingBox("Calculator Tests")

suite.add_test("addition", function() {
    TestingBox.assert_equals(1 + 1, 2)
})

suite.run()
```

---

## 🔮 Phase 3: Advanced Boxes (Week 5+)

### 13. **CryptoBox**
**Impact**: Security operations

```hakorune
// Hashing
local hash = CryptoBox.sha256("password")

// Encryption
local encrypted = CryptoBox.aes_encrypt("secret data", "key")
local decrypted = CryptoBox.aes_decrypt(encrypted, "key")

// Random
local random_bytes = CryptoBox.random_bytes(32)
local uuid = CryptoBox.uuid()
```

---

### 14. **CompressionBox**
**Impact**: Data compression/decompression

```hakorune
// Gzip
local compressed = CompressionBox.gzip("large data...")
local decompressed = CompressionBox.gunzip(compressed)

// Zstd (better compression)
local compressed2 = CompressionBox.zstd("large data...", level: 3)
```

---

### 15. **DatabaseBox** (Generic interface)
**Impact**: Database access

```hakorune
// SQLite
local db = DatabaseBox.connect("sqlite:///data.db")
local result = db.query("SELECT * FROM users WHERE age > ?", [25])

// Async
nowait future = db.query_async("SELECT * FROM large_table")
local result2 = await future
```

---

### 16. **CacheBox**
**Impact**: In-memory caching

```hakorune
local cache = new CacheBox()
cache.set("key", "value", ttl: 60)  // 60 seconds TTL

local value = cache.get("key")
if value == null {
    value = expensive_computation()
    cache.set("key", value)
}
```

---

### 17. **QueueBox**
**Impact**: Task queue for async processing

```hakorune
local queue = new QueueBox()
queue.push("task1")
queue.push("task2")

local task = queue.pop()  // "task1"
```

---

### 18. **WebSocketBox**
**Impact**: Real-time communication

```hakorune
local ws = new WebSocketBox("wss://example.com/socket")
ws.connect()

ws.on_message(function(message) {
    print("Received: " + message)
})

ws.send("Hello, server!")
```

---

### 19. **EmailBox**
**Impact**: Send emails

```hakorune
local email = new EmailBox()
email.set_smtp("smtp.gmail.com", 587, "user", "pass")
email.send(
    from: "sender@example.com",
    to: "recipient@example.com",
    subject: "Test Email",
    body: "Hello from Hakorune!"
)
```

---

### 20. **CLIBox** (Command-line argument parsing)
**Impact**: Better CLI tools

```hakorune
local cli = new CLIBox()
cli.add_argument("--input", "-i", required: true)
cli.add_argument("--output", "-o", default: "output.txt")
cli.add_flag("--verbose", "-v")

local args = cli.parse()
print(args.get("input"))
if args.get("verbose") {
    print("Verbose mode enabled")
}
```

---

## 🎯 Implementation Strategy

### Plugin vs Built-in Decision Matrix

| Box | Type | Reason |
|-----|------|--------|
| HTTPClient, WebSocket | **Plugin** | Network I/O, external dependencies |
| YAML, CSV | **Plugin** | Parser complexity, optional feature |
| Logger | **Plugin** | I/O operations |
| Validation | **Plugin** | Pure logic, can be built-in later |
| JSON, DateTime | **Built-in** | Core functionality |
| Path, Environment | **Built-in** | OS integration |
| Crypto, Compression | **Plugin** | External libraries (OpenSSL, zstd) |
| Database | **Plugin** | Multiple backends |

### Development Phases

**Phase 1 Priority** (Week 1-2):
1. HTTPClientBox - enables web development
2. YAMLBox - enables configuration
3. CSVBox - enables data processing
4. LoggerBox - enables debugging
5. ValidationBox - enables input safety

**Phase 2 Common** (Week 3-4):
1. JSONBox enhancement (JsonPath, schema)
2. DateTimeBox (formatting, arithmetic)
3. PathBox (safe file paths)
4. ProcessBox (spawn commands)
5. EnvironmentBox (env vars)
6. TemplateEngineBox (string templates)
7. TestingBox (test utilities)

**Phase 3 Advanced** (Week 5+):
1. CryptoBox (security)
2. CompressionBox (gzip, zstd)
3. DatabaseBox (SQLite, PostgreSQL)
4. CacheBox (in-memory)
5. QueueBox (task queue)
6. WebSocketBox (real-time)
7. EmailBox (SMTP)
8. CLIBox (argument parsing)

---

## 📈 Expected Outcomes

**Real-world usability**: Hakorune becomes practical for:
- ✅ Web services (HTTP + JSON + YAML + Logger)
- ✅ Data processing (CSV + Validation + DateTime)
- ✅ CLI tools (CLI + Path + Environment + Process)
- ✅ System automation (Process + Environment + Logger)

**Code reduction**: 50-70% reduction in boilerplate for common tasks

**Ecosystem growth**: Third-party Boxes can extend functionality

---

## ✅ Quality Standards

Each Box must have:
1. ✅ Complete API documentation with examples
2. ✅ Smoke tests (quick + integration)
3. ✅ Error handling (return ResultBox or panic with clear messages)
4. ✅ Thread safety (if applicable)
5. ✅ Performance benchmarks (for I/O operations)
6. ✅ Integration guide (how to install/enable)

---

**Next**: See [language-features-analysis.md](language-features-analysis.md) for cross-language feature comparison.