Hexser - Zero-Boilerplate Hexagonal Architecture

Zero-boilerplate hexagonal architecture with graph-based introspection for Rust.

The hexser crate provides reusable generic types and traits for implementing Hexagonal Architecture (Ports and Adapters pattern) with automatic graph construction, intent inference, and architectural validation. Write business logic, let hexser handle the architecture.

---

Table of Contents

• Why hexser?
• Quick Start
• Complete Tutorial
• CQRS Pattern with hex
• Testing Your Hexagonal Application
• Error Handling
• Real-World Example - TODO Application
• Advanced Patterns
• Knowledge Graph
• Static (non-dyn) DI — WASM-friendly
• Repository: Filter-based queries (vNext)
• AI Context Export (CLI)
• Examples & Tutorials
• Potions (copy-friendly examples)
• Contributing
• License
• Acknowledgments
• Additional Resources

Tip: Press Cmd/Ctrl+F and search for “Part” to jump to tutorials.

Why hexser?

Traditional hexagonal architecture requires significant boilerplate:

• Manual registration of components
• Explicit dependency wiring
• Repetitive trait implementations
• Complex validation logic

hexser eliminates all of this. Through intelligent trait design, compile-time graph construction, and rich error handling, you get:

• Zero Boilerplate - Define your types, derive traits, done
• Type-Safe Architecture - Compiler enforces layer boundaries
• Self-Documenting - Graph visualization shows your architecture
• Intent Inference - System understands itself through structure
• Rich Errors - Helpful, actionable error messages
• Zero Runtime Overhead - Everything happens at compile time
• AI Completion - Expose your Rust architecture to AI agents

---

Quick Start

Add to your Cargo.toml:

[dependencies]
hexser = "0.3.0"

Your First Hexagonal Application

use hexser::prelude::*;

// 1. Define your domain entity
#[derive(HexEntity)]
struct User {
  id: String,
  email: String,
  name: String,
}

// 2. Define a port (interface)
#[derive(HexPort)]
trait UserRepository: Repository<User> {
  fn find_by_email(&self, email: &str) -> HexResult<Option<User>>;
}

// 3. Implement an adapter
#[derive(HexAdapter)]
struct InMemoryUserRepository {
    users: Vec<User>,
}

impl Repository<User> for InMemoryUserRepository {
  fn find_by_id(&self, id: &String) -> HexResult<Option<User>> {
    Ok(self.users.iter().find(|u| &u.id == id).cloned())
  }

  fn save(&mut self, user: User) -> HexResult<()> {
    self.users.push(user);
    Ok(())
  }

  fn delete(&mut self, id: &String) -> HexResult<()> {
    self.users.retain(|u| &u.id != id);
    Ok(())
  }

  fn find_all(&self) -> HexResult<Vec<User>> {
    Ok(self.users.clone())
  }
}

impl UserRepository for InMemoryUserRepository {
  fn find_by_email(&self, email: &str) -> HexResult<Option<User>> {
    Ok(self.users.iter().find(|u| u.email == email).cloned())
  }
}

// 4. Use it!
fn main() -> HexResult<()> {
    let mut repo = InMemoryUserRepository { users: Vec::new() };

    let user = User {
      id: "1".to_string(),
      email: "alice@example.com".to_string(),
      name: "Alice".to_string(),
    };

    repo.save(user)?;

    let found = repo.find_by_email("alice@example.com")?;
    println!("Found: {:?}", found.map(|u| u.name));

    Ok(())
}

That's it! You've just built a hexagonal architecture application with:

• Clear layer separation
• Type-safe interfaces
• Testable components
• Swappable implementations

Complete Tutorial

Part 1: Understanding Hexagonal Architecture

Hexagonal Architecture (also known as Ports and Adapters) structures applications into concentric layers:

┌─────────────────────────────────────────────┐
│         Infrastructure Layer                │
│  (Databases, APIs, External Services)       │
│                                             │
│  ┌───────────────────────────────────────┐  │
│  │      Adapters Layer                   │  │
│  │  (Concrete Implementations)           │  │
│  │                                       │  │
│  │  ┌─────────────────────────────────┐  │  │
│  │  │    Ports Layer                  │  │  │
│  │  │  (Interfaces/Contracts)         │  │  │
│  │  │                                 │  │  │
│  │  │  ┌───────────────────────────┐  │  │  │
│  │  │  │   Domain Layer            │  │  │  │
│  │  │  │ (Business Logic)          │  │  │  │
│  │  │  └───────────────────────────┘  │  │  │
│  │  └─────────────────────────────────┘  │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Key Principles:

• Dependency Rule: Dependencies point inward (Domain has no dependencies)
• Port Interfaces: Define what the domain needs (don't dictate how)
• Adapter Implementations: Provide concrete implementations using specific tech
• Testability: Mock adapters for testing without infrastructure

Part 2: The Five Layers

1. Domain Layer - Your Business Logic The domain layer contains your core business logic, completely independent of frameworks or infrastructure. Entities - Things with identity:

use hexser::prelude::*;

#[derive(HexEntity)]
struct Order {
  id: OrderId,
  customer_id: CustomerId,
  items: Vec<OrderItem>,
  status: OrderStatus,
}

impl Aggregate for Order {
  fn check_invariants(&self) -> HexResult<()> {
    if self.items.is_empty() {
      return Err(hexser::hex_domain_error!(
        hexser::error::codes::domain::INVARIANT_EMPTY,
        "Order must contain at least one item"
      ).with_next_step("Add at least one item"));
    }
    Ok(())
  }
}

Value Objects - Things defined by values:

#[derive(Clone, PartialEq, Eq, HexValueObject)]
struct Email(String);

impl Email {
  fn validate(&self) -> HexResult<()> {
    if !self.0.contains('@') {
      return Err(Hexserror::validation("Email must contain @"));
    }
    Ok(())
  }
}

Domain Events - Things that happened:

#[derive(HexDomainEvent)]
struct OrderPlaced {
  order_id: OrderId,
  customer_id: CustomerId,
  timestamp: u64,
}

Domain Services - Operations spanning multiple entities:

#[derive(HexDomainService)]
struct PricingService;

impl PricingService {
  fn calculate_order_total(&self, order: &Order) -> Money {
    order.items
      .iter()
      .map(|item| item.price * item.quantity)
      .sum()
  }
}

2. Ports Layer - Your Interfaces Ports define the contracts between your domain and the outside world. Repositories - Persistence abstraction:

#[derive(HexPort)]
trait OrderRepository: Repository<Order> {
  fn find_by_customer(&self, customer_id: &CustomerId)
      -> HexResult<Vec<Order>>;

  fn find_pending(&self) -> HexResult<Vec<Order>>;
}

Use Cases - Business operations:

#[derive(HexPort)]
trait PlaceOrder: UseCase<PlaceOrderInput, PlaceOrderOutput> {}

struct PlaceOrderInput {
  customer_id: CustomerId,
  items: Vec<OrderItem>,
}

struct PlaceOrderOutput {
  order_id: OrderId,
}

Queries - Read operations (CQRS):

#[derive(HexPort)]
trait OrderHistory: Query<OrderHistoryParams, Vec<OrderView>> {}

struct OrderHistoryParams {
  customer_id: CustomerId,
  from_date: u64,
  to_date: u64,
}

struct OrderView {
  order_id: String,
  total: f64,
  status: String,
}

3. Adapters Layer - Your Implementations Adapters implement ports using specific technologies.

Database Adapter:

#[derive(HexAdapter)]
struct PostgresOrderRepository {
  pool: PgPool,
}

impl Repository<Order> for PostgresOrderRepository {
  fn find_by_id(&self, id: &OrderId) -> HexResult<Option<Order>> {
  // SQL query implementation
  todo!()
}

  fn save(&mut self, order: Order) -> HexResult<()> {
      // SQL insert/update implementation
      todo!()
  }

  // ... other methods
}

impl OrderRepository for PostgresOrderRepository {
  fn find_by_customer(&self, customer_id: &CustomerId)
  -> HexResult<Vec<Order>> {
    // Custom query implementation
    todo!()
  }

  fn find_pending(&self) -> HexResult<Vec<Order>> {
      // Custom query implementation
      todo!()
  }
}

API Adapter:

#[derive(HexAdapter)]
struct RestPaymentGateway {
  client: reqwest::Client,
  api_key: String,
}

impl PaymentPort for RestPaymentGateway {
  fn charge(&self, amount: Money, card: &Card) -> HexResult<PaymentResult> {
    // HTTP API call implementation
    todo!()
  }
}

Mapper - Data transformation:

#[derive(HexAdapter)]
struct OrderMapper;

impl Mapper<Order, DbOrderRow> for OrderMapper {
  fn map(&self, order: Order) -> HexResult<DbOrderRow> {
    Ok(DbOrderRow {
      id: order.id.to_string(),
      customer_id: order.customer_id.to_string(),
      items_json: serde_json::to_string(&order.items)?,
      status: order.status.to_string(),
    })
  }
}

4. Application Layer - Your Orchestration The application layer coordinates domain logic and ports. Directive (Write Operation):

#[derive(HexDirective)]
struct PlaceOrderDirective {
    customer_id: CustomerId,
    items: Vec<OrderItem>,
}

impl PlaceOrderDirective {
  fn validate(&self) -> HexResult<()> {
    if self.items.is_empty() {
      return Err(Hexserror::validation("Items cannot be empty"));
    }
    Ok(())
  }
}

Directive Handler:

#[derive(HexDirectiveHandler)]
struct PlaceOrderHandler {
  order_repo: Box<dyn OrderRepository>,
  payment_port: Box<dyn PaymentPort>,
}

impl PlaceOrderHandler {
  fn handle(&self, directive: PlaceOrderDirective) -> HexResult<()> {
    // Validate
    directive.validate()?;

    // Create domain object
    let order = Order::new(directive.customer_id, directive.items)?;

    // Check invariants
    order.check_invariants()?;

    // Save
    self.order_repo.save(order)?;

    // Side effects
    self.payment_port.charge(order.total(), &order.payment_method)?;

    Ok(())
  }
}

Query Handler:

#[derive(HexQueryHandler)]
struct OrderHistoryHandler {
  query_repo: Box<dyn OrderQueryRepository>,
}

impl OrderHistoryHandler {
  fn handle(&self, params: OrderHistoryParams) -> HexResult<Vec<OrderView>> {
    self.query_repo.get_order_history(
        &params.customer_id,
        params.from_date,
        params.to_date
    )
  }
}

5. Infrastructure Layer - Your Technology Infrastructure provides the concrete technology implementations.

#[derive(HexConfig)]
struct DatabaseConfig {
  connection_string: String,
  pool_size: u32,
}

impl DatabaseConfig {
  fn create_pool(&self) -> PgPool {
    // Create database connection pool
    todo!()
  }
}

Part 3: CQRS Pattern with hex

hexser supports Command Query Responsibility Segregation (CQRS) out of the box.

Write Side (Directives):

// Directive represents intent to change state
#[derive(HexDirective)]
struct UpdateUserEmail {
  user_id: UserId,
  new_email: Email,
}

impl UpdateUserEmail {
  fn validate(&self) -> HexResult<()> {
    self.new_email.validate()
  }
}

// Handler executes the directive
#[derive(HexDirectiveHandler)]
struct UpdateUserEmailHandler {
  repo: Box<dyn UserRepository>,
}

impl UpdateUserEmailHandler {
  fn handle(&self, directive: UpdateUserEmail) -> HexResult<()> {
    let mut user = self.repo.find_by_id(&directive.user_id)?
      .ok_or_else(|| Hexserror::not_found("User", &directive.user_id))?;

    user.email = directive.new_email;
    self.repo.save(user)?;

    Ok(())
  }
}

Read Side (Queries):

// Query represents read operation
#[derive(HexQuery)]
struct FindUserByEmail {
  email: String,
}

// Handler executes the query
#[derive(HexQueryHandler)]
struct FindUserByEmailHandler {
  query_repo: Box<dyn UserQueryRepository>,
}

impl FindUserByEmailHandler {
  fn handle(&self, query: FindUserByEmail)
  -> HexResult<Option<UserView>> {
    self.query_repo.find_by_email(&query.email)
  }
}

Part 4: Testing Your Hexagonal Application

Hexagonal architecture makes testing trivial - just mock the ports!

Unit Testing Domain Logic:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_order_invariants() {
        let order = Order {
          id: OrderId::new(),
          customer_id: CustomerId::new(),
          items: vec![],  // Empty!
          status: OrderStatus::Pending,
        };

        assert!(order.check_invariants().is_err());
    }

    #[test]
    fn test_email_validation() {
        let invalid = Email("notanemail".to_string());
        assert!(invalid.validate().is_err());

        let valid = Email("test@example.com".to_string());
        assert!(valid.validate().is_ok());
    }
}

