entity_derive/

lib.rs

// SPDX-FileCopyrightText: 2025 RAprogramm <andrey.rozanov.vl@gmail.com>
// SPDX-License-Identifier: MIT

#![doc = include_str!("../README.md")]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/RAprogramm/entity-derive/main/assets/logo.svg",
    html_favicon_url = "https://raw.githubusercontent.com/RAprogramm/entity-derive/main/assets/favicon.ico"
)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(
    missing_docs,
    rustdoc::missing_crate_level_docs,
    rustdoc::broken_intra_doc_links,
    rust_2018_idioms
)]
#![deny(unsafe_code)]

//! # Quick Navigation
//!
//! - **Getting Started**: See the [crate documentation](crate) above
//! - **Derive Macro**: [`Entity`](macro@Entity) — the main derive macro
//! - **Examples**: Check the [examples directory](https://github.com/RAprogramm/entity-derive/tree/main/examples)
//! - **Wiki**: [Comprehensive guides](https://github.com/RAprogramm/entity-derive/wiki)
//!
//! # Attribute Quick Reference
//!
//! ## Entity-Level `#[entity(...)]`
//!
//! ```rust,ignore
//! #[derive(Entity)]
//! #[entity(
//!     table = "users",      // Required: database table name
//!     schema = "public",    // Optional: database schema (default: "public")
//!     sql = "full",         // Optional: "full" | "trait" | "none" (default: "full")
//!     dialect = "postgres", // Optional: "postgres" | "clickhouse" | "mongodb" (default: "postgres")
//!     uuid = "v7"           // Optional: "v7" | "v4" (default: "v7")
//! )]
//! pub struct User { /* ... */ }
//! ```
//!
//! ## Field-Level Attributes
//!
//! ```rust,ignore
//! pub struct User {
//!     #[id]                           // Primary key, UUID v7, always in response
//!     pub id: Uuid,
//!
//!     #[field(create, update, response)]  // In all DTOs
//!     pub name: String,
//!
//!     #[field(create, response)]      // Create + Response only
//!     pub email: String,
//!
//!     #[field(skip)]                  // Excluded from all DTOs
//!     pub password_hash: String,
//!
//!     #[field(response)]
//!     #[auto]                         // Auto-generated (excluded from create/update)
//!     pub created_at: DateTime<Utc>,
//! }
//! ```
//!
//! # Generated Code Overview
//!
//! For a `User` entity, the macro generates:
//!
//! | Generated Type | Description |
//! |----------------|-------------|
//! | `CreateUserRequest` | DTO for `POST` requests |
//! | `UpdateUserRequest` | DTO for `PATCH` requests (all fields `Option<T>`) |
//! | `UserResponse` | DTO for API responses |
//! | `UserRow` | Database row mapping (for `sqlx::FromRow`) |
//! | `InsertableUser` | Struct for `INSERT` statements |
//! | `UserRepository` | Async trait with CRUD methods |
//! | `impl UserRepository for PgPool` | PostgreSQL implementation |
//! | `From<...>` impls | Type conversions between all structs |
//!
//! # SQL Generation Modes
//!
//! | Mode | Generates Trait | Generates Impl | Use Case |
//! |------|-----------------|----------------|----------|
//! | `sql = "full"` | ✅ | ✅ | Standard CRUD, simple queries |
//! | `sql = "trait"` | ✅ | ❌ | Custom SQL (joins, CTEs, search) |
//! | `sql = "none"` | ❌ | ❌ | DTOs only, no database layer |
//!
//! # Repository Methods
//!
//! The generated `{Name}Repository` trait includes:
//!
//! ```rust,ignore
//! #[async_trait]
//! pub trait UserRepository: Send + Sync {
//!     type Error: std::error::Error + Send + Sync;
//!
//!     /// Create a new entity
//!     async fn create(&self, dto: CreateUserRequest) -> Result<User, Self::Error>;
//!
//!     /// Find entity by primary key
//!     async fn find_by_id(&self, id: Uuid) -> Result<Option<User>, Self::Error>;
//!
//!     /// Update entity with partial data
//!     async fn update(&self, id: Uuid, dto: UpdateUserRequest) -> Result<User, Self::Error>;
//!
//!     /// Delete entity by primary key
//!     async fn delete(&self, id: Uuid) -> Result<bool, Self::Error>;
//!
//!     /// List entities with pagination
//!     async fn list(&self, limit: i64, offset: i64) -> Result<Vec<User>, Self::Error>;
//! }
//! ```
//!
//! # Error Handling
//!
//! The generated implementation uses `sqlx::Error` as the error type.
//! You can wrap it in your application's error type:
//!
//! ```rust,ignore
//! use entity_derive::Entity;
//!
//! #[derive(Entity)]
//! #[entity(table = "users", sql = "trait")]  // Generate trait only
//! pub struct User { /* ... */ }
//!
//! // Implement with your own error type
//! #[async_trait]
//! impl UserRepository for MyDatabase {
//!     type Error = MyAppError;  // Your custom error
//!
//!     async fn create(&self, dto: CreateUserRequest) -> Result<User, Self::Error> {
//!         // Your implementation
//!     }
//! }
//! ```
//!
//! # Compile-Time Guarantees
//!
//! This crate provides several compile-time guarantees:
//!
//! - **No sensitive data leaks**: Fields marked `#[field(skip)]` are excluded
//!   from all DTOs
//! - **Type-safe updates**: `UpdateRequest` fields are properly wrapped in
//!   `Option`
//! - **Consistent mapping**: `From` impls are always in sync with field
//!   definitions
//! - **SQL injection prevention**: All queries use parameterized bindings
//!
//! # Performance
//!
//! - **Zero runtime overhead**: All code generation happens at compile time
//! - **No reflection**: Generated code is plain Rust structs and impls
//! - **Minimal dependencies**: Only proc-macro essentials (syn, quote, darling)
//!
//! # Comparison with Alternatives
//!
//! | Feature | entity-derive | Diesel | SeaORM |
//! |---------|---------------|--------|--------|
//! | DTO generation | ✅ | ❌ | ❌ |
//! | Repository pattern | ✅ | ❌ | Partial |
//! | Type-safe SQL | ✅ | ✅ | ✅ |
//! | Async support | ✅ | Partial | ✅ |
//! | Boilerplate reduction | ~90% | ~50% | ~60% |

