[ANN] Akasha: Typed Browser API version 0.24 released

[Peter Donald]

Akasha is a typed browser API layer that is always up to date with the latest web specifications.

Several significant changes have been made since the 0.17 announced to this group. The major changes include:

• The ability to test for features before using the feature using methods such as WindowGlobal.isIndexedDBSupported(). The feature tests can be done dynamically at runtime or statically at compile-time. If done at compile time then the code can be compiled assuming that the feature is present or absent.
• Global execution contexts other than "window" are natively supported. From a practical perspective this means it is relatively easy to use Akasha to write service workers and access the globals via ServiceWorkerGlobal. Similarly  there exists AudioWorkletGlobal and DedicatedWorkerGlobal etc. Within a GWT application, these global execution contexts may still require custom linkers but are much easier to write.

Other changes since the 0.17 release:

• Update the WebGPU spec to the W3C Working Draft, 10 September 2021 version. This update resulted in a few minor name changes (i.e. the GPURequestAdapterOptions.forceSoftware member was renamed to GPURequestAdapterOptions.forceFallbackAdapter, GPUAdapter.isSoftware was renamed to GPUAdapter.isFallbackAdapter) as well as improved modelling of the types that contain constants (i.e. GPUMapMode no longer extends JsObject and is a final class in the java binding).
• Update the Permissions spec to the W3C Working Draft 07 September 2021 version. This update resulted in a few minor changes to the PermissionsName enumeration, the addition of the name attribute to the PermissionStatus type and the removal of the (unused) PermissionSetParameters.
• Update the WebCodecs spec to the W3C Working Draft, 8 September 2021 version. This update resulted in many changes across several types. See the API diff for further details.
• Migrate artifacts generated from the WebCodecs spec to the package codecs in the java binding.
• Update the Visual Viewport API spec to the Draft Community Group Report 10 September 2021 version. This update resulted in the VisualViewport.segments attribute being made optional (or Nullable in the java binding).
• Update the Web Share API spec to the W3C Working Draft 03 September 2021 version. This update resulted in the addition of the Navigator.canShare(...) operation.
• Update the WebXR Device API spec to the W3C Working Draft, 24 August 2021 version. This update resulted in several changes, check the API diff for further details.
• Update the HTML Living Standard spec to the 11 September 2021 version. This update resulted in several changes, check the API diff for further details. The most significant changes were the addition of oncontextlost and oncontextrestored message handlers to several types and the addition of isContextLost() to contexts as appropriate.
• Updates across several specifications resulted in PostMessageOptions being renamed to StructuredSerializeOptions.
• Re-fetch the entire set of specifications ensuring that the required members in dictionaries appear in declaration order as initiated in version v0.15. This has resulted in the reordering of parameters in create() methods in the java binding to represent members in declaration order. This impacted the following types at a minimum: StaticRangeInit, XRInputSourcesChangeEventInit, RTCRtpCodecCapability, RTCRtpCodecParameters, RTCRtpContributingSource, RTCRtpHeaderExtensionParameters, RTCRtpParameters, RTCRtpSendParameters, RTCStats, RTCTrackEventInit, HkdfParams, Pbkdf2Params, AllowedBluetoothDevice, AudioProcessingEventInit, IIRFilterOptions, OfflineAudioContextOptions (as well as several other less used dictionaries)
• Rename several union types to reflect intent, migrate the unions to the java package where they are used and convert unions to marker interfaces where appropriate. i.e. The union type IDBObjectStoreOrIDBIndexUnion was renamed to IDBCursorSource, converted to a marker interface and migrated to the akasha.idb java package. See the API diff for a full list of unions migrated.
• Type the AudioTrack.kind attribute as an enumeration containing the set of valid values.
• Add the Resize Observer spec at W3C First Public Working Draft, 11 February 2020 version to the set of specs that are used to generate the browser API. This added the ResizeObserver type and related infrastructure.
• Generate static types for global execution contexts of a service worker (i.e. SharedWorkerGlobal), a worker (i.e. DedicatedWorkerGlobal), a shared worker (i.e. SharedWorkerGlobal) and audio worklets (i.e. AudioWorkletGlobal).
• Change the way the java binding generates unions so that methods of the form as[X]() and is[X]() exist for every component type X that is part of the union.
• Replace usages of @javax.annotations.Nullable with @jsinterop.annotations.JsNullable and @javax.annotations.Nonnull with @jsinterop.annotations.JsNonNull on natively exposed elements to provide additional guidance to the J2CL/closure compiler variant of the java binding.
• Add event handling code to types (i.e. addXListener(...) and removeXListener(...) methods etc.) to more types and more events. The types and associated events as follows:
  • AbstractWorker: error
  • Animation: cancel finish remove
  • AudioWorkletNode: processorerror
  • BaseAudioContext: statechange
  • Element: click contextmenu
  • EventSource: error
  • GlobalEventHandlers: abort animationcancel animationend animationiteration animationstart auxclick beforeinput blur cancel canplay canplaythrough change click close compositionend compositionstart compositionupdate contextmenu cuechange dblclick drag dragend dragenter dragexit dragleave dragover dragstart drop durationchange emptied ended error focus focusin focusout gotpointercapture input invalid keydown keypress keyup load loadeddata loadedmetadata loadstart lostpointercapture mousedown mouseenter mouseleave mousemove mouseout mouseover mouseup pause play playing pointercancel pointerdown pointerenter pointerleave pointermove pointerout pointerover pointerup progress ratechange reset resize scroll securitypolicyviolation seeked seeking select selectionchange selectstart stalled submit suspend timeupdate toggle touchcancel touchend touchmove touchstart transitioncancel transitionend transitionrun transitionstart volumechange waiting wheel
  • HTMLCanvasElement: contextlost contextrestored
  • IDBDatabase: versionchange
  • MediaDevices: devicechange
  • MediaKeySession: keystatuseschange message
  • MediaQueryList: change
  • MediaSource: sourceclose sourceended sourceopen
  • Notification: click close error show
  • OffscreenCanvas: contextlost contextrestored
  • PermissionStatus: change
  • RTCDtlsTransport: error statechange
  • ScreenOrientation: change
  • ServiceWorkerContainer: controllerchange messageerror
  • ServiceWorkerGlobalScope: canmakepayment fetch messageerror notificationclose paymentrequest sync
  • ServiceWorkerRegistration: updatefound
  • SourceBuffer: abort error update updateend updatestart
  • SourceBufferList: addsourcebuffer removesourcebuffer
  • TextTrackCue: enter exit
  • TextTrackList: removetrack
  • WindowEventHandlers: afterprint beforeprint beforeunload hashchange languagechange message messageerror offline online pagehide pageshow popstate rejectionhandled storage unhandledrejection unload
  • WorkerGlobalScope: offline online rejectionhandled unhandledrejection
  • XMLHttpRequestEventTarget: abort error load loadend loadstart progress timeout
