🦆 waddling-sequences

Standard error sequence definitions for the Waddling ecosystem

What is this?

waddling-sequences provides standardized error sequence numbers with semantic meanings that are consistent across the entire Waddling ecosystem, following the WDP Part 6: Sequence Conventions specification.

Think of it like HTTP status codes for errors:

• Everyone knows 404 = Not Found
• With Waddling: Everyone knows 001 = MISSING, 003 = INVALID, 021 = NOT_FOUND, etc.

Reference: WDP Part 6: Sequence Conventions (WDP-6)

Features

• ✅ Zero dependencies - Just pure constants (by default)
• ✅ No-std compatible - Works everywhere
• ✅ Tree-shakeable - Only imports what you use
• ✅ Universal - Works with any error library
• ✅ Well-documented - Every sequence has clear meaning
• ✅ WDP-6 Compliant - Follows official sequence conventions
• 📚 Optional metadata - Get rich documentation at runtime (metadata feature)
• 🌐 Optional doc generation - Generate HTML/JSON docs (doc-gen feature)
• 🔧 Optional macros - Full waddling-errors ecosystem integration (macros feature)

Three Ways to Use

1. Pure Constants (Default - Zero Dependencies)

use waddling_sequences::prelude::*;

// Just numbers - minimal, no_std compatible
const MY_ERROR: u16 = MISSING;  // 001
const OTHER_ERROR: u16 = NOT_FOUND;  // 021

2. With Metadata (Runtime Documentation)

[dependencies]
waddling-sequences = { version = "0.2", features = ["metadata"] }

use waddling_sequences::{prelude::*, metadata};

// Query metadata at runtime
if let Some(info) = metadata::get(MISSING) {
    println!("{}: {}", info.name, info.docs);
    println!("Typical severity: {}", info.typical_severity);
}

3. With Macros (Full Ecosystem Integration)

[dependencies]
waddling-sequences = { version = "0.2", features = ["macros"] }
waddling-errors-macros = "0.6"

use waddling_errors_macros::{setup, diag};

setup! {
    sequences = waddling_sequences::macros::sequences,
    // ... your components and primaries
}

diag! {
    strict(sequence),  // Compile-time validation!
    
    E.Auth.Token.MISSING: {
        message: "JWT token missing",
        // MISSING validated at compile time!
    },
}

Quick Start

use waddling_sequences::prelude::*;

// Use standard sequences with semantic meaning
const MY_ERROR_CODE: u16 = MISSING;  // 001 - always means "missing"
const OTHER_ERROR: u16 = MISMATCH;   // 002 - always means "mismatch"

// Everyone in the ecosystem knows what these mean!

Sequence Categories

Input/Data Validation (001-010)

use waddling_sequences::input_validation::*;

MISSING         // 001 - Required data not provided
MISMATCH        // 002 - Type or length mismatch
INVALID         // 003 - Validation check failed
OVERFLOW        // 004 - Value too large
UNDERFLOW       // 005 - Value too small
OUT_OF_BOUNDS   // 006 - Outside valid range
DUPLICATE       // 007 - Duplicate entry
DENIED          // 008 - Permission denied
UNSUPPORTED     // 009 - Feature not supported
DEPRECATED      // 010 - Feature deprecated

State/Lifecycle (011-020)

use waddling_sequences::state_lifecycle::*;

UNINITIALIZED   // 011 - Not initialized
ALREADY_INIT    // 012 - Already initialized
CLOSED          // 013 - Resource closed
CANCELLED       // 014 - Operation cancelled
IN_PROGRESS     // 015 - Already in progress
NOT_READY       // 016 - Not ready
TIMEOUT         // 017 - Operation timed out
STALE           // 018 - Resource stale/expired
// 019-020 reserved for future use

Resource/Storage (021-030)

Includes network operations per WDP-6 §4.3.

use waddling_sequences::resource_storage::*;

NOT_FOUND       // 021 - Resource not found
ALREADY_EXISTS  // 022 - Resource already exists
CONFLICT        // 023 - Version/data conflict
LOCKED          // 024 - Resource locked
CORRUPTED       // 025 - Data corrupted
EXHAUSTED       // 026 - Resource exhausted
UNAVAILABLE     // 027 - Service temporarily unavailable (network)
UNREACHABLE     // 028 - Network connectivity failure
DISCONNECTED    // 029 - Connection lost
// 030 reserved for future use

Success/Completion (998-999)

use waddling_sequences::success::*;

PARTIAL         // 998 - Partial success
COMPLETE        // 999 - Full success

Three Ways to Use This Library

🟢 Approach 1: Pure Constants (Default)

Perfect for: Lightweight projects, no_std, minimal dependencies

use waddling_sequences::prelude::*;

const ERROR_CODE: u16 = MISSING;  // Just a number
const ANOTHER: u16 = NOT_FOUND;

Dependencies: Zero
Binary size: Minimal
Features: Basic constants only

🔵 Approach 2: With Metadata (Runtime Documentation)

Perfect for: Tools, CLIs, error reporting systems

[dependencies]
waddling-sequences = { version = "0.2", features = ["metadata"] }

use waddling_sequences::{prelude::*, metadata};

// Query metadata at runtime
if let Some(info) = metadata::get(MISSING) {
    println!("{}: {}", info.name, info.docs);
    println!("Severity: {}", info.typical_severity);
    println!("When to use: {}", info.when_to_use);
}

// Get by name
let meta = metadata::get_by_name("NOT_FOUND").unwrap();

// Browse all sequences
for seq in metadata::ALL_SEQUENCES.iter() {
    println!("{:03} - {}", seq.number, seq.name);
}

