feat: add polyfills build option to enable or disable polyfills (#496)

Author: dsherret

README.md

@@ -200,6 +200,46 @@ The module is transformed and type checked like the test files are and it is not
 included in the npm package. It is loaded once for each of the emitted script
 and ESM output, before any test file.
 
+### Polyfills
+
+dnt adds polyfills for language features that may not exist in the environment
+implied by `compilerOptions.target`. If you're targeting a runtime that already
+supports a feature, use the `polyfills` build option to opt out and keep the
+extra code out of your package:
+
+```ts
+await build({
+  // ...etc...
+  polyfills: {
+    importMeta: false,
+  },
+});
+```
+
+Pass `true` or `false` instead of an object to enable or disable every polyfill
+at once. Anything you don't specify continues to be decided by the target, so
+`polyfills` overrides the target rather than replacing it.
+
+The supported names are `arrayFindLast`, `arrayFromAsync`, `errorCause`,
+`importMeta`, `objectHasOwn`, `promiseWithResolvers`, and `stringReplaceAll`.
+
+Note that the polyfills also provide the type declarations for the features they
+polyfill, so opting out of one means relying on your `compilerOptions.lib`
+declarations for it instead.
+
+The `importMeta` polyfill can only be disabled when the `scriptModule` build
+option is `false`, because `import.meta` is not valid CommonJS:
+
+```ts
+await build({
+  // ...etc...
+  scriptModule: false,
+  polyfills: {
+    importMeta: false,
+  },
+});
+```
+
 ### Shims
 
 dnt will shim the globals specified in the build options. For example, if you

deno.jsonc

@@ -51,6 +51,7 @@
     "tests/node_types_project/npm",
     "tests/package_mappings_project/npm",
     "tests/polyfill_array_find_last_project/npm",
+    "tests/polyfill_disabled_project/npm",
     "tests/polyfill_project/npm",
     "tests/shim_project/npm",
     "tests/test_project/npm",

lib/polyfills.test.ts

@@ -0,0 +1,114 @@
+// Copyright 2018-2024 the Deno authors. MIT license.
+
+import { assertEquals, assertThrows } from "@std/assert";
+import {
+  resolvePolyfillOptions,
+  resolveUseImportMetaPolyfill,
+} from "./polyfills.ts";
+
+Deno.test("resolvePolyfillOptions - undefined leaves everything to the target", () => {
+  assertEquals(resolvePolyfillOptions(undefined), {});
+});
+
+Deno.test("resolvePolyfillOptions - boolean applies to every polyfill", () => {
+  assertEquals(resolvePolyfillOptions(false), {
+    arrayFindLast: false,
+    arrayFromAsync: false,
+    errorCause: false,
+    importMeta: false,
+    objectHasOwn: false,
+    promiseWithResolvers: false,
+    stringReplaceAll: false,
+  });
+  assertEquals(
+    Object.values(resolvePolyfillOptions(true)).every((v) => v),
+    true,
+  );
+});
+
+Deno.test("resolvePolyfillOptions - object only includes what's specified", () => {
+  assertEquals(
+    resolvePolyfillOptions({ importMeta: false, errorCause: true }),
+    { importMeta: false, errorCause: true },
+  );
+});
+
+Deno.test("resolvePolyfillOptions - undefined values fall back to the target", () => {
+  assertEquals(
+    resolvePolyfillOptions({ importMeta: undefined, errorCause: true }),
+    { errorCause: true },
+  );
+});
+
+Deno.test("resolvePolyfillOptions - throws for an unknown polyfill", () => {
+  assertThrows(
+    () =>
+      resolvePolyfillOptions(
+        { importMata: false } as Record<string, boolean>,
+      ),
+    Error,
+    "Unknown polyfill 'importMata'",
+  );
+});
+
+Deno.test("resolveUseImportMetaPolyfill - required when emitting a script module", () => {
+  assertEquals(
+    resolveUseImportMetaPolyfill({
+      polyfills: {},
+      target: "Latest",
+      emitScriptModule: true,
+    }),
+    true,
+  );
+});
+
+Deno.test("resolveUseImportMetaPolyfill - throws when disabled with a script module", () => {
+  assertThrows(
+    () =>
+      resolveUseImportMetaPolyfill({
+        polyfills: { importMeta: false },
+        target: "ES2021",
+        emitScriptModule: true,
+      }),
+    Error,
+    "cannot be disabled when emitting a script module",
+  );
+});
+
+Deno.test("resolveUseImportMetaPolyfill - esm only follows the target by default", () => {
+  assertEquals(
+    resolveUseImportMetaPolyfill({
+      polyfills: {},
+      target: "ES2021",
+      emitScriptModule: false,
+    }),
+    true,
+  );
+  assertEquals(
+    resolveUseImportMetaPolyfill({
+      polyfills: {},
+      target: "Latest",
+      emitScriptModule: false,
+    }),
+    false,
+  );
+});
+
+Deno.test("resolveUseImportMetaPolyfill - esm only respects an explicit override", () => {
+  assertEquals(
+    resolveUseImportMetaPolyfill({
+      polyfills: { importMeta: false },
+      target: "ES2021",
+      emitScriptModule: false,
+    }),
+    false,
+  );
+  assertEquals(
+    resolveUseImportMetaPolyfill({
+      polyfills: { importMeta: true },
+      target: "Latest",
+      emitScriptModule: false,
+    }),
+    true,
+  );
+});

lib/polyfills.ts

@@ -0,0 +1,71 @@
+// Copyright 2018-2024 the Deno authors. MIT license.
+
+import type { PolyfillName, PolyfillOptions, ScriptTarget } from "./types.ts";
+
+/** Every polyfill dnt knows how to apply. */
+export const polyfillNames: readonly PolyfillName[] = [
+  "arrayFindLast",
+  "arrayFromAsync",
+  "errorCause",
+  "importMeta",
+  "objectHasOwn",
+  "promiseWithResolvers",
+  "stringReplaceAll",
+];
+
+/** Resolves the user provided polyfill options into an explicit
+ * enabled/disabled value per polyfill.
+ *
+ * Polyfills that the user didn't specify are left out of the result so that
+ * the script target continues to decide whether they're used.
+ */
+export function resolvePolyfillOptions(
+  options: PolyfillOptions | undefined,
+): Record<string, boolean> {
+  if (options == null) {
+    return {};
+  }
+  if (typeof options === "boolean") {
+    return Object.fromEntries(polyfillNames.map((name) => [name, options]));
+  }
+
+  const resolved: Record<string, boolean> = {};
+  for (const [name, enabled] of Object.entries(options)) {
+    if (enabled == null) {
+      continue;
+    }
+    if (!polyfillNames.includes(name as PolyfillName)) {
+      throw new Error(
+        `Unknown polyfill '${name}' specified in the 'polyfills' option. ` +
+          `Supported polyfills: ${polyfillNames.join(", ")}`,
+      );
+    }
+    resolved[name] = enabled;
+  }
+  return resolved;
+}
+
+/** Whether the `import.meta` polyfill applies, given the resolved polyfill
+ * overrides and the rest of the build options.
+ *
+ * `import.meta` is a syntax error in CommonJS, so the polyfill is required
+ * whenever a script module is emitted regardless of the target.
+ */
+export function resolveUseImportMetaPolyfill(options: {
+  polyfills: Record<string, boolean>;
+  target: ScriptTarget;
+  emitScriptModule: boolean;
+}): boolean {
+  const explicit = options.polyfills["importMeta"];
+  if (options.emitScriptModule) {
+    if (explicit === false) {
+      throw new Error(
+        "The 'importMeta' polyfill cannot be disabled when emitting a script " +
+          "module because `import.meta` is not valid CommonJS. Set the " +
+          "'scriptModule' build option to false to distribute an ES module only.",
+      );
+    }
+    return true;
+  }
+  return explicit ?? options.target !== "Latest";
+}

lib/types.ts

@@ -52,6 +52,30 @@ export interface PackageJson {
   [propertyName: string]: any;
 }
 
+// NOTICE: make sure to update the `name` of each polyfill in the rust code
+// when changing the names on this
+// todo(dsherret): code generate this from the Rust code to prevent out of sync issues
+
+/** Name of a polyfill that dnt may add to the output. */
+export type PolyfillName =
+  | "arrayFindLast"
+  | "arrayFromAsync"
+  | "errorCause"
+  | "importMeta"
+  | "objectHasOwn"
+  | "promiseWithResolvers"
+  | "stringReplaceAll";
+
+/** Explicitly enables or disables polyfills by name.
+ *
+ * Provide `true` or `false` to enable or disable all polyfills, or an object
+ * to control them individually. Polyfills that aren't specified fall back to
+ * what the script target implies.
+ */
+export type PolyfillOptions =
+  | boolean
+  | Partial<Record<PolyfillName, boolean>>;
+
 // NOTICE: make sure to update `ScriptTarget` in the rust code when changing the names on this
 // todo(dsherret): code generate this from the Rust code to prevent out of sync issues
 

mod.ts

@@ -18,7 +18,15 @@ import {
 } from "./lib/compiler.ts";
 import { type ShimOptions, shimOptionsToTransformShims } from "./lib/shims.ts";
 import { getNpmIgnoreText } from "./lib/npm_ignore.ts";
-import type { PackageJson, ScriptTarget } from "./lib/types.ts";
+import {
+  resolvePolyfillOptions,
+  resolveUseImportMetaPolyfill,
+} from "./lib/polyfills.ts";
+import type {
+  PackageJson,
+  PolyfillOptions,
+  ScriptTarget,
+} from "./lib/types.ts";
 import { glob, runNpmCommand, standardizePath } from "./lib/utils.ts";
 import {
   type SpecifierMappings,
@@ -30,7 +38,11 @@ import { getPackageJson } from "./lib/package_json.ts";
 import { getTestRunnerCode } from "./lib/test_runner/get_test_runner_code.ts";
 
 export { emptyDir } from "@std/fs/empty-dir";
-export type { PackageJson } from "./lib/types.ts";
+export type {
+  PackageJson,
+  PolyfillName,
+  PolyfillOptions,
+} from "./lib/types.ts";
 export type { JsxEmit, LibName, SourceMapOptions } from "./lib/compiler.ts";
 export type { ShimOptions } from "./lib/shims.ts";
 
@@ -88,6 +100,20 @@ export interface BuildOptions {
    * @default true
    */
   esModule?: boolean;
+  /** Explicitly enables or disables polyfills, overriding what
+   * `compilerOptions.target` implies.
+   *
+   * Provide `true` or `false` to enable or disable all polyfills, or an object
+   * to control them individually:
+   *
+   * ```ts
+   * polyfills: { importMeta: false }
+   * ```
+   *
+   * @remarks The `importMeta` polyfill cannot be disabled unless `scriptModule`
+   * is `false`, because `import.meta` is not valid CommonJS.
+   */
+  polyfills?: PolyfillOptions;
   /** Skip running `npm install`.
    * @default false
    */
@@ -250,6 +276,14 @@ export async function build(options: BuildOptions): Promise<void> {
     (!!options.declaration && !options.skipSourceOutput);
   const packageManager = options.packageManager ?? "npm";
   const scriptTarget = options.compilerOptions?.target ?? "ES2021";
+  const polyfills = resolvePolyfillOptions(options.polyfills);
+  // `import.meta` call sites are rewritten by the TypeScript compiler rather
+  // than the transform, so resolve this up front and keep both sides in sync
+  polyfills["importMeta"] = resolveUseImportMetaPolyfill({
+    polyfills,
+    target: scriptTarget,
+    emitScriptModule: options.scriptModule !== false,
+  });
   const entryPoints: EntryPoint[] = options.entryPoints.map((e, i) => {
     if (typeof e === "string") {
       return {
@@ -433,7 +467,9 @@ export async function build(options: BuildOptions): Promise<void> {
     program = project.createProgram();
     emit({
       transformers: {
-        before: [compilerTransforms.transformImportMeta],
+        before: polyfills["importMeta"]
+          ? [compilerTransforms.transformImportMeta]
+          : [],
       },
     });
     writeFile(
@@ -458,7 +494,9 @@ export async function build(options: BuildOptions): Promise<void> {
     program = getProgramAndMaybeTypeCheck("script");
     emit({
       transformers: {
-        before: [compilerTransforms.transformImportMeta],
+        before: polyfills["importMeta"]
+          ? [compilerTransforms.transformImportMeta]
+          : [],
       },
     });
     writeFile(
@@ -634,6 +672,7 @@ export async function build(options: BuildOptions): Promise<void> {
       testShims,
       mappings: options.mappings,
       target: scriptTarget,
+      polyfills,
       importMap: options.importMap,
       configFile: options.configFile,
       cwd: path.toFileUrl(cwd).toString(),