• Move the classes IDBObjectStoreOrIDBIndexUnion and IDBObjectStoreOrIDBIndexOrIDBCursorUnion from the akasha.indexdb package to the akasha.idb package. This was done to align with the rename of indexDB package that occurred prior to the initial release of akasha.
• Annotate several synthesized unions with the @org.jetbrains.annotations.ApiStatus.Internal annotation to make it clear that these types should not be used in user code. IntelliJ IDE will also generate a warning if user code interacts directly with internal types.
• Ensure that the code parameter to GPUShaderModuleDescriptor.create() is annotated with @WGSL.
• Replace usages of goog.global with $wnd in the GWT variant. If there is an error while the GWT application is initializing or Akasha is used early in the initialization process, there was previously a period where goog.global had not been assigned and thus the Akasha code would generate errors when using the symbol. This change eliminated this possibility.
• Start generating @JsOverlay methods of the form boolean isXSupported() for features that may be optional in an implementation. This allows downstream libraries to detect whether a feature is present before making use of the feature. The feature detection can be done at run time or at compile time depending on the needs of the application. The default behaviour of feature detection methods are to perform the checks at runtime, however this can be be changed by defining an appropriately named property in closure compiler to either true or false when using the J2CL variant or setting the equivalent binding property when using the GWT variant. The name of the property is derived from the symbol that is feature detected. Feature detection methods added and the associated compile time properties include:
  • Navigator.isBluetoothSupported() with a property akasha.is__Navigator_bluetooth__supported
  • Navigator.isGpuSupported() with a property akasha.is__Navigator_gpu__supported
  • Window.isLocalStorageSupported() and WindowGlobal.isLocalStorageSupported() with a property akasha.is__Window_localStorage__supported
  • Window.isIndexedDBSupported() and WindowGlobal.isIndexedDBSupported() with a property akasha.is__Window_indexedDB__supported
  • Window.isSessionStorageSupported() and WindowGlobal.isSessionStorageSupported() with a property akasha.is__Window_sessionStorage__supported
  • Window.isSpeechSynthesisSupported() and WindowGlobal.isSpeechSynthesisSupported() with a property akasha.is__Window_speechSynthesis__supported
  • Navigator.isClipboardSupported() with a property akasha.is__Navigator_clipboard__supported
  • Navigator.isCredentialsSupported() with a property akasha.is__Navigator_credentials__supported
  • Navigator.isGeolocationSupported() with a property akasha.is__Navigator_geolocation__supported
  • Navigator.isGetGamepadsSupported() with a property akasha.is__Navigator_isGetGamepadsSupported__supported
  • Navigator.isMediaDevicesSupported() with a property akasha.is__Navigator_mediaDevices__supported
  • Navigator.isPermissionsSupported() with a property akasha.is__Navigator_permissions__supported
  • Navigator.isRequestMediaKeySystemAccessSupported() with a property akasha.is__Navigator_requestMediaKeySystemAccess__supported
  • Navigator.isSendBeaconSupported() with a property akasha.is__Navigator_sendBeacon__supported
  • Navigator.isServiceWorkerSupported() with a property akasha.is__Navigator_serviceWorker__supported
  • Navigator.isShareSupported() with a property akasha.is__Navigator_share__supported
  • Navigator.isVibrateSupported() with a property akasha.is__Navigator_vibrate__supported
  • Navigator.isWakeLockSupported() with a property akasha.is__Navigator_wakeLock__supported
  • Navigator.isXrSupported() with a property akasha.is__Navigator_xr__supported
