product_os_store_macros/

lib.rs

//! # Product OS Store Macros
//!
//! This crate provides procedural macros for generating SQL query builders from Rust structs.
//! It works in conjunction with the `product-os-store` crate to provide a type-safe, ergonomic
//! interface for database operations.
//!
//! ## Features
//!
//! - **Automatic SQL Generation**: Derive SQL operations from struct definitions
//! - **Type Safety**: Compile-time verification of field types and constraints
//! - **Flexible Naming**: Automatic table name pluralization or custom names
//! - **Constraint Support**: Primary keys, foreign keys, unique constraints, and more
//! - **No-std Compatible**: Works in `no_std` environments with `alloc`
//!
//! ## Usage
//!
//! ### Basic Example
//!
//! ```rust,ignore
//! use product_os_store_macros::ProductOSRelational;
//! use product_os_store::ProductOSRelationalObject;
//!
//! #[derive(ProductOSRelational, Debug, Default)]
//! struct User {
//!     #[primary_key]
//!     id: i32,
//!     name: String,
//!     email: String,
//!     active: bool,
//! }
//!
//! let user = User::default();
//! let insert_instruction = user.relational_insert();
//! ```
//!
//! ### Table Naming
//!
//! By default, table names are automatically pluralized:
//!
//! ```rust,ignore
//! #[derive(ProductOSRelational)]
//! struct User { /* ... */ }  // Table name: "Users"
//!
//! #[derive(ProductOSRelational)]
//! struct Category { /* ... */ }  // Table name: "Categories"
//! ```
//!
//! To disable pluralization:
//!
//! ```rust,ignore
//! #[derive(ProductOSRelational)]
//! #[do_not_pluralize]
//! struct Data { /* ... */ }  // Table name: "Data"
//! ```
//!
//! ### Field Attributes
//!
//! - `#[primary_key]` - Marks a field as the primary key
//! - `#[foreign_key]` - Marks a field as a foreign key
//! - `#[not_null]` - Ensures the field cannot be null (implied for non-Option types)
//! - `#[unique]` - Adds a unique constraint
//! - `#[always_identity]` - Marks the field as always generated (e.g., auto-increment)
//! - `#[default_identity]` - Marks the field as generated by default
//!
//! ### Supported Types
//!
//! #### Primitive Types
//! - `bool` → Boolean
//! - `String`, `&str` → Text
//! - `i8` → Char (single byte)
//! - `i16`, `u8` → SmallInt
//! - `i32`, `u16`, `isize` → Int
//! - `i64`, `u32` → BigInt
//! - `f32` → Real
//! - `f64` → Precision
//!
//! #### Special Types
//! - `Vec<u8>` → ByteA (binary data)
//! - `Vec` of any type → JsonB (serialized as JSON)
//! - `chrono::DateTime` with `Utc` → TimestampTZ
//! - `uuid::Uuid` → Uuid
//! - `serde_json::Value` → JsonB
//! - Custom types implementing `Serialize`/`Deserialize` → JsonB
//!
//! #### Optional Types
//!
//! Wrap any type in `Option` to make it nullable:
//!
//! ```rust,ignore
//! #[derive(ProductOSRelational)]
//! struct User {
//!     id: i32,                    // NOT NULL
//!     name: String,               // NOT NULL
//!     email: Option<String>,      // Nullable
//!     age: Option<i32>,           // Nullable
//! }
//! ```
//!
//! ## Generated Methods
//!
//! The `ProductOSRelational` derive macro generates implementations for the
//! `ProductOSRelationalObject` trait, including:
//!
//! ### DDL Operations
//! - `relational_create()` - Generate CREATE TABLE instruction
//! - `relational_alter()` - Generate ALTER TABLE instruction
//! - `relational_drop()` - Generate DROP TABLE instruction
//!
//! ### DML Operations
//! - `relational_insert()` - Generate INSERT instruction
//! - `relational_update()` - Generate UPDATE instruction
//! - `relational_delete()` - Generate DELETE instruction (static)
//! - `relational_upsert()` - Generate UPSERT instruction
//!
//! ### Query Operations
//! - `relational_query_all()` - Generate SELECT * query (static)
//! - `relational_query_basic()` - Generate basic SELECT query (static)
//! - `relational_query()` - Generate SELECT with conditions (static)
//! - `relational_query_advanced()` - Generate SELECT with joins (static)
//!
//! ### Utility Methods
//! - `relational_from_row()` - Populate struct from database row
//! - `relational_test()` - Debug helper for generated field information
//!
//! ## Compatibility
//!
//! This crate requires:
//! - Rust 1.69 or later
//! - Works with `no_std` (requires `alloc`)
//! - Designed for use with `product-os-store`

#![no_std]
extern crate no_std_compat as std;

use std::prelude::v1::*;


mod relational;
mod type_parsing;

use crate::relational::{ impl_relational_macro };


/// Derives the `ProductOSRelationalObject` trait for a struct.
///
/// This macro generates methods for creating SQL queries and instructions from Rust structs.
/// The struct name is automatically used as the table name (pluralized by default).
///
/// # Attributes
///
/// ## Struct-level Attributes
///
/// - `#[do_not_pluralize]` - Prevents automatic pluralization of the table name
///
/// ## Field-level Attributes
///
/// - `#[primary_key]` - Marks the field as a primary key
/// - `#[foreign_key]` - Marks the field as a foreign key
/// - `#[not_null]` - Adds a NOT NULL constraint (automatic for non-Option types)
/// - `#[unique]` - Adds a UNIQUE constraint
/// - `#[always_identity]` - Field is always generated (e.g., SERIAL)
/// - `#[default_identity]` - Field is generated by default
///
/// # Examples
///
/// ```rust,ignore
/// use product_os_store_macros::ProductOSRelational;
///
/// #[derive(ProductOSRelational, Debug, Default)]
/// struct User {
///     #[primary_key]
///     id: i32,
///     name: String,
///     email: Option<String>,
/// }
///
/// let user = User { id: 1, name: "Alice".to_string(), email: None };
/// let insert = user.relational_insert();
/// ```
///
/// # Generated Code
///
/// The macro generates an implementation of `ProductOSRelationalObject` with methods for:
/// - Creating SQL DDL statements (CREATE, ALTER, DROP)
/// - Creating SQL DML statements (INSERT, UPDATE, DELETE, UPSERT)
/// - Building queries (SELECT with various options)
/// - Mapping database rows to struct instances
///
/// # Table Naming
///
/// By default, the table name is the pluralized form of the struct name:
/// - `User` → `Users`
/// - `Category` → `Categories`
/// - `Person` → `People`
///
/// Use `#[do_not_pluralize]` to keep the original name.
#[proc_macro_derive(ProductOSRelational, attributes(primary_key, foreign_key, not_null, unique, always_identity, default_identity))]
pub fn relational_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let ast = syn::parse_macro_input!(input as syn::DeriveInput);

    impl_relational_macro(&ast)
}

/// Prevents automatic pluralization of the table name.
///
/// By default, the `ProductOSRelational` derive macro pluralizes struct names to create
/// table names (e.g., `User` → `Users`). Use this attribute to keep the original name.
///
/// # Example
///
/// ```rust,ignore
/// use product_os_store_macros::ProductOSRelational;
///
/// #[derive(ProductOSRelational)]
/// #[do_not_pluralize]
/// struct Data {
///     id: i32,
///     value: String,
/// }
/// // Table name will be "Data", not "Datas"
/// ```
#[proc_macro_attribute]
pub fn do_not_pluralize(_: proc_macro::TokenStream, input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    input
}