@esm.sh/import-map 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-2025 Je Xia <i@jex.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# import-map
+
+A [import maps](https://wicg.github.io/import-maps/) parser and resolver.

package/dist/generator.mjs

@@ -0,0 +1,24 @@
+let cdnOrigin = "https://esm.sh";
+function setCDNOrigin(origin) {
+  const url = new URL(origin);
+  cdnOrigin = url.origin;
+}
+function add(importMap, specifier) {
+  throw new Error("Not implemented");
+}
+function update(importMap, specifier, version) {
+  throw new Error("Not implemented");
+}
+function remove(importMap) {
+  throw new Error("Not implemented");
+}
+function tidy(importMap) {
+  throw new Error("Not implemented");
+}
+export {
+  add,
+  remove,
+  setCDNOrigin,
+  tidy,
+  update
+};

package/dist/import-map.mjs

@@ -0,0 +1,159 @@
+function createBlankImportMap(baseURL) {
+  return {
+    $baseURL: new URL(baseURL ?? ".", "file:///").href,
+    imports: {},
+    scopes: {}
+  };
+}
+function importMapFrom(v, baseURL) {
+  const im = createBlankImportMap(baseURL);
+  if (isObject(v)) {
+    const { imports, scopes } = v;
+    if (isObject(imports)) {
+      validateImports(imports);
+      im.imports = imports;
+    }
+    if (isObject(scopes)) {
+      validateScopes(scopes);
+      im.scopes = scopes;
+    }
+  }
+  return im;
+}
+function parseImportMapFromJson(json, baseURL) {
+  const importMap = {
+    $baseURL: new URL(baseURL ?? ".", "file:///").href,
+    imports: {},
+    scopes: {}
+  };
+  const v = JSON.parse(json);
+  if (isObject(v)) {
+    const { imports, scopes } = v;
+    if (isObject(imports)) {
+      validateImports(imports);
+      importMap.imports = imports;
+    }
+    if (isObject(scopes)) {
+      validateScopes(scopes);
+      importMap.scopes = scopes;
+    }
+  }
+  return importMap;
+}
+function parseImportMapFromHtml(html, baseURL) {
+  const tplEl = document.createElement("template");
+  tplEl.innerHTML = html;
+  const scriptEl = tplEl.content.querySelector("script[type='importmap']");
+  if (scriptEl) {
+    return parseImportMapFromJson(scriptEl.textContent, baseURL);
+  }
+  return createBlankImportMap(baseURL);
+}
+function resolve(importMap, specifier, containingFile) {
+  const { $baseURL, imports, scopes } = importMap;
+  const { origin, pathname } = new URL(containingFile, $baseURL);
+  const sameOriginScopes = [];
+  for (const scopeName in scopes) {
+    const scopeUrl = new URL(scopeName, $baseURL);
+    if (scopeUrl.origin === origin) {
+      sameOriginScopes.push([scopeUrl.pathname, scopes[scopeName]]);
+    }
+  }
+  sameOriginScopes.sort(([a], [b]) => b.split("/").length - a.split("/").length);
+  if (sameOriginScopes.length > 0) {
+    for (const [scopePathname, scopeImports] of sameOriginScopes) {
+      if (pathname.startsWith(scopePathname)) {
+        const url = matchImport(specifier, scopeImports);
+        if (url) {
+          return [url, true];
+        }
+      }
+    }
+  }
+  if (origin === new URL($baseURL).origin) {
+    const url = matchImport(specifier, imports);
+    if (url) {
+      return [url, true];
+    }
+  }
+  return [specifier, false];
+}
+function isSupportImportMap() {
+  return !globalThis.HTMLScriptElement?.supports?.("importmap");
+}
+function isBlankImportMap(importMap) {
+  const { imports, scopes } = importMap;
+  if (isObject(imports) && Object.keys(imports).length > 0 || isObject(scopes) && Object.keys(scopes).length > 0) {
+    return false;
+  }
+  return true;
+}
+function isSameImportMap(a, b) {
+  if (!isSameImports(a.imports, b.imports)) {
+    return false;
+  }
+  for (const k in a.scopes) {
+    if (!(k in b.scopes) || !isObject(b.scopes[k])) {
+      return false;
+    }
+    if (!isSameImports(a.scopes[k], b.scopes[k])) {
+      return false;
+    }
+  }
+  return true;
+}
+function matchImport(specifier, imports) {
+  if (specifier in imports) {
+    return imports[specifier];
+  }
+  for (const [k, v] of Object.entries(imports)) {
+    if (k.endsWith("/")) {
+      if (specifier.startsWith(k)) {
+        return v + specifier.slice(k.length);
+      }
+    } else if (specifier.startsWith(k + "/")) {
+      return v + specifier.slice(k.length);
+    }
+  }
+  return null;
+}
+function validateImports(imports) {
+  for (const [k, v] of Object.entries(imports)) {
+    if (!v || typeof v !== "string") {
+      delete imports[k];
+    }
+  }
+}
+function validateScopes(imports) {
+  for (const [k, v] of Object.entries(imports)) {
+    if (isObject(v)) {
+      validateImports(v);
+    } else {
+      delete imports[k];
+    }
+  }
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isSameImports(a, b) {
+  if (Object.keys(a).length !== Object.keys(b).length) {
+    return false;
+  }
+  for (const k in a) {
+    if (a[k] !== b[k]) {
+      return false;
+    }
+  }
+  return true;
+}
+export {
+  createBlankImportMap,
+  importMapFrom,
+  isBlankImportMap,
+  isSameImportMap,
+  isSupportImportMap,
+  parseImportMapFromHtml,
+  parseImportMapFromJson,
+  resolve
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@esm.sh/import-map",
+  "version": "0.1.0",
+  "description": "A import map parser and resolver.",
+  "type": "module",
+  "main": "dist/import-map.mjs",
+  "module": "dist/import-map.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/import-map.mjs",
+      "types": "./types/import-map.d.ts"
+    },
+    "./generator": {
+      "import": "./dist/generator.mjs",
+      "types": "./types/generator.d.ts"
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "esbuild --format=esm --outdir=dist --out-extension:.js=.mjs src/*.ts"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/esm-dev/import-map.git"
+  },
+  "bugs": {
+    "url": "https://github.com/esm-dev/import-map/issues"
+  },
+  "homepage": "https://github.com/esm-dev/import-map#readme",
+  "author": "ije",
+  "license": "MIT"
+}

package/src/generator.ts

@@ -0,0 +1,28 @@
+import type { ImportMap } from "../types/import-map.d.ts";
+
+let cdnOrigin = "https://esm.sh";
+
+export function setCDNOrigin(origin: string): void {
+  const url = new URL(origin);
+  cdnOrigin = url.origin;
+}
+
+/** Add a module to the import map. */
+export function add(importMap: ImportMap, specifier: string): Promise<void> {
+  throw new Error("Not implemented");
+}
+
+/** Update a module in the import map. */
+export function update(importMap: ImportMap, specifier: string, version: string): Promise<void> {
+  throw new Error("Not implemented");
+}
+
+/** Remove a module from the import map. */
+export function remove(importMap: ImportMap): Promise<void> {
+  throw new Error("Not implemented");
+}
+
+/** Tidy the import map. */
+export function tidy(importMap: ImportMap): Promise<void> {
+  throw new Error("Not implemented");
+}

package/src/import-map.ts

@@ -0,0 +1,171 @@
+import type { ImportMap } from "../types/import-map.d.ts";
+
+/** Create a blank import map. */
+export function createBlankImportMap(baseURL?: string): ImportMap {
+  return {
+    $baseURL: new URL(baseURL ?? ".", "file:///").href,
+    imports: {},
+    scopes: {},
+  };
+}
+
+/** Create an import map from the given object. */
+export function importMapFrom(v: any, baseURL?: string): ImportMap {
+  const im = createBlankImportMap(baseURL);
+  if (isObject(v)) {
+    const { imports, scopes } = v;
+    if (isObject(imports)) {
+      validateImports(imports);
+      im.imports = imports as ImportMap["imports"];
+    }
+    if (isObject(scopes)) {
+      validateScopes(scopes);
+      im.scopes = scopes as ImportMap["scopes"];
+    }
+  }
+  return im;
+}
+
+/** Parse the import map from JSON. */
+export function parseImportMapFromJson(json: string, baseURL?: string): ImportMap {
+  const importMap: ImportMap = {
+    $baseURL: new URL(baseURL ?? ".", "file:///").href,
+    imports: {},
+    scopes: {},
+  };
+  const v = JSON.parse(json);
+  if (isObject(v)) {
+    const { imports, scopes } = v;
+    if (isObject(imports)) {
+      validateImports(imports);
+      importMap.imports = imports as ImportMap["imports"];
+    }
+    if (isObject(scopes)) {
+      validateScopes(scopes);
+      importMap.scopes = scopes as ImportMap["scopes"];
+    }
+  }
+  return importMap;
+}
+
+/** Parse the import map from the given HTML. (requires Browser environment) */
+export function parseImportMapFromHtml(html: string, baseURL?: string): ImportMap {
+  const tplEl = document.createElement("template");
+  tplEl.innerHTML = html;
+  const scriptEl: HTMLScriptElement | null = tplEl.content.querySelector("script[type='importmap']");
+  if (scriptEl) {
+    return parseImportMapFromJson(scriptEl.textContent!, baseURL);
+  }
+  return createBlankImportMap(baseURL);
+}
+
+/** Resolve the specifier with the import map. */
+export function resolve(importMap: ImportMap, specifier: string, containingFile: string): [string, boolean] {
+  const { $baseURL, imports, scopes } = importMap;
+  const { origin, pathname } = new URL(containingFile, $baseURL);
+  const sameOriginScopes: [string, ImportMap["imports"]][] = [];
+  for (const scopeName in scopes) {
+    const scopeUrl = new URL(scopeName, $baseURL);
+    if (scopeUrl.origin === origin) {
+      sameOriginScopes.push([scopeUrl.pathname, scopes[scopeName]]);
+    }
+  }
+  sameOriginScopes.sort(([a], [b]) => b.split("/").length - a.split("/").length);
+  if (sameOriginScopes.length > 0) {
+    for (const [scopePathname, scopeImports] of sameOriginScopes) {
+      if (pathname.startsWith(scopePathname)) {
+        const url = matchImport(specifier, scopeImports);
+        if (url) {
+          return [url, true];
+        }
+      }
+    }
+  }
+  if (origin === new URL($baseURL).origin) {
+    const url = matchImport(specifier, imports);
+    if (url) {
+      return [url, true];
+    }
+  }
+  return [specifier, false];
+}
+
+/** Check if current browser supports import maps. */
+export function isSupportImportMap(): boolean {
+  return !(globalThis.HTMLScriptElement?.supports?.("importmap"));
+}
+
+/** Check if the import map is blank. */
+export function isBlankImportMap(importMap: ImportMap) {
+  const { imports, scopes } = importMap;
+  if ((isObject(imports) && Object.keys(imports).length > 0) || (isObject(scopes) && Object.keys(scopes).length > 0)) {
+    return false;
+  }
+  return true;
+}
+
+/** Check if the given two import maps are the same. */
+export function isSameImportMap(a: ImportMap, b: ImportMap): boolean {
+  if (!isSameImports(a.imports, b.imports)) {
+    return false;
+  }
+  for (const k in a.scopes) {
+    if (!(k in b.scopes) || !isObject(b.scopes[k])) {
+      return false;
+    }
+    if (!isSameImports(a.scopes[k], b.scopes[k])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function matchImport(specifier: string, imports: ImportMap["imports"]): string | null {
+  if (specifier in imports) {
+    return imports[specifier];
+  }
+  for (const [k, v] of Object.entries(imports)) {
+    if (k.endsWith("/")) {
+      if (specifier.startsWith(k)) {
+        return v + specifier.slice(k.length);
+      }
+    } else if (specifier.startsWith(k + "/")) {
+      return v + specifier.slice(k.length);
+    }
+  }
+  return null;
+}
+
+function validateImports(imports: Record<string, unknown>) {
+  for (const [k, v] of Object.entries(imports)) {
+    if (!v || typeof v !== "string") {
+      delete imports[k];
+    }
+  }
+}
+
+function validateScopes(imports: Record<string, unknown>) {
+  for (const [k, v] of Object.entries(imports)) {
+    if (isObject(v)) {
+      validateImports(v);
+    } else {
+      delete imports[k];
+    }
+  }
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isSameImports(a: Record<string, string>, b: Record<string, string>): boolean {
+  if (Object.keys(a).length !== Object.keys(b).length) {
+    return false;
+  }
+  for (const k in a) {
+    if (a[k] !== b[k]) {
+      return false;
+    }
+  }
+  return true;
+}

package/types/generator.d.ts

@@ -0,0 +1,4 @@
+import type { ImportMap } from "./import-map.d.ts";
+
+/** Search a NPM package from esm.sh CDN and add it to the import map. */
+export function addImport(importMap: ImportMap, specifier: string): void;

package/types/import-map.d.ts

@@ -0,0 +1,31 @@
+/** The import maps follow the spec at https://wicg.github.io/import-maps/. */
+export interface ImportMap {
+  $src?: string;
+  $baseURL: string;
+  imports: Record<string, string>;
+  scopes: Record<string, Record<string, string>>;
+}
+
+/** Create a blank import map. */
+export function createBlankImportMap(): ImportMap;
+
+/** Create an import map from the given object. */
+export function importMapFrom(v: any, baseURL?: string): ImportMap;
+
+/** Parse the import map from JSON. */
+export function parseImportMapFromJson(json: string, baseURL?: string): ImportMap;
+
+/** Parse the import map from the given HTML. (requires Browser environment) */
+export function parseImportMapFromHtml(html: string, baseURL?: string): ImportMap;
+
+/** Resolve the specifier with the import map. */
+export function resolve(importMap: ImportMap, specifier: string, containingFile: string): string;
+
+/** Check if current browser supports import maps. */
+export function isSupportImportMap(): boolean;
+
+/** Check if the import map is blank. */
+export function isBlankImportMap(importMap: ImportMap): boolean;
+
+/** Check if the given two import maps are the same. */
+export function isSameImportMap(a: ImportMap, b: ImportMap): boolean;