wasm-bindgen 0.2.130

on Rust Cargo

Added

• A borrowed number, bool, char or borrowed string crosses by copy, so
  &f64, &Option<T>, &Nullable<T>, Option<&f64> and
  Option<&Nullable<T>> are argument types, and an
  experimental_generic_mono import taking &T accepts T = f64,
  Option<f64> or Nullable<String>, as std's contains(&T) does.
  #5436

• Added a rejection type parameter to js_sys::Promise<T, E = JsValue>,
  mirrored on JsFuture<T, E>, PromiseState<T, E> and
  PromiseWithResolvers<T, E>. Awaiting a Promise<T, E> yields
  Result<T, E>, converting the rejection reason as an E the same unchecked
  way the fulfilled value is converted as a T. Both parameters are covariant
  under Upcast; catch, then_with_reject and the withResolvers reject
  function receive an E; all_tuple / all_settled_tuple carry a shared E
  through; and under js_sys_unstable_apis, Promise::new, Promise::reject
  and Promise::any are typed on the rejection too, any as
  AggregateError. The default keeps existing Promise<T> code unchanged.
  PromiseWithResolvers<T, E> is invariant in both, since its resolve and
  reject functions take them, and JsFuture<T, E> is UnwindSafe whenever
  T and E are.
  #5426

• Added the --js-string-builtins CLI flag, importing static_string
  constants as JS String Builtins
  string constants from wasm:js/string-constants instead of defining them in
  the JS glue. With reference types, static_string constants now occupy
  fixed externref table slots filled in when the module is instantiated, so
  cloning and dropping them is free and never calls into JS.
  #5401

• Added Nullable<T>, re-exported as js_sys::Nullable, for a T | null
  value at the JS boundary, as Option<T> is for T | undefined, with
  Option<Nullable<T>> for T | null | undefined. Both are accepted wherever
  Option<T> is, for every T and in every position: JS null is
  Nullable::Null and is sent back as null, while undefined into a plain
  Nullable<T> goes to T's own conversion. A plain Option<T> still reads
  both undefined and null as None and writes None as undefined; the
  Option layer of Option<Nullable<T>> treats only undefined as None,
  since null has to reach the Nullable layer. Option<T> converts from
  and into Nullable<T>, and
  JsNullable<T> converts from both and into Option<Nullable<T>> for
  T: JsGeneric.
  The API follows Option's, including ok_or, and_then, filter,
  as_deref, take, replace and IntoIterator, and
  --cfg wasm_bindgen_unstable_try_trait enables ? on nightly.
  NullableIntoWasmAbi / NullableFromWasmAbi carry Nullable<T>'s null
  for every T, and are supertraits of JsStringLike and the js-sys
  primitive-union markers, so Nullable<impl JsStringLike> and
  Nullable<impl JsNumberOrStringLike> work under experimental_generic_mono,
  and Nullable<T> erases like Option<T> on a generic import.
  #5410
  #5423

• Nullable<T> converts into JsValue with From, Null becoming null
  as None becomes undefined for Option<T>, and Option<T>,
  Nullable<T> and Result<T, E> are Promising for any T: Promising,
  so a Promise<Nullable<JsString>> awaits to a Nullable<JsString>.
  String and &str upcast to JsValue, and String to itself, so a
  Promise<String> from an experimental_generic_mono import is JsGeneric
  and upcasts to Promise<JsValue> as Promise<bool> does. Together these
  make a Promise<Nullable<JsString>> or Promise<String> from a mono
  import usable wherever a promise is expected. &str and String upcast to
  each other, so an Array<&str> inferred from borrowed arguments settles to
  Array<String>. Option<T> and Nullable<T> upcast to JsValue whenever
  T does, so a Promise<Option<String>> relabels to Promise<JsValue>, and
  Undefined and Null upcast to Option<T> and Null to Nullable<T>, so a
  Function<fn(A) -> R> stands in for a Function<fn(A, Option<B>) -> R>.
  Every Rust and JS carrier wraps into Option<Target> and Nullable<Target>
  whenever it upcasts to Target, and Nullable<T> upcasts to Option<T>,
  so an Array<JsString> relabels to Array<Option<JsString>> or
  Array<Option<Nullable<JsString>>>, and a Function<fn(Option<T>) -> R>
  stands in for a Function<fn(T) -> R>.
  #5427
  #5437

