Crate zirv_macros

zirv-macros

The zirv-macros crate provides a collection of custom macros designed to ease backend development in Rust, especially for projects using Actix and SQLx. The macros help reduce boilerplate, improve logging, enhance error handling, and aid with instrumentation and performance measurement.

Features

• Error Handling & Assertions:

  • try_log!: Evaluates an expression returning a Result, logs on error, and returns an error.
  • unwrap_or_log!: Unwraps a result and uses a default value if it fails, logging the error.
  • assert_msg!: Asserts a condition with a custom error message.

• Timing & Instrumentation:

  • time_it!: Measures and logs the execution time of a code block.
  • log_duration!: Logs the duration of a code block using tracing.
  • span_wrap!: Wraps a block of code inside a tracing span.
  • call_with_trace!: Calls a function inside a tracing span.

• JSON & Environment Helpers:

  • json_merge!: Merges two JSON objects.
  • parse_env!: Reads an environment variable with a default fallback.
  • pretty_debug!: Pretty-prints a JSON representation of an object.

• SQL Debugging:

  • debug_query!: Logs the full SQL query string before executing it.

• Retry Utilities:

  • with_retry!: Synchronously retries an expression a fixed number of times.
  • retry_async!: Asynchronously retries an expression a fixed number of times.

Usage

Add zirv-macros as a dependency in your Cargo.toml and import the macros:

[dependencies]
zirv-macros = { path = "../zirv-macros" }

use zirv_macros::*;

See the examples below for details.

Macros

assert_msg

Asserts a condition and logs an error with a custom message if it fails, then panics.

call_with_trace

Calls a function with the provided arguments, wrapping the call in a tracing span with the specified name.

debug_query

Logs the SQL query string (and optionally its bind parameters) before executing it. Useful for debugging SQLx queries.

json_merge

Merges two serde_json::Value objects (expected to be JSON objects). Keys in the second object override those in the first.

log_duration

Logs the duration of a code block using tracing. Executes the block, logs the elapsed time with the provided label, and returns the result.

log_error

Attempts to evaluate an expression returning a Result and logs an error if it fails, returning a default value instead.

parse_env

Attempts to read an environment variable. If the variable is not set, logs a warning and returns a default value as a String.

pretty_debug

Prints a pretty-printed JSON representation of an object that implements Serialize.

retry_async

Retries an asynchronous expression (returning a Result) a specified number of times, waiting a fixed number of milliseconds between attempts. Uses tokio::time::sleep.

span_wrap

Wraps a block of code in a tracing span with the given name, enabling automatic instrumentation.

time_it

Measures the execution time of a block of code and prints the duration with the provided label.

try_log

Attempts to evaluate an expression returning a Result. If the result is Ok, returns the value. Otherwise, logs an error with file and line info and returns an error as a String.

unwrap_or_log

Attempts to unwrap a result, returning a default value if an error occurs. Logs an error with file and line info if the unwrap fails.

with_retry

Retries a synchronous expression (returning a Result) a specified number of times, waiting a fixed number of milliseconds between attempts.