12.0.0

This major release is mostly about keeping import map for node module and writing importmap file separated.

- replace generateImportMapForProjectPackage by getImportMapFromNodeModules
- getImportMapFromNodeModules only return importmap, it does not write to filesystem anymore.
- add getImportMapFromFile
- add generateImportMapForProject
- generate importmap for package self ref by default
see nodejs/node#31002
- rename some parameter like favoredExports becoming packagesExportsPreference
- ensure a package self reference is stronger than self dev dependency

Author: Damien Maillard

docs/advanced.md

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/node-module-import-map",
-  "version": "12.0.0-alpha.0",
+  "version": "12.0.0",
   "description": "Generate importmap for node_modules.",
   "license": "MIT",
   "repository": {

package.json

@@ -19,7 +19,12 @@ Generate importmap for node_modules.
   - [Step 1 - Setup basic project](#step-1---setup-project)
   - [Step 2 - Generate project importMap](#step-2---generate-project-importMap)
 - [Custom node module resolution](#custom-node-module-resolution)
-- [Advanced usage](#Advanced-usage)
+- [generateImportMapForProject](#generateImportMapForProject)
+  - [importMapFile](#importMapFile)
+  - [importMapFileRelativeUrl](#importMapFileRelativeUrl)
+  - [importMapFileLog](#importMapFileLog)
+- [getImportMapFromFile](#getImportMapFromFile)
+  - [importMapFileUrl](#importMapFileUrl)
 
 # Presentation
 
@@ -135,8 +140,75 @@ We do this because importMap are used on the web where a file outside project fo
 
 In practice it does not impact you because node modules are inside your project folder. If not, write all your dependencies in your `package.json` and re-run `npm install`.
 
-# Advanced usage
+# generateImportMapForProject
 
-This repository also provides the ability to compose several import map into a final importmap file.
+`generateImportMapForProject` is an async function receiving an array of promise resolving to importmaps. It awaits for every importmap, compose them into one and write it into a file.
 
-[docs/advanced.md](./docs/advanced.md)
+> This function is meant to be responsible of generating the final importMap file that a project uses.
+
+For example code below will generate an import map from node_modules + a file + an inline importmap.
+
+```js
+import {
+  getImportMapFromNodeModules,
+  getImportMapFromFile,
+  generateImportMapForProject,
+} from "@jsenv/node-module-import-map"
+
+const projectDirectoryUrl = new URL("./", import.meta.url)
+const customImportMapFileUrl = new URL("./import-map-custom.importmap", projectDirectoryUrl)
+const importMapInputs = [
+  getImportMapFromNodeModules({
+    projectDirectoryUrl,
+    projectPackageDevDependenciesIncluded: true,
+  }),
+  getImportMapFromFile(customImportMapFileUrl),
+  {
+    imports: {
+      foo: "./bar.js",
+    },
+  },
+]
+
+await generateImportMapForProject(importMapInputs, {
+  projectDirectoryUrl,
+  importMapFileRelativeUrl: "./import-map.importmap",
+})
+```
+
+— source code at [src/generateImportMapForProject.js](./src/generateImportMapForProject.js).
+
+## importMapInputs
+
+`importMapInputs` is an array of importmap object or promise resolving to importmap objects. This parameter is optional and is an empty array by default.
+
+> When `importMapInputs` is empty a warning is emitted and `generateImportMapForProject` write an empty importmap file.
+
+## importMapFile
+
+`importMapFile` parameter is a boolean controling if importMap is written to a file. This parameters is optional and enabled by default.
+
+## importMapFileRelativeUrl
+
+`importMapFileRelativeUrl` parameter is a string controlling where importMap file is written. This parameter is optional and by default it's `"./import-map.importmap"`.
+
+## importMapFileLog
+
+`importMapFileLog` parameter a boolean controlling if there is log in the terminal when importMap file is written. This parameter is optional and by default it's enabled.
+
+# getImportMapFromFile
+
+`getImportMapFromFile` is an async function reading importmap from a file.
+
+```js
+import { getImportMapFromFile } from "@jsenv/node-module-import-map"
+
+const importMapFileUrl = new URL("./import-map.importmap", import.meta.url)
+const importMap = await getImportMapFromFile(importMapFileUrl)
+```
+
+— source code at [src/getImportMapFromFile.js](../src/getImportMapFromFile.js).
+
+## importMapFileUrl
+
+`importMapFileUrl` parameter a string or an url leading to the importmap file. This parameter is **required**.

readme.md

@@ -26,6 +26,10 @@ export const generateImportMapForProject = async (
     async () => {
       projectDirectoryUrl = assertAndNormalizeDirectoryUrl(projectDirectoryUrl)
 
+      if (importMapInputs.length === 0) {
+        console.warn(`importMapInputs is empty, the generated importmap will be empty`)
+      }
+
       const importMaps = await Promise.all(importMapInputs)
 
       const importMap = importMaps.reduce((previous, current) => {

src/generateImportMapForProject.js

@@ -29,7 +29,7 @@ export const getImportMapFromNodeModules = async ({
   // pass ["import", "browser", "require"] to read browser first if defined
   packagesExportsPreference = ["import", "node", "require"],
   packagesExportsIncluded = true,
-  packagesSelfImport = true,
+  packagesSelfReference = true,
   packagesImportsIncluded = true,
   packagesManualOverrides = {},
 }) =>
@@ -152,7 +152,7 @@ export const getImportMapFromNodeModules = async ({
           })
         }
 
-        if (packagesSelfImport) {
+        if (packagesSelfReference) {
           const { packageIsRoot, packageDirectoryRelativeUrl } = packageInfo
 
           // allow import 'package-name/dir/file.js' in package-name files
@@ -191,7 +191,7 @@ export const getImportMapFromNodeModules = async ({
             // packageDirectoryUrlExpected,
           } = packageInfo
 
-          if (packageIsRoot && packagesSelfImport) {
+          if (packageIsRoot && packagesSelfReference) {
             Object.keys(importsForPackageExports).forEach((from) => {
               const to = importsForPackageExports[from]
               addImportMapping({
@@ -258,7 +258,7 @@ export const getImportMapFromNodeModules = async ({
         },
       }) => {
         const self = packageIsRoot || packageIsProject
-        if (self && !packagesSelfImport) return
+        if (self && !packagesSelfReference) return
 
         const mainFileUrl = await resolvePackageMain({
           packageFileUrl,

src/getImportMapFromNodeModules.js

@@ -6,7 +6,7 @@ const testDirectoryUrl = resolveUrl("./", import.meta.url)
 
 const actual = await getImportMapFromNodeModules({
   projectDirectoryUrl: testDirectoryUrl,
-  packagesSelfImport: false,
+  packagesSelfReference: false,
 })
 const expected = {
   imports: {

test/getImportMapFromNodeModules/circular/circular.test.js

@@ -6,7 +6,7 @@ const testDirectoryUrl = resolveUrl("./", import.meta.url)
 
 const actual = await getImportMapFromNodeModules({
   projectDirectoryUrl: testDirectoryUrl,
-  packagesSelfImport: false,
+  packagesSelfReference: false,
 })
 const expected = {
   imports: {

test/getImportMapFromNodeModules/exports-and-main/exports-and-main.test.js

@@ -6,7 +6,7 @@ const testDirectoryUrl = resolveUrl("./", import.meta.url)
 
 const actual = await getImportMapFromNodeModules({
   projectDirectoryUrl: testDirectoryUrl,
-  packagesSelfImport: false,
+  packagesSelfReference: false,
 })
 const expected = {
   imports: {

test/getImportMapFromNodeModules/exports-complex/exports-complex.test.js

@@ -6,7 +6,7 @@ const testDirectoryUrl = resolveUrl("./", import.meta.url)
 
 const actual = await getImportMapFromNodeModules({
   projectDirectoryUrl: testDirectoryUrl,
-  packagesSelfImport: false,
+  packagesSelfReference: false,
 })
 const expected = {
   imports: {

test/getImportMapFromNodeModules/exports-directory-scoped/exports-directory-scoped.test.js

@@ -6,7 +6,7 @@ const testDirectoryUrl = resolveUrl("./", import.meta.url)
 
 const actual = await getImportMapFromNodeModules({
   projectDirectoryUrl: testDirectoryUrl,
-  packagesSelfImport: false,
+  packagesSelfReference: false,
 })
 const expected = {
   imports: {