Testing with Mock Adapters:

#[derive(HexAdapter)]
struct MockUserRepository {
  users: std::collections::HashMap<UserId, User>,
}

impl Repository<User> for MockUserRepository {
  fn find_by_id(&self, id: &UserId) -> HexResult<Option<User>> {
    Ok(self.users.get(id).cloned())
  }

  fn save(&mut self, user: User) -> HexResult<()> {
    self.users.insert(user.id.clone(), user);
    Ok(())
  }

  // ... other methods
}

#[test]
fn test_create_user_handler() {
  let mut repo = MockUserRepository {
    users: std::collections::HashMap::new(),
  };

  let handler = CreateUserHandler {
      repo: Box::new(repo),
  };

  let directive = CreateUserDirective {
      email: "test@example.com".to_string(),
      name: "Test User".to_string(),
  };

  assert!(handler.handle(directive).is_ok());
}

Part 5: Error Handling

hexser provides rich, actionable, code-first errors with automatic source location and layering support. Prefer the new macro-based constructors and error codes over manual struct construction.

Preferred: macro + code + guidance

fn validate_order(order: &Order) -> HexResult<()> {
  if order.items.is_empty() {
    return Err(
        hexser::hex_domain_error!(
            hexser::error::codes::domain::INVARIANT_EMPTY,
            "Order must contain at least one item"
        )
        .with_next_steps(&["Add at least one item to the order"]) // actionable guidance
        .with_suggestions(&["order.add_item(item)", "order.items.push(item)"]) // quick fixes
        .with_more_info("https://docs.rs/hexser/latest/hexser/error/codes/domain")
    );
  }
  Ok(())
}