• Added MaybeIntoWasmAbi / MaybeFromWasmAbi, the ABI of Option<T> for
  every T, with an associated MaybeAbi that lets a type without a spare
  value in its own ABI, such as i32 or f64, pick a wider one. Option<T>
  converts through it, and a blanket impl provides it for every
  OptionIntoWasmAbi / OptionFromWasmAbi type, so existing impls and bounds
  are unaffected. NullableIntoWasmAbi / NullableFromWasmAbi extend it with
  null. As a result, Option<impl JsNumberOrStringLike> and the other
  primitive-union bounds now work in experimental_generic_mono imports
  without a where Option<T>: IntoWasmAbi clause.
  #5423

• Under js_sys_unstable_apis, RegExp::exec and JsString::match_ return
  Nullable<T> rather than Option<T>, as the JS APIs return null on no
  match.
  #5410

• Added the slice = view | copy | array and vec = copy | array
  attributes for imported JS functions, choosing what JS receives for a
  sequence argument with numeric elements: a live typed array over wasm
  memory, a fresh typed array, or a fresh plain Array. slice applies to
  borrowed slices (&[T], Option<&[T]>, Clamped<&[u8]>) and vec to
  owned ones (Vec<T>, Box<[T]>, Option<Vec<T>>, Clamped<Vec<u8>>).
  Each key is accepted per argument, per function and per extern "C" block,
  with a more specific level overriding a broader one. Inherited from a
  function or block, a key only affects arguments of its own shape; written
  on an argument it doesn't fit, it is an error. A generic element type
  resolves the mode per instantiation under experimental_generic_mono,
  where Option<&[T]> is now supported too. Neither key is accepted on
  exported functions.
  #5384

• Borrowed slices of String, &str, bool, char and exported enums
  (&[T] and Option<&[T]>) can be passed to imported JS functions,
  arriving as a fresh Array.
  #5384

• Slices of every JsStringLike shape, including &String, &Box<str>,
  &Cow<str> and &JsString, can be passed to imported JS functions, and
  JsStringLike alone bounds a &[T] argument of an
  experimental_generic_mono import.
  #5384

• Owned vectors (Vec<T>, Box<[T]>, Option<Vec<T>>) of bool, char
  and string enums can be passed to and from JS, and Vec<&str> can be
  passed to JS.
  #5384

• String enums implement TryFromJsValue, accepting only their listed values,
  so they can be used as dynamic-union variant payloads.
  #5376

• Added JsValue::from_utf8_lossy to create a JS string directly from a
  &[u8], decoding on the JS side with replacement characters for invalid
  UTF-8 instead of requiring a String::from_utf8_lossy allocation first.
  #5370

• Documented in the guide that passing an exported Rust type by value moves it
  out of the JavaScript object, which throws on any later use.
  #5354

• Added Rolldown compatibility to the deployment docs in the guide.
  #5355

• Added source property to ToggleEvent.
  #5353

• Added 11 experimental js-sys marker traits for every union of two or more
  of the TypeScript bigint, boolean, number, and string primitive
  categories. Traits such as JsNumberOrStringLike can bound
  experimental_generic_mono import parameters while preserving each concrete
  Rust type's native ABI representation. String-containing unions accept every
  wasm_bindgen::JsStringLike type.
  #5341

• Added the experimental js_sys::PropertyKey marker trait for the
  string | number | symbol keys accepted by TypeScript's Record type.
  JsNumberOrStringLike widens to PropertyKey.
  #5341

• JsStringLike and the js-sys string primitive-union traits now accept
  &String, &Box<str> and &Cow<str>. These shapes, and Option of each,
  also work as plain import argument types.
  #5374

