@import-maps/resolve - npm Package Compare versions

Comparing version 0.2.6 to 0.3.1

CHANGELOG.md

@@ -6,2 +6,21 @@ # Change Log
 
+## [0.3.1](https://github.com/open-wc/open-wc/compare/@import-maps/resolve@0.3.0...@import-maps/resolve@0.3.1) (2020-05-07)
+
+**Note:** Version bump only for package @import-maps/resolve
+
+
+
+
+
+# [0.3.0](https://github.com/open-wc/open-wc/compare/@import-maps/resolve@0.2.6...@import-maps/resolve@0.3.0) (2020-04-28)
+
+
+### Features
+
+* **resolve:** update to latest proposal specs (only mapping and scopes) ([86ab538](https://github.com/open-wc/open-wc/commit/86ab53844e74e16982aa221b1f8520bc6598e6e0))
+
+
+
+
+
 ## [0.2.6](https://github.com/open-wc/open-wc/compare/@import-maps/resolve@0.2.5...@import-maps/resolve@0.2.6) (2020-04-12)
@@ -8,0 +27,0 @@

package.json

 {
   "name": "@import-maps/resolve",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },
-  "description": "Read and resolve urls via an import map",
+  "description": "Parse and resolve imports via an import map",
   "license": "MIT",
@@ -16,13 +16,12 @@ "repository": {
   "homepage": "https://github.com/open-wc/open-wc/tree/master/packages/import-maps-resolve",
-  "main": "dist/index.js",
+  "main": "./index.js",
   "scripts": {
-    "build": "babel src --out-dir dist --copy-files --include-dotfiles",
-    "prepublishOnly": "npm run build && ../../scripts/insert-header.js",
-    "start": "npm run build && node ./dist/index.js",
+    "prepublishOnly": "../../scripts/insert-header.js",
     "test": "npm run test:node",
-    "test:node": "mocha --require @babel/register",
-    "test:watch": "onchange 'src/**/*.js' 'test/**/*.js' -- npm run test --silent"
+    "test:node": "mocha test/run-tests.js"
   },
   "files": [
-    "dist"
+    "*.d.ts",
+    "*.js",
+    "src"
   ],
@@ -32,11 +31,3 @@ "keywords": [
     "import-maps"
-  ],
-  "devDependencies": {
-    "@babel/cli": "^7.8.4",
-    "@babel/core": "^7.9.0",
-    "@babel/preset-env": "^7.9.0",
-    "@babel/register": "^7.9.0",
-    "babel-plugin-transform-dynamic-import": "^2.1.0",
-    "onchange": "^5.2.0"
-  }
+  ]
 }

README.md

 # Resolve import-maps
 
-This will allow you to parse and resolve urls by a given [import-map](https://github.com/WICG/import-maps).
+Library for parsing and resolving [import maps](https://github.com/WICG/import-maps).
 
@@ -14,51 +14,90 @@ > Part of [Open Web Components](https://github.com/open-wc/open-wc/): guides, tools and libraries for modern web development and web components
 ```bash
-yarn add @import-maps/resolve
+npm i --save-dev @import-maps/resolve
 ```
 
-You may then override a resolve method in your build process.
+### Base URL
 
+Parsing and resolving import maps requires a base URL. This is an instance of the `URL` constructor.
+
+This can be a browser URL:
+
 ```js
-import { parseFromString, resolve } from '@import-maps/resolve';
+const myUrl = new URL('https://www.example.com/');
+```
 
-// you probably want to cache the map processing and not redo it for every resolve
-// a simple example
-const importMapCache = null;
+Or a file URL when working with a file system. The `pathToFileURL` function is useful for converting a file path to a URL object:
 
-function myResolve(specifier) {
-  const rootDir = process.cwd();
-  const basePath = importer ? importer.replace(rootDir, `${rootDir}::`) : `${rootDir}::`;
-  if (!importMapCache) {
-    const mapString = fs.readFileSync(path.join(rootDir, 'import-map.json'), 'utf-8');
-    mapCache = parseFromString(mapString, basePath);
-  }
+```js
+import path from 'path';
+import { pathToFileURL } from 'url';
 
-  const relativeSource = source.replace(rootDir, '');
-  const resolvedPath = resolve(relativeSource, importMapCache, basePath);
+const fileUrl1 = new URL('file:///foo/bar');
+const fileUrl2 = pathToFileURL(path.join(process.cwd(), 'foo', 'bar'));
+```
 
-  if (resolvedPath) {
-    return resolvedPath;
-  }
-}
+### Parsing an import map from a string
+
+The `parseFromString` parses an import map from a JSON string. It returns the parsed import map object to be used when resolving import specifiers.
+
+```js
+import { parseFromString } from '@import-maps/resolve';
+
+// get the import map from somewhere, for example read it from a string
+const importMapString = '{ "imports": { "foo": "./bar.js" } }';
+// create a base URL to resolve imports relatively to
+const baseURL = new URL('https://www.example.com/');
+
+const importMap = parseFromString(importMapString, baseURL);
 ```
 
-### Additional info
+### Parsing an import map from an object
 
-The 3rd parameter of `resolve` is the "baseUrl/basePath" and it's format is `/path/to/root::/subdir/foo`.
-You can compare it with an url `http://example.com/subdir/foo`.
+If you already have an object which represents the import map, it still needs to be parsed to validate it and to prepare it for resolving. You can use the `parse` function for this.
 
-- Everything before the `::` is sort of the `domain` e.g. `http://example.com/`
-- Everything after is the path/directory to your appliaction
+```js
+import { parse } from '@import-maps/resolve';
 
-Such a path is needed as import maps support relative pathes as values.
+// get the import map from somewhere, for example read it from a string
+const rawImportMap = { imports: { foo: './bar.js' } };
+// create a base URL to resolve imports relatively to
+const baseURL = new URL('https://www.example.com/');
 
+const importMap = parse(importMapString, baseURL);
+```
+
+### Resolving specifiers
+
+Once you've created a parsed import map, you can start resolving specifiers. The `resolve` function returns a `URL`, you can use this to either use the resolved `href` or just the `pathname`.
+
+```js
+import { resolve } from '@import-maps/resolve';
+
+const importMap = /* parse import map shown above */;
+// create a base URL to resolve imports relatively to
+const baseURL = new URL('https://www.example.com/');
+
+const resolvedUrl = resolve(importMapString, baseURL);
+
+// the full url including protocol and domain
+console.log(resolvedUrl.href);
+// just the path
+console.log(resolvedUrl.url);
+```
+
+If you need to use the resolved path on the file system, you can use the `fileURLToPath` utility:
+
+```js
+import { fileURLToPath } from 'url';
+import { resolve } from '@import-maps/resolve';
+
+const resolvedUrl = resolve(importMapString, baseURL);
+
+// the fully resolved file path
+console.log(fileURLToPath(resolvedUrl));
+```
+
 ## Acknowledgments
 
 This implementation is heavily based on the [import-maps reference implementation](https://github.com/WICG/import-maps/tree/master/reference-implementation).
-Thanks to @domenic and @guybedford for sharing that prototype.
 
-Some adjustments have been made
-
-- Allow to process/resolve node pathes besides urls
-- Use mocha/chai for testing (already available in our setup)
-
 <script>
@@ -65,0 +104,0 @@ export default {

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Dev dependency count

0

decreased by-100%

Number of package files

8

increased by14.29%

Number of lines in readme file

113

increased by52.7%

Worsened metrics

Total package byte prevSize

19219

decreased by-12.66%

Lines of code

306

decreased by-14.04%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes