Merge pull request #52 from jsenv/many_entry_points

Many entry points

Author: dmail

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "search.exclude": {
+    "**/dist/": true
+  }
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/importmap-node-module",
-  "version": "2.8.1",
+  "version": "3.0.0",
   "description": "Generate importmap for node_modules",
   "license": "MIT",
   "repository": {

readme.md

@@ -77,29 +77,32 @@ await writeImportMapFiles({
     "./importmap_for_dev.importmap": {
       mappingsForNodeResolution: true,
       mappingsForDevDependencies: true,
-      checkImportResolution: true,
     },
     "./importmap_for_prod.importmap": {
       mappingsForNodeResolution: true,
-      checkImportResolution: true,
-      removeUnusedMappings: true,
     },
   },
 })
 ```
 
 ## projectDirectoryUrl
 
-_projectDirectoryUrl_ parameter is a string url leading to a folder with a _package.json_.
-This parameters is **required** and accepted values are documented in [@jsenv/filesystem#assertAndNormalizeDirectoryUrl](https://github.com/jsenv/filesystem/blob/main/docs/API.md#assertandnormalizedirectoryurl)
+_projectDirectoryUrl_ is a string/url leading to a folder with a _package.json_.
+
+_projectDirectoryUrl_ is **required**.
 
 ## importMapFiles
 
-_importMapFiles_ parameter is an object where keys are importmap file relative urls and values are parameters controlling the mappings that will be written in the importmap file.
+_importMapFiles_ is an object where keys are file relative urls and value are objects configuring which mappings will be written in the importmap files.
+
+_importMapFiles_ is **required**.
 
 ### mappingsForNodeResolution
 
-When _mappingsForNodeResolution_ is enabled, the mappings required to implement node module resolution are generated.
+_mappingsForNodeResolution_ is a boolean. When enabled mappings required to implement node module resolution are generated.
+
+_mappingsForNodeResolution_ is optional.
+
 The following source of information are used to create complete and coherent mappings in the importmap.
 
 - Your _package.json_
@@ -110,97 +113,130 @@ The following source of information are used to create complete and coherent map
 
 ### mappingsForDevDependencies
 
-When enabled, `"devDependencies"` declared in your _package.json_ are included in the generated importMap.
+_mappingsForDevDependencies_ is a boolean. When enabled, `"devDependencies"` declared in your _package.json_ are included in the generated importMap.
 
-### manualImportMap
+_mappingsForDevDependencies_ is optional.
 
-_manualImportMapp_ parameter is an importMap object. Mappings declared in this parameter are added to mappings generated for node resolution. This can be used to provide additional mappings and/or override node mappings.
-This parameter is optional and by default it's an empty object.
+### runtime
+
+_runtime_ is a string used to determine what to pick in [package.json conditions](https://nodejs.org/docs/latest-v16.x/api/packages.html#packages_conditions_definitions).
+
+_runtime_ is optional and defaults to `"browser"`.
 
 ```js
 import { writeImportMapFiles } from "@jsenv/importmap-node-module"
 
 await writeImportMapFiles({
   projectDirectoryUrl: new URL("./", import.meta.url),
   importMapFiles: {
-    "./test.importmap": {
+    "./browser.importmap": {
       mappingsForNodeResolution: true,
-      manualImportMap: {
-        imports: {
-          "#env": "./env.js",
-        },
-      },
+      runtime: "browser",
+    },
+    "./node.importmap": {
+      mappingsForNodeResolution: true,
+      runtime: "node",
     },
   },
 })
 ```
 
-### checkImportResolution
+### packageUserConditions
 
-_checkImportResolution_ is a boolean parameter controlling if script tries to resolve all import found in your js files using the importmap.
+_packageUserConditions_ is an array controlling which conditions are favored in [package.json conditions](https://nodejs.org/dist/latest-v15.x/docs/api/packages.html#packages_conditions_definitions).
 
-It is recommended to enable this parameter, it gives more confidence in the generated importmap and outputs nice warnings in case some import cannot be resolved.
+_packageUserConditions_ is optional.
 
-The import resolution starts from your project entry point which is determined using your package.json "exports" or "main" field.
+```js
+import { writeImportMapFiles } from "@jsenv/importmap-node-module"
 
-This import resolution check is auto enabled when [removeUnusedMappings](#removeUnusedMappings) or [extensionlessAutomapping](#extensionlessAutomapping) are used.
+await writeImportMapFiles({
+  projectDirectoryUrl: new URL("./", import.meta.url),
+  importMapFiles: {
+    "./dev.importmap": {
+      mappingsForNodeResolution: true,
+      packageUserConditions: ["development"],
+    },
+    "./prod.importmap": {
+      mappingsForNodeResolution: true,
+      packageUserConditions: ["production"],
+    },
+  },
+})
+```
 
-### removeUnusedMappings
+### manualImportMap
 
-_removeUnusedMappings_ parameter is a boolean controlling if mappings will be treeshaked according to the import found in your files.
+_manualImportMap_ is an object containing mappings that will be added to the importmap. This can be used to provide additional mappings and/or override node mappings.
 
-During development, you can start or stop using a mapping often so it's convenient to have all mappings.
+_manualImportMap_ is optional.
 
-In production you likely want to keep only the mappings actually used by your js files. In that case enable removeUnusedMappings: it will drastically decrease the importmap file size.
+```js
+import { writeImportMapFiles } from "@jsenv/importmap-node-module"
 
-### runtime
+await writeImportMapFiles({
+  projectDirectoryUrl: new URL("./", import.meta.url),
+  importMapFiles: {
+    "./test.importmap": {
+      mappingsForNodeResolution: true,
+      manualImportMap: {
+        imports: {
+          "#env": "./env.js",
+        },
+      },
+    },
+  },
+})
+```
+
+### entryPointsToCheck
+
+_entryPointsToCheck_ is an array composed of string representing file relative urls. Each file is considered as an entry point using the import mappings. For each entry point, _writeImportMapFiles_ will check if import can be resolved and repeat this process for every static and dynamic import.
 
-A string parameter indicating where the importmap will be used. The default runtime is `"browser"`.
-The runtime is used to determine what to pick in [package.json conditions](https://nodejs.org/docs/latest-v16.x/api/packages.html#packages_conditions_definitions).
+_entryPointsToCheck_ is optional.
 
 ```js
 import { writeImportMapFiles } from "@jsenv/importmap-node-module"
 
 await writeImportMapFiles({
   projectDirectoryUrl: new URL("./", import.meta.url),
   importMapFiles: {
-    "./browser.importmap": {
-      mappingsForNodeResolution: true,
-      runtime: "browser",
-    },
-    "./node.importmap": {
+    "./project.importmap": {
       mappingsForNodeResolution: true,
-      runtime: "node",
+      entryPointsToCheck: ["./main.js"],
     },
   },
 })
 ```
 
-### packageUserConditions
+It is recommended to use _entryPointsToCheck_ as it gives confidence in the generated importmap. When an import cannot be resolved, a warning is logged.
 
-Controls which conditions are favored in [package.json conditions](https://nodejs.org/dist/latest-v15.x/docs/api/packages.html#packages_conditions_definitions).
+### removeUnusedMappings
+
+_removeUnusedMappings_ is a boolean. When enabled mappings will be treeshaked according to the import found in js files. It must be used with _entryPointsToCheck_.
 
 ```js
 import { writeImportMapFiles } from "@jsenv/importmap-node-module"
 
 await writeImportMapFiles({
   projectDirectoryUrl: new URL("./", import.meta.url),
   importMapFiles: {
-    "./dev.importmap": {
-      mappingsForNodeResolution: true,
-      packageUserConditions: ["development"],
-    },
-    "./prod.importmap": {
+    "./test.importmap": {
       mappingsForNodeResolution: true,
-      packageUserConditions: ["production"],
+      entryPointsToCheck: ["./main.js"],
+      removeUnusedMappings: true,
     },
   },
 })
 ```
 
+During development, you can start or stop using a mapping often so it's convenient to have all mappings.
+
+In production you likely want to keep only the mappings actually used by your js files. In that case enable removeUnusedMappings: it will drastically decrease the importmap file size.
+
 ### extensionlessAutomapping
 
-_extensionlessAutomapping_ parameter is a boolean controlling if mappings are generated for import(s) without extension found in your js files. Should be combined with _magicExtensions_ as shown in the code below.
+_extensionlessAutomapping_ is a boolean. When enabled mappings are generated for import(s) without extension found in your js files. It must be used with _entryPointsToCheck_ and _magicExtensions_.
 
 ```js
 import { writeImportMapFiles } from "@jsenv/importmap-node-module"
@@ -210,16 +246,19 @@ await writeImportMapFiles({
   importMapFiles: {
     "./test.importmap": {
       mappingsForNodeResolution: true,
+      entryPointsToCheck: ["./main.js"],
+      extensionlessAutomapping: true,
+      magicExtensions: [".js"],
     },
   },
 })
 ```
 
 ## packagesManualOverrides
 
-Ideally package.json should use `"exports"` field documented in https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_package_entry_points. But not every one has updated to this new field yet.
+_packagesManualOverrides_ is an object that can be used to override some of your dependencies package.json.
 
-_packagesManualOverrides_ parameter is an object that can be used to override some of your dependencies package.json.
+_packagesManualOverrides_ exists in case some of your dependencies use non standard fields to configure their entry points in their _package.json_. Ideally they should use `"exports"` field documented in https://nodejs.org/dist/latest-v16.x/docs/api/packages.html#packages_package_entry_points. But not every one has updated to this new field yet.
 
 ```js
 import { writeImportMapFiles } from "@jsenv/importmap-node-module"