Support loading additional TS lib files (#3863)

Fixes #3726

This PR provides support for referencing other lib files (like lib.dom.d.ts that are not
used by default in Deno.

1 files changed, 100 insertions, 0 deletions

diff --git a/std/manual.md b/std/manual.md
index e5bd6ef75..78037ad1e 100644
--- a/std/manual.md
+++ b/std/manual.md
@@ -174,6 +174,12 @@ command line:
 $ deno types
 ```
 
+The output is the concatenation of three library files that are built into Deno:
+
+- [lib.deno.ns.d.ts](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.ns.d.ts)
+- [lib.deno.shared_globals.d.ts](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.shared_globals.d.ts)
+- [lib.deno.window.d.ts](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.window.d.ts)
+
 [This is what the output looks like.](https://github.com/denoland/deno/blob/master/cli/js/lib.deno_runtime.d.ts)
 
 ### Reference websites
@@ -640,6 +646,100 @@ reference directive. If Deno used this, it would interfere with the behavior of
 the TypeScript compiler. Deno only looks for the directive in JavaScript (and
 JSX) files.
 
+### Referencing TypeScript library files
+
+When you use `deno run`, or other Deno commands which type check TypeScript,
+that code is evaluated against custom libraries which describe the environment
+that Deno supports. By default, the compiler runtime APIs which type check
+TypeScript also use these libraries (`Deno.compile()` and `Deno.bundle()`).
+
+But if you want to compile or bundle TypeScript for some other runtime, you may
+want to override the default libraries. In order to do this, the runtime APIs
+support the `lib` property in the compiler options. For example, if you had
+TypeScript code that is destined for the browser, you would want to use the
+TypeScript `"dom"` library:
+
+```ts
+const [errors, emitted] = Deno.compile(
+  "main.ts",
+  {
+    "main.ts": `document.getElementById("foo");\n`
+  },
+  {
+    lib: ["dom", "esnext"]
+  }
+);
+```
+
+For a list of all the libraries that TypeScript supports, see the
+[`lib` compiler option](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
+documentation.
+
+**Don't forget to include the JavaScript library**
+
+Just like `tsc`, when you supply a `lib` compiler option, it overrides the
+default ones, which means that the basic JavaScript library won't be included
+and you should include the one that best represents your target runtime (e.g.
+`es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`).
+
+#### Including the `Deno` namespace
+
+In addition to the libraries that are provided by TypeScript, there are four
+libraries that are built into Deno that can be referenced:
+
+- `deno.ns` - Provides the `Deno` namespace.
+- `deno.shared_globals` - Provides global interfaces and variables which Deno
+  supports at runtime that are then exposed by the final runtime library.
+- `deno.window` - Exposes the global variables plus the Deno namespace that are
+  available in the Deno main worker and is the default for the runtime compiler
+  APIs.
+- `deno.worker` - Exposes the global variables that are available in workers
+  under Deno.
+
+So to add the Deno namespace to a compilation, you would include the `deno.ns`
+lib in the array. For example:
+
+```ts
+const [errors, emitted] = Deno.compile(
+  "main.ts",
+  {
+    "main.ts": `document.getElementById("foo");\n`
+  },
+  {
+    lib: ["dom", "esnext", "deno.ns"]
+  }
+);
+```
+
+**Note** that the Deno namespace expects a runtime environment that is at least
+ES2018 or later. This means if you use a lib "lower" than ES2018 you will get
+errors logged as part of the compilation.
+
+#### Using the triple slash reference
+
+You do not have to specify the `lib` in just the compiler options. Deno supports
+[the triple-slash reference to a lib](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-lib-).
+and could be embedded in the contents of the file. For example of you have a
+`main.ts` like:
+
+```ts
+/// <reference lib="dom" />
+
+document.getElementById("foo");
+```
+
+It would compiler without errors like this:
+
+```ts
+const [errors, emitted] = Deno.compile("./main.ts", undefined, {
+  lib: ["esnext"]
+});
+```
+
+**Note** that the `dom` library conflicts with some of the default globals that
+are defined in the default type library for Deno. To avoid this, you need to
+specify a `lib` option in the compiler options to the runtime compiler APIs.
+
 ### Testing if current file is the main program
 
 To test if the current script has been executed as the main input to the program