rorpc 0.2.5

Rust oRPC — annotation-driven Axum handlers with automatic TypeScript contract generation
Documentation
//! # rorpc
//!
//! Unified facade for handler metadata collection, auto-router construction,
//! and TypeScript contract generation.
//!
//! ## Quick Start
//!
//! ```rust,ignore
//! use axum::{extract::State, Json};
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Serialize, Deserialize)]
//! struct Planet { id: i32, name: String }
//!
//! #[rorpc::get("/planet/list")]
//! async fn list_planets(State(db): State<Db>) -> Json<Vec<Planet>> {
//!     Json(db.list().await)
//! }
//!
//! #[tokio::main]
//! async fn main() {
//!     let app = rorpc::router!(db);
//!
//!     rorpc::generate_contract()
//!         .output("../client/src/rpc/index.ts")
//!         .unwrap();
//!
//!     axum::serve(listener, app).await.unwrap();
//! }
//! ```

pub mod codegen;
pub mod error_registry;
pub mod metadata;
pub mod registration;
pub mod resolution;
pub mod schema_registry;

pub use codegen::ContractBuilder;
pub use error_registry::{ErrorRegistration, ErrorVariant};
pub use metadata::{HandlerMetadata, NamespaceMetadata};
pub use registration::HandlerRegistration;
pub use schema_registry::{
    EnumRepr, FieldDef, SchemaDef, SchemaRegistration, VariantDef, VariantKind,
};

// Re-export inventory so users don't need to depend on it directly
pub use inventory;

pub use rorpc_macros::{OrpcError, ZodTs};

// Re-export the attribute macros and router! proc macro
pub use rorpc_macros::contract;
pub use rorpc_macros::delete;
pub use rorpc_macros::get;
pub use rorpc_macros::namespace;
pub use rorpc_macros::patch;
pub use rorpc_macros::post;
pub use rorpc_macros::put;
pub use rorpc_macros::route;
pub use rorpc_macros::router;