• Added support for threads on memory64 (wasm64-unknown-unknown with
  +atomics). On memory64, __wbindgen_thread_destroy takes JS numbers.
  #5378

• Added js-sys bindings for the modern ECMAScript builtins that were still
  missing: the Iterator helpers (Iterator.from as from_iterable,
  Iterator.concat, map,
  filter, take, drop, flatMap, reduce, toArray, forEach, some,
  every, find), Map / WeakMap getOrInsert and getOrInsertComputed,
  Object.groupBy and Map.groupBy, Promise.try and
  Promise.withResolvers (with a PromiseWithResolvers<T> type), explicit
  resource management (DisposableStack, AsyncDisposableStack,
  SuppressedError, Symbol.dispose, Symbol.asyncDispose), Uint8Array
  base64 and hex conversion (fromBase64, fromHex, toBase64, toHex,
  setFromBase64, setFromHex, with Base64Options, its Base64Alphabet
  and Base64LastChunkHandling enums and a SetFromResult type), Error.isError, Math.sumPrecise, Math.f16round,
  RegExp.escape and the dotAll, hasIndices and unicodeSets flag
  getters, String.prototype.isWellFormed and toWellFormed,
  Symbol.prototype.description, JSON.rawJSON and JSON.isRawJSON, and
  the typed array toReversed, toSorted, with, findLast,
  findLastIndex, includes and indexOf methods. From ECMA-402, the
  Intl.Locale firstDayOfWeek and variants getters. From the WebAssembly
  JS API, WebAssembly.JSTag, the compile-options variants of validate,
  compile, compileStreaming, instantiate, instantiateStreaming and
  the Module constructor (taking a CompileOptions dictionary, with an
  InstantiatedSource result type),
  Memory toResizableBuffer and toFixedLengthBuffer, Global.valueOf
  and Exception.stack.
  #5403
  #5421

Changed

• Reworked the js_sys::Temporal bindings and Date::to_temporal_instant,
  which stay behind js_sys_unstable_apis and now also need the new temporal
  feature, against the final Stage 4
  specification and reshaped them to the web-sys conventions. Inputs are
  typed: *Like dictionaries such as PlainDateLike for from, calendar-free
  *Fields dictionaries for with, and the bare form of a method takes the
  type its argument converts to (&str time zones and calendars, &PlainTime,
  &Duration, &Self for until/since/equals), while every other member
  of a specification union gets a _with_<type> variant, so
  with_calendar_with_plain_date, add_with_duration_like, add_with_str,
  equals_with_zoned_date_time, with_plain_time_with_str,
  PlainYearMonth::from_with_plain_date and the typed relativeTo, calendar,
  timeZone and plainTime dictionary setters all exist; compare keeps
  taking &Self only. Optional arguments expand to the plain method plus
  _with_options/_and_options, to_locale_string takes no locale, a
  _with_str/_with_str_sequence one or an Option<&str> with options, and round,
  total and get_time_zone_transition take their options dictionary, with
  round_with_unit, total_with_unit and
  get_time_zone_transition_with_direction shortcuts. The option dictionaries
  are OverflowOptions, DifferenceOptions, RoundToOptions::new(unit),
  DurationTotalOptions::new(unit), TimeZoneTransitionOptions::new(direction)
  and friends, the enums drop their Temporal prefix (Overflow, Unit,
  LargestUnit, TransitionDirection, …). Bindings for the removed
  toPlainYearMonth/toPlainMonthDay on PlainDateTime and ZonedDateTime,
  ZonedDateTime::with_plain_date and PlainTime::to_plain_date_time are gone,
  offset_nanoseconds returns f64, era, era_year, week_of_year and
  year_of_week return Options, fractionalSecondDigits is a u8,
  get_time_zone_transition returns Nullable<ZonedDateTime>,
  to_js_string_with_options and to_locale_string are fallible, constructors
  expand their optional trailing fields (PlainTime::new(), new_with_hour, …,
  PlainDate::new_with_calendar), and catch follows the specification:
  equals, compare, the typed from forms (except PlainYearMonth's date
  conversions, which can leave the range) and the option-less
  Instant/PlainTime arithmetic are infallible, while
  ZonedDateTime::start_of_day, hours_in_day and
  PlainDate::to_plain_year_month are fallible. Fallible bindings return
  Result<T, RangeError>, or Result<T, Error> where a property bag, a
  relativeTo/plainTime union or Intl options can also throw a TypeError. PartialEq/Eq on the
  date-time types compare by the spec equals(), and Instant and PlainTime
  are Ord through compare().
  #5402

