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