chronon_macros/lib.rs
1//! Chronon proc-macro crate.
2//!
3//! Provides the [`script`] attribute macro for auto-registering scheduled Rust functions.
4//!
5//! # Quick start
6//!
7//! 1. Annotate an async function with `#[chronon::script(name = "...")]`.
8//! 2. First parameter must be `Box<dyn ScriptContext>`.
9//! 3. Link the defining crate into your worker binary.
10//! 4. Boot Chronon with `.auto_registry()` and a `ContextFactory` from `chronon-core`.
11//!
12//! # Identity
13//!
14//! Handlers receive `Box<dyn ScriptContext>`. At boot, install a factory on `ChrononBuilder`:
15//!
16//! - `JsonScriptContextFactory` for examples and actor-json-only handlers.
17//! - A custom `ContextFactory` when handlers need application-specific session state rebuilt
18//! from `actor_json`.
19//!
20//! See `chronon-core` rustdoc for factory types. Runnable samples:
21//! - `examples/script_macro.rs` — register script, `Job::new`, upsert, tick
22//! - `examples/script_handle_job.rs` — typed `ScriptHandle` defaults
23
24use proc_macro::TokenStream;
25
26mod script;
27mod script_attrs;
28mod script_expand;
29mod script_validate;
30
31/// Marks an async function as a Chronon script, enabling automatic registration
32/// and typed parameter handling.
33///
34/// # Requirements
35///
36/// - Function must be `async`
37/// - First parameter must be `Box<dyn ScriptContext>`
38/// - Return type must be `Result<()>` (for example `chronon_core::Result<()>`)
39/// - `name` attribute is required and must be unique
40/// - Parameters after `ScriptContext` must be simple identifiers
41///
42/// # Examples
43///
44/// ```ignore
45/// #[chronon::script(name = "nightly_cleanup")]
46/// async fn nightly_cleanup(
47/// ctx: Box<dyn ScriptContext>,
48/// retention_days: u32,
49/// ) -> chronon::Result<()> {
50/// let _ = (ctx.label(), retention_days);
51/// Ok(())
52/// }
53/// ```
54#[proc_macro_attribute]
55pub fn script(attr: TokenStream, item: TokenStream) -> TokenStream {
56 script::script_impl(attr, item)
57}