refactor api (fix #131, fix #136, fix #152, fix #172, fix #153)

.gitignore

@@ -7,11 +7,12 @@
 /npm/esbuild-linux-64/bin/esbuild
 /npm/esbuild-linux-arm64/bin/esbuild
 /npm/esbuild-linux-ppc64le/bin/esbuild
+/npm/esbuild-wasm/browser.js
 /npm/esbuild-wasm/esbuild.wasm
 /npm/esbuild-wasm/lib/
 /npm/esbuild-wasm/wasm_exec.js
 /npm/esbuild-windows-64/esbuild.exe
-/pkg/
+/npm/esbuild/lib/
 /scripts/.end-to-end-tests/
 /scripts/.js-api-tests/
 /scripts/.verify-source-map/

CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## Unreleased
+
+* Overhaul public-facing API code
+
+    This is a rewrite of all externally facing API code. It fixes some bugs and inconsistencies, adds some new features, and makes it easier to support various use cases going forward.
+
+    At a high-level, esbuild's API supports two separate operations: "build" and "transform". Building means reading from the file system and writing back to the file system. Transforming takes an input string and generates an output string. You should use the build API if you want to take advantage of esbuild's bundling capability, and you should use the transform API if you want to integrate esbuild as a library inside another tool (e.g. a "minify" plugin). This rewrite ensures the APIs for these two operations are exposed consistently for all ways of interacting with esbuild (both through the CLI and as a library).
+
+    Here are some of the highlights:
+
+    * There is now a public Go API ([#152](https://github.com/evanw/esbuild/issues/152))
+
+        The main API can be found in the [`github.com/evanw/esbuild/pkg/api`](pkg/api/api.go) module. It exposes the exact same features as the JavaScript API. This means you can use esbuild as a JavaScript transformation and bundling library from Go code without having to run esbuild as a child process. There is also the [`github.com/evanw/esbuild/pkg/cli`](pkg/cli/cli.go) module which can be used to wrap the esbuild CLI itself.
+
+    * There are now synchronous JavaScript APIs ([#136](https://github.com/evanw/esbuild/issues/136))
+
+        Sometimes JavaScript source transformations must be synchronous. For example, using esbuild's API to shim `require()` for `.ts` files was previously not possible because esbuild only had an asynchronous transform API.
+
+        This release adds the new `transformSync()` and `buildSync()` synchronous functions to mirror the existing `transform()` and `build()` asynchronous functions. Note that these synchronous calls incur the cost of starting up a new child process each time, so you should only use these instead of `startService()` if you have to (or if you don't care about optimal performance).
+
+    * There is now an experimental browser-based API ([#172](https://github.com/evanw/esbuild/issues/172))
+
+        The `esbuild-wasm` package now has a file called `browser.js` that exposes a `createService()` API which is similar to the esbuild API available in node. You can either import the `esbuild-wasm` package using a bundler that respects the `browser` field in `package.json` or import the `esbuild-wasm/lib/browser.js` file directly.
+
+        This is what esbuild's browser API looks like:
+
+        ```ts
+        interface BrowserOptions {
+          wasmURL: string
+          worker?: boolean
+        }
+
+        interface BrowserService {
+          transform(input: string, options: TransformOptions): Promise<TransformResult>
+          stop(): void
+        }
+
+        declare function createService(options: BrowserOptions): Promise<BrowserService>
+        ```
+
+        You must provide the URL to the `esbuild-wasm/esbuild.wasm` file in `wasmURL`. The optional `worker` parameter can be set to `false` to load the WebAssembly module in the same thread instead of creating a worker thread. Using a worker thread is recommended because it means transforming will not block the main thread.
+
+        This API is experimental and may be changed in the future depending on the feedback it gets.
+
+    * Error messages now use `sourcefile` ([#131](https://github.com/evanw/esbuild/issues/131))
+
+        Errors from transform API calls now use `sourcefile` as the the original file name if present. Previously the file name in error messages was always `/input.js`.
+
 ## 0.4.14
 
 * Do not reorder `"use strict"` after support code ([#173](https://github.com/evanw/esbuild/issues/173))

Makefile

@@ -1,6 +1,6 @@
 ESBUILD_VERSION = $(shell cat version.txt)
 
-esbuild: cmd/esbuild/*.go internal/*/*.go
+esbuild: cmd/esbuild/*.go pkg/*/*.go internal/*/*.go
 	go build ./cmd/esbuild
 
 # These tests are for development
@@ -59,15 +59,16 @@ platform-linux-ppc64le:
 	cd npm/esbuild-linux-ppc64le && npm version "$(ESBUILD_VERSION)" --allow-same-version
 	GOOS=linux GOARCH=ppc64le go build -o npm/esbuild-linux-ppc64le/bin/esbuild ./cmd/esbuild
 
-platform-wasm:
+platform-wasm: | esbuild
 	GOOS=js GOARCH=wasm go build -o npm/esbuild-wasm/esbuild.wasm ./cmd/esbuild
 	cd npm/esbuild-wasm && npm version "$(ESBUILD_VERSION)" --allow-same-version
 	cp "$(shell go env GOROOT)/misc/wasm/wasm_exec.js" npm/esbuild-wasm/wasm_exec.js
-	rm -fr npm/esbuild-wasm/lib && cp -r npm/esbuild/lib npm/esbuild-wasm/lib
-	cat npm/esbuild/lib/main.js | sed 's/WASM = false/WASM = true/' > npm/esbuild-wasm/lib/main.js
+	mkdir -p npm/esbuild-wasm/lib
+	node scripts/esbuild.js ./esbuild --wasm
 
-platform-neutral:
+platform-neutral: | esbuild
 	cd npm/esbuild && npm version "$(ESBUILD_VERSION)" --allow-same-version
+	node scripts/esbuild.js ./esbuild
 
 publish-all: update-version-go test-all
 	make -j7 publish-windows publish-darwin publish-linux publish-linux-arm64 publish-linux-ppc64le publish-wasm publish-neutral
@@ -104,6 +105,7 @@ clean:
 	rm -rf npm/esbuild-linux-arm64/bin
 	rm -rf npm/esbuild-linux-ppc64le/bin
 	rm -f npm/esbuild-wasm/esbuild.wasm npm/esbuild-wasm/wasm_exec.js
+	rm -rf npm/esbuild/lib
 	rm -rf npm/esbuild-wasm/lib
 	go clean -testcache ./internal/...
 

README.md

@@ -215,7 +215,6 @@ Usage:
   esbuild [options] [entry points]
 
 Options:
-  --name=...            The name of the module
   --bundle              Bundle all dependencies into the output files
   --outfile=...         The output file (for one entry point)
   --outdir=...          The output directory (for multiple entry points)
@@ -225,6 +224,7 @@ Options:
   --external:M          Exclude module M from the bundle
   --format=...          Output format (iife, cjs, esm)
   --color=...           Force use of color terminal escapes (true or false)
+  --global-name=...     The name of the global for the IIFE format
 
   --minify              Sets all --minify-* flags
   --minify-whitespace   Remove whitespace
@@ -243,7 +243,7 @@ Advanced options:
   --sourcemap=external      Do not link to the source map with a comment
   --sourcefile=...          Set the source file for the source map (for stdin)
   --error-limit=...         Maximum error count or 0 to disable (default 10)
-  --log-level=...           Disable logging (info, warning, error)
+  --log-level=...           Disable logging (info, warning, error, silent)
   --resolve-extensions=...  A comma-separated list of implicit extensions
   --metafile=...            Write metadata about the build to a JSON file
 
@@ -278,7 +278,6 @@ Example build script:
 const { build } = require('esbuild')
 
 build({
-  stdio: 'inherit',
   entryPoints: ['./src/main.ts'],
   outfile: './dist/main.js',
   minify: true,
@@ -312,12 +311,16 @@ Example usage:
   const esbuild = require('esbuild')
   const service = await esbuild.startService()
 
-  // This can be called many times without the overhead of starting a service
-  const { js } = await service.transform(jsx, { loader: 'jsx' })
-  console.log(js)
+  try {
+    // This can be called many times without the overhead of starting a service
+    const { js } = await service.transform(jsx, { loader: 'jsx' })
+    console.log(js)
+  }
 
-  // The child process can be explicitly killed when it's no longer needed
-  service.stop()
+  finally {
+    // The child process can be explicitly killed when it's no longer needed
+    service.stop()
+  }
 })()
 ```