Display output (example):

E_HEX_001: Order must contain at least one item
at src/domain/order.rs:42:13
Next steps:
- Add at least one item to the order
Suggestions:
- order.add_item(item)
- order.items.push(item)

Cookbook

// Validation errors (field-aware)
return Err(hexser::error::hex_error::Hexserror::validation_field(
    "Title cannot be empty",
    "title",
));

// Not Found errors (resource + id)
return Err(hexser::error::hex_error::Hexserror::not_found("User", "123")
    .with_next_step("Verify the ID and try again"));

// Port errors (communication issues)
let port_err = hexser::hex_port_error!(
    hexser::error::codes::port::PORT_TIMEOUT,
    "User service timed out"
).with_suggestion("Increase timeout or retry later");

// Adapter errors (infra failures) with source error
fn fetch_from_api(url: &str) -> HexResult<String> {
    let resp = std::fs::read_to_string(url)
        .map_err(|ioe| hexser::hex_adapter_error!(
            hexser::error::codes::adapter::IO_FAILURE, // or API_FAILURE in real HTTP
            "Failed to fetch resource"
        ).with_source(ioe))?;
    Ok(resp)
}

🔥 Amazing Example: Layered mapping (Adapter → Port → Domain)

// Adapter layer
fn db_get_user(id: &str) -> HexResult<User> {
    let conn = std::fs::read_to_string("/tmp/mock-db").map_err(|e|
        hexser::hex_adapter_error!(
            hexser::error::codes::adapter::DB_CONNECTION_FAILURE,
            "Database unavailable"
        )
        .with_source(e)
        .with_next_steps(&["Ensure DB is running", "Check connection string"]) 
    )?;
    // ... parse and return User or NotFound
    Err(hexser::error::hex_error::Hexserror::not_found("User", id))
}

// Port layer wraps adapter failure with port context
fn port_get_user(id: &str) -> HexResult<User> {
    db_get_user(id).map_err(|e|
        hexser::hex_port_error!(
            hexser::error::codes::port::COMMUNICATION_FAILURE,
            "UserRepository failed"
        ).with_source(e)
    )
}

// Domain layer consumes rich errors
fn ensure_user_exists(id: &str) -> HexResult<()> {
    let _user = port_get_user(id)?; // `?` preserves full rich error stack
    Ok(())
}

Notes

