Hooks en

Lifecycle Hooks

Execute custom logic before and after entity operations. Hooks enable validation, normalization, side effects, and authorization.

Quick Start

#[derive(Entity)]
#[entity(table = "users", hooks)]
pub struct User {
    #[id]
    pub id: Uuid,

    #[field(create, update, response)]
    pub email: String,

    #[field(create, response)]
    pub name: String,

    #[field(skip)]
    pub password_hash: String,

    #[field(response)]
    #[auto]
    pub created_at: DateTime<Utc>,
}

Generated Code

The hooks attribute generates an async trait:

/// Generated by entity-derive
#[async_trait]
pub trait UserHooks: Send + Sync {
    type Error: std::error::Error + Send + Sync;

    /// Called before creating a new entity.
    /// Modify the DTO or return an error to abort.
    async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error>;

    /// Called after entity creation.
    async fn after_create(&self, entity: &User) -> Result<(), Self::Error>;

    /// Called before updating an entity.
    /// Modify the DTO or return an error to abort.
    async fn before_update(&self, id: &Uuid, dto: &mut UpdateUserRequest) -> Result<(), Self::Error>;

    /// Called after entity update.
    async fn after_update(&self, entity: &User) -> Result<(), Self::Error>;

    /// Called before deleting an entity.
    /// Return an error to abort.
    async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error>;

    /// Called after entity deletion.
    async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
}

Implementation Example

use async_trait::async_trait;

struct UserService {
    pool: PgPool,
    cache: RedisPool,
    email_sender: EmailService,
}

#[async_trait]
impl UserHooks for UserService {
    type Error = AppError;

    async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error> {
        // Normalize email
        dto.email = dto.email.trim().to_lowercase();

        // Validate email format
        if !dto.email.contains('@') {
            return Err(AppError::Validation("Invalid email format".into()));
        }

        // Check for duplicate email
        let exists = sqlx::query_scalar::<_, bool>(
            "SELECT EXISTS(SELECT 1 FROM users WHERE email = $1)"
        )
        .bind(&dto.email)
        .fetch_one(&self.pool)
        .await?;

        if exists {
            return Err(AppError::Conflict("Email already registered".into()));
        }

        Ok(())
    }

    async fn after_create(&self, entity: &User) -> Result<(), Self::Error> {
        // Send welcome email
        self.email_sender
            .send_welcome(&entity.email, &entity.name)
            .await?;

        // Cache the new user
        self.cache.set(&format!("user:{}", entity.id), entity).await?;

        Ok(())
    }

    async fn before_update(&self, id: &Uuid, dto: &mut UpdateUserRequest) -> Result<(), Self::Error> {
        // Normalize email if provided
        if let Some(ref mut email) = dto.email {
            *email = email.trim().to_lowercase();

            // Check for duplicate (excluding current user)
            let exists = sqlx::query_scalar::<_, bool>(
                "SELECT EXISTS(SELECT 1 FROM users WHERE email = $1 AND id != $2)"
            )
            .bind(&*email)
            .bind(id)
            .fetch_one(&self.pool)
            .await?;

            if exists {
                return Err(AppError::Conflict("Email already in use".into()));
            }
        }

        Ok(())
    }

    async fn after_update(&self, entity: &User) -> Result<(), Self::Error> {
        // Invalidate cache
        self.cache.del(&format!("user:{}", entity.id)).await?;

        Ok(())
    }

    async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error> {
        // Check if user can be deleted
        let has_orders = sqlx::query_scalar::<_, bool>(
            "SELECT EXISTS(SELECT 1 FROM orders WHERE user_id = $1 AND status = 'pending')"
        )
        .bind(id)
        .fetch_one(&self.pool)
        .await?;

        if has_orders {
            return Err(AppError::Forbidden("Cannot delete user with pending orders".into()));
        }

        Ok(())
    }

    async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error> {
        // Invalidate cache
        self.cache.del(&format!("user:{}", id)).await?;

        // Clean up related data
        sqlx::query("DELETE FROM user_sessions WHERE user_id = $1")
            .bind(id)
            .execute(&self.pool)
            .await?;

        Ok(())
    }
}

Use Cases

Validation

async fn before_create(&self, dto: &mut CreateProductRequest) -> Result<(), Self::Error> {
    // Price validation
    if dto.price_cents <= 0 {
        return Err(AppError::Validation("Price must be positive".into()));
    }

    // SKU format validation
    if !dto.sku.chars().all(|c| c.is_alphanumeric() || c == '-') {
        return Err(AppError::Validation("Invalid SKU format".into()));
    }

    Ok(())
}

Normalization

