nulid_macros

Procedural macros for convenient NULID generation.

This crate provides macros to simplify working with NULIDs in your Rust code.

Features

The nulid!() macro provides convenient NULID generation with flexible error handling:

• nulid!() - Generate a NULID, panicking on error (for convenience)
• nulid!(?) - Generate a NULID, returning Result<Nulid, Error> (for error handling)

Usage

Add this to your Cargo.toml:

[dependencies]
nulid = { version = "0.5", features = ["macros"] }

Then use the macro in your code:

use nulid::nulid;

fn main() {
    // Simple generation (panics on error)
    let id1 = nulid!();
    println!("Generated: {}", id1);

    // Multiple generations
    let id2 = nulid!();
    let id3 = nulid!();

    assert_ne!(id1, id2);
    assert_ne!(id2, id3);
}

Error Handling

Use nulid!(?) when you need to handle errors gracefully:

use nulid::nulid;

fn create_user_id() -> nulid::Result<nulid::Nulid> {
    // Returns Result for explicit error handling
    let id = nulid!(?)?;
    Ok(id)
}

fn main() -> nulid::Result<()> {
    let user_id = create_user_id()?;
    println!("User ID: {}", user_id);

    // Or use with expect
    let order_id = nulid!(?).expect("Failed to generate order ID");
    println!("Order ID: {}", order_id);

    Ok(())
}

When to Use Each Variant

Use nulid!()

• In tests where panicking is acceptable
• In initialization code where failure should stop the program
• When you want concise, readable code and don't need error recovery

use nulid::nulid;

#[test]
fn test_user_creation() {
    let user_id = nulid!(); // Panic is fine in tests
    // ... rest of test
}

fn main() {
    let config_id = nulid!(); // App initialization
    // ... rest of app
}

Use nulid!(?)

• In library code where you want to propagate errors
• In production code that needs graceful error handling
• When integrating with other Result-returning code

use nulid::nulid;

pub fn create_entity() -> nulid::Result<Entity> {
    let id = nulid!(?)?; // Propagate errors to caller
    Ok(Entity { id, /* ... */ })
}

fn handle_request() -> Result<Response, AppError> {
    let request_id = nulid!(?).map_err(|e| AppError::IdGeneration(e))?;
    // ... process request
}

Comparison with Direct API

The macro provides syntactic sugar over the direct API:

use nulid::{nulid, Nulid};

// These are equivalent:
let id1 = nulid!();
let id2 = Nulid::new().expect("Failed to generate NULID");

// These are equivalent:
let id3 = nulid!(?)?;
let id4 = Nulid::new()?;

The macro makes code more concise and readable, especially when generating multiple IDs:

// With macro
let (user_id, session_id, request_id) = (nulid!(), nulid!(), nulid!());

// Without macro
let user_id = Nulid::new().expect("Failed to generate NULID");
let session_id = Nulid::new().expect("Failed to generate NULID");
let request_id = Nulid::new().expect("Failed to generate NULID");

Performance

The macro has zero runtime overhead - it expands to direct function calls at compile time:

// This macro call:
let id = nulid!();

// Expands to:
let id = ::nulid::Nulid::new().expect("Failed to generate NULID");

Examples

See the examples directory in the nulid repository for more usage examples.

License

This project is licensed under the MIT License - see the LICENSE file for details.