The amount of data present in the world continues to grow exponentially with time. This huge amount of data exists in many different types. These data can be text files, images, videos, audios, etc. Furthermore, these data can be stored in several file formats as well. A file format is a standard way in which data is encoded to be stored on a file storage system. There are numerous file formats such as HTML, JSON, XML, JPEG, PNG, MP3, MP4, etc. Although the format is different from one another, the core concept is the data. In order to use this data which exists in several file formats, we needed a way to import them to our JavaScript applications safely. Import Assertion is such a proposal we will be discussing about today.

What is Import Assertion?

Import Assertion is a proposal that allows for additional metadata to be passed alongside import modules.

In web development, there was a need to import data that exist in various forms into our JavaScript code. This was especially much needed with JSON data types as it was very common amongst modern web developers as it was served as a replacement for XML in AJAX applications.

According to the development team, this was a core reason for the introduction of the import assertion proposal. According to the proposal, a JSON module will be imported as shown below.

import json from "./foo.json" assert { type: "json" };
import("foo.json", { assert: { type: "json" } });

Now you might start wondering, why we cannot import JSON modules as simple as,

import json from "./data.json";

In fact, this approach was supported by many and quickly got accepted. It was later implemented by Chromium’s V8 engine. But an issue highlighted by engineers from Apple and Mozilla specified a security issue associated with the existing implementation involving MIME types.

Some developers have the intuition that the file extension could be used to determine the module type, as it is in many existing non-standard module systems. However, there exists a principle in web development that the suffix of a URL (the file extension of the data being loaded) does not determine the way it is interpreted by the web browser. Instead, it depends on the MIME type. It is also a web observed fact that there is a mismatch between the file extensions and HTTP Content-Type header.

All these troublesome issues led to the conclusion that type assertions were necessary at the time of file import.

How Was It Done Before?

If you look at the past, you will realize that it was possible to import non-JS modules into your JS code. Require JS provided a feature called plugins that allowed for the imports of non-JS artifacts into your code. An example can be seen below.

require(['json!someData.json'], function(data){
  ...
})

This syntax looked like '«specifier-of-plugin-module»!«specifier-of-artifact»'

After the success of Require JS, webpack also implemented a non-JS module loader that followed the same syntax as Require JS. Several file types were supported including styles, frameworks, templates, etc.

Proposed Syntax of Import Assertion

The import assertion will be made in several contexts. There are many possible syntax that can be integrated, but the currently proposed syntax will be discussed in this section.

A key-value syntax will be used with the property type being used to denote the module type.

Static Import Statements

We have already seen an example for static import’s syntax that looked like this.

import json from "./foo.json" assert { type: "json" };

This syntax would allow any arbitrary assertions after the assert keyword. Since JS developers are quite familiar with object literals, this syntax will be quite comfortable. In the above example, the assertion is based on the type JSON.

You can also note that standard object literal features are supported.

• The keys of the object can be either quoted or unquoted
• The values must be strings

The JavaScript engines are encouraged to throw an exception if either the key or value of the object is not supported. This would make it easier on the developers’ end.

Re-export Statements

Similar to static import statements, we can add assertions using the assert keyword.

export { default as foo } from './foo.json' assert { type: 'json' };

Dynamic Import Statements

To cater assertions in dynamic import statements, the import() function would contain an optional parameter that requires an options bag. This will be an object with property assert with its value being the import assertion. It must be noted that this object only supports the assert property currently and has been built with forward compatibility in mind.

import("foo.json", { assert: { type: "json" } })

Integration Into Other Environments

Currently, there plans to integrate assertions into several other environments.

Web Worker Instantiation

Although this feature is still under discussion, if implemented, it would look like below.

new Worker("foo.wasm", { type: "module", assert: { type: "webassembly" } });

HTML

Changes to HTML will not be specified by the TC39 committee. But there is a possibility to include assert as an attribute to script tags when importing modules.

<script src="foo.wasm" type="module" asserttype="webassembly"></script>

JSON Modules

This has the possibility to be one of the first implementations of import assertion. In fact, the import assertion proposal initially included JSON modules in its scope. But later, JSON modules were de-scoped and transferred to their own proposal.

Probable Non-JSON Use Cases

There are several other data types that may be implemented with import assertions in the future.

• Stylesheet imports for styling — CSS, LESS, SASS, SCSS, etc
• Framework components for integration — React, Vue, Angular components
• Templates — HTML documents, markdowns, etc
• Raw files

Thank you for reading and happy coding!

Build & share independent components with Bit

Bit is an ultra-extensible tool that lets you create truly modular applicationswith independently authored, versioned, and maintained components.

Use it to build modular apps & design systems, author and deliver micro frontends, or simply share components between applications.