• All hexser errors implement std::error::Error and the RichError trait (code, message, next_steps, suggestions, location, more_info, source).
• Prefer hex_domain_error!, hex_port_error!, hex_adapter_error! and constants from hexser::error::codes::*.
• Use with_source(err) to preserve underlying causes; Display shows a helpful, compact summary.

Part 6: Real-World Example - TODO Application Let's build a complete TODO application using hexagonal architecture. Domain Layer:

use hexser::prelude::*;

#[derive(Clone, HexEntity)]
struct Todo {
  id: TodoId,
  title: String,
  description: String,
  completed: bool,
}

#[derive(Clone, PartialEq, Eq, Hash)]
struct TodoId(String);

impl TodoId {
  fn new() -> Self {
    Self(uuid::Uuid::new_v4().to_string())
  }
}

Ports Layer:

#[derive(HexPort)]
trait TodoRepository: Repository<Todo> {
    fn find_active(&self) -> HexResult<Vec<Todo>>;
    fn find_completed(&self) -> HexResult<Vec<Todo>>;
}

Adapters Layer:

#[derive(HexAdapter)]
struct InMemoryTodoRepository {
  todos: std::sync::Mutex<Vec<Todo>>,
}

impl Repository<Todo> for InMemoryTodoRepository {
  fn find_by_id(&self, id: &TodoId) -> HexResult<Option<Todo>> {
    let todos = self.todos.lock().unwrap();
    Ok(todos.iter().find(|t| &t.id == id).cloned())
  }

  fn save(&mut self, todo: Todo) -> HexResult<()> {
      let mut todos = self.todos.lock().unwrap();
      if let Some(existing) = todos.iter_mut().find(|t| t.id == todo.id) {
          *existing = todo;
      } else {
          todos.push(todo);
      }
      Ok(())
  }

  fn delete(&mut self, id: &TodoId) -> HexResult<()> {
      let mut todos = self.todos.lock().unwrap();
      todos.retain(|t| &t.id != id);
      Ok(())
  }

  fn find_all(&self) -> HexResult<Vec<Todo>> {
      let todos = self.todos.lock().unwrap();
      Ok(todos.clone())
  }
}

impl TodoRepository for InMemoryTodoRepository {
  fn find_active(&self) -> HexResult<Vec<Todo>> {
    let todos = self.todos.lock().unwrap();
    Ok(todos.iter().filter(|t| !t.completed).cloned().collect())
  }

  fn find_completed(&self) -> HexResult<Vec<Todo>> {
    let todos = self.todos.lock().unwrap();
    Ok(todos.iter().filter(|t| t.completed).cloned().collect())
  }
}

Application Layer:

#[derive(HexDirective)]
struct CreateTodoDirective {
    title: String,
    description: String,
}

impl CreateTodoDirective {
    fn validate(&self) -> HexResult<()> {
        if self.title.is_empty() {
            return Err(Hexserror::validation_field("Title cannot be empty", "title"));
        }
        Ok(())
    }
}

#[derive(HexDirectiveHandler)]
struct CreateTodoHandler {
    repo: Box<dyn TodoRepository>,
}

impl CreateTodoHandler {
    fn handle(&self, directive: CreateTodoDirective) -> HexResult<()> {
        directive.validate()?;

        let todo = Todo {
            id: TodoId::new(),
            title: directive.title,
            description: directive.description,
            completed: false,
        };

        self.repo.save(todo)?;
        Ok(())
    }
}

---

🎓 Advanced Patterns

Event Sourcing

#[derive(HexAggregate)]
struct OrderAggregate {
  id: OrderId,
  uncommitted_events: Vec<Box<dyn DomainEvent>>,
}

impl OrderAggregate {
  fn place_order(&mut self, items: Vec<OrderItem>) -> HexResult<()> {
    // Validate
    if items.is_empty() {
      return Err(hexser::hex_domain_error!(
        hexser::error::codes::domain::INVARIANT_EMPTY,
        "Order must have items"
      ));
    }

    // Create event
    let event = OrderPlaced {
        order_id: self.id.clone(),
        items,
        timestamp: current_timestamp(),
    };

    // Apply event
    self.apply_event(&event);

    // Record event
    self.uncommitted_events.push(Box::new(event));

    Ok(())
  }

  fn apply_event(&mut self, event: &dyn DomainEvent) {
      // Update state based on event
  }
}

