add tests and comments

Makefile

@@ -107,11 +107,14 @@ test-old-ts: platform-neutral | require/old-ts/node_modules
 node-unref-tests: | scripts/node_modules
 	node scripts/node-unref-tests.js
 
-lib-typecheck: lib-typecheck-node lib-typecheck-deno
+lib-typecheck: lib-typecheck-node lib-typecheck-node-nolib lib-typecheck-deno
 
 lib-typecheck-node: | lib/node_modules
 	cd lib && node_modules/.bin/tsc -noEmit -p tsconfig.json
 
+lib-typecheck-node-nolib: | lib/node_modules
+	cd lib && node_modules/.bin/tsc -noEmit -p tsconfig-nolib.json
+
 lib-typecheck-deno: lib/deno/lib.deno.d.ts | lib/node_modules
 	cd lib && node_modules/.bin/tsc -noEmit -p tsconfig-deno.json
 

lib/shared/types.ts

@@ -635,12 +635,6 @@ export declare function analyzeMetafileSync(metafile: Metafile | string, options
  */
 export declare function initialize(options: InitializeOptions): Promise<void>
 
-declare global {
-  namespace WebAssembly {
-    interface Module {}
-  }
-}
-
 export interface InitializeOptions {
   /**
    * The URL of the "esbuild.wasm" file. This must be provided when running
@@ -683,3 +677,25 @@ export let version: string
 // killing it before the test ends, so you have to call this function (and
 // await the returned promise) in every Deno test that uses esbuild.
 export declare function stop(): Promise<void>
+
+// Note: These declarations exist to avoid type errors when you omit "dom" from
+// "lib" in your "tsconfig.json" file. TypeScript confusingly declares the
+// global "WebAssembly" type in "lib.dom.d.ts" even though it has nothing to do
+// with the browser DOM and is present in many non-browser JavaScript runtimes
+// (e.g. node and deno). Declaring it here allows esbuild's API to be used in
+// these scenarios.
+//
+// There's an open issue about getting this problem corrected (although these
+// declarations will need to remain even if this is fixed for backward
+// compatibility with older TypeScript versions):
+//
+//   https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/826
+//
+declare global {
+  namespace WebAssembly {
+    interface Module {
+    }
+  }
+  interface URL {
+  }
+}

lib/tsconfig-nolib.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "module": "CommonJS", // Allow the "import assignment" syntax
+    "target": "es2017", // Allow calling APIs such as "Object.entries"
+    "strict": true,
+    "lib": [], // Omit "dom" to test what happens with the "WebAssembly" type, which is defined in "dom"
+  },
+  "include": [
+    "shared/types.ts",
+  ],
+}