mod entity;
mod utils;

use proc_macro::TokenStream;

/// Derive macro for generating complete domain boilerplate from a single entity
/// definition.
///
/// # Overview
///
/// The `Entity` derive macro generates all the boilerplate code needed for a
/// typical CRUD application: DTOs, repository traits, SQL implementations, and
/// type mappers.
///
/// # Generated Types
///
/// For an entity named `User`, the macro generates:
///
/// - **`CreateUserRequest`** — DTO for creation (fields marked with
///   `#[field(create)]`)
/// - **`UpdateUserRequest`** — DTO for updates (fields marked with
///   `#[field(update)]`, wrapped in `Option`)
/// - **`UserResponse`** — DTO for responses (fields marked with
///   `#[field(response)]`)
/// - **`UserRow`** — Database row struct (implements `sqlx::FromRow`)
/// - **`InsertableUser`** — Struct for INSERT operations
/// - **`UserRepository`** — Async trait with CRUD methods
/// - **`impl UserRepository for PgPool`** — PostgreSQL implementation (when
///   `sql = "full"`)
///
/// # Entity Attributes
///
/// Configure the entity using `#[entity(...)]`:
///
/// | Attribute | Required | Default | Description |
/// |-----------|----------|---------|-------------|
/// | `table` | **Yes** | — | Database table name |
/// | `schema` | No | `"public"` | Database schema name |
/// | `sql` | No | `"full"` | SQL generation: `"full"`, `"trait"`, or `"none"` |
/// | `dialect` | No | `"postgres"` | Database dialect: `"postgres"`, `"clickhouse"`, `"mongodb"` |
/// | `uuid` | No | `"v7"` | UUID version for ID: `"v7"` (time-ordered) or `"v4"` (random) |
///
/// # Field Attributes
///
/// | Attribute | Description |
/// |-----------|-------------|
/// | `#[id]` | Primary key. Auto-generates UUID (v7 by default, configurable with `uuid` attribute). Always included in `Response`. |
/// | `#[auto]` | Auto-generated field (e.g., `created_at`). Excluded from `Create`/`Update`. |
/// | `#[field(create)]` | Include in `CreateRequest`. |
/// | `#[field(update)]` | Include in `UpdateRequest`. Wrapped in `Option<T>` if not already. |
/// | `#[field(response)]` | Include in `Response`. |
/// | `#[field(skip)]` | Exclude from ALL DTOs. Use for sensitive data. |
///
/// Multiple attributes can be combined: `#[field(create, update, response)]`
///
/// # Examples
///
/// ## Basic Usage
///
/// ```rust,ignore
/// use entity_derive::Entity;
/// use uuid::Uuid;
/// use chrono::{DateTime, Utc};
///
/// #[derive(Entity)]
/// #[entity(table = "users", schema = "core")]
/// pub struct User {
///     #[id]
///     pub id: Uuid,
///
///     #[field(create, update, response)]
///     pub name: String,
///
///     #[field(create, update, response)]
///     pub email: String,
///
///     #[field(skip)]
///     pub password_hash: String,
///
///     #[field(response)]
///     #[auto]
///     pub created_at: DateTime<Utc>,
/// }
/// ```
///
/// ## Custom SQL Implementation
///
/// For complex queries with joins, use `sql = "trait"`:
///
/// ```rust,ignore
/// #[derive(Entity)]
/// #[entity(table = "posts", sql = "trait")]
/// pub struct Post {
///     #[id]
///     pub id: Uuid,
///     #[field(create, update, response)]
///     pub title: String,
///     #[field(create, response)]
///     pub author_id: Uuid,
/// }
///
/// // Implement the repository yourself
/// #[async_trait]
/// impl PostRepository for PgPool {
///     type Error = sqlx::Error;
///
///     async fn find_by_id(&self, id: Uuid) -> Result<Option<Post>, Self::Error> {
///         sqlx::query_as!(Post,
///             r#"SELECT p.*, u.name as author_name
///                FROM posts p
///                JOIN users u ON p.author_id = u.id
///                WHERE p.id = $1"#,
///             id
///         )
///         .fetch_optional(self)
///         .await
///     }
///     // ... other methods
/// }
/// ```
///
/// ## DTOs Only (No Database Layer)
///
/// ```rust,ignore
/// #[derive(Entity)]
/// #[entity(table = "events", sql = "none")]
/// pub struct Event {
///     #[id]
///     pub id: Uuid,
///     #[field(create, response)]
///     pub name: String,
/// }
/// // Only generates CreateEventRequest, EventResponse, etc.
/// // No repository trait or SQL implementation
/// ```
///
/// # Security
///
/// Use `#[field(skip)]` to prevent sensitive data from leaking:
///
/// ```rust,ignore
/// pub struct User {
///     #[field(skip)]
///     pub password_hash: String,  // Never in any DTO
///
///     #[field(skip)]
///     pub api_secret: String,     // Never in any DTO
///
///     #[field(skip)]
///     pub internal_notes: String, // Admin-only, not in public API
/// }
/// ```
///
/// # Generated SQL
///
/// The macro generates parameterized SQL queries that are safe from injection:
///
/// ```sql
/// -- CREATE
/// INSERT INTO schema.table (id, field1, field2, ...)
/// VALUES ($1, $2, $3, ...)
///
/// -- READ
/// SELECT * FROM schema.table WHERE id = $1
///
/// -- UPDATE (dynamic based on provided fields)
/// UPDATE schema.table SET field1 = $1, field2 = $2 WHERE id = $3
///
/// -- DELETE
/// DELETE FROM schema.table WHERE id = $1 RETURNING id
///
/// -- LIST
/// SELECT * FROM schema.table ORDER BY created_at DESC LIMIT $1 OFFSET $2
/// ```
#[proc_macro_derive(Entity, attributes(entity, field, id, auto, validate))]
pub fn derive_entity(input: TokenStream) -> TokenStream {
    entity::derive(input)
}