rkyv_js_codegen/lib.rs
1//! # rkyv-js-codegen
2//!
3//! TypeScript codec-binding generator for [rkyv](https://rkyv.org) types, targeting the `rkyv-js` runtime.
4//!
5//! The generator parses Rust sources with `syn`,
6//! extracts every type marked with `#[derive(Archive)]` (or a custom marker),
7//! and emits one `export const Archived{Name} = ...` codec per type.
8//!
9//! TypeScript types are always derived from the codecs via `r.Infer<typeof Archived{Name}>`.
10//!
11//! ## build.rs
12//!
13//! ```no_run
14//! use rkyv_js_codegen::CodeGenerator;
15//!
16//! fn main() -> Result<(), rkyv_js_codegen::Error> {
17//! CodeGenerator::new()
18//! .add_source_file("src/lib.rs")?
19//! .write_to_file("generated/bindings.ts")?;
20//!
21//! println!("cargo:rerun-if-changed=src/lib.rs");
22//! Ok(())
23//! }
24//! ```
25//!
26//! ## Source extraction
27//!
28//! [`add_source_file`](CodeGenerator::add_source_file),
29//! [`add_source_dir`](CodeGenerator::add_source_dir) (recursive), and
30//! [`add_source_str`](CodeGenerator::add_source_str) all extract every type carrying the marker derive.
31//! `use` imports are resolved to fully-qualified paths — aliases and globs included —
32//! so registry lookups never depend on local names:
33//!
34//! ```
35//! use rkyv_js_codegen::CodeGenerator;
36//!
37//! let mut generator = CodeGenerator::new();
38//! generator.add_source_str(r#"
39//! use rkyv::Archive;
40//!
41//! #[derive(Archive)]
42//! pub struct Point { pub x: f64, pub y: f64 }
43//! "#)?;
44//!
45//! assert_eq!(generator.archived_name_of("Point").as_deref(), Some("ArchivedPoint"));
46//! # Ok::<(), rkyv_js_codegen::Error>(())
47//! ```
48//!
49//! `#[derive(Archive)]` must be resolvable — through `use rkyv::Archive`, an
50//! alias, a `use rkyv::*` glob, or an extra marker registered with
51//! [`add_marker_path`](CodeGenerator::add_marker_path).
52//!
53//! ## Output options
54//!
55//! | Method | Effect |
56//! |--------|--------|
57//! | [`set_header`](CodeGenerator::set_header) | Replace the generated file's header comment |
58//! | [`set_archived_name`](CodeGenerator::set_archived_name) | Override an export name, matching `#[rkyv(archived = Name)]` |
59//! | [`set_direction`](CodeGenerator::set_direction) | Emit full, decode-only, or encode-only bindings |
60//! | [`set_format`](CodeGenerator::set_format) | Target a non-default rkyv wire format |
61//! | [`set_jit`](CodeGenerator::set_jit) | Wrap every export in the direction-matched `rkyv-js/jit` compile function |
62//! | [`allow_typescript_syntax`](CodeGenerator::allow_typescript_syntax) | Drop `export type` lines, emitting plain JavaScript |
63//! | [`on_unknown_type`](CodeGenerator::on_unknown_type) | Fail, or warn and omit, on unmappable types |
64//!
65//! ```
66//! use rkyv_js_codegen::{CodeGenerator, Direction};
67//!
68//! let mut generator = CodeGenerator::new();
69//! generator
70//! .set_direction(Direction::Decode) // imports become `rkyv-js/decode`
71//! .set_format("big", 64, true) // mirrors rkyv's feature flags
72//! .allow_typescript_syntax(false);
73//! ```
74//!
75//! [`Direction`] rewrites only the `rkyv-js` import specifiers.
76//!
77//! Factory names and type exports are unchanged, and modules registered through
78//! [`register_external`](CodeGenerator::register_external) are left alone,
79//! so one schema can produce direction-matched bundles for a browser client and a Rust-facing service.
80//!
81//! Emission is deterministic: dependency-ordered, alphabetical within ties, so generated files diff cleanly.
82//!
83//! ## Expressions instead of format strings
84//!
85//! Codec expressions are a typed tree ([`CodecExpr`]) with builders that mirror the runtime combinators ([`codec`]):
86//!
87//! ```
88//! use rkyv_js_codegen::{CodeGenerator, codec};
89//!
90//! let mut generator = CodeGenerator::new();
91//! generator.add_struct("Person", [
92//! ("name", codec::string()),
93//! ("age", codec::u32()),
94//! ("email", codec::option(codec::string())),
95//! ]);
96//! let code = generator.generate()?;
97//! assert!(code.contains("email: r.option(r.string),"));
98//! # Ok::<(), rkyv_js_codegen::Error>(())
99//! ```
100//!
101//! ## Extending the registry
102//!
103//! External crate types are registered by fully-qualified Rust path:
104//!
105//! ```
106//! use rkyv_js_codegen::{CodeGenerator, CodecExpr, ExternalType, WithWrapper};
107//!
108//! let mut generator = CodeGenerator::new();
109//!
110//! // `my_crate::MyVec<T>` → `myVec(T)` from a custom module.
111//! generator.register_external(
112//! "my_crate::MyVec",
113//! ExternalType::generic1(|t| {
114//! CodecExpr::call(CodecExpr::import_from("my-package/codecs", "myVec"), [t])
115//! }),
116//! );
117//!
118//! // `#[rkyv(with = AsJson)]` fields → a hand-written codec.
119//! generator.register_with(
120//! "AsJson",
121//! WithWrapper::replace(CodecExpr::import_from("./custom.ts", "asJson")),
122//! );
123//! ```
124//!
125//! ## Error handling
126//!
127//! Parse failures surface immediately from `add_source_*`; everything else is validated in [`CodeGenerator::generate`],
128//! which aggregates all [`Diagnostic`]s into a single [`Error::Codegen`].
129//!
130//! Set [`OnUnknown::SkipContainingType`] to emit `cargo:warning`s and omit affected types instead of failing.
131
132mod error;
133mod expr;
134mod extractor;
135mod generator;
136mod registry;
137
138pub use error::{Diagnostic, DiagnosticKind, Error, SourceLocation};
139pub use expr::{CodecExpr, Import, codec, generate_import_block};
140pub use generator::{CodeGenerator, Direction, EnumVariant, OnUnknown};
141pub use registry::{ExternalType, WithWrapper};