Breaking Change: Deno.emit() replaces Deno.compile(), Deno.bundle(), and Deno.transpileOnly()

[kitsonk]

Part of the reason why the runtime compiler APIs were never stabilised is because we knew that we weren't really happy with them. As Deno has evolved, so has our understanding of how we consume, type check, and emit code.

In #4752 we indicated that we would be refactoring these and we now have that work done in #8799.

While holding them behind the --unstable flag should have set community expectations that we would break them in the future, we realise that there are quite a few people and projects who have leveraged and implemented the previous APIs, as they are one of the powerful features of Deno, having the ability to emit arbitrary JavaScript and TypeScript to JavaScript. We think the new, consolidated API is better and easier to use for everyone, but it will require those using the feature to refactor their code once it is landed in master.

Based on the potential disruption we are currently targeting Deno 1.7.0 for this breaking change, but of course want to hear feedback from the wider community.

A couple new features over the existing APIs:

• ignoredOptions are returned to the caller, instead of logged to the console.
• stats which for internal compiles are logged at a debug level are returned to the caller. This helps expose some performance information for better management of applications.
• import-maps are supported
• The API is all in one. By default, the API will type check the code, but setting the option check to false will cause the API to behave like --no-check does on the command line.
• For security purposes, when resolving external resources the Deno.emit() API respects the same permissions that dynamic import() and workers do, which require currently --allow-read and/or --allow-net permissions.

The new API looks something like this:

const { diagnostics, files, ignoredOptions, stats } = await Deno.emit(
  "/a.ts",
  {
    compilerOptions: {
      module: "amd",
      sourceMap: false,
    },
    sources: { "/a.ts": `export const a = "a";` },
  },
);

And has the signature of:

  interface ImportMap {
    imports: Record<string, string>;
    scopes?: Record<string, Record<string, string>>;
  }

  interface EmitOptions {
    /** Indicate that the source code should be emitted to a single file
     * JavaScript bundle that is an ES module (`"esm"`). */
    bundle?: "esm";
    /** If `true` then the sources will be typed checked, returning any
     * diagnostic errors in the result.  If `false` type checking will be
     * skipped.  Defaults to `true`.
     * 
     * *Note* by default, only TypeScript will be type checked, just like on
     * the command line.  Use the `compilerOptions` options of `checkJs` to
     * enable type checking of JavaScript. */
    check?: boolean;
    /** A set of options that are aligned to TypeScript compiler options that
     * are supported by Deno. */
    compilerOptions?: CompilerOptions;
    /** An [import-map](https://deno.land/manual/linking_to_external_code/import_maps#import-maps)
     * which will be applied to the imports. */
    importMap?: ImportMap;
    /** An absolute path to an [import-map](https://deno.land/manual/linking_to_external_code/import_maps#import-maps).
     * Required to be specified if an `importMap` is specified to be able to
     * determine resolution of relative paths. If a `importMap` is not
     * specified, then it will assumed the file path points to an import map on
     * disk and will be attempted to be loaded based on current runtime
     * permissions.
     */
    importMapPath?: string;
    /** A record of sources to use when doing the emit.  If provided, Deno will
     * use these sources instead of trying to resolve the modules externally. */
    sources?: Record<string, string>;
  }

  interface EmitResult {
    /** Diagnostic messages returned from the type checker (`tsc`). */
    diagnostics: Diagnostic[];
    /** Any emitted files.  If bundled, then the JavaScript will have the
     * key of `deno:///bundle.js` with an optional map (based on
     * `compilerOptions`) in `deno:///bundle.js.map`. */
    files: Record<string, string>;
    /** An optional array of any compiler options that were ignored by Deno. */
    ignoredOptions?: string[];
    /** An array of internal statics related to the emit, for diagnostic
     * purposes. */
    stats: Array<[string, number]>;
  }

  /**
   * **UNSTABLE**: new API, yet to be vetted.
   * 
   * Similar to the command line functionality of `deno run` or `deno cache`,
   * `Deno.emit()` provides a way to provide Deno arbitrary JavaScript
   * or TypeScript and have it return JavaScript based on the options and
   * settings provided. The source code can either be provided or the modules
   * can be fetched and resolved like other modules are resolved.
   * 
   * Requires `allow-read` and/or `allow-net` if sources are not provided.
   * 
   * @param rootSpecifier The specifier that will be used as the entry point.
   *                      If no sources are provided, then the specifier would
   *                      be the same as if you typed it on the command line for
   *                      `deno run`. If sources are provided, it should match
   *                      one of the names of the sources.
   * @param options  A set of options to be used with the emit.
   */
  export function emit(
    rootSpecifier: string | URL,
    options?: EmitOptions,
  ): Promise<EmitResult>;

A couple of things that we can do down the road, which aren't addressed in the PR at the moment:

• Persist the tsc compiler runtime in memory, so that several calls to Deno.emit() with type checking do not require the compiler runtime to be "spun up". Currently that occurs every time. I would have added it to this PR, but it is a more complex refactor to do that then I had anticipated, and we need to get this in first, before addressing that.
• Deal better with the ability to reload remote modules. Currently Deno.emit() follows whatever behaviour is followed on the command line.

[SRNV]

why not just a rootSpecifier property (like main), to indicate which source is the root ?

const { diagnostics, files, ignoredOptions, stats } = await Deno.emit(
  {
    compilerOptions: {
      module: "amd",
      sourceMap: false,
    },
    sources: { "/a.ts": `export const a = "a";` },
    main:   "/a.ts",
    // or root
  },
);

[kitsonk]

What do you not like about the current proposal (which has landed in master)? A root specifier is not optional, where as all other options are optional.

[SRNV]

yeah I understood it after reconsidering it.

[SRNV]

I see bundle: "esm"
what are the other types that we can specify ?
shouldn't it be a boolean instead ?

[kitsonk]

IIFE (mentioned in #8824)

[The-Noah]

I'm confused on what this line does:

sources: { "/a.ts": `export const a = "a";` }`

[kitsonk]

Confused in what sense? sources is an option which provides the sources as part of the API and Deno won't attempt to resolve the sources externally. This is pretty well covered in the manual and documentation.

[The-Noah]

Sorry, I didn't realize there was better documentation on this. I've got it now 🙂

[kitsonk]

This has been delivered, so the conversation here is locked.