# 🦆 waddling-sequences
**Standard error sequence definitions for the Waddling ecosystem**
[](https://crates.io/crates/waddling-sequences)
[](https://docs.rs/waddling-sequences)
[](LICENSE-MIT)
---
## 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)](https://github.com/waddling/wdp-specs/blob/main/6-SEQUENCE-CONVENTIONS.md)
## 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)
```rust
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)
```toml
[dependencies]
waddling-sequences = { version = "0.2", features = ["metadata"] }
```
```rust
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)
```toml
[dependencies]
waddling-sequences = { version = "0.2", features = ["macros"] }
waddling-errors-macros = "0.6"
```
```rust
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
```rust
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)
```rust
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)
```rust
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.
```rust
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)
```rust
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
```rust
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
```toml
[dependencies]
waddling-sequences = { version = "0.2", features = ["metadata"] }
```
```rust
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
```toml
[dependencies]
waddling-sequences = { version = "0.2", features = ["macros"] }
waddling-errors-macros = "0.6"
```
```rust
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
| **Dependencies** | Zero | Zero | waddling-errors |
| **no_std** | ✅ Yes | ✅ Yes | ✅ Yes |
| **Runtime Metadata** | ❌ No | ✅ Yes | ✅ Yes |
| **Compile-time Validation** | ❌ No | ❌ No | ✅ Yes |
| **Auto-registration** | ❌ No | ❌ No | ✅ Optional |
| **Doc Generation** | ❌ No | ❌ No | ✅ Yes (with doc-gen) |
| **Best For** | Minimal deps | Tools/CLIs | Full ecosystem |
## With Metadata Feature
Enable the `metadata` feature to get rich documentation at runtime:
```toml
[dependencies]
waddling-sequences = { version = "0.2", features = ["metadata"] }
```
```rust
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:
```toml
[dependencies]
waddling-sequences = { version = "0.2", features = ["doc-gen"] }
```
```rust
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:
```bash
cargo run --example generate_docs --features doc-gen
```
## Examples
Check out the [examples/](examples/) directory:
- **[basic.rs](examples/basic.rs)** - Simple usage with constants
- **[metadata.rs](examples/metadata.rs)** - Querying metadata at runtime
- **[with_macros.rs](examples/with_macros.rs)** - Full ecosystem integration with macros
- **[generate_docs.rs](examples/generate_docs.rs)** - Generate HTML/JSON documentation
## Project-Specific Sequences
Sequences **031-897** are **available for project-specific use** per WDP-6!
```rust
// 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:
```rust
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:
```rust
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)
```rust
// 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)
```rust
// 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:
```rust
#![no_std]
use waddling_sequences::core::*;
const ERR: u16 = MISSING; // Works everywhere!
```
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option.
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
---
**Made with waddles by 🦆**