async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error> {
    // Normalize email
    dto.email = dto.email.trim().to_lowercase();

    // Normalize name
    dto.name = dto.name.trim().to_string();

    // Capitalize first letter of each word
    dto.name = dto.name
        .split_whitespace()
        .map(|word| {
            let mut chars = word.chars();
            match chars.next() {
                None => String::new(),
                Some(first) => first.to_uppercase().chain(chars).collect(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ");

    Ok(())
}

Authorization

async fn before_update(&self, id: &Uuid, _dto: &mut UpdatePostRequest) -> Result<(), Self::Error> {
    // Get current user from context (e.g., thread-local or passed via self)
    let current_user = self.current_user()?;

    // Check ownership
    let post = sqlx::query_as::<_, Post>(
        "SELECT * FROM posts WHERE id = $1"
    )
    .bind(id)
    .fetch_optional(&self.pool)
    .await?
    .ok_or(AppError::NotFound)?;

    if post.author_id != current_user.id && !current_user.is_admin {
        return Err(AppError::Forbidden("Cannot edit other user's posts".into()));
    }

    Ok(())
}

Side Effects

async fn after_create(&self, entity: &Order) -> Result<(), Self::Error> {
    // Update inventory
    for item in &entity.items {
        sqlx::query(
            "UPDATE products SET stock = stock - $1 WHERE id = $2"
        )
        .bind(item.quantity)
        .bind(item.product_id)
        .execute(&self.pool)
        .await?;
    }

    // Send notification
    self.notifications.send_order_confirmation(entity).await?;

    // Schedule fulfillment job
    self.job_queue.enqueue(FulfillOrderJob { order_id: entity.id }).await?;

    Ok(())
}

Audit Logging

async fn after_update(&self, entity: &User) -> Result<(), Self::Error> {
    sqlx::query(
        "INSERT INTO audit_log (entity_type, entity_id, action, performed_by, performed_at)
         VALUES ('user', $1, 'update', $2, NOW())"
    )
    .bind(entity.id)
    .bind(self.current_user_id())
    .execute(&self.pool)
    .await?;

    Ok(())
}

With Soft Delete

When soft_delete is enabled, additional hooks are generated:

#[derive(Entity)]
#[entity(table = "documents", hooks, soft_delete)]
pub struct Document { /* ... */ }

Generated hooks:

#[async_trait]
pub trait DocumentHooks: Send + Sync {
    type Error: std::error::Error + Send + Sync;

    // Standard CRUD hooks...
    async fn before_create(&self, dto: &mut CreateDocumentRequest) -> Result<(), Self::Error>;
    async fn after_create(&self, entity: &Document) -> Result<(), Self::Error>;
    async fn before_update(&self, id: &Uuid, dto: &mut UpdateDocumentRequest) -> Result<(), Self::Error>;
    async fn after_update(&self, entity: &Document) -> Result<(), Self::Error>;
    async fn before_delete(&self, id: &Uuid) -> Result<(), Self::Error>;  // Soft delete
    async fn after_delete(&self, id: &Uuid) -> Result<(), Self::Error>;

    // Soft delete specific hooks
    async fn before_restore(&self, id: &Uuid) -> Result<(), Self::Error>;
    async fn after_restore(&self, entity: &Document) -> Result<(), Self::Error>;
    async fn before_hard_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
    async fn after_hard_delete(&self, id: &Uuid) -> Result<(), Self::Error>;
}

With Commands

When commands and hooks are both enabled, command hooks are generated:

#[derive(Entity)]
#[entity(table = "orders", hooks, commands)]
#[command(Place)]
#[command(Cancel, requires_id)]
pub struct Order { /* ... */ }

Additional hooks:

#[async_trait]
pub trait OrderHooks: Send + Sync {
    type Error: std::error::Error + Send + Sync;

    // Standard CRUD hooks...

    // Command hooks
    async fn before_command(&self, cmd: &OrderCommand) -> Result<(), Self::Error>;
    async fn after_command(&self, cmd: &OrderCommand, result: &OrderCommandResult) -> Result<(), Self::Error>;
}

Usage:

async fn before_command(&self, cmd: &OrderCommand) -> Result<(), Self::Error> {
    match cmd {
        OrderCommand::Place(place) => {
            // Validate order can be placed
            if place.items.is_empty() {
                return Err(AppError::Validation("Order must have items".into()));
            }
        }
        OrderCommand::Cancel(cancel) => {
            // Check if order can be cancelled
            let order = self.find_order(cancel.id).await?;
            if order.status == "shipped" {
                return Err(AppError::Forbidden("Cannot cancel shipped order".into()));
            }
        }
    }
    Ok(())
}

async fn after_command(&self, cmd: &OrderCommand, result: &OrderCommandResult) -> Result<(), Self::Error> {
    match (cmd, result) {
        (OrderCommand::Place(_), OrderCommandResult::Place(order)) => {
            self.send_order_confirmation(order).await?;
        }
        (OrderCommand::Cancel(_), OrderCommandResult::Cancel) => {
            // Refund logic
        }
    }
    Ok(())
}

Best Practices

1. Keep hooks fast — Long-running operations should be async jobs
2. Use transactions — Wrap hook + repository call in a transaction
3. Handle errors gracefully — Return meaningful error types
4. Don't duplicate logic — Use hooks for cross-cutting concerns
5. Test hooks independently — Unit test hook implementations

Error Handling Pattern

#[derive(Debug)]
pub enum HookError {
    Validation(String),
    Authorization(String),
    Conflict(String),
    Database(sqlx::Error),
}

impl std::error::Error for HookError {}
impl std::fmt::Display for HookError { /* ... */ }

impl From<sqlx::Error> for HookError {
    fn from(err: sqlx::Error) -> Self {
        HookError::Database(err)
    }
}

#[async_trait]
impl UserHooks for UserService {
    type Error = HookError;

    async fn before_create(&self, dto: &mut CreateUserRequest) -> Result<(), Self::Error> {
        if dto.email.is_empty() {
            return Err(HookError::Validation("Email required".into()));
        }
        Ok(())
    }
}

See Also

• Events — Lifecycle events for audit logging
• Commands — CQRS pattern with command hooks
• Best Practices — Production tips