waddling

📋 Overview

waddling-errors provides structured diagnostic codes with a consistent 4-part format:

Examples:

This system enables type-safe error handling with compile-time checking, semantic methods for intelligent error handling, and automatic documentation generation with role-based filtering.

✨ Key Features

🎯 Severity Levels

Nine severity levels with semantic methods:

🔢 Sequence Conventions

Semantic sequence numbers provide consistency across all Waddling projects:

🚀 Quick Start

Get started with waddling-errors using macros for compile-time safety:

Step 1: Add Dependencies

[dependencies]
waddling-errors = "0.5"
waddling-errors-macros = "0.5"

Step 2: Define Your Error Components

You can use either simple syntax (compact, relaxed validation) or enum wrapper syntax (full validation support):

Option A: Simple Syntax (Relaxed Validation)

use waddling_errors_macros::{component, primary, sequence, diag};

// Simple syntax - compact but limited validation
component! {
    Auth { value: "AUTH", docs: "Authentication system" }
}

primary! {
    Token { value: "TOKEN", docs: "Token-related errors" }
}

sequence! {
    MISSING(1) { description: "Required field missing" }
}

Option B: Enum Wrapper Syntax (Full Validation) ✅ Recommended

use waddling_errors_macros::{component, primary, sequence, diag};

// Module + Enum wrapper - enables full compile-time validation
mod components {
    use super::*;
    component! {
        pub enum Component {
            Auth { value: "AUTH", docs: "Authentication system" }
        }
    }
}

mod primaries {
    use super::*;
    primary! {
        pub enum Primary {
            Token { value: "TOKEN", docs: "Token-related errors" }
        }
    }
}

mod sequences {
    use super::*;
    sequence! {
        pub MISSING(1) { description: "Required field missing" }
    }
}

use components::Component;
use primaries::Primary;
use sequences::MISSING;

Step 3: Create Error Diagnostics with Validation

Validation mode depends on which syntax you chose in Step 2:

With Simple Syntax (Relaxed Validation)

diag! {
    // No strict validation with simple syntax
    // But still generates constants and docs!
    <json, html, my_custom_format>,

    E.Auth.Token.MISSING: {
        message: "JWT token not found in Authorization header",
        hints: ["Include 'Authorization: Bearer ' header"],
        role: "public",
    }
}

// Use the generated constant
fn authenticate(token: Option<&str>) -> Result<(), Code> {
    token.ok_or(E_AUTH_TOKEN_MISSING)?;
    Ok(())
}

With Enum Wrapper Syntax (Full Validation) ✅

diag! {
    // Full compile-time validation enabled!
    strict(sequence, primary, component, naming, duplicates),

    // Generate documentation in multiple formats
    <json, html, my_custom_format>,

    E.Auth.Token.MISSING: {
        message: "JWT token not found in Authorization header",
        hints: ["Include 'Authorization: Bearer ' header"],
        role: "public",
    }
}

// Compiler will catch:
// - Typos in Auth, Token, or MISSING
// - Wrong naming conventions
// - Duplicate error codes
// - Type mismatches

Generated Output & Documentation

The error code automatically formats as [E.AUTH.TOKEN.001] → aB3xY and generates documentation in JSON, HTML, and custom formats:

{
  "code": "E.AUTH.TOKEN.001",
  "hash": "aB3xY",
  "message": "JWT token not found in Authorization header",
  "hints": ["Include 'Authorization: Bearer ' header"],
  "role": "public"
}

💡 Why Use Macros?

While you can use waddling-errors without macros (as shown in Quick Start), macros provide additional compile-time safety that catches errors before your code even runs.

// Manual approach - more flexible
const ERR: Code = error(
    Component::Autth,  // Typo compiles
    Primary::Token,
    1
);

// No compile-time checks
const ERR2: Code = error(
    Component::Auth,
    Primary::Token,
    9999  // Out of range
);

diag! {
    strict(component, primary, sequence),

    E.Autth.Token.MISSING: {
        message: "Token missing",
    }
}

// Compiler error immediately:
// error: no constant `Autth` in scope
// help: did you mean `Auth`?

🔍 Compile-Time Validation Deep Dive

Syntax Comparison

The diag! macro supports 7 granular validation modes to catch errors at compile time:

diag! {
    // Enable all validations
    strict(sequence, primary, component, naming, duplicates),

    E.Auth.Token.MISSING: {
        message: "Authentication token not found",
        hints: ["Include Authorization header"],
    },
    W.Parser.Syntax.INVALID: {
        message: "Invalid syntax detected",
    }
}

🌐 Browser-Server Catalog Pattern

Compact error transmission with client-side i18n expansion - transmit 85% less data while supporting multiple languages.

💡 Tip: Click "Play Animation" above to see the full demo of how compact errors flow from server to browser and expand in multiple languages.

For complex projects and team environments, waddling-errors offers additional capabilities: