Home

import-sync

4 min read

Graph View

Stage 1
Classification: API Change
Human Validated: KW
Title: Sync Imports
Authors: Guy Bedford
Champions: Guy Bedford
Last Presented: December 2024
Stage Upgrades:
Stage 1: 2024-12-05
Stage 2: NA
Stage 2.7: NA
Stage 3: NA
Stage 4: NA
Last Commit: 2024-12-05
Topics: concurrency modules others
Keywords: synchronous import module registry
GitHub Link: https://github.com/guybedford/proposal-import-sync
GitHub Note Link: https://github.com/tc39/notes/blob/HEAD/meetings/2024-12/december-04.md#import-sync-discussion-request-for-stage-1

Proposal Description:

Import Sync

Status

Champion: Guy Bedford Stage: 1

Problem Statement

When modules are already fully loaded into the module registry, it would be useful to support a synchronous import function to allow loading of dynamic specifier expressions in synchronous function paths.

Background

As we enter the maturity stage of native ESM being adopted throughout the JS ecosystem, with features like require(esm) in Node.js unlocking upgrade paths for many, some remaining ergonomic issues remain on the migration path from CommonJS to ES modules.

In particular CommonJS users in Node.js are used to being able to synchronously dynamically require modules, without that causing them to have to convert their codepaths to async.

Lazy-import solves one of these issues in allowing synchronous lazy loading of modules. It does this by effectively separating the async aspects of the module loading pipeline from the sync aspects to allow a synchronous evaluation function on the deferred namespace.

Even with this proposal supported, there still remains a gap for dynamic lazy loading when the specifier is not known in advance, since a dynamic import.defer(specifier) is still an asynchronous function.

Using the exact same semantics as the synchronous evaluation already defined in the Defer Import Eval proposal, we can provide an explicit hook for a synchronous import in JavaScript solving this ergonomic problem for JavaScript developers.

Previously one of the major blockers in the early stages of the ESM specification to enabling a feature like this was the question of asynchronous resolution. It has since turned out that all JS environments implement synchronous module resolution. As a result, and given this constraint, a synchronous import is possible.

Proposal

We propose to expose an explicit synchronous import function for ES modules, as a direct extension of the synchronous execution behaviour already defined by the Defer Import Eval proposal:

// synchronously import a module if it is available synchronously
const ns = import.sync('./mod.js');

The major design of the proposal is a new Error which is thrown when a module is not synchronously available, or uses top-level await.

Whether a module is synchronously available would otherwise be a host-determined property.

Use Cases

Getting an Already-Loaded Module

On the web, if a module has already been loaded before, it can always be available synchronously.

In this way import.sync() can behave like a registry getter function:

import 'app';
 
// this will always work if 'app' has been loaded previously
const app = import.sync('app');

Conditional Loading

Just like with dynamic import, with a synchronous import, it’s possible to check if a module or builtin is available, but synchronously.

For example, checking if host builtins are available:

let fs;
try {
  fs = import.sync('node:fs');
} catch {}
 
if (fs) {
  // Use node:fs, only if it is available
}

Or a library that conditionally binds to a framework dependency:

let react;
try {
  react = import.sync('react');
} catch {}
 
if (react) {
  // Bind to the React framework, if available
}

Synchronous Loading of ModuleExpressions & ModuleDeclarations

Importing module expressions without TLA and async dependencies can be supported:

// immediately logs 'hello world'
import.sync(module {
  console.log('hello world');
})

Similarly for module declarations:

module dep {
  console.log('hi');
}
 
module x {
  import dep;
}
 
// logs 'hi', since both modules are synchronously available
const instance = import.sync(x);

FAQ

Is Import Sync a module loading phase?

No, unlike defer and source, import.sync is not a phase, it is a new meta property like import.meta.

No syntax is supported for import sync mod from 'mod'.

To guarantee that a graph is sync upfront, instead see the module-sync-assert proposal, which may provide an import attribute or otherwise.

Post an issue.


Graph View