• The js-sys JsFunction* traits' associated types (Ret, ArgN, BindN)
  no longer carry a JsGeneric bound, so a Function<fn(..)> signature may
  name a converted carrier such as Nullable<JsString>, and
  Function::from_closure accepts a closure with converted arguments. Generic
  code over these traits that calls call* or bind* now needs the bound
  itself, as where F::Ret: JsGeneric, F::Arg1: JsGeneric. The hidden
  PromiseTuple trait's Joined and Settled likewise drop it, its
  Rust-tuple impl packing the promise handles directly rather than upcasting
  each, and the
  JsGeneric bounds that only existed to satisfy a Function<fn(..)> slot
  or to tag a type argument are gone: Promising for Promise<T, E>,
  Promise::new_typed, the PromiseWithResolvers resolve/reject
  getters, the PropertyDescriptor get/set accessors, WeakMap::new and
  the entries/from_entries family of Array, Set, Map and Object.
  #5427

• Option<T>: TryFromJsValue now reads null as None, as the Option<T>
  ABI does, so Option::<JsValue>::try_from_js_value(JsValue::NULL) is
  None where it was Some(null). A T that accepts null as a distinct
  value space sets the new TryFromJsValue::NULLABLE const, as
  Nullable<T> does, and an Option of it passes null through, so
  Option<Nullable<T>> reads it as Some(Nullable::Null). Nullable<T>
  itself converts from a JsValue with TryFromJsValue.
  #5427

• With reference types, static_string constants and the reserved
  undefined, null, true and false values are stored at fixed slots of
  the externref table, which is now sized to include them, and cloning or
  dropping them no longer allocates or calls into JS. The per-string JS import
  function is no longer emitted.
  #5401