Dependency Injection

struct ApplicationContext {
    user_repo: Box<dyn UserRepository>,
    order_repo: Box<dyn OrderRepository>,
    payment_port: Box<dyn PaymentPort>,
}

impl ApplicationContext {
    fn new_production() -> Self {
        Self {
            user_repo: Box::new(PostgresUserRepository::new()),
            order_repo: Box::new(PostgresOrderRepository::new()),
            payment_port: Box::new(StripePaymentGateway::new()),
        }
    }

    fn new_test() -> Self {
        Self {
            user_repo: Box::new(MockUserRepository::new()),
            order_repo: Box::new(MockOrderRepository::new()),
            payment_port: Box::new(MockPaymentGateway::new()),
        }
    }
}

📊 Knowledge Graph

hexser/
├── domain/              [Core Business Logic - No Dependencies]
│   ├── Entity           - Identity-based objects
│   ├── ValueObject      - Value-based objects
│   ├── Aggregate        - Consistency boundaries
│   ├── DomainEvent      - Significant occurrences
│   └── DomainService    - Cross-entity operations
│
├── ports/               [Interface Definitions]
│   ├── Repository       - Persistence abstraction
│   ├── UseCase          - Business operations
│   ├── Query            - Read-only operations (CQRS)
│   ├── InputPort        - Entry points
│   └── OutputPort       - External system interfaces
│
├── adapters/            [Concrete Implementations]
│   ├── Adapter          - Port implementations
│   └── Mapper           - Data transformation
│
├── application/         [Orchestration Layer]
│   ├── Directive        - Write operations (CQRS)
│   ├── DirectiveHandler - Directive execution
│   └── QueryHandler     - Query execution
│
├── infrastructure/      [Technology Layer]
│   └── Config           - Infrastructure setup
│
├── error/               [Rich Error Types]
│   └── Hexserror         - Actionable errors
│
└── graph/               [Introspection - Phase 2+]
    ├── Layer            - Architectural layers
    ├── Role             - Component roles
    ├── Relationship     - Component connections
    └── NodeId           - Unique identification

💡 Design Philosophy

• "Language of the Language": Use Rust's type system to express architecture
• Zero Boilerplate: Derive everything, configure nothing
• Compile-Time Guarantees: Catch errors before runtime
• Rich Errors: Every error is helpful and actionable
• Self-Documenting: Graph reveals architecture automatically
• Testability First: Mock anything, test everything

🤝 Contributing

We welcome contributions! This crate follows strict coding standards:

• One item per file: Each file contains one logical item
• No imports: Fully qualified paths (except std prelude)
• Documentation: Every item has //! and /// docs
• In-file tests: Tests live with the code they test
• No unsafe: Safe Rust only
• Rust 2024: Latest edition

See CONTRIBUTING.md for details.

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🙏 Acknowledgments

Inspired by:

• CEQRS by Scott Wyatt
• N Lang by Scott Wyatt
• Domain-Driven Design by Eric Evans
• Hexagonal Architecture by Alistair Cockburn
• Clean Architecture by Robert C. Martin
• Rust's type system and error handling
• The Rust community's commitment to excellence

📚 Additional Resources

• Hexagonal Architecture Explained
• Domain-Driven Design
• CQRS Pattern
• Ports and Adapters

🎯 Examples & Tutorials

The hex crate includes comprehensive examples and tutorials to help you learn hexagonal architecture.

Running Examples

cargo run --example simple_todo

---

🧪 Potions (copy-friendly examples)

Looking for concrete, minimal examples you can paste into your app? Check out the Potions crate in this workspace:

• Path: ./hexser_potions
• Crate: hexser_potions
• Focus: small, mixable examples (auth signup, CRUD, etc.)

Add to your project via workspace path:

[dependencies]
hexser_potions = { path = "../hexser_potions", version = "0.3.0" }

Then in code:

use hexser_potions::auth::{SignUpUser, InMemoryUserRepository, execute_signup};

---

⚙️ Static (non-dyn) DI — WASM-friendly

When you want zero dynamic dispatch and the smallest possible runtime footprint (including on wasm32-unknown-unknown), use the new static DI utilities.

Feature flags:

• Enabled by default: static-di
• Opt-in for dyn container (tokio-based): container

