npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

import-sync

v2.2.2

Published

Synchronously import dynamic ECMAScript Modules similar to CommonJS require. Basic wrapper around esm for compatibility with both ESM and CJS projects in NodeJS.

Downloads

16,497

Readme

Import Sync

pipeline   codecov   Maintainability   Snyk Security   GitHub top language

NPM Version   install size   Depfu Dependencies   FOSSA Status   NPM License   GitHub issues

Quality Gate Status   Codacy Badge   DeepSource   codebeat badge   GitHub stars

Downloads Total   Downloads Yearly   Downloads Monthly   Downloads Weekly   Downloads Daily


Synchronously import dynamic ECMAScript Modules similar to CommonJS require

Basic wrapper around esm for compatibility with both ESM and CJS projects in NodeJS

Capable of importing ESM-only libraries such as node-fetch@3 in CJS projects

Try with Replit


1. Installation

npm install import-sync

2. Usage

Try with Replit.

importSync(id, options);

Importing from the same directory

const { someVariable, someFunction } = importSync('./some-module');

Importing .mjs file from a different directory

const { someFunction  } = importSync('../src/someModule.mjs');

Using a different basePath

const { someFunction } = importSync(
  './someModule',
  { basePath: process.cwd() }
);

Using additional esm options as described in esm's documentation

const { someFunction } = importSync(
  './someModule',
  {
    esmOptions: {
      cjs: {
        cache: true
      },
      mode: 'all',
      force: 'true',
    }
  }
);

Importing an ESM-only module

const fetch = importSync('node-fetch'),

2.1. id

Module name or relative path similar to CommonJS require. For example,

  • '../animals/cats.js'
  • './dogs.mjs'
  • './minimal'
    • importSync will look for matching extensions in the order [.js, .mjs, .cjs, .ts]
  • 'node-fetch'
    • importSync can import pure-esm node-fetch (v3) into your cjs project

2.2. options

2.3. return

The importSync function returns the exported module content similar to NodeJS require.

If an unknown file path is provided a default Error object is thrown.

3. License

Copyright (c) 2023 Khiet Tam Nguyen

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the “Software”),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

FOSSA Status

4. Limitations

There are currently no known limitations.

5. Caveats

5.1. Idea

import-sync was created to enable the implementation of a global dryrun script that can be run by students undertaking COMP1531 Software Engineering Fundamentals in their major group project. This requires the ability to import external ES Modules from any directory or path for use in both CommonJS and ESM-based projects.

The dryrun serves as a sanity check before the final submission is made, and is located in the centralised COMP1531 course account at the path ~cs1531/bin. Students who are connected to the CSE lab environment (e.g. via VLAB) can run the dryrun script from their major project repository, e.g. at the path ~z5313514/comp1531/project-backend.

5.2. Discovery

Initially, the esm library looked promising. However, when the global dryrun script was executed in a mock student's project directory, the following error occurred:

Error [ERR_REQUIRE_ESM]: require() of ES Module /import/ravel/5/z5313515/project-backend/src/auth.js not supported. Instead change the require of auth.js in null to a dynamic import() which is available in all CommonJS modules

This is due to the package.json containing "type": "module", as iteration 1 of the student major project uses ESM for the seamless transition to future iterations.

The following approaches were thus attempted, but were unsatisfactory for our purpose:

  1. jewire/rewire/require
    • in iteration 1, the dryrun requires the import of ES6 modules, so jewire (which was used for the dryrun of iteration 0) was no longer satisfying our requirements
    • the same limitations of being CommonJS exclusive applies to rewire and require
  2. import() - ECMAScript dynamic import
    • this was the previous attempt at writing the dryrun
    • However, it relied on asynchronous code. Since COMP1531 is fully synchronous (including the use of sync-request-curl for sending HTTP requests), this became a source of mystery and confusion for students
    • additionally, students had to append the suffix .js to all of their file imports in the project solely to use the dryrun. This resulted in ambiguous error messages and obscure dryrun requirements unrelated to the project
  3. require-esm-in-cjs
    • this library utilises deasync, which when used in NodeJS for Jest tests, could hang indefinitely as seen in Jest's issue #9729
    • since COMP1531 uses Jest as the sole testing framework, deasync was ruled out
  4. Other async-to-sync conversions for dynamic import()
    • synckit: worker_threads, Jest and external imports did not work (unclear reason)
    • sync-rpc: leaves orphan processes when used in Jest as explained in issue #10
    • fibers: obsolete and does not work for node versions later than 16
    • synchronize: documentation link gives 404 and has fiber as a dependency
    • sync/node-sync: uses fiber (note: "redblaze/node-sync" on github, "sync" on npm)

5.3. Result

Upon a more thorough investigation into the initial issue with the esm module, the cause was the introduction of the exception starting from NodeJS version 13, as noted in @fregante's comment:

  • https://github.com/standard-things/esm/issues/855#issuecomment-558319872

Further down the thread was a link to the solution by @guybedford

  • https://github.com/standard-things/esm/issues/868#issuecomment-594480715

which removes the exception through module extension and serves as a satisfactory workaround. This reduced the codebase of import-sync to simply a wrapper around esm.

Another issue that import-sync (v2) addresses is esm's open issue #904, which yields the error message:

Error [ERR_INVALID_PROTOCOL]: Protocol 'node:' not supported. Expected 'file:'

when importing ESM-only libraries such as node-fetch@3 in a CommonJS module. This is done by overriding the default Module._resolveFilename function to remove the node: prefix, effectively changing any imports of the form (for example):

import http from 'node:http';

to

import http from 'http';

for all imported modules.

For further discussions about this issue, visit:

  • https://stackoverflow.com/a/77329422/22324694