@esm.sh/import-map 0.2.1 → 0.3.0

package/dist/index.mjs

@@ -1,5 +1,563 @@
-export * from "./add.ts";
-export * from "./blank.ts";
-export * from "./parse.ts";
-export * from "./resolve.ts";
-export * from "./support.ts";
+// src/add.ts
+import { satisfies, valid } from "semver";
+var KNOWN_TARGETS = /* @__PURE__ */ new Set([
+  "es2015",
+  "es2016",
+  "es2017",
+  "es2018",
+  "es2019",
+  "es2020",
+  "es2021",
+  "es2022",
+  "es2023",
+  "es2024",
+  "esnext"
+]);
+var ESM_SEGMENTS = /* @__PURE__ */ new Set([
+  "es2015",
+  "es2016",
+  "es2017",
+  "es2018",
+  "es2019",
+  "es2020",
+  "es2021",
+  "es2022",
+  "es2023",
+  "es2024",
+  "esnext",
+  "denonext",
+  "deno",
+  "node"
+]);
+var SPECIFIER_MARK_SEPARATOR = "\0";
+var META_CACHE = /* @__PURE__ */ new Map();
+async function addImport(importMap, specifier, noSRI) {
+  const imp = parseImportSpecifier(specifier);
+  const config = importMap.config ?? {};
+  const target = normalizeTarget(config.target);
+  const cdnOrigin = getCdnOrigin(config.cdn);
+  const meta = await fetchImportMeta(cdnOrigin, imp, target);
+  const mark = /* @__PURE__ */ new Set();
+  await addImportImpl(importMap, mark, meta, false, void 0, cdnOrigin, target, noSRI ?? false);
+}
+async function addImportImpl(importMap, mark, imp, indirect, targetImports, cdnOrigin, target, noSRI) {
+  const markedSpecifier = `${specifierOf(imp)}${SPECIFIER_MARK_SEPARATOR}${imp.version}`;
+  if (mark.has(markedSpecifier)) {
+    return;
+  }
+  mark.add(markedSpecifier);
+  const cdnScopeKey = `${cdnOrigin}/`;
+  const cdnScopeImports = importMap.scopes?.[cdnScopeKey];
+  const imports = indirect ? targetImports ?? ensureScope(importMap, cdnScopeKey) : importMap.imports;
+  const moduleUrl = moduleUrlOf(cdnOrigin, target, imp);
+  const currentSpecifier = specifierOf(imp);
+  imports[currentSpecifier] = moduleUrl;
+  await updateIntegrity(importMap, imp, moduleUrl, cdnOrigin, target, noSRI);
+  if (!indirect) {
+    if (cdnScopeImports) {
+      delete cdnScopeImports[currentSpecifier];
+    }
+    pruneEmptyScopes(importMap);
+  }
+  const allDeps = [
+    ...imp.peerImports.map((pathname) => ({ pathname, isPeer: true })),
+    ...imp.imports.map((pathname) => ({ pathname, isPeer: false }))
+  ];
+  await Promise.all(
+    allDeps.map(async ({ pathname, isPeer }) => {
+      if (pathname.startsWith("/node/")) {
+        return;
+      }
+      const depImport = parseEsmPath(pathname);
+      if (depImport.name === imp.name) {
+        depImport.version = imp.version;
+      }
+      const depSpecifier = specifierOf(depImport);
+      const existingUrl = importMap.imports[depSpecifier] ?? importMap.scopes?.[cdnScopeKey]?.[depSpecifier];
+      let scopedTargetImports = targetImports;
+      if (existingUrl?.startsWith(`${cdnOrigin}/`)) {
+        const existingImport = parseEsmPath(existingUrl);
+        const existingVersion = valid(existingImport.version);
+        if (existingVersion && depImport.version === existingImport.version) {
+          return;
+        }
+        if (existingVersion && depImport.version && !valid(depImport.version)) {
+          if (satisfies(existingVersion, depImport.version, { includePrerelease: true })) {
+            return;
+          }
+          if (isPeer) {
+            console.warn(
+              `incorrect peer dependency(unmeet ${depImport.version}): ${depImport.name}@${existingVersion}`
+            );
+            return;
+          }
+          const scope = `${cdnOrigin}/${esmSpecifierOf(imp)}/`;
+          scopedTargetImports = ensureScope(importMap, scope);
+        }
+      }
+      const depMeta = await fetchImportMeta(cdnOrigin, depImport, target);
+      await addImportImpl(importMap, mark, depMeta, !isPeer, scopedTargetImports, cdnOrigin, target, noSRI);
+    })
+  );
+  pruneEmptyScopes(importMap);
+}
+async function updateIntegrity(importMap, imp, moduleUrl, cdnOrigin, target, noSRI) {
+  if (noSRI) {
+    if (importMap.integrity) {
+      delete importMap.integrity[moduleUrl];
+    }
+    return;
+  }
+  if (!hasExternalImports(imp)) {
+    if (imp.integrity) {
+      importMap.integrity ??= {};
+      importMap.integrity[moduleUrl] = imp.integrity;
+    }
+    return;
+  }
+  const integrityMeta = await fetchImportMeta(
+    cdnOrigin,
+    {
+      name: imp.name,
+      version: imp.version,
+      subPath: imp.subPath,
+      github: imp.github,
+      jsr: imp.jsr,
+      external: true,
+      dev: imp.dev
+    },
+    target
+  );
+  if (integrityMeta.integrity) {
+    importMap.integrity ??= {};
+    importMap.integrity[moduleUrl] = integrityMeta.integrity;
+  }
+}
+function parseImportSpecifier(specifier) {
+  let source = specifier.trim();
+  const imp = {
+    name: "",
+    version: "",
+    subPath: "",
+    github: false,
+    jsr: false,
+    external: false,
+    dev: false
+  };
+  if (source.startsWith("gh:")) {
+    imp.github = true;
+    source = source.slice(3);
+  } else if (source.startsWith("jsr:")) {
+    imp.jsr = true;
+    source = source.slice(4);
+  }
+  let scopeName = "";
+  if ((source.startsWith("@") || imp.github) && source.includes("/")) {
+    [scopeName, source] = splitByFirst(source, "/");
+  }
+  let packageAndVersion = "";
+  [packageAndVersion, imp.subPath] = splitByFirst(source, "/");
+  [imp.name, imp.version] = splitByFirst(packageAndVersion, "@");
+  if (scopeName) {
+    imp.name = `${scopeName}/${imp.name}`;
+  }
+  if (!imp.name) {
+    throw new Error(`invalid package name or version: ${specifier}`);
+  }
+  return imp;
+}
+function normalizeTarget(target) {
+  if (target && KNOWN_TARGETS.has(target)) {
+    return target;
+  }
+  return "es2022";
+}
+function getCdnOrigin(cdn) {
+  if (cdn && (cdn.startsWith("https://") || cdn.startsWith("http://"))) {
+    return cdn.replace(/\/+$/, "");
+  }
+  return "https://esm.sh";
+}
+function specifierOf(imp) {
+  const prefix = imp.github ? "gh:" : imp.jsr ? "jsr:" : "";
+  return `${prefix}${imp.name}${imp.subPath ? `/${imp.subPath}` : ""}`;
+}
+function esmSpecifierOf(imp) {
+  const prefix = imp.github ? "gh/" : imp.jsr ? "jsr/" : "";
+  const external = hasExternalImports(imp) ? "*" : "";
+  return `${prefix}${external}${imp.name}@${imp.version}`;
+}
+function registryPrefix(imp) {
+  if (imp.github) {
+    return "gh/";
+  }
+  if (imp.jsr) {
+    return "jsr/";
+  }
+  return "";
+}
+function hasExternalImports(meta) {
+  if (meta.peerImports.length > 0) {
+    return true;
+  }
+  for (const dep of meta.imports) {
+    if (!dep.startsWith("/node/") && !dep.startsWith(`/${meta.name}@`)) {
+      return true;
+    }
+  }
+  return false;
+}
+function moduleUrlOf(cdnOrigin, target, imp) {
+  let url = `${cdnOrigin}/${esmSpecifierOf(imp)}/${target}/`;
+  if (imp.subPath) {
+    if (imp.dev || imp.subPath === "jsx-dev-runtime") {
+      url += `${imp.subPath}.development.mjs`;
+    } else {
+      url += `${imp.subPath}.mjs`;
+    }
+    return url;
+  }
+  const fileName = imp.name.includes("/") ? imp.name.split("/").at(-1) : imp.name;
+  return `${url}${fileName}.mjs`;
+}
+async function fetchImportMeta(cdnOrigin, imp, target) {
+  const star = imp.external ? "*" : "";
+  const version = imp.version ? `@${imp.version}` : "";
+  const subPath = imp.subPath ? `/${imp.subPath}` : "";
+  const targetQuery = target !== "es2022" ? `&target=${encodeURIComponent(target)}` : "";
+  const url = `${cdnOrigin}/${star}${registryPrefix(imp)}${imp.name}${version}${subPath}?meta${targetQuery}`;
+  const cached = META_CACHE.get(url);
+  if (cached) {
+    return cached;
+  }
+  const pending = (async () => {
+    const res = await fetch(url);
+    if (res.status === 404) {
+      throw new Error(`package not found: ${imp.name}${version}${subPath}`);
+    }
+    if (!res.ok) {
+      throw new Error(`unexpected http status ${res.status}: ${await res.text()}`);
+    }
+    const bodyText = await res.text();
+    let data;
+    try {
+      data = JSON.parse(bodyText);
+    } catch {
+      throw new Error(`invalid meta response from ${url}: ${bodyText.slice(0, 200)}`);
+    }
+    return {
+      name: data.name ?? imp.name,
+      version: data.version ?? imp.version,
+      subPath: imp.subPath,
+      github: imp.github,
+      jsr: imp.jsr,
+      external: imp.external,
+      dev: imp.dev,
+      module: data.module ?? "",
+      integrity: data.integrity ?? "",
+      exports: data.exports ?? [],
+      imports: data.imports ?? [],
+      peerImports: data.peerImports ?? []
+    };
+  })();
+  META_CACHE.set(url, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    META_CACHE.delete(url);
+    throw error;
+  }
+}
+function ensureScope(importMap, scopeKey) {
+  importMap.scopes ??= {};
+  importMap.scopes[scopeKey] ??= {};
+  return importMap.scopes[scopeKey];
+}
+function pruneEmptyScopes(importMap) {
+  if (!importMap.scopes) {
+    return;
+  }
+  for (const [scope, imports] of Object.entries(importMap.scopes)) {
+    if (Object.keys(imports).length === 0) {
+      delete importMap.scopes[scope];
+    }
+  }
+}
+function parseEsmPath(pathnameOrUrl) {
+  let pathname;
+  if (pathnameOrUrl.startsWith("https://") || pathnameOrUrl.startsWith("http://")) {
+    pathname = new URL(pathnameOrUrl).pathname;
+  } else if (pathnameOrUrl.startsWith("/")) {
+    pathname = splitByFirst(splitByFirst(pathnameOrUrl, "#")[0], "?")[0];
+  } else {
+    throw new Error(`invalid pathname or url: ${pathnameOrUrl}`);
+  }
+  const imp = {
+    name: "",
+    version: "",
+    subPath: "",
+    github: false,
+    jsr: false,
+    external: false,
+    dev: false
+  };
+  if (pathname.startsWith("/gh/")) {
+    imp.github = true;
+    pathname = pathname.slice(3);
+  } else if (pathname.startsWith("/jsr/")) {
+    imp.jsr = true;
+    pathname = pathname.slice(4);
+  }
+  const segs = pathname.split("/").filter(Boolean);
+  if (segs.length === 0) {
+    throw new Error(`invalid pathname: ${pathnameOrUrl}`);
+  }
+  if (segs[0].startsWith("@")) {
+    if (!segs[1]) {
+      throw new Error(`invalid pathname: ${pathnameOrUrl}`);
+    }
+    const [name, version] = splitByLast(segs[1], "@");
+    imp.name = `${segs[0]}/${name}`.replace(/^\*/, "");
+    imp.version = version;
+    segs.splice(0, 2);
+  } else {
+    const [name, version] = splitByLast(segs[0], "@");
+    imp.name = name.replace(/^\*/, "");
+    imp.version = version;
+    segs.splice(0, 1);
+  }
+  let hasTargetSegment = false;
+  if (segs[0] && ESM_SEGMENTS.has(segs[0])) {
+    hasTargetSegment = true;
+    segs.shift();
+  }
+  if (segs.length > 0) {
+    if (hasTargetSegment && pathname.endsWith(".mjs")) {
+      let subPath = segs.join("/");
+      if (subPath.endsWith(".mjs")) {
+        subPath = subPath.slice(0, -4);
+      }
+      if (subPath.endsWith(".development")) {
+        subPath = subPath.slice(0, -12);
+        imp.dev = true;
+      }
+      if (subPath.includes("/") || subPath !== imp.name && !imp.name.endsWith(`/${subPath}`)) {
+        imp.subPath = subPath;
+      }
+    } else {
+      imp.subPath = segs.join("/");
+    }
+  }
+  return imp;
+}
+function splitByFirst(value, separator) {
+  const idx = value.indexOf(separator);
+  if (idx < 0) {
+    return [value, ""];
+  }
+  return [value.slice(0, idx), value.slice(idx + separator.length)];
+}
+function splitByLast(value, separator) {
+  const idx = value.lastIndexOf(separator);
+  if (idx < 0) {
+    return [value, ""];
+  }
+  return [value.slice(0, idx), value.slice(idx + separator.length)];
+}
+
+// src/resolve.ts
+function resolve(importMap, specifier, containingFile) {
+  const baseURL = importMap.baseURL;
+  const referrer = new URL(containingFile, baseURL);
+  const [specifierWithoutHash, hashPart = ""] = specifier.split("#", 2);
+  const [specifierWithoutQuery, queryPart = ""] = specifierWithoutHash.split("?", 2);
+  const hash = hashPart ? `#${hashPart}` : "";
+  const query = queryPart ? `?${queryPart}` : "";
+  const cleanSpecifier = specifierWithoutQuery;
+  const scopes = importMap.scopes ?? {};
+  const scopeEntries = Object.entries(scopes).map(([scopeKey, scopeImports]) => {
+    try {
+      return [new URL(scopeKey, baseURL).toString(), scopeImports];
+    } catch {
+      return [scopeKey, scopeImports];
+    }
+  }).sort((a, b) => compareScopeKeys(a[0], b[0]));
+  for (const [scopeKey, scopeImports] of scopeEntries) {
+    if (!referrer.toString().startsWith(scopeKey)) {
+      continue;
+    }
+    const mapped2 = resolveWith(cleanSpecifier, scopeImports ?? {});
+    if (mapped2) {
+      return [normalizeUrl(baseURL, mapped2) + query + hash, true];
+    }
+  }
+  const mapped = resolveWith(cleanSpecifier, importMap.imports);
+  if (mapped) {
+    return [normalizeUrl(baseURL, mapped) + query + hash, true];
+  }
+  return [cleanSpecifier + query + hash, false];
+}
+function resolveWith(specifier, imports) {
+  if (imports[specifier]) {
+    return imports[specifier];
+  }
+  if (!specifier.includes("/")) {
+    return null;
+  }
+  const prefixKeys = Object.keys(imports).filter((k) => k.endsWith("/") && specifier.startsWith(k)).sort((a, b) => b.length - a.length || (a < b ? 1 : -1));
+  for (const key of prefixKeys) {
+    const value = imports[key];
+    if (value && value.endsWith("/")) {
+      return value + specifier.slice(key.length);
+    }
+  }
+  return null;
+}
+function compareScopeKeys(a, b) {
+  const aSlashCount = a.split("/").length;
+  const bSlashCount = b.split("/").length;
+  if (aSlashCount !== bSlashCount) {
+    return bSlashCount - aSlashCount;
+  }
+  return a < b ? 1 : -1;
+}
+function normalizeUrl(baseURL, path) {
+  if (path.startsWith("/") || path.startsWith("./") || path.startsWith("../")) {
+    return new URL(path, baseURL).toString();
+  }
+  return path;
+}
+
+// src/sanitize.ts
+function sanitizeStringMap(map) {
+  if (!isObject(map)) {
+    return {};
+  }
+  const next = {};
+  for (const [key, value] of Object.entries(map)) {
+    if (typeof value === "string") {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+function sanitizeScopes(scopes) {
+  if (!isObject(scopes)) {
+    return {};
+  }
+  const next = {};
+  for (const [scopeKey, scopeImports] of Object.entries(scopes)) {
+    if (isObject(scopeImports)) {
+      next[scopeKey] = sanitizeStringMap(scopeImports);
+    }
+  }
+  return next;
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/importmap.ts
+var ImportMap = class {
+  #baseURL;
+  config = {};
+  imports = {};
+  scopes = {};
+  integrity = {};
+  constructor(baseURL, init) {
+    this.#baseURL = new URL(baseURL ?? globalThis.location?.href ?? "file:///");
+    if (init) {
+      this.config = sanitizeStringMap(init.config);
+      this.imports = sanitizeStringMap(init.imports);
+      this.scopes = sanitizeScopes(init.scopes);
+      this.integrity = sanitizeStringMap(init.integrity);
+    }
+  }
+  get baseURL() {
+    return this.#baseURL;
+  }
+  get isBlank() {
+    return Object.keys(this.imports).length === 0 && Object.keys(this.scopes).length === 0;
+  }
+  get raw() {
+    const json = {};
+    const config = sortStringMap(this.config);
+    if (Object.keys(config).length > 0) {
+      json.config = config;
+    }
+    const imports = sortStringMap(this.imports);
+    if (Object.keys(imports).length > 0) {
+      json.imports = imports;
+    }
+    const scopes = sortScopes(this.scopes);
+    if (Object.keys(scopes).length > 0) {
+      json.scopes = scopes;
+    }
+    const integrity = sortStringMap(this.integrity);
+    if (Object.keys(integrity).length > 0) {
+      json.integrity = integrity;
+    }
+    return json;
+  }
+  addImport(specifier, noSRI) {
+    return addImport(this, specifier, noSRI);
+  }
+  resolve(specifier, containingFile) {
+    return resolve(this, specifier, containingFile);
+  }
+};
+function sortStringMap(map) {
+  const source = map;
+  const next = {};
+  for (const key of Object.keys(source).sort()) {
+    const value = source[key];
+    if (typeof value === "string") {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+function sortScopes(scopes) {
+  const next = {};
+  for (const scopeKey of Object.keys(scopes).sort()) {
+    const scopeImports = sortStringMap(scopes[scopeKey]);
+    if (Object.keys(scopeImports).length > 0) {
+      next[scopeKey] = scopeImports;
+    }
+  }
+  return next;
+}
+
+// src/parse.ts
+function parseFromJson(json, baseURL) {
+  const im = new ImportMap(baseURL);
+  const v = JSON.parse(json);
+  if (isObject(v)) {
+    const { config, imports, scopes, integrity } = v;
+    im.config = sanitizeStringMap(config);
+    im.imports = sanitizeStringMap(imports);
+    im.scopes = sanitizeScopes(scopes);
+    im.integrity = sanitizeStringMap(integrity);
+  }
+  return im;
+}
+function parseFromHtml(html, baseURL) {
+  const tplEl = document.createElement("template");
+  tplEl.innerHTML = html;
+  const scriptEl = tplEl.content.querySelector("script[type='importmap']");
+  if (scriptEl) {
+    return parseFromJson(scriptEl.textContent, baseURL);
+  }
+  return new ImportMap(baseURL);
+}
+
+// src/support.ts
+function isSupportImportMap() {
+  return !!globalThis.HTMLScriptElement?.supports?.("importmap");
+}
+export {
+  ImportMap,
+  isSupportImportMap,
+  parseFromHtml,
+  parseFromJson
+};

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@esm.sh/import-map",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A import map parser and resolver.",
   "type": "module",
-  "main": "dist/index.mjs",
-  "module": "dist/index.mjs",
-  "types": "types/index.d.ts",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./types/index.d.ts",
   "files": [
-    "dist",
-    "types",
+    "dist/",
+    "types/",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "prepublishOnly": "npm run build",
-    "build": "rm -rf dist && esbuild --format=esm --outdir=dist --out-extension:.js=.mjs src/index.ts src/add.ts src/blank.ts src/parse.ts src/resolve.ts src/support.ts",
+    "build": "rm -rf dist && esbuild --bundle --format=esm --outdir=dist --out-extension:.js=.mjs --external:semver src/index.ts",
     "test": "bun test src/*.test.ts"
   },
   "dependencies": {

package/types/index.d.ts

@@ -1,39 +1,71 @@
-/** The import maps follow the spec at https://wicg.github.io/import-maps/. */
-export interface ImportMap {
-  baseURL?: URL;
-  config?: Record<string, string>;
-  imports: Record<string, string>;
+/**
+ * The import map config.
+ *
+ * The config is not a standard part of the import map spec,
+ * it is used to create the new import url from CDN.
+ */
+export interface ImportMapConfig {
+  /** The CDN origin to use for the import map. defaults to `https://esm.sh` */
+  cdn?: string;
+  /** The build target for the new import url from CDN. defaults to `es2022` */
+  target?: string;
+}
+
+/** The import map raw object. */
+export interface ImportMapRaw {
+  /** The config for generating the new import url from CDN. */
+  config?: ImportMapConfig;
+  /** The imports of the import map. */
+  imports?: Record<string, string>;
+  /** The scopes of the import map. */
   scopes?: Record<string, Record<string, string>>;
+  /** The integrity of the import map. */
   integrity?: Record<string, string>;
 }
 
-/** Create a blank import map. */
-export function createBlankImportMap(baseURL?: string): ImportMap;
+/** The import map class. */
+export class ImportMap {
+  constructor(baseURL?: string | URL, init?: Record<string, any>);
 
-/** Create an import map from the given object. */
-export function importMapFrom(v: any, baseURL?: string): ImportMap;
+  /** The config for generating the new import url from CDN. */
+  config: ImportMapConfig;
 
-/** Parse the import map from a JSON string. */
-export function parseImportMapFromJson(json: string, baseURL?: string): ImportMap;
+  /** The imports of the import map. */
+  imports: Record<string, string>;
 
-/** Parse the import map from the given HTML. (Requires Browser environment) */
-export function parseImportMapFromHtml(html: string, baseURL?: string): ImportMap;
+  /** The scopes of the import map. */
+  scopes: Record<string, Record<string, string>>;
 
-/**
- * Add an import from esm.sh CDN to the import map.
- *
- * @param importMap - The import map to add the import to.
- * @param specifier - The specifier of the import to add.
- * @param noSRI - Whether to add the import without SRI.
- * @returns A promise that resolves when the import is added.
- */
-export function addImport(importMap: ImportMap, specifier: string, noSRI?: boolean): Promise<void>;
+  /** The integrity of the import map. */
+  integrity: Record<string, string>;
+
+  /** The base URL of the import map. */
+  get baseURL(): URL;
+
+  /** Check if the import map is blank. */
+  get isBlank(): boolean;
 
-/** Resolve the specifier with the import map. */
-export function resolve(importMap: ImportMap, specifier: string, containingFile: string): [url: string, ok: boolean];
+  /** Return a clean, key-ordered raw import map object. */
+  get raw(): ImportMapRaw;
+
+  /**
+   * Add an import from esm.sh CDN to the import map.
+   *
+   * @param specifier - The specifier of the import to add.
+   * @param noSRI - Whether to add the import without SRI.
+   * @returns A promise that resolves when the import is added.
+   */
+  addImport(specifier: string, noSRI?: boolean): Promise<void>;
+
+  /** Resolve the specifier with the import map. */
+  resolve(specifier: string, containingFile: string): [url: string, ok: boolean];
+}
+
+/** Parse the import map from a JSON string. */
+export function parseFromJson(json: string, baseURL?: string): ImportMap;
+
+/** Parse the import map from the given HTML. (Requires Browser environment) */
+export function parseFromHtml(html: string, baseURL?: string): ImportMap;
 
 /** Check if current browser supports import maps. */
 export function isSupportImportMap(): boolean;
-
-/** Check if the import map is blank. */
-export function isBlankImportMap(importMap: ImportMap): boolean;