JSAPI changes for ESR 140 Migration Guide

[jandem]

Filing this issue to track JSAPI changes we should mention in the migration guide for the next ESR release.

[jandem]

Bug 1921963 - When throwing an 'uncatchable exception' to terminate execution, it's now necessary to call JS::ReportUncatchableException(cx) before returning false, to avoid assertion failures in debug builds. This API will also clear any pending exception set on the context.

[Jon4t4n]

Bug 1877792

• CreateModuleRequest now takes an additional parameter to be able to set the module type. This parameter can be either ModuleType::JavaScript or ModuleType::JSON.
• GetModuleScript is now failable if the module record passed to it is a synthetic module.

[Jon4t4n]

Bug 1917899 and bug 1918449 - GetRequestedModuleSpecifier is now failable if the requested module has an unsupported import attribute or the module has an unknown type.

[jandem]

Bug 1914895 - JSAPI functions that take an envChain vector now have a JS::EnvironmentChain argument instead of HandleObjectVector. This JS::EnvironmentChain type lets embedders specify whether Symbol.unscopables must be supported with JS::SupportUnscopables::{Yes,No}.

To migrate, in most cases all you need to do is change this:

JS::RootedObjectVector envChain(cx);

to this (or JS::SupportUnscopables::Yes if you need to support Symbol.unscopables):

#include "js/EnvironmentChain.h"
...
JS::EnvironmentChain envChain(cx, JS::SupportUnscopables::No);

[arai-a]

Bug 1899090 - Incremental encoding APIs are rewritten and renamed to collect-delazification APIs, and moved to experimental/JSStencil.h header.

// ==== ESR128 ====

RefPtr<JS::Stencil> stencil = ...;
JS::Rooted<JSScript*> script(cx, ...); // instantiate stencil

// Start.
if (!JS::StartIncrementalEncoding(cx, std::move(stencil))) {
  return false;
}

// Finish and encode.
JS::TranscodeBuffer buffer;
if (!JS::FinishIncrementalEncoding(cx, script, buffer)) {
  return false;
}

// or, abort.
JS::AbortIncrementalEncoding(script);

// ==== ESR140 ====

RefPtr<JS::Stencil> stencil = ...;
JS::Rooted<JSScript*> script(cx, ...); // instantiate stencil

// Start.
if (!JS::StartCollectingDelazifications(cx, script, stencil, &alreadyStarted)) {
  return false;
}

// Finish and encode.
JS::TranscodeBuffer buffer;
if (!JS::FinishCollectingDelazifications(cx, script, buffer)) {
  return false;
}

// or, finish and get stencil.
RefPtr<JS::Stencil> stencil2;
if (!JS::FinishCollectingDelazifications(cx, script, getter_AddRefs(stencil2))) {
  return false;
}
// NOTE: stencil == stencil2

// or, abort.
JS::AbortCollectingDelazifications(script);

At the same time, the internal representation of JS::Stencil is modified from an initial compilation to a set of an initial compilation and a list of delazifications.
This allows caching the delazifications as JS::Stencil without merging or encoding, and also allows sharing single JS::Stencil across multiple threads where 2 or more threads adds delazifications.