• Move the akasha.StringOrLongLongUnion type to akasha.core.StringOrLongLongUnion as it is only used by the akasha.core.JSON type.
• Add initial support for the akasha:webgpu-j2cl artifact which is an Elemental2 compatible variant of the WebGPU specification.
• Remove the TrustedScript symbol from the externs generated for the akasha:j2cl artifact as it is no longer required with more recent versions of the closure compiler.

To learn more about Akasha and get started:

https://github.com/akasha/akasha

Thanks!

The Akasha Team

[Jens]

Hi,

really interesting work, but don't you think something like feature detection should be handled by a dedicated library like Modernizr for example? You likely want to check for vendor prefixed support when you do feature detection.

-- J.

[Peter Donald]

Hi,

On Wed, Sep 15, 2021 at 6:27 PM Jens <jens.ne...@gmail.com> wrote:

really interesting work, but don't you think something like feature detection should be handled by a dedicated library like Modernizr for example? You likely want to check for vendor prefixed support when you do feature detection.

It depends upon the actual feature detection that is taking place. All the akasha stuff does is check whether a property/function is present on an object. So mostly it allows you to replace something like:

if (Js.global().has("indexedDB")) { /* perform logic requiring indexDB */ }

with:

if (WindowGlobal.isIndexedDBSupported()) { /* perform logic requiring indexDB */ }

Largely Akasha assumes that browsers conform with the HTML Living document (or whatever it is called) or the underlying spec and only presents the prefixes that are declared as part of the living document. If you want to perform more complex feature detection and polyfills (i.e. assigning prefixed version to unprefixed property or adding polyfills or detecting non-code related features such as css properties) then going with a dedicated library is a better option. 

Mostly we have found that our needs are served with pretty simple feature detection but YMMV

 

--

Cheers,

Peter Donald