tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5597b78f0de343628f9942fbca0e413005e08aa7
hakorune/docs/private/roadmap/phases/phase-24-ultimate-language-design/practical-boxes-proposals.md

17 KiB
Raw Blame History

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)

// 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:

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)

// 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:

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)

// 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:

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)

// 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:

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)

// 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:

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

// 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

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)

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

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

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

local all_vars = EnvironmentBox.all()  // MapBox

11. TemplateEngineBox

Impact: String template rendering

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

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

// 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

// 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

// 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

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

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

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

18. WebSocketBox

Impact: Real-time communication

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

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

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 for cross-language feature comparison.