• Breaking (experimental): experimental_generic_mono imports no longer add
  hidden ABI bounds to the generated wrapper. The conversion bounds each
  position needs are now declared on the import like any other bound:
  T: IntoWasmAbi for an argument, T: RefIntoWasmAbi (a new trait in
  wasm_bindgen::convert) for a &T argument, T: VectorRefIntoWasmAbi for a
  &[T] or Option<&[T]> argument, T: FromWasmAbi for a return
  (+ 'static when async), A: FromWasmAbi for a callback argument and
  R: IntoWasmAbi for a callback return. A missing bound is reported at the
  position that needs it.
  #5385

• The generated TextDecoder no longer sets fatal: true. Rust &str is
  always valid UTF-8, so this only removes a redundant check and lets
  JsValue::from_str and JsValue::from_utf8_lossy share a single decoder.
  #5370

• Replaced the once_cell dependency with core::cell::LazyCell, which is
  available now that the library MSRV is 1.81.
  #5359

• Under js_sys_unstable_apis, the unsuffixed Object::define_property,
  Object::from_entries, Object::get_own_property_descriptor,
  Object::has_own, Object::property_is_enumerable,
  Reflect::define_property, Reflect::delete_property, Reflect::get,
  Reflect::get_own_property_descriptor, Reflect::has, and Reflect::set
  now take a generic K: PropertyKey key, accepting string, number, or symbol
  keys. Object::get_own_property_descriptor and
  Reflect::get_own_property_descriptor now return
  Option<PropertyDescriptor<T>>, and Reflect::has now takes an
  &Object<T> target. Callers passing &"key".into() should pass "key" (or
  another concrete key type) instead.
  #5341

• wasm-bindgen-test no longer depends on async-trait. Its benchmark code
  now uses native async fn in traits.
  #5365

• Escape string inputs in debugString.
  #5366

• #[wasm_bindgen] now warns when a function sets more than one of this,
  getter, setter, indexing_getter, indexing_setter and
  indexing_deleter. Only one of them takes effect, and the others used to be
  ignored silently. Conflicting options will be an error in the next major
  version.
  #4272
  #5369

• &[T], Vec<T>, Box<[T]>, Option<Vec<T>> and Option<Box<[T]>>
  arguments with a number element type are now declared in TypeScript and
  JSDoc as the typed array or a plain array (e.g. Uint8Array | number[], or
  BigInt64Array | bigint[] for 64-bit elements), matching what the generated
  JS already accepts. Read-write struct fields of these types are declared as
  a getter and setter pair. &mut [T] arguments still take only a typed
  array, since the results are copied back into its buffer, and so do
  Clamped arguments, since numbers in a plain array would wrap around
  instead of being clamped.
  #4504

• Numeric enums are passed between JS and Rust as an f64, so a value from
  JS that isn't one of the enum's values, such as 'abc', NaN, 1.5 or
  2 ** 32, throws "invalid enum value passed" in release builds too,
  rather than becoming variant 0 or being truncated. Conversions from
  JsValue likewise reject NaN and fractions. Values above
  i32::MAX in a #[repr(u32)] enum are now returned to JS unchanged
  rather than as negative numbers.
  #5384

• A Vec<T> of a numeric enum passed from JS checks each element as a
  single enum value, so a wrong element throws the same error a single
  argument would, rather than "array contains a value of the wrong type".
  #5384

Fixed

• Upcast::upcast and upcast_into no longer let a safe UpcastFrom impl
  extend a borrow's lifetime: ErasableGeneric::Repr now keeps the real
  lifetime of a reference, slice, &str, closure reference or
  ScopedClosure instead of 'static, so the Repr-equality bound rejects
  such an upcast. A generic import likewise no longer accepts an owned
  ScopedClosure that borrows a non-'static value, which handed JS a
  closure over freed data; borrowed arguments, and owned ones that only
  contain a borrow, still accept any lifetime.
  #5178

• Concurrent calls to the web and no-modules init function no longer
  instantiate the module more than once; later calls share the in-flight
  initialization and resolve to the same instance.
  #5429

• js_sys::Promise::catch_map's handler now receives the rejection reason,
  typed as the promise's E, instead of the reason mislabelled as the
  fulfilled type T. A handler on a Promise<Foo> written as |v: Foo| must
  take JsValue; it was never a Foo.
  #5426

• Large JS snippets (module = "...", inline_js) and
  typescript_custom_section expressions such as include_str! no longer make
  compilation slow or print "constant evaluation is taking a long time"
  warnings. The macro now lays out the __wasm_bindgen_unstable custom section
  as a #[repr(C)] struct of byte arrays, so const evaluation copies each
  chunk at once instead of byte by byte. A crate with a 5 MB snippet went from
  64 s to under a second for cargo check; the section's bytes are unchanged.
  #5413

• Emscripten output now keeps a private class that is only created from
  Rust, such as one converted into a JsValue and passed to JS. Every
  generated function that references a class by name now lists it in its
  __deps. Previously emcc dropped the class, and calling into it failed with
  ReferenceError: <Class> is not defined.
  #5415

• Imported methods, static methods and constructors without a js_class now
  bind to the js_name and js_namespace of the type they belong to when that
  type is declared in the same extern "C" block. Previously they used the
  type's Rust name, so for example a constructor of
  #[wasm_bindgen(js_name = CustomName)] type Type; called new Type().
  #5391

• Lists passed from JS to Rust no longer leak memory when an element is
  rejected, such as a value of the wrong type in a Vec<String> or
  Vec<T> of exported structs, or an invalid value in a Vec<T> of a
  numeric enum.
  #5384

• An exported function or closure that rejects an argument from JS, such as
  an invalid numeric enum value or an exported struct that is still borrowed,
  no longer leaks its other arguments or leaves an exported object it borrowed,
  including self, permanently borrowed. Field setters, free() on a
  borrowed object, closures called after being dropped and FnOnce closures
  called twice also release what JS passed them. The same holds when the
  generated JS rejects an argument before calling Rust, such as an object of
  the wrong class or a number passed for a u64, after copying an earlier
  string or array into Wasm memory.
  #5388

• An exported function taking an Option<JsValue>, or without reference
  types an owned JsValue, no longer leaks an externref table or JS heap
  slot when Wasm rejects a later numeric argument, such as a number passed
  for a u64.
  #5404

• The test runner works again with WASM_BINDGEN_NO_DEBUG=1, so a test suite
  can run against the glue a release build gets. The tests are reached through
  the __wasm export, which only debug glue has had since #4879; the new
  Bindgen::export_wasm option exports it on its own.
  #5404

• An async export now converts its arguments when it is called, rather than
  when its future is first polled. A rejected argument rejects the returned
  promise, instead of throwing from the task queue, and an async method's
  self stays borrowed from the call on, so freeing the object before the
  future runs throws instead of leaving the method with a freed self.
  #5388

• Reference types are now detected from the runtime's externref intrinsics when
  the target_features section is missing, as with strip = true. Previously
  such builds skipped the externref transform, and #[wasm_bindgen(catch)]
  imports failed with externref table required for catch wrappers. A warning
  now recommends running wasm-opt on the wasm-bindgen output instead of
  strip = true.
  #5382

• String enums, numeric enums and dynamic unions with the same name in
  different modules of one crate are now handled like same-named items in
  different crates: two public definitions report that the name is exported
  multiple times, and private copies are numbered (Mode, Mode2, ...).
  Previously wasm-bindgen failed with dynamic union variant descriptor not found or duplicate enums.
  #5381

• private string enums and dynamic unions with the same name in different
  crates can now coexist, numbered like structs and numeric enums.
  #5381

• The TypeScript alias for a string enum that is only referenced through a
  dynamic union is now emitted.
  #5376

• Attributes on imported statics, such as doc comments, #[allow(...)],
  #[deprecated] and #[cfg(...)], are now applied to the generated static
  instead of being dropped.
  #5377

• Imported functions and statics from two different inline_js snippets no
  longer share one binding when they have the same name and signature. The
  snippet contents are now part of the generated shim name, so each import
  reads its own snippet's export.
  #3878

• Imported types with the same Rust name no longer share one instanceof
  check when their module, inline_js snippet, js_name or js_namespace
  differ. Imported static_string statics with the same name no longer share
  one string.
  #5352

• Imported functions with the same name and signature no longer share one
  binding when they differ in how JS is called: catch, variadic, final,
  slice_to_array, suspending, experimental_generic_mono, the method kind
  (constructor, static_method_of, getter, setter, indexing_*), or a
  js_name with characters that a shim name drops. Two
  experimental_generic_mono imports that differ only in one of these now
  both bind instead of failing the build.
  #5352

• debugString handles bigint values (e.g. 123n).
  #5356

• Fixed JSPI task pointers being truncated to 32 bits on wasm64.
  #5358

• Return pointers above 2 GiB on wasm32 (e.g. thread stacks allocated under
  +atomics) are no longer treated as negative offsets in the generated JS,
  which previously threw a RangeError on number and string conversions.
  #5360

• With --debug, passing a value that is not an object with a numeric
  length, such as an ArrayBuffer or a string, where Rust takes &[T],
  Vec<T>, Box<[T]> or Option<Vec<T>> now throws an error naming the
  expected and received types, instead of silently passing an empty or zeroed
  slice. &mut [T] arguments must be a typed array with the same element size
  and the same integer or float kind, since the results are copied back into
  its buffer.
  #1961

• Exported function arguments named like an identifier their generated JS
  glue binds or references, such as wasm, ret or a class name, no longer
  shadow it, which made calling the function throw. Such arguments get a
  numeric suffix in the JS, while the TypeScript definitions keep their name.
  #3729

• Getters generated by getter_with_clone no longer trigger the
  clippy::clone_on_copy lint.
  #5363