2.0.0-rc.2 - New datamodel, who dis?

Specta v2

I have been really happy with Specta v1 but as with everything in life hindsight is 20/20 and so work on a major refactor of Specta's internals has already begun.

One of my biggest goals of Specta v2 is for it to be the last major release. Well actually as close to it as humanly possible. I really want Specta to be able to develop a stable ecosystem similar to other Rust crates such as Serde and frequent major releases discourage downstream crates from adopting Specta support directly and generally make for a horrible DX cause mismatched majors can cause really hard to understand trait errors.

If you're not using a framework with Specta (rspc, tauri-specta) you should be fine to upgrade if you would like to try out the new improvements. This release is "production ready" but it is not shielded from breaking changes so be aware of that. Major changes are going to happen in the next release but they won't affect many of the "public" API's for people using Specta directly. Release notes will also exist to help you upgrade if you do choose to adopt this RC.

WARNING: This release is stable but you must lock its version (Eg. specta = "=2.0.0-rc.2" in your Cargo.toml) because more breaking changes are going to be coming in future release candidates.

As always thanks to @Brendonovich who did a lot of work to aid with typed-error handling which is coming to rspc and tauri-specta very soon!

DataType remodeling

Specta internally works on what we like to call the "DataType system".

This entire system revolves around this massive enum which holds all of the possible types. Specta's Type macro will pass your Rust type and convert it into a DataType and then you can apply any exporter which is able to pass the DataModel format and convert it a string of another programming language.

At its core this is how Specta works but here in lies the limitations with the existing design. The original "DataType system" was designed to be Typescript and Serde-centric. This made it really easy to build the initial version of Specta but it is making is really hard to properly support other language exporters. Specta v2 is going to launch with a completely Rust-centric system. The system will describe your Rust type as is, and provide extra metadata about how Serde sees your type. It will then be completely up to the exporter to interpret this data, validate it, and export the type. This will make implementing other exporters significantly easier and will also allow using Specta with non-Serde formats as the Serde validation will be optional.

This release includes the first part of this remodelling but much more is still to come. All changes to the types in the datatype module are not documented as there was enough of them that it was not worth it. Most users of Specta do not directly touch this system so they will be shielded from breaking changes but if you need assistance upgrading please jump in the Discord and I can give you a hand.

This refactor has led to dropping Result from the return type of Type::* methods as the checking is now done in a Serde post-processing step. Many structs have also moved to private fields and providing accessor methods to make internal API changes possible without breaking the public API. This will help with reducing the need for a Specta's v3 once v2 launches.

New features

• Added specta::selection (has been moved here from rspc)
• Add formatter support to ExportConfiguration with builtin support for Prettier and ESLint
• Doc comment exporting issue - #97
• Support destructuring in function arguments Eg. fn demo(Demo { demo }: Demo) {}
• Fix handling of struct A (null) vs struct B () ([]) and struct C {} ({}) - #88
• Remove unnecessary generics brackets in TS. Eg. type Demo<> = ... is now type Demo = ... - #88

Added support for new crates:

• either
• serde_yaml
• toml

Fixed bugs

• Exporting maps with non-string/number keys will now error
• Significantly stricter checking of valid types - Internally tagged enums will fail to export if they could present as a Serde runtime error.
• Fix handling of #[repr(transparent)]
• Completely refactoring the SpectaID system. SpectaIDs are now ordered by type name but default and are os-agnostic. The lack of these has caused endless bugs.

Breaking changes

• Rename collect_types to collect_functions
• Implemented Type for Result - This does break a lotta frameworks built on Specta (Eg. rspc and tauri-specta)
• #[specta(remote = "Type")] is now #[specta(remote = Type)] and supports paths such as #[specta(remote = crate::Type)]
• Remove SpectaFunctionArg & SpectaFunctionResult from public API
• Change fn_datatype!(type_map, fn_name) to fn_datatype!(type_map; fn_name)
• Rename export_datatype to export_named_datatype cause it's misleading. Its differentiation with datatype was confusing.
• Many occurrences of &'static str in the public API have been moved to Cow<'static, str> to increase flexibility
• #[specta(crate = "todo")] is now #[specta(crate = todo)]
• Removed ts::RESERVED_IDENTS from public API
• Drop old specta::RspcType internal API. rspc::Type is deprecated in v1.x.x in favor of using specta::Type directly. If this affects you, what da hell were you doing?
• Remove the already deprecated rename_to_value attribute from Type macro. Use rename_from_path instead
• Make export::TYPE_MAP internal and use accessor functions instead.
• Add SID and IMPL_LOCATION as constants to the NameDataType trait
• Rename SpectaSID to SpectaID

To be transparent this is not everything, most of the changes to the "DataType system" are not documented because they will affect very few people, and those people can reach out and I would be happy to aid them with the upgrade.

New Contributors

• @0HyperCube made their first contribution in #97

Full Changelog: v1.0.5...v2.0.0-rc.2