@statewalker/webrun-bundler 0.0.0-stage → 0.1.1

package/src/resolve.ts

@@ -0,0 +1,116 @@
+import { imports as resolveImports, exports as resolvePackageExports } from "resolve.exports";
+import { dirOf, isFile, joinWithin, parsePackageSpecifier } from "./paths.js";
+import type { Importer, Mount, PackageManifest, PackageStore } from "./types.js";
+
+/** Extensions tried, in order, for a path written without one (or with `.js` for a `.ts` file). */
+const EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
+
+export interface Resolved {
+  mount: Mount;
+  path: string;
+}
+
+/** `path` as written, else with an extension, else its `index` file. */
+async function resolveFile(mount: Mount, path: string): Promise<string | undefined> {
+  if (await isFile(mount, path)) return path;
+  // TypeScript sources import `./x.js` for `./x.ts`.
+  const js = /\.(m|c)?jsx?$/.exec(path);
+  if (js) {
+    const base = path.slice(0, -js[0].length);
+    for (const ext of [`.${js[1] ?? ""}ts`, ".tsx"])
+      if (await isFile(mount, base + ext)) return base + ext;
+  }
+  for (const ext of EXTENSIONS) if (await isFile(mount, path + ext)) return path + ext;
+  const dir = path.endsWith("/") ? path.slice(0, -1) : path;
+  for (const ext of EXTENSIONS)
+    if (await isFile(mount, `${dir}/index${ext}`)) return `${dir}/index${ext}`;
+  return undefined;
+}
+
+type Conditions = { conditions: string[]; require: boolean; browser: boolean };
+
+function exportsTarget(
+  manifest: PackageManifest,
+  entry: string,
+  c: Conditions,
+): string | undefined {
+  try {
+    const out = resolvePackageExports(manifest, entry, {
+      conditions: c.conditions,
+      require: c.require,
+      browser: c.browser,
+    }) as string[] | undefined;
+    return out?.[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/** A package's file for `subpath`: `exports` first, then `module`/`main` (and `browser` when it is a string). */
+async function resolvePackageEntry(
+  mount: Mount,
+  subpath: string | undefined,
+  c: Conditions,
+): Promise<string | undefined> {
+  const manifest = mount.manifest ?? {};
+  const entry = subpath ? `./${subpath}` : ".";
+  if (manifest.exports !== undefined) {
+    const target = exportsTarget(manifest, entry, c);
+    if (!target) return undefined; // not exported: Node refuses it as well
+    return joinWithin(mount.root, mount.root, target);
+  }
+  if (subpath) return resolveFile(mount, joinWithin(mount.root, mount.root, subpath) ?? "");
+  const fields = [
+    ...(c.browser && typeof manifest.browser === "string" ? [manifest.browser] : []),
+    ...(c.require ? [] : [manifest.module]),
+    manifest.main,
+    "index.js",
+  ].filter((f): f is string => typeof f === "string");
+  for (const f of fields) {
+    const p = joinWithin(mount.root, mount.root, f);
+    const file = p && (await resolveFile(mount, p));
+    if (file) return file;
+  }
+  return undefined;
+}
+
+/**
+ * Resolves `spec` as written in `importer`: a path of the same tree (`./x`, `../y.js`,
+ * `/z`), a `#imports` alias of the importer's package, or a package found by `packages`
+ * (with its `exports`, `module` and `main`).
+ */
+export async function resolveSpecifier(
+  spec: string,
+  importer: Importer,
+  packages: PackageStore,
+  c: Conditions,
+): Promise<Resolved | undefined> {
+  const { mount } = importer;
+  if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || spec === ".") {
+    const base = spec.startsWith("/") ? mount.root : dirOf(importer.path);
+    const target = joinWithin(mount.root, base, spec.startsWith("/") ? spec.slice(1) : spec);
+    const path = target && (await resolveFile(mount, target));
+    return path ? { mount, path } : undefined;
+  }
+  if (spec.startsWith("#")) {
+    try {
+      const out = resolveImports(mount.manifest ?? {}, spec, {
+        conditions: c.conditions,
+        require: c.require,
+        browser: c.browser,
+      }) as string[] | undefined;
+      const target = out?.[0];
+      if (!target) return undefined;
+      if (!target.startsWith(".")) return resolveSpecifier(target, importer, packages, c);
+      const path = joinWithin(mount.root, mount.root, target);
+      return path && (await isFile(mount, path)) ? { mount, path } : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  const { name, subpath } = parsePackageSpecifier(spec);
+  const pkg = await packages.get(name, importer);
+  if (!pkg) return undefined;
+  const path = await resolvePackageEntry(pkg, subpath, c);
+  return path && (await isFile(pkg, path)) ? { mount: pkg, path } : undefined;
+}

package/src/types.ts

@@ -0,0 +1,154 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { BuildOptions, build, Message, Metafile, transform } from "esbuild-wasm";
+
+/**
+ * The esbuild API the bundler calls: `esbuild-wasm` (initialized, in browsers and
+ * workers) or native `esbuild` on Node. Only `build` and `transform` are used, and
+ * every file reaches esbuild through the bundler's plugin: esbuild never touches a
+ * file system itself.
+ */
+export interface Esbuild {
+  build: typeof build;
+  transform: typeof transform;
+}
+
+/** The fields of a `package.json` the resolver reads. */
+export interface PackageManifest {
+  name?: string;
+  version?: string;
+  exports?: unknown;
+  imports?: unknown;
+  main?: string;
+  module?: string;
+  browser?: unknown;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/**
+ * A tree of files the bundler reads: the project, or one npm package. Its files get
+ * ids `<prefix><path>` (`~/src/app.ts`, `npm:react@18.3.1/index.js`); the ids are what
+ * the source maps name, so every bundled line traces back to the user's file or to the
+ * package it came from.
+ */
+export interface Mount {
+  /** `~` for the project, `npm:<name>@<version>` for a package. */
+  prefix: string;
+  files: FilesApi;
+  /** The tree's directory in `files` (`/` for a package of its own, `/node_modules/x`). */
+  root: string;
+  /** Its `package.json`, when it has one. */
+  manifest?: PackageManifest;
+}
+
+/** Where an import comes from: a file of a mount. */
+export interface Importer {
+  mount: Mount;
+  /** The importing file's path in `mount.files` (root included). */
+  path: string;
+}
+
+/**
+ * Finds the npm packages bare specifiers name: in `node_modules` folders of a FilesApi
+ * (`nodeModulesPackages`), fetched from a registry on demand (`npmPackages`), or both
+ * (`chainPackages`).
+ */
+export interface PackageStore {
+  /** The package `name` as `importer` sees it; `undefined` when it has none. */
+  get(name: string, importer: Importer): Promise<Mount | undefined>;
+}
+
+/** A specifier left to the runtime (`cloudflare:workers`, `node:fs`): a string ending in `*` is a prefix. */
+export type ExternalPattern = string | RegExp;
+
+export interface BundleOptions {
+  /** `esbuild-wasm` (or native `esbuild` on Node). */
+  esbuild: Esbuild;
+  /** The project's files. */
+  files: FilesApi;
+  /** The project's directory in `files` (default `/`). */
+  root?: string;
+  /** The entry module, a path in the project (`/src/index.ts`). */
+  entry: string;
+  /** Where bare specifiers go (default: `node_modules` folders of `files`). */
+  packages?: PackageStore;
+  /** Specifiers kept as imports for the runtime. `http(s):` and `data:` URLs always are. */
+  external?: ExternalPattern[];
+  /**
+   * Modules the host supplies, by specifier (`cloudflare:workers`, `node:buffer`): their
+   * JavaScript source, or `undefined` to resolve the specifier as usual. They come before
+   * `external`. Their own imports resolve from the project's root; they name themselves
+   * `virtual:<specifier>` in the source map.
+   */
+  modules?: Record<string, string> | ((specifier: string) => string | undefined);
+  /**
+   * Modules whose exports replace the globals of the same name in every bundled file
+   * (esbuild `inject`): specifiers or project paths, resolved like imports (`modules` too).
+   */
+  inject?: string[];
+  /**
+   * `package.json` `exports` conditions besides `import`/`require` and `default`
+   * (default `["browser"]`; a workerd target takes `["workerd", "worker", "browser"]`).
+   */
+  conditions?: string[];
+  /** Output format (default `esm`). */
+  format?: "esm" | "iife" | "cjs";
+  /** esbuild platform (default `browser`): sets `process.env.NODE_ENV` handling and the like. */
+  platform?: "browser" | "node" | "neutral";
+  /** Language target (default `es2022`). */
+  target?: string | string[];
+  /**
+   * Lower `async`/`await`, async generators and `for await` to generators, so that each
+   * `await` resumes through `Promise.prototype.then` (an AsyncLocalStorage polyfill can then
+   * carry its context through it). Source maps follow the lowered code.
+   */
+  lowerAwait?: boolean;
+  minify?: boolean;
+  define?: Record<string, string>;
+  /** Name of the output file: the map is linked as `<outfile>.map` (default `bundle.js`). */
+  outfile?: string;
+  /** `external` (default): `code` links `<outfile>.map`, which `map` holds; `inline`: `code` carries it too. */
+  sourcemap?: "external" | "inline" | false;
+  /** Other esbuild options, applied last (the bundler's plugin and source maps stay). */
+  esbuildOptions?: Partial<BuildOptions>;
+}
+
+/** A source map (version 3). */
+export interface SourceMap {
+  version: 3;
+  file?: string;
+  sources: string[];
+  sourcesContent?: (string | null)[];
+  names: string[];
+  mappings: string;
+  sourceRoot?: string;
+}
+
+export interface BundleResult {
+  code: string;
+  /** The bundle's source map: sources are file ids (`~/src/app.ts`, `npm:pkg@1.0.0/src/x.ts`). */
+  map: SourceMap;
+  metafile: Metafile;
+  warnings: Message[];
+}
+
+export interface TranspileOptions {
+  esbuild: Esbuild;
+  /** The file's id or path: names it in the source map and picks the loader by extension. */
+  path: string;
+  format?: "esm" | "iife" | "cjs";
+  target?: string | string[];
+  lowerAwait?: boolean;
+  minify?: boolean;
+  define?: Record<string, string>;
+  sourcemap?: "external" | "inline";
+}
+
+export interface TranspileResult {
+  code: string;
+  map: SourceMap;
+  warnings: Message[];
+}