@statewalker/webrun-bundler 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+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

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# @statewalker/webrun-bundler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## What it is
+
+A transpiler, resolver and bundler on [esbuild-wasm](https://esbuild.github.io/getting-started/#wasm)
+that reads every file through a
+[`FilesApi`](https://www.npmjs.com/package/@statewalker/webrun-files): a `MemFilesApi` in tests,
+OPFS or a folder the user picked in a browser, a FilesApi served over a `MessagePort` to a worker.
+It never touches `node:fs`, and esbuild never reads a file itself.
+
+Every transformation keeps a source map. TypeScript, JSX, CommonJS-to-ESM, `await` lowering and
+bundling all happen in one esbuild pass, and where a package ships its own map (TypeScript compiled
+to `.js`), that map is composed in. Each line of a bundle traces back to the user's file or to the
+npm package's original source, and the map carries the text of each.
+
+## Why it exists
+
+Code that runs in Durable Objects, workers and browsers is built in places without a disk: in a
+browser worker, in a ServiceWorker, inside a Worker runtime. esbuild-wasm runs there, but it can only
+read what it is handed, and a bundle whose map stops at a package's compiled `dist/` (or at an
+intermediate transform) says little about where an error comes from. This package hands esbuild
+the files from a FilesApi, finds packages in `node_modules` folders or fetches them from the npm
+registry (through `@statewalker/webrun-modules`' `npmRegistrySource`), and keeps the map chain
+unbroken.
+
+## How to use
+
+### Install
+
+```sh
+pnpm add @statewalker/webrun-bundler esbuild-wasm
+```
+
+`esbuild-wasm` is a peer dependency: initialize it once (in a browser, `esbuild.initialize({
+wasmURL })`; on Node it needs nothing) and pass it in. Native `esbuild` works too on Node.
+
+### Bundle a project
+
+```ts
+import * as esbuild from "esbuild-wasm";
+import { getOPFSFilesApi } from "@statewalker/webrun-files-browser";
+import { bundle, chainPackages, nodeModulesPackages, npmPackages } from "@statewalker/webrun-bundler";
+
+await esbuild.initialize({ wasmURL: "/esbuild.wasm" });
+const files = await getOPFSFilesApi();
+
+const { code, map } = await bundle({
+  esbuild,
+  files,
+  root: "/my-project",
+  entry: "/src/index.ts",
+  // node_modules in the FilesApi first, then the npm registry
+  packages: chainPackages(nodeModulesPackages(), npmPackages()),
+  external: ["cloudflare:*", "node:*"], // left to the runtime
+  conditions: ["workerd", "worker", "browser"],
+  lowerAwait: true,
+});
+// `code` ends with `//# sourceMappingURL=bundle.js.map`; `map` is that map.
+```
+
+`map.sources` are file ids: `~/src/index.ts` for the project, `npm:<name>@<version>/<file>` for
+packages (`npm:hono@4.6.3/src/hono.ts` when the package ships its TypeScript and a map).
+
+### Transpile one file
+
+```ts
+import { transpile } from "@statewalker/webrun-bundler";
+
+const { code, map } = await transpile(source, { esbuild, path: "~/src/f.ts", lowerAwait: true });
+```
+
+### `bundle` options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `esbuild` | required | `esbuild-wasm` (or native `esbuild`) |
+| `files`, `root` | required, `/` | the project's FilesApi and its directory |
+| `entry` | required | the entry module, a project path |
+| `packages` | `nodeModulesPackages()` | where bare specifiers go |
+| `external` | `[]` | specifiers kept as imports; `"x:*"` is a prefix. `http(s):`/`data:` always are |
+| `modules` | | modules the host supplies by specifier (a record, or a function returning source or `undefined`); mapped as `virtual:<specifier>` |
+| `inject` | | modules whose exports replace same-named globals in every file (esbuild `inject`), resolved like imports |
+| `conditions` | `["browser"]` | `exports` conditions besides `import`/`require` and `default` |
+| `format`, `platform`, `target` | `esm`, `browser`, `es2022` | as in esbuild |
+| `lowerAwait` | `false` | lower `async`/`await`, async generators and `for await` to generators |
+| `minify`, `define` | | as in esbuild |
+| `outfile` | `bundle.js` | the name the map link uses (`<outfile>.map`) |
+| `sourcemap` | `external` | `inline` also puts the map in `code` |
+| `esbuildOptions` | | other esbuild options, applied last (the plugin and source maps stay) |
+
+## Examples
+
+### Packages from the registry, at the versions the project asks for
+
+`npmPackages()` takes each package at the range the importer's `package.json` declares (the
+project's for project files, the package's own for its dependencies), else the latest. One range
+loads once, and two ranges that land on one version share it. Pass `source` to fetch from
+elsewhere (any `@statewalker/webrun-modules` `Source`).
+
+### The host supplies its runtime's modules
+
+A runtime embedding the bundle provides modules the bundle cannot read from files: `cloudflare:workers`,
+`node:*` polyfills from its own realm, its own `Response`. `modules` gives their source by
+specifier (a function can cover a whole family), and `inject` replaces globals with a module's
+exports:
+
+```ts
+await bundle({
+  esbuild, files, entry: "/src/index.ts",
+  modules: (spec) =>
+    spec.startsWith("node:")
+      ? `const m = globalThis.__host.get(${JSON.stringify(spec)}); export default m; export const { Buffer } = m;`
+      : undefined,
+  inject: ["/src/runtime-globals.ts"],
+});
+```
+
+### `lowerAwait` for an AsyncLocalStorage polyfill
+
+Browsers have no async context propagation yet (TC39 AsyncContext is at Stage 2). A polyfill that
+patches `Promise.prototype.then` cannot see a native `await`; with `lowerAwait`, each `await`
+resumes through `then`, and the source map follows the lowered code.
+
+### Tests
+
+`pnpm test` runs the Node suite: esbuild-wasm on `MemFilesApi` projects, with packages from a fake
+registry and from `node_modules`, checking that the bundles run and that their lines trace to the
+right files and lines. `pnpm test:browser` runs `e2e/browser.mjs`: a Dedicated Worker in Chromium
+bundles a project stored in OPFS with esbuild-wasm and checks the same.
+
+## Internals
+
+### One esbuild pass, one plugin
+
+The bundler is an esbuild plugin. `onResolve` resolves every specifier (relative paths with
+extension and `index` resolution, `./x.js` written for `./x.ts`, `#imports`, packages with their
+`exports` conditions, `module` and `main`) and names the file by its id; `onLoad` reads it from its
+FilesApi. esbuild does the rest. There is no intermediate file, so there is no intermediate map
+to lose.
+
+### Input maps are inlined, and their sources renamed
+
+esbuild composes a loaded file's map with its own only when the map is inline. A published file
+usually links one (`//# sourceMappingURL=index.js.map`): the bundler reads it from the package's
+tree, rewrites its sources to ids of that tree (`../src/index.ts` → `npm:pkg@1.0.0/src/index.ts`),
+fills a missing `sourcesContent` from the package's files, and inlines it. A map that is missing
+or broken is dropped: the file then maps to itself.
+
+### pnpm layouts
+
+In a pnpm install, `node_modules/x` is a symlink into `node_modules/.pnpm`, and `x`'s own
+dependencies sit next to its real directory there. Node follows the real path; a FilesApi sees
+only the link. When the usual walk up the `node_modules` folders finds nothing,
+`nodeModulesPackages` tries each ancestor's `node_modules/.pnpm/node_modules`, where pnpm links
+every installed package (with one version per name: a package that two dependencies need in
+different versions resolves to the hoisted one).
+
+### What has no source
+
+esbuild's own runtime (`__commonJS`, `__toESM`, `__async` when lowering), the wrapper lines of a
+CommonJS module, and the bundle's closing `export { … }` are written by esbuild, not by an input:
+they have no mapping. Every other line maps to a file.
+
+### What does not work yet
+
+- The `browser` field as a map of substitutions (only a string `browser` entry is used).
+- CSS bundling beyond what esbuild's `css` loader does; `@import` of packages resolves like JS.
+- Packages are matched by name and range, not deduplicated across ranges that resolve to
+  different versions (as npm would install both).
+
+### Dependencies
+
+`@statewalker/webrun-files` (FilesApi), `@statewalker/webrun-modules` (the npm registry `Source`,
+loaded only when `npmPackages()` falls back to it), `resolve.exports` (`exports`/`imports` maps);
+`esbuild-wasm` as a peer.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,225 @@
+import { FilesApi } from "@statewalker/webrun-files";
+import { BuildOptions, Loader, Message, Metafile, build, transform } from "esbuild-wasm";
+import { Source } from "@statewalker/webrun-modules";
+//#region src/types.d.ts
+/**
+ * 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.
+ */
+interface Esbuild {
+  build: typeof build;
+  transform: typeof transform;
+}
+/** The fields of a `package.json` the resolver reads. */
+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.
+ */
+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. */
+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`).
+ */
+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. */
+type ExternalPattern = string | RegExp;
+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";
+  /** Other esbuild options, applied last (the bundler's plugin and source maps stay). */
+  esbuildOptions?: Partial<BuildOptions>;
+}
+/** A source map (version 3). */
+interface SourceMap {
+  version: 3;
+  file?: string;
+  sources: string[];
+  sourcesContent?: (string | null)[];
+  names: string[];
+  mappings: string;
+  sourceRoot?: string;
+}
+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[];
+}
+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";
+}
+interface TranspileResult {
+  code: string;
+  map: SourceMap;
+  warnings: Message[];
+}
+//#endregion
+//#region src/bundle.d.ts
+export declare const loaderFor: (path: string) => Loader;
+/**
+ * Bundles `entry` of a project into one module with esbuild (esbuild-wasm in browsers).
+ * Every file is read through FilesApi (the project's, or a package's from `packages`):
+ * esbuild resolves and loads nothing itself. esbuild transpiles TypeScript and JSX,
+ * converts CommonJS, lowers `await` when asked, and bundles, all in one pass, and its
+ * source map goes back through each step to the files it read; where a package ships
+ * its own map (TypeScript compiled to `.js`), to the package's original source. The
+ * map's sources are file ids: `~/src/app.ts`, `npm:pkg@1.2.3/src/index.ts`.
+ */
+export declare function bundle(opts: BundleOptions): Promise<BundleResult>;
+/**
+ * Transpiles one file (TypeScript, JSX, modern syntax down to `target`; `await` lowered
+ * when asked) with a source map back to it. A map the code carries (`sourceMappingURL`,
+ * inline) is composed in, so the result still traces to the original.
+ */
+export declare function transpile(code: string, opts: TranspileOptions): Promise<TranspileResult>;
+//#endregion
+//#region src/input-maps.d.ts
+/**
+ * A file's own source map, made usable by esbuild, which reads only maps inlined in
+ * the file it loads (it cannot follow a linked `.map` through a FilesApi):
+ *
+ * - a linked map (`//# sourceMappingURL=index.js.map`) is read from the same tree and
+ *   inlined; an inline `data:` map is kept;
+ * - its sources become ids of the same tree (`npm:pkg@1.0.0/src/index.ts`), so the
+ *   bundle's map names the package's original files, not the published JavaScript;
+ * - missing `sourcesContent` is filled from the tree when the original file ships
+ *   with the package.
+ *
+ * esbuild then composes it with its own: a bundled line traces to the original source.
+ * A map that is missing or unreadable is dropped (the file maps to itself).
+ */
+export declare function inlineInputMap(mount: Mount, path: string, code: string): Promise<string>;
+//#endregion
+//#region src/packages.d.ts
+/**
+ * Packages from `node_modules` folders, found as Node finds them: in the importing
+ * file's directory and each parent, inside the importer's own FilesApi. A package
+ * installed in the project (or in another package's `node_modules`) is read where it is.
+ *
+ * pnpm layouts: a package's own dependencies sit next to its real directory in
+ * `node_modules/.pnpm`, which Node reaches through the symlink's real path and a FilesApi
+ * cannot see. When the walk finds nothing, each ancestor's `node_modules/.pnpm/node_modules`
+ * (pnpm's hoisted links to every installed package) is tried too.
+ */
+export declare function nodeModulesPackages(): PackageStore;
+/**
+ * Packages fetched on demand (default: the npm registry, through webrun-modules'
+ * `npmRegistrySource`) and kept in memory: each one is its own FilesApi tree. The
+ * version is the range the importer's `package.json` declares (the project's for the
+ * project's files), else the latest; one range loads once.
+ */
+export declare function npmPackages(opts?: {
+  source?: Source;
+}): PackageStore;
+/** The first store that has the package wins (`node_modules` first, then the registry). */
+export declare function chainPackages(...stores: PackageStore[]): PackageStore;
+//#endregion
+//#region src/resolve.d.ts
+interface Resolved {
+  mount: Mount;
+  path: string;
+}
+type Conditions = {
+  conditions: string[];
+  require: boolean;
+  browser: boolean;
+};
+/**
+ * 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 declare function resolveSpecifier(spec: string, importer: Importer, packages: PackageStore, c: Conditions): Promise<Resolved | undefined>;
+//#endregion
+export type { BundleOptions, BundleResult, Esbuild, ExternalPattern, Importer, Mount, PackageManifest, PackageStore, SourceMap, TranspileOptions, TranspileResult };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/bundle.ts","../src/input-maps.ts","../src/packages.ts","../src/resolve.ts"],"mappings":";;;;;;;;;;UASiB;EACf,cAAc;EACd,kBAAkB;;;UAIH;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA,eAAe;EACf,mBAAmB;EACnB,uBAAuB;EACvB,kBAAkB;GACjB;;;;;;;;UASc;;EAEf;EACA,OAAO;;EAEP;;EAEA,WAAW;;;UAII;EACf,OAAO;;EAEP;;;;;;;UAQe;;EAEf,IAAI,cAAc,UAAU,WAAW,QAAQ;;;KAIrC,2BAA2B;UAEtB;;EAEf,SAAS;;EAET,OAAO;;EAEP;;EAEA;;EAEA,WAAW;;EAEX,WAAW;;;;;;;EAOX,UAAU,2BAA2B;;;;;EAKrC;;;;;EAKA;;EAEA;;EAEA;;EAEA;;;;;;EAMA;EACA;EACA,SAAS;;EAET;;EAEA;;EAEA,iBAAiB,QAAQ;;;UAIV;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;;EAEA,KAAK;EACL,UAAU;EACV,UAAU;;UAGK;EACf,SAAS;;EAET;EACA;EACA;EACA;EACA;EACA,SAAS;EACT;;UAGe;EACf;EACA,KAAK;EACL,UAAU;;;;qBChHC,YAAS,iBAAmB;;;;;;;;;;wBA+CnB,OAAO,MAAM,gBAAgB,QAAQ;;;;;;wBA2IrC,UAAU,cAAc,MAAM,mBAAmB,QAAQ;;;;;;;;;;;;;;;;;wBCnMzD,eAAe,OAAO,OAAO,cAAc,eAAe;;;;;;;;;;;;;wBCdhE,uBAAuB;;;;;;;wBA0DvB,YAAY;EAAQ,SAAS;IAAgB;;wBAkC7C,iBAAiB,QAAQ,iBAAiB;;;UCtGzC;EACf,OAAO;EACP;;KAoBG;EAAe;EAAsB;EAAkB;;;;;;;wBAoDtC,iBACpB,cACA,UAAU,UACV,UAAU,cACV,GAAG,aACF,QAAQ"}