Dependencies: Zero (still!)
Binary size: Includes metadata strings
Features: Runtime documentation, lookup functions

🟣 Approach 3: With Macros (Full Ecosystem Integration)

Perfect for: waddling-errors projects, compile-time validation

[dependencies]
waddling-sequences = { version = "0.2", features = ["macros"] }
waddling-errors-macros = "0.6"

use waddling_errors_macros::{setup, diag};

// Set up paths for macro validation
setup! {
    sequences = waddling_sequences::macros::sequences,
    components = crate::components,
    primaries = crate::primaries,
}

// Use with compile-time validation!
diag! {
    strict(sequence),  // Validates MISSING exists at compile time
    
    E.Auth.Token.MISSING: {
        message: "JWT token missing",
        description: "Authorization header is missing required JWT token",
        hints: ["Add Authorization: Bearer <token> header"],
        tags: ["authentication", "jwt"],
    },
}

Dependencies: waddling-errors, waddling-errors-macros
Binary size: Comparable to metadata (macros expand at compile time)
Features: Compile-time validation, auto-registration, type safety

Comparison Table

With Metadata Feature

Enable the metadata feature to get rich documentation at runtime:

[dependencies]
waddling-sequences = { version = "0.2", features = ["metadata"] }

use waddling_sequences::metadata;

// Get documentation for a sequence by number
let meta = metadata::get(1).unwrap();
println!("{}: {}", meta.name, meta.docs);
// Output: MISSING: Required data not provided

// Get by name (case-insensitive)
let meta2 = metadata::get_by_name("TIMEOUT").unwrap();
println!("Sequence {}: {}", meta2.number, meta2.when_to_use);

// Browse by category
let validation_sequences = metadata::by_category("Input/Data Validation");
for seq in validation_sequences {
    println!("{:03} {}: {}", seq.number, seq.name, seq.docs);
}

The metadata includes:

• Sequence number and name
• Description from WDP-6
• When to use this sequence
• Category and range
• Typical severity level

Documentation Generation

Generate comprehensive HTML and JSON documentation with the doc-gen feature:

[dependencies]
waddling-sequences = { version = "0.2", features = ["doc-gen"] }

use waddling_sequences::docgen::generate_docs;

fn main() {
    // Generates role-based documentation (pub, dev, int)
    generate_docs("target/doc").unwrap();
    println!("📚 Documentation generated!");
}

This creates:

• 📄 Waddling_Standard_Sequences-pub.html - Public documentation
• 📄 Waddling_Standard_Sequences-dev.html - Developer documentation
• 📄 Waddling_Standard_Sequences-int.html - Internal documentation
• 📄 JSON exports - For custom tooling and integrations

Run the example:

cargo run --example generate_docs --features doc-gen

Examples

Check out the examples/ directory:

• basic.rs - Simple usage with constants
• metadata.rs - Querying metadata at runtime
• with_macros.rs - Full ecosystem integration with macros
• generate_docs.rs - Generate HTML/JSON documentation

Project-Specific Sequences

Sequences 031-897 are available for project-specific use per WDP-6!

// Your custom sequences (unreserved range)
const MY_CUSTOM_ERROR: u16 = 031;
const ANOTHER_ERROR: u16 = 050;
const DOMAIN_SPECIFIC: u16 = 101;
const BUSINESS_LOGIC: u16 = 250;

// Reserved sequences 001-030, 998-999 follow WDP-6 conventions

Usage with waddling-errors

waddling-sequences integrates seamlessly with the waddling-errors ecosystem:

use waddling_errors::Code;
use waddling_sequences::prelude::*;

// Use standard sequences in your error codes
const TYPE_ERROR: Code = Code::new("E", "TYPES", "CHECK", INVALID);  // 003
const USER_NOT_FOUND: Code = Code::new("E", "USER", "LOOKUP", NOT_FOUND);  // 021

Or with macros for compile-time validation:

use waddling_errors_macros::diag;
use waddling_sequences::macros::sequences::*;

diag! {
    strict(sequence),  // Validates sequences at compile time!
    
    E.User.Lookup.NOT_FOUND: {
        message: "User not found",
        // NOT_FOUND is validated to exist
    },
}

Why Standard Sequences?

Before (Inconsistent)

// Project A
const ERR_MISSING: u16 = 001;  // "missing"
const ERR_NOTFOUND: u16 = 002; // "not found"

// Project B  
const ERR_NOTFOUND: u16 = 001; // "not found"
const ERR_MISSING: u16 = 005;  // "missing"

❌ Same concept, different numbers across projects!

After (Consistent with WDP-6)

// Project A
use waddling_sequences::core::MISSING;      // 001
use waddling_sequences::resource::NOT_FOUND; // 021

// Project B
use waddling_sequences::core::MISSING;      // 001
use waddling_sequences::resource::NOT_FOUND; // 021

✅ Same number, same meaning, everywhere!

WDP-6 Compliance

This crate implements WDP Part 6: Sequence Conventions:

• ✅ Reserved sequences (001-030) follow standard semantics
• ✅ Project-specific range (031-897) available for custom use
• ✅ Success sequences (998-999) for completion states
• ✅ Consistent naming with underscores (e.g., NOT_FOUND, IN_PROGRESS)
• ✅ Comprehensive metadata aligned with specification

No-std Support

Works in no-std environments:

#![no_std]
use waddling_sequences::core::*;

const ERR: u16 = MISSING;  // Works everywhere!

License

Licensed under either of:

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

at your option.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

Made with waddles by 🦆