ontogen_ts/lib.rs
1#![forbid(unsafe_code)]
2#![allow(clippy::doc_markdown)]
3
4//! Rust AST → TypeScript emitter for ontogen's long-tail type bindings.
5//!
6//! This crate is the build-time replacement for the OF-014 spike's `specta`
7//! side-car. Given a set of root types, a pool of candidate type definitions
8//! (`syn::Item` keyed by canonical [`TypePath`]), and an [`EmitConfig`], it
9//! produces TypeScript source covering the supported subset documented in
10//! [`OF-015`](https://github.com/sksizer/rust-ontogen/blob/main/docs/tasks/OF-015-productionize-typescript-generation.md):
11//!
12//! - Named structs over primitive / container / smart-pointer / reference
13//! field types
14//! - C-style enums (and tagged enums where the tag is implicit from variant
15//! idents)
16//! - `Vec<T>`, `Option<T>`, `HashMap<K, V>`, `BTreeMap<K, V>`
17//! - Primitives: `bool`, all integer types, `f32`/`f64`, `String`, `&str`
18//! - Smart-pointer wrappers (`Box`, `Rc`, `Arc`, `Cow`, `Pin`) peeled
19//! silently
20//! - External types via [`EmitConfig::external_types`]
21//! - `#[serde(flatten)]` on a struct field (or an enum struct-variant
22//! field), emitted as a TS intersection: `StepMeta & { program: string }`
23//! - The full rename family, each on the axis serde gives it: `rename_all`
24//! (a container's members), `rename_all_fields` (an enum's struct-variant
25//! fields), `rename_all` on a variant (that variant's fields), `rename`
26//!
27//! See `docs/tasks/OF-015-productionize-typescript-generation.md` for the
28//! full design pass.
29//!
30//! # PR series state (PR 4 of 8)
31//!
32//! PR 1-3 landed the crate scaffold, per-type emission, serde rename
33//! family, type-pool walker, use-resolution, external-types table, and
34//! topological ordering. PR 4 wires them together: the top-level [`emit`]
35//! function now composes collection → name resolution → collision
36//! detection → topological ordering → per-type emission → error
37//! aggregation, all in one pass. The `#[ts_opaque(target = "...")]` and
38//! `#[ts_name = "..."]` proc-macro attrs (shipped in `ontogen-macros`)
39//! are read here to short-circuit emission for opaque types and override
40//! TS names. External-types lookup is wired into `emit_type`'s
41//! fall-through so types like `chrono::DateTime` resolve to `string`
42//! per the shipped defaults.
43//!
44//! PR 5 wires `ontogen` itself to call [`emit`] instead of the side-car
45//! emitter.
46
47mod attr;
48mod emit;
49mod external;
50mod order;
51mod pool;
52mod rename;
53mod resolve;
54mod types;
55
56pub use emit::{emit, emit_with_imports, render_type, render_type_str};
57pub use pool::{LOCAL_CRATE_ROOT, ScanError, scan_crate_root_with_imports, scan_src_dir, scan_src_dir_with_imports};
58pub use resolve::{ModuleImports, Resolution, resolve_reference};
59pub use types::{BigIntBehavior, EmitConfig, EmitError, QuoteStyle, RenameAll, TypePath, TypePathError};