Static DI provides two simple building blocks:

• StaticContainer<T>: owns your fully built object graph
• hex_static! { ... } macro: builds the graph from a block without any dyn

Example:

use hexser::prelude::*;

#[derive(Clone, Debug)]
struct Repo;
#[derive(Clone, Debug)]
struct Service { repo: Repo }

let app = hexser::hex_static!({
    let repo = Repo;
    let service = Service { repo: repo.clone() };
    (repo, service)
});

let (repo, service) = app.into_inner();

WASM guidance:

• Default features are WASM-friendly (no tokio). Keep container disabled for wasm.
• Use static-di (default) and avoid the dyn container for maximum compatibility.

---

Repository: Filter-based queries (vNext)

We are migrating the repository port away from id-centric methods (find_by_id/find_all) toward a generic, filter-oriented API that better models your domain while staying storage-agnostic. The new QueryRepository trait introduces domain-owned Filter and SortKey types plus FindOptions for sorting and pagination.

Highlights:

• Define small Filter and SortKey enums/structs in your domain
• Use find_one for unique lookups and find for lists with sorting/pagination
• Legacy methods are still available but deprecated; prefer the new API

Example:

use hexser::prelude::*;
use hexser::ports::repository::{QueryRepository, FindOptions, Sort, Direction};

#[derive(HexEntity, Clone, Debug)]
struct User { id: String, email: String, created_at: u64 }

// Domain-owned query types
#[derive(Clone, Debug)]
enum UserFilter {
    ById(String),
    ByEmail(String),
    All,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum UserSortKey { CreatedAt, Email }

#[derive(Default)]
struct InMemoryUserRepository { users: Vec<User> }

impl Repository<User> for InMemoryUserRepository {
    fn find_by_id(&self, id: &String) -> HexResult<Option<User>> { Ok(self.users.iter().find(|u| &u.id == id).cloned()) }
    fn save(&mut self, user: User) -> HexResult<()> { if let Some(i)=self.users.iter().position(|u| u.id==user.id){self.users[i]=user;} else { self.users.push(user);} Ok(()) }
    fn delete(&mut self, id: &String) -> HexResult<()> { self.users.retain(|u| &u.id != id); Ok(()) }
    fn find_all(&self) -> HexResult<Vec<User>> { Ok(self.users.clone()) }
}

impl QueryRepository<User> for InMemoryUserRepository {
    type Filter = UserFilter;
    type SortKey = UserSortKey;

    fn find_one(&self, f: &Self::Filter) -> HexResult<Option<User>> {
        Ok(self.users.iter().find(|u| match f { UserFilter::ById(id)=>&u.id==id, UserFilter::ByEmail(e)=>&u.email==e, UserFilter::All=>true }).cloned())
    }

