Fix TypeScript-specific class transform edge case (#3559)

The previous release introduced an optimization that avoided transforming super() in the class constructor for TypeScript code compiled with useDefineForClassFields set to false if all class instance fields have no initializers. The rationale was that in this case, all class instance fields are omitted in the output so no changes to the constructor are needed. However, if all of this is the case and there are #private instance fields with initializers, those private instance field initializers were still being moved into the constructor. This was problematic because they were being inserted before the call to super() (since super() is now no longer transformed in that case). This release introduces an additional optimization that avoids moving the private instance field initializers into the constructor in this edge case, which generates smaller code, matches the TypeScript compiler's output more closely, and avoids this bug:

// Original code
class Foo extends Bar {
  #private = 1;
  public: any;
  constructor() {
    super();
  }
}

// Old output (with esbuild v0.19.9)
class Foo extends Bar {
  constructor() {
    super();
    this.#private = 1;
  }
  #private;
}

// Old output (with esbuild v0.19.10)
class Foo extends Bar {
  constructor() {
    this.#private = 1;
    super();
  }
  #private;
}

// New output
class Foo extends Bar {
  #private = 1;
  constructor() {
    super();
  }
}

Minifier: allow reording a primitive past a side-effect (#3568)

The minifier previously allowed reordering a side-effect past a primitive, but didn't handle the case of reordering a primitive past a side-effect. This additional case is now handled:

// Original code
function f() {
  let x = false;
  let y = x;
  const boolean = y;
  let frag = $.template(`<p contenteditable="${boolean}">hello world</p>`);
  return frag;
}

// Old output (with --minify)
function f(){const e=!1;return $.template(`<p contenteditable="${e}">hello world</p>`)}

// New output (with --minify)
function f(){return $.template('<p contenteditable="false">hello world</p>')}

Minifier: consider properties named using known Symbol instances to be side-effect free (#3561)

Many things in JavaScript can have side effects including property accesses and ToString operations, so using a symbol such as Symbol.iterator as a computed property name is not obviously side-effect free. This release adds a special case for known Symbol instances so that they are considered side-effect free when used as property names. For example, this class declaration will now be considered side-effect free:

class Foo {
  *[Symbol.iterator]() {
  }
}

Provide the stop() API in node to exit esbuild's child process (#3558)

You can now call stop() in esbuild's node API to exit esbuild's child process to reclaim the resources used. It only makes sense to do this for a long-lived node process when you know you will no longer be making any more esbuild API calls. It is not necessary to call this to allow node to exit, and it's advantageous to not call this in between calls to esbuild's API as sharing a single long-lived esbuild child process is more efficient than re-creating a new esbuild child process for every API call. This API call used to exist but was removed in version 0.9.0. This release adds it back due to a user request.

Fix glob imports in TypeScript files (#3319)

This release fixes a problem where bundling a TypeScript file containing a glob import could emit a call to a helper function that doesn't exist. The problem happened because esbuild's TypeScript transformation removes unused imports (which is required for correctness, as they may be type-only imports) and esbuild's glob import transformation wasn't correctly marking the imported helper function as used. This wasn't caught earlier because most of esbuild's glob import tests were written in JavaScript, not in TypeScript.

Fix require() glob imports with bundling disabled (#3546)

Previously require() calls containing glob imports were incorrectly transformed when bundling was disabled. All glob imports should only be transformed when bundling is enabled. This bug has been fixed.

Fix a panic when transforming optional chaining with define (#3551, #3554)

This release fixes a case where esbuild could crash with a panic, which was triggered by using define to replace an expression containing an optional chain. Here is an example:

// Original code
console.log(process?.env.SHELL)

// Old output (with --define:process.env={})
/* panic: Internal error (while parsing "<stdin>") */

// New output (with --define:process.env={})
var define_process_env_default = {};
console.log(define_process_env_default.SHELL);

This fix was contributed by @hi-ogawa.

Work around a bug in node's CommonJS export name detector (#3544)

The export names of a CommonJS module are dynamically-determined at run time because CommonJS exports are properties on a mutable object. But the export names of an ES module are statically-determined at module instantiation time by using import and export syntax and cannot be changed at run time.

When you import a CommonJS module into an ES module in node, node scans over the source code to attempt to detect the set of export names that the CommonJS module will end up using. That statically-determined set of names is used as the set of names that the ES module is allowed to import at module instantiation time. However, this scan appears to have bugs (or at least, can cause false positives) because it doesn't appear to do any scope analysis. Node will incorrectly consider the module to export something even if the assignment is done to a local variable instead of to the module-level exports object. For example:

// confuseNode.js
exports.confuseNode = function(exports) {
  // If this local is called "exports", node incorrectly
  // thinks this file has an export called "notAnExport".
  exports.notAnExport = function() {
  };
};

You can see that node incorrectly thinks the file confuseNode.js has an export called notAnExport when that file is loaded in an ES module context:

$ node -e 'import("./confuseNode.js").then(console.log)'
[Module: null prototype] {
  confuseNode: [Function (anonymous)],
  default: { confuseNode: [Function (anonymous)] },
  notAnExport: undefined
}

To avoid this, esbuild will now rename local variables that use the names exports and module when generating CommonJS output for the node platform.

Fix the return value of esbuild's super() shim (#3538)

Some people write constructor methods that use the return value of super() instead of using this. This isn't too common because TypeScript doesn't let you do that but it can come up when writing JavaScript. Previously esbuild's class lowering transform incorrectly transformed the return value of super() into undefined. With this release, the return value of super() will now be this instead:

// Original code
class Foo extends Object {
  field
  constructor() {
    console.log(typeof super())
  }
}
new Foo

// Old output (with --target=es6)
class Foo extends Object {
  constructor() {
    var __super = (...args) => {
      super(...args);
      __publicField(this, "field");
    };
    console.log(typeof __super());
  }
}
new Foo();

// New output (with --target=es6)
class Foo extends Object {
  constructor() {
    var __super = (...args) => {
      super(...args);
      __publicField(this, "field");
      return this;
    };
    console.log(typeof __super());
  }
}
new Foo();

Terminate the Go GC when esbuild's stop() API is called (#3552)

If you use esbuild with WebAssembly and pass the worker: false flag to esbuild.initialize(), then esbuild will run the WebAssembly module on the main thread. If you do this within a Deno test and that test calls esbuild.stop() to clean up esbuild's resources, Deno may complain that a setTimeout() call lasted past the end of the test. This happens when the Go is in the middle of a garbage collection pass and has scheduled additional ongoing garbage collection work. Normally calling esbuild.stop() will terminate the web worker that the WebAssembly module runs in, which will terminate the Go GC, but that doesn't happen if you disable the web worker with worker: false.

With this release, esbuild will now attempt to terminate the Go GC in this edge case by calling clearTimeout() on these pending timeouts.

Apply /* @__NO_SIDE_EFFECTS__ */ on tagged template literals (#3511)

Tagged template literals that reference functions annotated with a @__NO_SIDE_EFFECTS__ comment are now able to be removed via tree-shaking if the result is unused. This is a convention from Rollup. Here is an example:

// Original code
const html = /* @__NO_SIDE_EFFECTS__ */ (a, ...b) => ({ a, b })
html`<a>remove</a>`
x = html`<b>keep</b>`

// Old output (with --tree-shaking=true)
const html = /* @__NO_SIDE_EFFECTS__ */ (a, ...b) => ({ a, b });
html`<a>remove</a>`;
x = html`<b>keep</b>`;

// New output (with --tree-shaking=true)
const html = /* @__NO_SIDE_EFFECTS__ */ (a, ...b) => ({ a, b });
x = html`<b>keep</b>`;

Note that this feature currently only works within a single file, so it's not especially useful. This feature does not yet work across separate files. I still recommend using @__PURE__ annotations instead of this feature, as they have wider tooling support. The drawback of course is that @__PURE__ annotations need to be added at each call site, not at the declaration, and for non-call expressions such as template literals you need to wrap the expression in an IIFE (immediately-invoked function expression) to create a call expression to apply the @__PURE__ annotation to.

Publish builds for IBM AIX PowerPC 64-bit (#3549)

This release publishes a binary executable to npm for IBM AIX PowerPC 64-bit, which means that in theory esbuild can now be installed in that environment with npm install esbuild. This hasn't actually been tested yet. If you have access to such a system, it would be helpful to confirm whether or not doing this actually works.

Add support for bundling code that uses import attributes (#3384)

JavaScript is gaining new syntax for associating a map of string key-value pairs with individual ESM imports. The proposal is still a work in progress and is still undergoing significant changes before being finalized. However, the first iteration has already been shipping in Chromium-based browsers for a while, and the second iteration has landed in V8 and is now shipping in node, so it makes sense for esbuild to support it. Here are the two major iterations of this proposal (so far):

1. Import assertions (deprecated, will not be standardized)

   • Uses the assert keyword
   • Does not affect module resolution
   • Causes an error if the assertion fails
   • Shipping in Chrome 91+ (and in esbuild 0.11.22+)

2. Import attributes (currently set to become standardized)

   • Uses the with keyword
   • Affects module resolution
   • Unknown attributes cause an error
   • Shipping in node 21+

You can already use esbuild to bundle code that uses import assertions (the first iteration). However, this feature is mostly useless for bundlers because import assertions are not allowed to affect module resolution. It's basically only useful as an annotation on external imports, which esbuild will then preserve in the output for use in a browser (which would otherwise refuse to load certain imports).

With this release, esbuild now supports bundling code that uses import attributes (the second iteration). This is much more useful for bundlers because they are allowed to affect module resolution, which means the key-value pairs can be provided to plugins. Here's an example, which uses esbuild's built-in support for the upcoming JSON module standard:

// On static imports
import foo from './package.json' with { type: 'json' }
console.log(foo)

// On dynamic imports
const bar = await import('./package.json', { with: { type: 'json' } })
console.log(bar)

One important consequence of the change in semantics between import assertions and import attributes is that two imports with identical paths but different import attributes are now considered to be different modules. This is because the import attributes are provided to the loader, which might then use those attributes during loading. For example, you could imagine an image loader that produces an image of a different size depending on the import attributes.

Import attributes are now reported in the metafile and are now provided to on-load plugins as a map in the with property. For example, here's an esbuild plugin that turns all imports with a type import attribute equal to 'cheese' into a module that exports the cheese emoji:

const cheesePlugin = {
  name: 'cheese',
  setup(build) {
    build.onLoad({ filter: /.*/ }, args => {
      if (args.with.type === 'cheese') return {
        contents: `export default "🧀"`,
      }
    })
  }
}

require('esbuild').build({
  bundle: true,
  write: false,
  stdin: {
    contents: `
      import foo from 'data:text/javascript,' with { type: 'cheese' }
      console.log(foo)
    `,
  },
  plugins: [cheesePlugin],
}).then(result => {
  const code = new Function(result.outputFiles[0].text)
  code()
})

Warning: It's possible that the second iteration of this feature may change significantly again even though it's already shipping in real JavaScript VMs (since it has already happened once before). In that case, esbuild may end up adjusting its implementation to match the eventual standard behavior. So keep in mind that by using this, you are using an unstable upcoming JavaScript feature that may undergo breaking changes in the future.

Adjust TypeScript experimental decorator behavior (#3230, #3326, #3394)

With this release, esbuild will now allow TypeScript experimental decorators to access both static class properties and #private class names. For example:

const check =
  <T,>(a: T, b: T): PropertyDecorator =>
    () => console.log(a === b)

async function test() {
  class Foo {
    static #foo = 1
    static bar = 1 + Foo.#foo
    @check(Foo.#foo, 1) a: any
    @check(Foo.bar, await Promise.resolve(2)) b: any
  }
}

test().then(() => console.log('pass'))

This will now print true true pass when compiled by esbuild. Previously esbuild evaluated TypeScript decorators outside of the class body, so it didn't allow decorators to access Foo or #foo. Now esbuild does something different, although it's hard to concisely explain exactly what esbuild is doing now (see the background section below for more information).

Note that TypeScript's experimental decorator support is currently buggy: TypeScript's compiler passes this test if only the first @check is present or if only the second @check is present, but TypeScript's compiler fails this test if both checks are present together. I haven't changed esbuild to match TypeScript's behavior exactly here because I'm waiting for TypeScript to fix these bugs instead.

Some background: TypeScript experimental decorators don't have consistent semantics regarding the context that the decorators are evaluated in. For example, TypeScript will let you use await within a decorator, which implies that the decorator runs outside the class body (since await isn't supported inside a class body), but TypeScript will also let you use #private names, which implies that the decorator runs inside the class body (since #private names are only supported inside a class body). The value of this in a decorator is also buggy (the run-time value of this changes if any decorator in the class uses a #private name but the type of this doesn't change, leading to the type checker no longer matching reality). These inconsistent semantics make it hard for esbuild to implement this feature as decorator evaluation happens in some superposition of both inside and outside the class body that is particular to the internal implementation details of the TypeScript compiler.

Forbid --keep-names when targeting old browsers (#3477)

The --keep-names setting needs to be able to assign to the name property on functions and classes. However, before ES6 this property was non-configurable, and attempting to assign to it would throw an error. So with this release, esbuild will no longer allow you to enable this setting while also targeting a really old browser.

Fix printing of JavaScript decorators in tricky cases (#3396)

This release fixes some bugs where esbuild's pretty-printing of JavaScript decorators could incorrectly produced code with a syntax error. The problem happened because esbuild sometimes substitutes identifiers for other expressions in the pretty-printer itself, but the decision about whether to wrap the expression or not didn't account for this. Here are some examples:

// Original code
import { constant } from './constants.js'
import { imported } from 'external'
import { undef } from './empty.js'
class Foo {
  @constant()
  @imported()
  @undef()
  foo
}

// Old output (with --bundle --format=cjs --packages=external --minify-syntax)
var import_external = require("external");
var Foo = class {
  @123()
  @(0, import_external.imported)()
  @(void 0)()
  foo;
};

// New output (with --bundle --format=cjs --packages=external --minify-syntax)
var import_external = require("external");
var Foo = class {
  @(123())
  @((0, import_external.imported)())
  @((void 0)())
  foo;
};

Allow pre-release versions to be passed to target (#3388)

People want to be able to pass version numbers for unreleased versions of node (which have extra stuff after the version numbers) to esbuild's target setting and have esbuild do something reasonable with them. These version strings are of course not present in esbuild's internal feature compatibility table because an unreleased version has not been released yet (by definition). With this release, esbuild will now attempt to accept these version strings passed to target and do something reasonable with them.