feat: add --location=<href> and globalThis.location (#7369)

3 files changed, 82 insertions, 4 deletions

diff --git a/docs/runtime/location_api.md b/docs/runtime/location_api.md
new file mode 100644
index 000000000..6e7341828
--- /dev/null
+++ b/docs/runtime/location_api.md
@@ -0,0 +1,76 @@
+## Location API
+
+Deno supports the
+[`location`](https://developer.mozilla.org/en-US/docs/Web/API/Window/location)
+global from the web. Please read on.
+
+### Location flag
+
+There is no "web page" whose URL we can use for a location in a Deno process. We
+instead allow users to emulate a document location by specifying one on the CLI
+using the `--location` flag. It can be a `http` or `https` URL.
+
+```ts
+// deno run --location https://example.com/path main.ts
+
+console.log(location.href);
+// "https://example.com/path"
+```
+
+You must pass `--location <href>` for this to work. If you don't, any access to
+the `location` global will throw an error.
+
+```ts
+// deno run main.ts
+
+console.log(location.href);
+// error: Uncaught ReferenceError: Access to "location", run again with --location <href>.
+```
+
+Setting `location` or any of its fields will normally cause navigation in
+browsers. This is not applicable in Deno, so it will throw in this situation.
+
+```ts
+// deno run --location https://example.com/path main.ts
+
+location.pathname = "./foo";
+// error: Uncaught NotSupportedError: Cannot set "location.pathname".
+```
+
+### Extended usage
+
+On the web, resource resolution (excluding modules) typically uses the value of
+`location.href` as the root on which to base any relative URLs. This affects
+some web APIs adopted by Deno.
+
+#### Fetch API
+
+```ts
+// deno run --location https://api.github.com/ --allow-net main.ts
+
+const response = await fetch("./orgs/denoland");
+// Fetches "https://api.github.com/orgs/denoland".
+```
+
+The `fetch()` call above would throw if the `--location` flag was not passed,
+since there is no web-analogous location to base it onto.
+
+#### Worker modules
+
+```ts
+// deno run --location https://example.com/index.html --allow-net main.ts
+
+const worker = new Worker("./workers/hello.ts", { type: "module" });
+// Fetches worker module at "https://example.com/workers/hello.ts".
+```
+
+### Only use if necessary
+
+For the above use cases, it is preferable to pass URLs in full rather than
+relying on `--location`. You can manually base a relative URL using the `URL`
+constructor if needed.
+
+The `--location` flag is intended for those who have some specific purpose in
+mind for emulating a document location and are aware that this will only work at
+application-level. However, you may also use it to silence errors from a
+dependency which is frivolously accessing the `location` global.
diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md
index 14e028705..82e1e5b2d 100644
--- a/docs/runtime/workers.md
+++ b/docs/runtime/workers.md
@@ -9,10 +9,11 @@ is run on a separate thread, dedicated only to that worker.
 Currently Deno supports only `module` type workers; thus it's essential to pass
 the `type: "module"` option when creating a new worker.
 
-Relative module specifiers are
-[not supported](https://github.com/denoland/deno/issues/5216) at the moment. You
-can instead use the `URL` constructor and `import.meta.url` to easily create a
-specifier for some nearby script.
+Use of relative module specifiers in the main worker are only supported with
+`--location <href>` passed on the CLI. This is not recommended for portability.
+You can instead use the `URL` contructor and `import.meta.url` to easily create
+a specifier for some nearby script. Dedicated workers, however, have a location
+and this capability by default.
 
 ```ts
 // Good
diff --git a/docs/toc.json b/docs/toc.json
index df2c004c5..6d1896999 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -23,6 +23,7 @@
       "permission_apis": "Permission APIs",
       "compiler_apis": "Compiler APIs",
       "web_platform_apis": "Web Platform APIs",
+      "location_api": "Location API",
       "workers": "Workers"
     }
   },