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/// Boot with `ChrononBuilder::auto_registry()` so inventory discovers the handler. In a
43/// coordinator–worker split, link scripts into **worker** binaries. Prefer
44/// `chronon_core::ScriptHandle` for typed job defaults; see the `chronon` crate getting-started
45/// §4–5.
46///
47/// # Examples
48///
49/// ```ignore
50/// use chronon::prelude::*;
51///
52/// #[chronon::script(name = "nightly_cleanup")]
53/// async fn nightly_cleanup(
54///     ctx: Box<dyn ScriptContext>,
55///     retention_days: u32,
56/// ) -> chronon::Result<()> {
57///     let _ = (ctx.label(), retention_days);
58///     Ok(())
59/// }
60/// ```
61///
62/// Runnable: `cargo run -p uf-chronon --example script_macro --features mem`
63/// and `script_handle_job`.
64#[proc_macro_attribute]
65pub fn script(attr: TokenStream, item: TokenStream) -> TokenStream {
66    script::script_impl(attr, item)
67}
chronon_macros/lib.rs

chronon_macros/
lib.rs