    fn find(&self, f: &Self::Filter, opts: FindOptions<Self::SortKey>) -> HexResult<Vec<User>> {
        let mut items: Vec<_> = self.users.iter().filter(|u| match f { UserFilter::ById(id)=>&u.id==id, UserFilter::ByEmail(e)=>&u.email==e, UserFilter::All=>true }).cloned().collect();
        if let Some(sorts) = opts.sort {
            for s in sorts.into_iter().rev() {
                match (s.key, s.direction) {
                    (UserSortKey::CreatedAt, Direction::Asc) => items.sort_by_key(|u| u.created_at),
                    (UserSortKey::CreatedAt, Direction::Desc) => items.sort_by_key(|u| std::cmp::Reverse(u.created_at)),
                    (UserSortKey::Email, Direction::Asc) => items.sort_by(|a,b| a.email.cmp(&b.email)),
                    (UserSortKey::Email, Direction::Desc) => items.sort_by(|a,b| b.email.cmp(&a.email)),
                }
            }
        }
        let offset = opts.offset.unwrap_or(0) as usize;
        let limit = opts.limit.map(|l| l as usize).unwrap_or_else(|| items.len().saturating_sub(offset));
        let end = offset.saturating_add(limit).min(items.len());
        Ok(items.into_iter().skip(offset).take(end.saturating_sub(offset)).collect())
    }
}

fn main() -> HexResult<()> {
    let repo = InMemoryUserRepository::default();
    // Unique lookup
    let _ = <InMemoryUserRepository as QueryRepository<User>>::find_one(&repo, &UserFilter::ByEmail("alice@ex.com".into()))?;

    // List with pagination
    let opts = FindOptions { sort: Some(vec![Sort { key: UserSortKey::CreatedAt, direction: Direction::Desc }]), limit: Some(25), offset: Some(0) };
    let _page = <InMemoryUserRepository as QueryRepository<User>>::find(&repo, &UserFilter::All, opts)?;
    Ok(())
}

Migration tips:

• find_by_id(id) -> find_one(&Filter::ById(id))
• find_all() -> find(&Filter::All, FindOptions::default())
• Add sorting/pagination via FindOptions { sort, limit, offset }

For more details, see MIGRATION_GUIDE.md and docs/core-concepts.md.

v0.4 QueryRepository Examples (5+)

The following focused examples demonstrate the new query-first API using domain-owned Filter and SortKey types. These snippets avoid deprecated methods and illustrate common tasks.

1. Unique lookup with find_one

// Given: domain types User, UserFilter::ByEmail(String)
let repo = InMemoryUserRepository::default();
let maybe_user = <InMemoryUserRepository as hexser::ports::repository::QueryRepository<User>>
    ::find_one(&repo, &UserFilter::ByEmail(String::from("alice@example.com")))?;

2. Listing with multi-key sorting (Email asc, CreatedAt desc)

let opts = hexser::ports::repository::FindOptions {
    sort: Some(vec![
        hexser::ports::repository::Sort { key: UserSortKey::Email, direction: hexser::ports::repository::Direction::Asc },
        hexser::ports::repository::Sort { key: UserSortKey::CreatedAt, direction: hexser::ports::repository::Direction::Desc },
    ]),
    limit: None,
    offset: None,
};
let users = <InMemoryUserRepository as hexser::ports::repository::QueryRepository<User>>::find(
    &repo,
    &UserFilter::All,
    opts,
)?;

3. Pagination (page size 10, second page)

let opts = hexser::ports::repository::FindOptions { sort: None, limit: Some(10), offset: Some(10) };
let page = <InMemoryUserRepository as hexser::ports::repository::QueryRepository<User>>::find(&repo, &UserFilter::All, opts)?;

4. Existence check

let exists = <InMemoryUserRepository as hexser::ports::repository::QueryRepository<User>>::exists(
    &repo,
    &UserFilter::ByEmail(String::from("bob@example.com")),
)?;

5. Count matching entities

let total = <InMemoryUserRepository as hexser::ports::repository::QueryRepository<User>>::count(
    &repo,
    &UserFilter::All,
)?;

6. Delete by filter (returns removed count)

let removed = <InMemoryUserRepository as hexser::ports::repository::QueryRepository<User>>::delete_where(
    &mut repo.clone(),
    &UserFilter::ByEmail(String::from("bob@example.com")),
)?;

---

🤖 AI Context Export (CLI)

Export a machine-readable JSON describing your project's architecture for AI assistants and tooling.

Requirements:

• Enable the ai feature (serde/serde_json are included automatically).

Commands:

# Build and run the exporter (prints JSON to stdout)
cargo run -p hexser --features ai --bin hex-ai-export

# Save to a file
cargo run -p hexser --features ai --bin hex-ai-export --quiet > target/ai-context.json

What it does:

• Builds the current HexGraph from the component registry
• Generates an AIContext via hexser::ai::ContextBuilder
• Serializes to JSON with a stable field order

Notes:

• The binary hex-ai-export is only built when the ai feature is enabled.
• For reproducible diffs, commit target/ai-context.json or generate it in CI as an artifact.

🧠 AI Agent Pack (All-in-One)

Export a comprehensive, single-file JSON that bundles:

• AIContext (machine-readable architecture)
• Guidelines snapshot (rules enforced for agents)
• Embedded key docs (README, ERROR_GUIDE, and local AI/guideline prompts when present)

Commands:

# Print Agent Pack JSON to stdout
cargo run -p hexser --features ai --bin hex-ai-pack

# Save to a file
cargo run -p hexser --features ai --bin hex-ai-pack --quiet > target/ai-pack.json

Notes:

• Missing optional docs are skipped gracefully. The pack remains valid JSON.
• Use this artifact as the single source of truth for external AIs and tools when proposing changes.