hyle

README

hyle

Hyle (pronounced /ˈhaɪli/, from Greek ὕλη meaning "fundamental substance") provides atomic building blocks for Go applications. Like chemical elements forming complex matter, Hyle offers self-contained utilities that work independently or combine powerfully.

Overview

Hyle (/ˈhaɪli/, from Greek ὕλη "fundamental substance") provides atomic building blocks for Go applications. Designed as the periodic table of Go utilities, each component works independently while enabling powerful combinations - with zero third-party dependencies.

Features

• 🧪 Self-contained Atoms: 300-500 LOC modules with single responsibility
• 🚫 Dependency-Free: Pure Go standard library implementation
• ⚡ Nanosecond Precision: Memory-safe, allocation-optimized critical paths
• 🧩 Modern Go 1.21+: Leverages generics, slog, and arena experiments
• 📦 Production Ready: Battle-tested in high-load environments

Installation

go get github.com/yourusername/hyle@latest

Quick Start

Structured Logging

logger := hyle.NewCoreLogger(hyle.WithUTC, hyle.WithLevel(slog.LevelDebug))
logger.LogAttrs(context.Background(), slog.LevelInfo, "Service initialized",
    slog.Int("port", 8080), 
    slog.Duration("startup_latency", 12*time.Millisecond))

Error Taxonomy

const ErrAuthFailure = hyle.DefineError("AUTH_FAILURE", 
    "Authentication failed", 
    http.StatusUnauthorized,
    hyle.WithRetryable(true))

func LoginHandler() error {
    if invalid {
        return ErrAuthFailure.Wrap(err).
            With("attempts", 3).
            With("client_ip", "192.168.1.1")
    }
}

Cryptographic Primitives

key := hyle.GenerateAEADKey() // XChaCha20-Poly1305
cipher, _ := hyle.NewAEADCipher(key)

encrypted := cipher.Seal(nil, []byte("sensitive data"))
decrypted, _ := cipher.Open(nil, encrypted)

Core Modules

Package	Description	Key Features
hyle/log	Zero-alloc structured logging	Slog integration, event tracking
hyle/errcode	Hierarchical error taxonomy	Stack traces, metadata attachment
hyle/algo	High-performance algorithms	Parallel sort, memory-mapped bloom
hyle/crypto	Modern cryptography	XChaCha20, Argon2id, FIPS 140-2 modes
hyle/containers	Concurrent data structures	Lock-free LRU, sharded maps
hyle/validate	Runtime validation	JSON Schema, type guards

Performance Benchmarks

BenchmarkLogAttr-16         12.7 ns/op        0 allocs/op  
BenchmarkErrorWrap-16       8.3 ns/op         0 allocs/op  
BenchmarkXXH3Hash-16        1.88 GB/s        16 B/op
BenchmarkAEADEncrypt-16     289 MB/s          32 B/op  

Run benchmarks:

go test -bench=. -count=5 -benchmem ./...

Design Principles

1. Atomic Composition
   Each module solves exactly one problem with minimal API surface

2. Transparent Mechanics
   No hidden goroutines or implicit initialization

3. Memory Discipline
   Zero heap allocations in hot paths

4. Forward Compatibility
   Strict SemVer with 5-year LTS guarantee

Contributing

We welcome atomic-sized contributions! Please review:
📘 Contribution Guide
📜 Code of Conduct

Key requirements:

• Single-purpose PRs (<300 LOC changes)
• Benchmark proofs for performance claims
• No new dependencies

Documentation

📚 Full API Reference
🎮 Interactive Examples
📝 Architecture Decisions

---

📄 License: Apache 2.0 © 2024 [Your Name]
🐞 Report Issues
💬 Join Discussion

Key features of this README:

1. **Interactive Documentation**: Direct links to GoDoc and examples
2. **Performance Transparency**: Benchmark data and run instructions
3. **Module Clarity**: Table-based package overview
4. **Project Maturity Signals**: CI/CD badges and LTS promise
5. **Visual Hierarchy**: Clean section separation with emoji markers
6. **Actionable Content**: Copy-paste ready code samples

Recommended next steps:
1. Create `docs/` directory with architecture diagrams
2. Add real benchmark data from your implementation
3. Set up GitHub Actions for CI/CD
4. Write detailed contribution guidelines
5. Develop interactive examples in Go Playground format