load-esm - npm Package Compare versions

Comparing version 0.1.0 to 0.1.1

index.cjs.js

 module.exports = {
-    loadEsm: (module) => import(module)
+    loadModule: (module) => import(module)
 };

index.d.ts

@@ -1,1 +0,1 @@
-export function loadEsm<T = any>(name: string): Promise<T>;
+export function loadModule<T = any>(name: string): Promise<T>;

package.json

 {
   "name": "load-esm",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "index.cjs",
@@ -33,2 +33,3 @@ "types": "index.d.ts",
     "ESM",
+    "Import ESM",
     "CommonJS",
@@ -38,5 +39,3 @@ "TypeScript",
     "dynamic import",
-    "JavaScript modules",
-    "module interoperability",
-    "mixed-module environment"
+    "dynamic load"
   ],
@@ -43,0 +42,0 @@ "engines": {

README.md

@@ -0,5 +1,6 @@
+[![NPM version](https://img.shields.io/npm/v/load-esm.svg)](https://npmjs.org/package/load-esm)
+
 # load-esm
 
 ***load-esm*** is a utility for dynamically importing pure ESM (ECMAScript Module) packages in CommonJS TypeScript projects.
-This is particularly useful when working with Node.js environments configured for CommonJS while needing to integrate ESM-only dependencies.
 
@@ -17,14 +18,22 @@ ## Installation
 
-## Features
-- Enables dynamic import of pure ESM modules in CommonJS-based projects.
-- Compatible with TypeScript, offering proper type definitions.
-- Simple and lightweight implementation.
-
 ## Usage
 
-Here’s an example demonstrating how to use load-esm to dynamically load an ESM module in a CommonJS project:
+Here’s a conceptual example demonstrating how to use load-esm to dynamically load an ESM module in a CommonJS project:
 
 ```ts
+import {loadModule} from 'load-esm';
+
+/**
+ * Import 'file-type' ES-Module in CommonJS Node.js module
+ */
+(async () => {
+  const esmModule = await loadModule('esm-module');
+})();
+```
+
+A concrete example loading [file-typ](https://github.com/sindresorhus/file-type), a pure ESM package:
+
+```ts
 import * as path from 'path';
-import { loadEsm } from 'load-esm';
+import {loadModule} from 'load-esm';
 
@@ -37,3 +46,3 @@ /**
         // Dynamically import the ESM module
-        const { fileTypeFromFile } = await loadEsm('file-type');
+        const { fileTypeFromFile } = await loadModule('file-type');
 
@@ -52,3 +61,3 @@ // Use the imported function
 ```ts
-loadEsm<T = any>(name: string): Promise<T>
+loadModule<T = any>(name: string): Promise<T>
 ```
@@ -65,6 +74,6 @@ Dynamically imports an ESM module.
 ```ts
-import { loadEsm } from 'load-esm';
+import { loadModule } from 'load-esm';
 
 (async () => {
-  const module = await loadEsm('some-esm-module');
+  const module = await loadModule('some-esm-module');
   console.log(module);
@@ -75,5 +84,11 @@ })();
 ## How It Works
-The utility leverages Node.js's import() function to dynamically load ESM modules.
-This allows CommonJS-based projects to interact with ESM dependencies without converting the entire project to ESM.
+Using `await import` in a CommonJS TypeScript project poses challenges because the TypeScript compiler transpiles `import()` statements to `require()` calls when module is set to CommonJS in `tsconfig.json`.
+This behavior conflicts with the dynamic nature of `import()` used for ESM.
 
+Workarounds, such as wrapping the `import()` statement within `eval()` or similar constructs, can prevent TypeScript from transpiling it, but these approaches are clunky and error-prone.
+
+The utility of [load-esm](https://github.com/Borewit/load-esm) bypasses the TypeScript compiler by executing the `import()` outside the compilation scope. 
+By doing so, it maintains the intended behavior of `import()` for loading ESM modules dynamically, 
+providing a clean and effective solution for such scenarios.
+
 ## Compatibility
@@ -83,8 +98,3 @@ - Node.js: Requires Node.js 13.2.0 or later, as import() is only supported in these versions and beyond.
 
-## Why Use load-esm?
-In mixed-module environments where your project is primarily CommonJS but relies on some ESM-only dependencies,
-load-esm serves as a seamless bridge,
-enabling interoperability without changing your project’s module system.
-
 ## License
-[MIT](./LICENSE)
+[MIT](./LICENSE)

No alert changes

Improved metrics

Total package byte prevSize

4806

8.59%

Number of lines in readme file

95

13.1%

No dependency changes