/// Begin building a TypeScript contract from all discovered handlers.
///
/// # Example
///
/// ```no_run
/// rorpc::generate_contract()
///     .output("../client/src/rpc/index.ts")
///     .unwrap();
/// ```
pub fn generate_contract() -> ContractBuilder {
    // Build namespace lookup map: module_path -> prefix
    let namespace_map = resolution::build_namespace_map();

    let handlers: Vec<codegen::HandlerInfo> = inventory::iter::<HandlerMetadata>
        .into_iter()
        .map(|m| {
            // Resolve namespace-prefixed path for this handler
            let final_path =
                resolution::resolve_namespace_path(m.module_path, m.path, &namespace_map);

            codegen::HandlerInfo {
                name: m.name,
                method: m.method,
                path: Box::leak(final_path.into_boxed_str()),
                input_type_name: m.input_type_name,
                query_type_name: m.query_type_name,
                output_type_name: m.output_type_name,
                module_path: m.module_path,
                error_type_name: m.error_type_name,
                stream_event_type_name: m.stream_event_type_name,
                path_param_types: m.path_param_types,
            }
        })
        .collect();

    // Build schema registry and track ALL registrations (including collisions)
    let mut registry: std::collections::HashMap<&'static str, Vec<&SchemaRegistration>> =
        std::collections::HashMap::new();

    for reg in inventory::iter::<SchemaRegistration>.into_iter() {
        // Normalize type_name: strip module paths so "crate::types::Session" → "Session"
        // This groups handler-emitted fallbacks together with real ZodTs registrations
        let normalized = reg.type_name.rsplit("::").next().unwrap_or(reg.type_name);
        registry.entry(normalized).or_default().push(reg);
    }

    // Process registrations: prefer real schemas, warn on collisions
    let mut final_registry: std::collections::HashMap<
        &'static str,
        (&'static SchemaRegistration, String),
    > = std::collections::HashMap::new();
    let mut type_to_keys: std::collections::HashMap<&'static str, Vec<&'static str>> =
        std::collections::HashMap::new();

    for (type_name, regs) in registry {
        let real_schemas: Vec<_> = regs
            .iter()
            .filter(|r| !matches!(r.schema_def, SchemaDef::Unknown))
            .copied()
            .collect();

        if real_schemas.is_empty() {
            if let Some(reg) = regs.first() {
                let ts_name = format!("{}Schema", type_name);
                final_registry.insert(type_name, (reg, ts_name));
                type_to_keys.entry(type_name).or_default().push(type_name);
            }
        } else if real_schemas.len() == 1 {
            let reg = real_schemas[0];
            let ts_name = format!("{}Schema", type_name);
            final_registry.insert(type_name, (reg, ts_name));
            type_to_keys.entry(type_name).or_default().push(type_name);
        } else {
            eprintln!(
                "⚠️  WARNING: Schema name collision detected for '{}'",
                type_name
            );
            eprintln!("   Multiple types with #[derive(ZodTs)] have the same name:");
            for reg in &real_schemas {
                let disambiguated = resolution::module_path_to_ts_name(reg.module_path, type_name);
                let ts_name = format!("{}Schema", disambiguated);
                eprintln!("     {} → {}", reg.module_path, ts_name);
                final_registry.insert(reg.module_path, (reg, ts_name));
                type_to_keys
                    .entry(type_name)
                    .or_default()
                    .push(reg.module_path);
            }
            eprintln!();
        }
    }

    // Topological sort: emit dependency schemas before the types that use them
    use topological_sort::TopologicalSort;

    let mut topo_sort = TopologicalSort::<&'static str>::new();

    // Build the dependency graph
    for (type_name, keys) in &type_to_keys {
        for key in keys {
            if let Some((reg, _)) = final_registry.get(key) {
                // Add dependencies for this type
                for dep in (reg.dependent_types)() {
                    // Normalize dependency: strip to bare name for lookup
                    let normalized = dep.rsplit("::").next().unwrap_or(dep);

                    // Add edge: type_name depends on normalized
                    // In topological-sort, add_dependency(before, after) means "before must come before after"
                    topo_sort.add_dependency(normalized, *type_name);
                }

                // Also insert the type itself to ensure it's in the graph even if it has no deps
                topo_sort.insert(*type_name);
            }
        }
    }

    // Extract sorted order
    let mut ordered: Vec<codegen::SchemaEntry> = Vec::new();
    let mut registered: Vec<(String, &'static SchemaRegistration)> = Vec::new();

    // Pop all items in topological order
    while let Some(type_name) = topo_sort.pop() {
        // Get all keys for this type (could be multiple if collision)
        let keys = type_to_keys
            .get(type_name)
            .map(|v| v.as_slice())
            .unwrap_or(&[]);

        for key in keys {
            if let Some((reg, ts_schema_name)) = final_registry.get(key) {
                ordered.push(codegen::SchemaEntry {
                    type_name: reg.type_name,
                    ts_schema_name: ts_schema_name.clone(),
                });
                registered.push((ts_schema_name.clone(), reg));
            }
        }
    }

    // Check for cycles (though the manual implementation didn't explicitly check either)
    if !topo_sort.is_empty() {
        eprintln!("⚠️  WARNING: Circular dependency detected in schema types");
        eprintln!("   The following types form a dependency cycle:");
        for remaining in topo_sort.into_items() {
            eprintln!("     - {}", remaining);
        }
        eprintln!();
    }

    // Collect error registrations
    let errors: Vec<codegen::ErrorInfo> = inventory::iter::<ErrorRegistration>
        .into_iter()
        .map(|e| codegen::ErrorInfo {
            type_name: e.type_name,
            variants: e
                .variants
                .iter()
                .map(|v| codegen::ErrorVariantInfo {
                    name: v.name,
                    data_schema: v.data_schema,
                })
                .collect(),
        })
        .collect();

    // -----------------------------------------------------------------------
    // Resolution pass: SchemaDef → Vec<ResolvedSchema>
    // -----------------------------------------------------------------------
    //
    // Build a lookup map: bare type name → all (ts_schema_name, module_path)
    // candidates. Used by `resolve_type_ref` to pick the right disambiguated
    // name for each field's type_ref.
    let mut candidates_by_name: std::collections::HashMap<
        &'static str,
        Vec<(String, &'static str)>,
    > = std::collections::HashMap::new();
    for (ts_schema_name, reg) in &registered {
        candidates_by_name
            .entry(reg.type_name)
            .or_default()
            .push((ts_schema_name.clone(), reg.module_path));
    }

    /// Resolve a single `FieldDef` into a `ResolvedField`.
    fn resolve_field(
        field: &crate::schema_registry::FieldDef,
        referencing_module: &str,
        candidates_by_name: &std::collections::HashMap<&'static str, Vec<(String, &'static str)>>,
    ) -> codegen::ir::ResolvedField {
        let zod_expr = if field.type_ref.is_empty() {
            // Primitive — already a complete expression
            field.zod_expr.to_string()
        } else {
            // Custom type — resolve to ts_schema_name, apply optional/nullable wrapper
            let base = resolution::resolve_type_ref(
                field.type_ref,
                referencing_module,
                candidates_by_name,
            )
            .unwrap_or_else(|| format!("{}Schema", field.type_ref));
            if field.optional {
                if field.skip_if_none {
                    format!("{}.optional()", base)
                } else {
                    format!("{}.nullable()", base)
                }
            } else {
                base
            }
        };
        codegen::ir::ResolvedField {
            ts_key: field.ts_name.to_string(),
            zod_expr,
        }
    }

    /// Resolve a single `VariantDef` into a `ResolvedVariant`.
    fn resolve_variant(
        variant: &crate::schema_registry::VariantDef,
        referencing_module: &str,
        candidates_by_name: &std::collections::HashMap<&'static str, Vec<(String, &'static str)>>,
    ) -> codegen::ir::ResolvedVariant {
        use crate::schema_registry::VariantKind;
        let kind = match variant.kind {
            VariantKind::Unit => codegen::ir::ResolvedVariantKind::Unit,
            VariantKind::NewtypeZod { zod_expr } => codegen::ir::ResolvedVariantKind::Newtype {
                zod_expr: zod_expr.to_string(),
            },
            VariantKind::NewtypeRef { type_ref } => {
                let resolved =
                    resolution::resolve_type_ref(type_ref, referencing_module, candidates_by_name)
                        .unwrap_or_else(|| format!("{}Schema", type_ref));
                codegen::ir::ResolvedVariantKind::Newtype { zod_expr: resolved }
            }
            VariantKind::Struct { fields } => {
                let resolved_fields = fields
                    .iter()
                    .map(|f| resolve_field(f, referencing_module, candidates_by_name))
                    .collect();
                codegen::ir::ResolvedVariantKind::Struct {
                    fields: resolved_fields,
                }
            }
        };
        codegen::ir::ResolvedVariant {
            serialized_name: variant.serialized_name.to_string(),
            kind,
        }
    }

    let resolved_schemas: Vec<codegen::ir::ResolvedSchema> = registered
        .iter()
        .filter_map(|(ts_schema_name, reg)| {
            let ts_type_name = ts_schema_name
                .strip_suffix("Schema")
                .unwrap_or(ts_schema_name)
                .to_string();

            let def = match &reg.schema_def {
                SchemaDef::Unknown => return None, // skip fallbacks
                SchemaDef::Object { fields } => {
                    let resolved_fields = fields
                        .iter()
                        .map(|f| resolve_field(f, reg.module_path, &candidates_by_name))
                        .collect();
                    codegen::ir::ResolvedDef::Object {
                        fields: resolved_fields,
                    }
                }
                SchemaDef::Enum { repr, variants } => {
                    // Convert EnumRepr → ResolvedEnumRepr
                    let resolved_repr = match repr {
                        schema_registry::EnumRepr::External => {
                            codegen::ir::ResolvedEnumRepr::External
                        }
                        schema_registry::EnumRepr::Internal { tag } => {
                            codegen::ir::ResolvedEnumRepr::Internal {
                                tag: tag.to_string(),
                            }
                        }
                        schema_registry::EnumRepr::Adjacent { tag, content } => {
                            codegen::ir::ResolvedEnumRepr::Adjacent {
                                tag: tag.to_string(),
                                content: content.to_string(),
                            }
                        }
                        schema_registry::EnumRepr::Untagged => {
                            codegen::ir::ResolvedEnumRepr::Untagged
                        }
                    };

                    let resolved_variants = variants
                        .iter()
                        .map(|v| resolve_variant(v, reg.module_path, &candidates_by_name))
                        .collect();
                    codegen::ir::ResolvedDef::Enum {
                        repr: resolved_repr,
                        variants: resolved_variants,
                    }
                }
            };

            Some(codegen::ir::ResolvedSchema {
                ts_schema_name: ts_schema_name.clone(),
                ts_type_name,
                module_path: reg.module_path,
                def,
            })
        })
        .collect();

    ContractBuilder::new(handlers, ordered, resolved_schemas).with_errors(errors)
}