import-maps/README.md

# Import maps

Reference implementation playground for import maps proposal.

**Copy from WICG's [import-maps implementation](https://github.com/WICG/import-maps/tree/master/reference-implementation).**

## Install

Using npm:

```sh
npm install import-maps
```

or using yarn:

```sh
yarn add import-maps
```

## Usage

The import-maps files:

```json
{
  "imports": {
    "a": "/1",
    "a/": "/2/",
    "a/b": "/3",
    "a/b/": "/4/"
  }
}
```

### JavaScript

```js
import { resolve, parseFromString } from "import-maps";

const importMapBaseURL = "https://example.com/app/index.html";
const scriptBaseURL = "https://example.com/js/app.mjs";
const rawImportMaps = `{
  "imports": {
    "a": "/1",
    "a/": "/2/",
    "a/b": "/3",
    "a/b/": "/4/"
  }
}`;

try {
  const parsedImportMaps = parseFromString(rawImportMaps, importMapBaseURL);
  const parsedUrl = resolve('a', parsedImportMaps, new URL(scriptBaseURL));
  console.log(parsedUrl);
  // URL {
  //   href: 'https://example.com/1',
  //   origin: 'https://example.com',
  //   protocol: 'https:',
  //   username: '',
  //   password: '',
  //   host: 'example.com',
  //   hostname: 'example.com',
  //   port: '',
  //   pathname: '/1',
  //   search: '',
  //   searchParams: URLSearchParams {},
  //   hash: ''
  // }
  } catch (e) {
  console.trace(e);
}
```

### TypeScript

```ts
import { resolve, parseFromString, ImportMaps } from "import-maps";

const rawImportMaps: string = `{
  "imports": {
    "a": "/1",
    "a/": "/2/",
    "a/b": "/3",
    "a/b/": "/4/"
  }
}`;

const importMapBaseURL: string = "https://example.com/app/index.html";
const scriptBaseURL: string = "https://example.com/js/app.mjs";

try {
  const parsedImportMaps: ImportMaps = parseFromString(rawImportMaps, importMapBaseURL);
  const parsedUrl: URL = resolve('a', parsedImportMaps, new URL(scriptBaseURL));
  console.log(parsedUrl);
  // URL {
  //   href: 'https://example.com/1',
  //   origin: 'https://example.com',
  //   protocol: 'https:',
  //   username: '',
  //   password: '',
  //   host: 'example.com',
  //   hostname: 'example.com',
  //   port: '',
  //   pathname: '/1',
  //   search: '',
  //   searchParams: URLSearchParams {},
  //   hash: ''
  // }
} catch (e) {
  console.trace(e);
}
```

## Note ⚠️

**The return value of `resolve` is a `URL` instead of a `string`.** 

## Scope inheritance

Scopes "inherit" from each other in an intentionally-simple manner, merging but overriding as they go. For example, the following import map:

```json
{
  "imports": {
    "a": "/a-1.mjs",
    "b": "/b-1.mjs",
    "c": "/c-1.mjs"
  },
  "scopes": {
    "/scope2/": {
      "a": "/a-2.mjs"
    },
    "/scope2/scope3/": {
      "b": "/b-3.mjs"
    }
  }
}
```

would give the following resolutions:

|Specifier|Referrer               |Resulting URL |
|---------|-----------------------|--------------|
|a        |/scope1/foo.mjs        |/a-1.mjs      |
|b        |/scope1/foo.mjs        |/b-1.mjs      |
|c        |/scope1/foo.mjs        |/c-1.mjs      |
|         |                       |              |
|a        |/scope2/foo.mjs        |/a-2.mjs      |
|b        |/scope2/foo.mjs        |/b-1.mjs      |
|c        |/scope2/foo.mjs        |/c-1.mjs      |
|         |                       |              |
|a        |/scope2/scope3/foo.mjs |/a-2.mjs      |
|b        |/scope2/scope3/foo.mjs |/b-3.mjs      |
|c        |/scope2/scope3/foo.mjs |/c-1.mjs      |

## License

All Reports in this Repository are licensed by Contributors under the [W3C Software and Document License](http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document).

Contributions to Specifications are made under the [W3C CLA](https://www.w3.org/community/about/agreements/cla/).