2.0.0-rc.4 - Minor fixes

This release has some small improvements that were blocking the v2.0.0-rc.1 release of Tauri Specta.

Fixes:

• Generate BigInt type as bigint - #151

Features:

• Introduce js_doc:: Builder helper for efficiently constructing JS doc comments.

Breaking Changes:

• js_doc::format_comment was renamed to js_doc::typedef_named_datatype

Thanks, @avinassh and @Brendonovich for contributing to this release!

2.0.0-rc.3 - A bag of improvements

Features:

• Helpers for JSDoc comment exporting (still undocumented and untested)
• Support for (T,) tuples. Turns out (T) and (T,) are completely different types.

Important Breaking Changes:

• Drop typescript as a default feature. You will now need to go specta = { version = "...", features = ["typescript"] } to use the specta::ts and specta::export::ts modules.

Other Breaking Changes:

• Drop serde as default feature. It's now temporarily under typescript. I would recommend adding it manually if your using Specta with Serde as I will likely drop this in the future for now Specta's Typescript exporter is not ready for it to be dropped.
• Rename conf to cfg on ExportContext
• Rename TsExportError to ExportError
• Drop thiserror feature, it was a no-op anyway. You can use Specta fine with thiserror but it doesn't require us to do stuff.
• Move specta::ts::js_doc to specta::ts::comments::js_doc. This was just a mistake.
• Remove Into<TupleType> for T where T: DataTypeFrom. You can use Into<DataType> for T instead.
• EnumVariant was renamed to EnumVariants and EnumVariant is now a wrapper struct with shared metadata about the variant such as skip , comments or deprecated.
• NamedDataType.comments is now NamedDataType.docs and is now Cow<'static, str> instead of Vec<Cow<'static, str>>.
• CommentFormatterFn now takes CommentFormatterArgs as an argument to allow handling deprecated attributes.
• Breaking changes to SpectaFunction's argument to handle deprecated exporting although this type shouldn't be used for anything publically

Fixes:

• Fix a heap of incorrectly handled cases when using serde(skip).
  • Attribute was ignored on unnamed field of enum variants.
  • Move skip handling from the macro into the exporter. A(String) and A(#[serde(skip] (), String) are different types in TS (string and [string] respectively) and the exporter needs to know that.
• Drop dependency on document-features and indoc to make builds slightly quicker and fix issues while vendoring Specta
• Fix pub struct A((String)) or pub enum A { A((String)) } causing the macro to error out.
• Reject invalid names when doing #[specta(rename = "name")] on a container (struct or enum). Eg. names containing @
• Fix #[specta(rename = "@demo") not working due to an issue with the way the macro processed strings for the rename attribute.
• Fix the combination of #[specta(inline, transparent)] on a struct that also has #[specta(optional)] on the single field. It would previously act as if #[specta(optional)] was not applied.

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

1.0.5 - Minor fixes

Changes:

• Support url crate - #84
• Fix incorrect std::time::{SystemTime, Instant, Duration} definitions - #77
• Lazily export standard library types due to SystemTime containing a bigint number - explaination
• Do prettier looking escaping - #71

Thanks, @tonymushah for contributing!

1.0.4 - Fix `specta::specta` macro

Changes:

• Better serde optional handling - #69
• Fix specta::specta handling of functions with mut arguments. - specta-rs/tauri-specta#24

Thanks @Brendonovich for his PR on better serde optional handling and @probablykasper for reporting the issue with handling of function args.

Important Note

Previously destructuring in function arguments would compile but as of this release, it will not.

#[derive(Type)]
pub struct Group {
     name: String
}

// This will be a compile error now and would previously emit invalid Typescript.
#[command]
#[specta::specta]
pub async fn new_group(Group { name }: Group) {}

Due to the previous behavior previously causing invalid Typescript to be emitted, I don't view this as a breaking change. This will hopefully be properly fixed in a future update but it will likely require some breaking changes.

1.0.3 - Squashing Bugs

Fixes:

• fixes #65 - enum as the key of an object
• fixes #66 - invalid array type escaping
• fixes #60 - nesting of options

New Features:

• Support Range and RangeInclusive - #66
• Support tailing comma in collect_types - #63
• Support Cow<'static, str> support for DataTypeFrom

Thanks @Brendonovich, @Ziothh, @stephen-h-d for reporting the bugs and thanks @Vlad-Shcherbina for the PR!

v1.0.2

Changes:

• Remove rename_from_expr from the previous release - Publishing this in v1.0.1 was a mistake

Features:

• Add rename_from_path. This is an advanced API targetted at being used within the include/select macros within Prisma Client Rust

v1.0.1

A handful of minor fixes.

Features:

• Export comments for functions
• Store whether a function is async or not - 2408c61

Fixes:

• Fix sanitiser incorrectly double quoting - #56
• Fix reserved keyword sanitiser to loosen unnecessary restrictions - #51
• Fix incorrect handling of #[serde(transparent)]

v1.0.0

A much-anticipated release for Specta coming with a major internal refactor and huge improvements to type safety and error handling.

This release is a v1.0.0 to ensure Specta follows the semantic versioning standard set forth by Cargo. The internal API is not currently stable as it will likely undergo major changes in future releases to support the exporting of types into languages other than Typescript.

Below are some of the major changes for this release:

Overhaul error handling

The main external change of this release is a significant improvement in error handling across the board. A major refactor of the Type macro has taken place to ensure the errors are significantly more helpful.

For example, these are some of the new errors you may come across when using Specta:

error: specta: found string literal containing an unsupported inflection
 --> tests/macro/compile_error.rs:7:22
  |
7 | #[serde(rename_all = "camelCase123")]
  |                      ^^^^^^^^^^^^^^

error: specta: trait objects are not currently supported.
  --> tests/macro/compile_error.rs:13:34
   |
13 |     pub(crate) cause: Option<Box<dyn std::error::Error + Send + Sync>>,
   |                                  ^^^

error: specta: Found unsupported container attribute 'noshot'
  --> tests/macro/compile_error.rs:75:10
   |
75 | #[specta(noshot = true)]
   |          ^^^^^^

error: specta: Found unsupported container attribute 'noshot'
  --> tests/macro/compile_error.rs:79:10
   |
79 | #[specta(noshot)]
   |          ^^^^^^

error: specta: Found unsupported field attribute 'noshot'
  --> tests/macro/compile_error.rs:84:14
   |
84 |     #[specta(noshot = true)]
   |              ^^^^^^

error: specta: Found unsupported field attribute 'noshot'
  --> tests/macro/compile_error.rs:90:14
   |
90 |     #[specta(noshot)]
   |              ^^^^^^

The Typescript exporter has already been redesigned to use statically typed errors. This change means all of the functions which previously returned Result<String, String>, now return Result<String, TsExportError>

Strict BigInt handling

Previously Specta would export the Rust types isize, usize, i64, u64, i128, u128 as a Typescript BigInt. This however is problematic when used for web backends. JSON.parse will truncate BigInt types when deserializing your JSON on the frontend leading to unintentional bugs.

With this release exporting a BigInt type by default will result in an error. If you would like to export them, you can control the behavior using ExportConfiguration and BigIntExportBehavior (example). This also allows library authors building on top of Specta to set the capabilities of their IPC bus, so you can prevent mistakes from making it into production!

Drop OpenAPI support

The existing OpenAPI support was half-baked and should have never been released. With future improvements, it will be rereleased once the handling of generic types has been worked out. If you were using this feature please open a GH discussion or send a message on Discord and we can work on getting a beta version of it supported for your use case.

Major internal refactors

I am going to spare the exact details but anything manually working with Type (the trait not macro) or anything in the datatype module will likely require changes. This will mainly affect library authors using Specta. These changes make it impossible to represent many invalid types that could previously be constructed. This allowed for removing many runtime errors and significantly improved the readability of the Specta codebase!

Huge thanks to @Brendonovich for his help on a lot of this work!

Do open an issue on GitHub or ask a question in Discord if you are having problems upgrading your code!