hyperstack_macros/
lib.rs

1//! # hyperstack-macros
2//!
3//! Procedural macros for defining HyperStack streams.
4//!
5//! This crate provides the `#[hyperstack]` attribute macro that transforms
6//! annotated Rust structs into full streaming pipeline specifications, including:
7//!
8//! - State struct generation with field accessors
9//! - Handler creation functions for event processing
10//! - IDL/Proto parser integration for Solana programs
11//! - Automatic AST serialization for deployment
12//!
13//! ## Module Usage (IDL-based)
14//!
15//! ```rust,ignore
16//! use hyperstack_macros::{hyperstack, Stream};
17//!
18//! #[hyperstack(idl = "idl.json")]
19//! pub mod my_stream {
20//!     #[entity(name = "MyEntity")]
21//!     #[derive(Stream)]
22//!     struct Entity {
23//!         #[map(from = "MyAccount", field = "value")]
24//!         pub value: u64,
25//!     }
26//! }
27//! ```
28//!
29//! ## Supported Attributes
30//!
31//! - `#[map(...)]` - Map from account fields
32//! - `#[from_instruction(...)]` - Map from instruction fields
33//! - `#[event(...)]` - Capture instruction events
34//! - `#[snapshot(...)]` - Capture entire source data
35//! - `#[aggregate(...)]` - Aggregate field values
36//! - `#[computed(...)]` - Computed fields from other fields
37//! - `#[derive_from(...)]` - Derive values from instructions
38
39// Public modules - AST types needed for SDK generation
40pub(crate) mod ast;
41
42// Internal modules - not exposed publicly
43mod codegen;
44mod idl_codegen;
45mod idl_parser_gen;
46mod idl_vixen_gen;
47mod parse;
48mod proto_codegen;
49mod stream_spec;
50mod utils;
51
52use proc_macro::TokenStream;
53use std::collections::HashMap;
54use syn::{parse_macro_input, ItemMod, ItemStruct};
55
56// Use the stream_spec module functions
57use stream_spec::{process_module, process_struct_with_context};
58
59/// Process a `#[hyperstack(...)]` attribute.
60///
61/// This macro can be applied to:
62/// - A module containing entity structs
63/// - A single struct (legacy usage)
64///
65/// ## Module Usage (IDL-based)
66///
67/// ```rust,ignore
68/// #[hyperstack(idl = "idl.json")]
69/// pub mod my_stream {
70///     #[entity(name = "MyEntity")]
71///     struct Entity {
72///         // fields with mapping attributes
73///     }
74/// }
75/// ```
76///
77/// ## Proto-based Usage
78///
79/// ```rust,ignore
80/// #[hyperstack(proto = ["events.proto"])]
81/// pub mod my_stream {
82///     // entity structs
83/// }
84/// ```
85#[proc_macro_attribute]
86pub fn hyperstack(attr: TokenStream, item: TokenStream) -> TokenStream {
87    if let Ok(module) = syn::parse::<ItemMod>(item.clone()) {
88        return process_module(module, attr);
89    }
90
91    let input = parse_macro_input!(item as ItemStruct);
92    process_struct_with_context(input, HashMap::new(), false)
93}
94
95/// Derive macro for `Stream`.
96///
97/// This is a marker derive that enables the following attributes on struct fields:
98/// - `#[map(...)]` - Map from account fields
99/// - `#[from_instruction(...)]` - Map from instruction fields
100/// - `#[event(...)]` - Capture instruction events
101/// - `#[snapshot(...)]` - Capture entire source
102/// - `#[aggregate(...)]` - Aggregate field values
103/// - `#[computed(...)]` - Computed fields from other fields
104/// - `#[derive_from(...)]` - Derive values from instructions
105#[proc_macro_derive(
106    Stream,
107    attributes(
108        map,
109        from_instruction,
110        event,
111        snapshot,
112        aggregate,
113        computed,
114        derive_from
115    )
116)]
117pub fn stream_derive(_input: TokenStream) -> TokenStream {
118    TokenStream::new()
119}
hyperstack_macros/lib.rs

hyperstack_macros/
lib.rs
