Merge branch 'main' into rework-npm-specifiers

denoland · Sep 15, 2023 · e462ec5 · e462ec5
2 parents 4eebe52 + 1eb97b2
commit e462ec5
Show file tree

Hide file tree

Showing 61 changed files with 1,920 additions and 363 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,8 @@
+version: 2
+updates:
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"
diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml
@@ -11,7 +11,7 @@ jobs:
   broken-links:
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Check Markdown Links
         uses: ruzickap/action-my-markdown-link-checker@v1
         with:

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -7,11 +7,22 @@ on:
     branches: [main]
 
 jobs:
+  typos:
+    name: spell-check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - uses: crate-ci/typos@master
+        with:
+          config: ./typos.toml
+
   format:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Deno
         uses: denoland/setup-deno@v1
@@ -23,7 +34,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Set up Deno
         uses: denoland/setup-deno@v1

diff --git a/.github/workflows/suggest-format.yml b/.github/workflows/suggest-format.yml
@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Deno
         uses: denoland/setup-deno@v1

diff --git a/.github/workflows/update-algolia.yml b/.github/workflows/update-algolia.yml
@@ -13,7 +13,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Deno
         uses: denoland/setup-deno@v1

diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 .DS_Store
 .env
+.vscode
diff --git a/README.md b/README.md
@@ -1,29 +1,8 @@
-# Deno Manual
+# (DEPRECATED) Deno Manual
 
-This repository is the official documentation for Deno, and it's available at:
-https://deno.land/manual
+This repository was formerly the home of the Deno manual, running at
+deno.land/manual. The instructions below describe how to run the doc site and
+preview changes.
 
-## Contributing
-
-1. Clone this project and `dotland` in the same parent folder:
-
-```
-git clone https://github.com/denoland/manual.git
-git clone https://github.com/denoland/dotland.git
-```
-
-2. Move into the `dotland` folder, and run the following command to start the
-   local `deno.land` website with the local manual contents:
-
-```
-cd dotland
-MANUAL_PATH=../manual deno task start
-```
-
-When opening a PR, make sure the code is formatted correctly. To format the
-code:
-
-1. Install Deno (https://deno.land/#installation)
-2. Run `deno fmt` at the root of this repository
-
-Before creating new pages, open an issue and discuss the proposed changes.
+**New contributions should be made to
+[docs.deno.com](https://github.com/denoland/deno-docs)**
diff --git a/advanced/jsx_dom/css.md b/advanced/jsx_dom/css.md
@@ -27,7 +27,7 @@ Then we will stringify the modified CSS AST and output it to the console:
 
 ```ts, ignore
 import * as css from "https://esm.sh/css@3.0.0";
-import { assert } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+import { assert } from "https://deno.land/std@$STD_VERSION/assert/mod.ts";
 
 declare global {
   interface AbortSignal {

diff --git a/advanced/jsx_dom/deno_dom.md b/advanced/jsx_dom/deno_dom.md
@@ -20,7 +20,7 @@ first heading it encounters and print out the text content of that heading:
 
 ```ts
 import { DOMParser } from "https://deno.land/x/deno_dom/deno-dom-wasm.ts";
-import { assert } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+import { assert } from "https://deno.land/std@$STD_VERSION/assert/mod.ts";
 
 const document = new DOMParser().parseFromString(
   `<!DOCTYPE html>

diff --git a/advanced/jsx_dom/jsdom.md b/advanced/jsx_dom/jsdom.md
@@ -66,7 +66,7 @@ first heading it encounters and print out the text content of that heading:
 
 ```ts, ignore
 import { JSDOM } from "jsdom";
-import { assert } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+import { assert } from "https://deno.land/std@$STD_VERSION/assert/mod.ts";
 
 const { window: { document } } = new JSDOM(
   `<!DOCTYPE html>

diff --git a/advanced/jsx_dom/linkedom.md b/advanced/jsx_dom/linkedom.md
@@ -29,7 +29,7 @@ first heading it encounters and print out the text content of that heading:
 
 ```ts
 import { DOMParser } from "https://esm.sh/linkedom";
-import { assert } from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+import { assert } from "https://deno.land/std@$STD_VERSION/assert/mod.ts";
 
 const document = new DOMParser().parseFromString(
   `<!DOCTYPE html>

diff --git a/advanced/language_server/overview.md b/advanced/language_server/overview.md
@@ -143,7 +143,7 @@ with Deno:
   }
   ```
 
-- `deno/task` - Requests the return of avalaible deno tasks, see
+- `deno/task` - Requests the return of available deno tasks, see
   [task_runner](../../tools/task_runner.md).
 
   It does not expect any parameters.

diff --git a/advanced/typescript.md b/advanced/typescript.md
@@ -1,6 +1,13 @@
 # Using TypeScript
 
-In this chapter we will discuss:
+Deno not only supports TypeScript out of the box, but also treats TypeScript as
+a first class language. This means the developer experience when authoring and
+importing TypeScript will be as easy and straightforward as that of JavaScript.
+
+You can run or import TypeScript without installing anything more than the Deno
+CLI.
+
+In this chapter, we'll discuss:
 
 - [Overview of TypeScript in Deno](./typescript/overview.md)
 - [Configuring TypeScript in Deno](./typescript/configuration.md)

diff --git a/basics/connecting_to_databases.md b/basics/connecting_to_databases.md
@@ -267,7 +267,7 @@ console.log(`Started on http://localhost:3000`);
 To make GraphQL client calls in Deno, import the
 [graphql npm module](https://www.npmjs.com/package/graphql) with the
 [esm CDN](https://esm.sh/). To learn more about using npm modules in Deno via
-CDN read [here](../node/cdns.md)
+CDN read [here](../node/cdns.md).
 
 #### Make GraphQL client calls with the graphql npm module
 

diff --git a/basics/import_maps.md b/basics/import_maps.md
@@ -40,7 +40,7 @@ written something similar in our `deno.json` configuration file:
 
 ## Example - Using deno_std's fmt module via `fmt/`
 
-**import_map.json**
+**deno.json**
 
 ```json
 {
@@ -62,7 +62,7 @@ console.log(red("hello world"));
 
 To use your project root for absolute imports:
 
-**import_map.json**
+**deno.json**
 
 ```jsonc
 {

diff --git a/basics/modules.md b/basics/modules.md
@@ -136,7 +136,7 @@ The solution is to import and re-export your external libraries in a central
 `deps.ts` file (which serves the same purpose as Node's `package.json` file).
 For example, let's say you were using the above assertion library across a large
 project. Rather than importing
-`"https://deno.land/std@$STD_VERSION/testing/asserts.ts"` everywhere, you could
+`"https://deno.land/std@$STD_VERSION/assert/mod.ts"` everywhere, you could
 create a `deps.ts` file that exports the third-party code:
 
 **deps.ts**
@@ -146,7 +146,7 @@ export {
   assert,
   assertEquals,
   assertStringIncludes,
-} from "https://deno.land/std@$STD_VERSION/testing/asserts.ts";
+} from "https://deno.land/std@$STD_VERSION/assert/mod.ts";
 ```
 
 And throughout the same project, you can import from the `deps.ts` and avoid

diff --git a/basics/modules/private.md b/basics/modules/private.md
@@ -1,31 +1,31 @@
 # Private Modules and Repositories
 
-There maybe instances where you want to load a remote module that is located in
+There may be instances where you want to load a remote module that is located in
 a _private_ repository, like a private repository on GitHub.
 
 Deno supports sending bearer tokens when requesting a remote module. Bearer
-tokens are the predominant type of access token used with OAuth 2.0 and is
-broadly supported by hosting services (e.g. GitHub, Gitlab, BitBucket,
+tokens are the predominant type of access token used with OAuth 2.0, and are
+broadly supported by hosting services (e.g., GitHub, GitLab, Bitbucket,
 Cloudsmith, etc.).
 
 ## DENO_AUTH_TOKENS
 
 The Deno CLI will look for an environment variable named `DENO_AUTH_TOKENS` to
 determine what authentication tokens it should consider using when requesting
-remote modules. The value of the environment variable is in the format of a _n_
-number of tokens deliminated by a semi-colon (`;`) where each token is either:
+remote modules. The value of the environment variable is in the format of _n_
+number of tokens delimited by a semi-colon (`;`) where each token is either:
 
-- a bearer token in the format of `{token}@{hostname[:port]}`
+- a bearer token in the format of `{token}@{hostname[:port]}` or
 
 - basic auth data in the format of `{username}:{password}@{hostname[:port]}`
 
-For example a single token for would look something like this:
+For example, a single token for `deno.land` would look something like this:
 
 ```sh
 DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land
 ```
 
-or
+or:
 
 ```sh
 DENO_AUTH_TOKENS=username:password@deno.land
@@ -46,9 +46,9 @@ modules on the server.
 
 ## GitHub
 
-To be able to access private repositories on GitHub, you would need to issue
-yourself a _personal access token_. You do this by logging into GitHub and going
-under _Settings -> Developer settings -> Personal access tokens_:
+To access private repositories on GitHub, you would need to issue yourself a
+_personal access token_. You do this by logging into GitHub and going under
+_Settings -> Developer settings -> Personal access tokens_:
 
 ![Personal access tokens settings on GitHub](../../images/private-pat.png)
 

diff --git a/basics/permissions.md b/basics/permissions.md
@@ -4,6 +4,18 @@ Deno is secure by default. Therefore, unless you specifically enable it, a
 program run with Deno has no file, network, or environment access. Access to
 security sensitive functionality requires that permissions have been granted to
 an executing script through command line flags, or a runtime permission prompt.
+This is a major difference from Node, where dependencies are automatically
+granting full access to everything, introducing hidden vulnerabilities in your
+project.
+
+## Run untrusted code with confidence
+
+Since Deno provides no I/O access by default, it's useful for running untrusted
+code and auditing third-party code. If you're building or extending a platform
+that runs user generated code, you can use Deno for running third-party code
+securely and host this code through
+[Deno Subhosting](https://deno.com/subhosting) or any other cloud platform of
+your choice.
 
 For the following example `mod.ts` has been granted read-only access to the file
 system. It cannot write to the file system, or perform any other security
@@ -53,6 +65,41 @@ The following permissions are available:
 - **-A, --allow-all** Allow all permissions. This enables all security sensitive
   functions. Use with caution.
 
+Starting with Deno 1.36 following flags are available:
+
+- **--deny-env=\<VARIABLE_NAME\>** Deny environment access for things like
+  getting and setting of environment variables. You can specify an optional,
+  comma-separated list of environment variables to provide an allow-list of
+  allowed environment variables. Any environment variables specified here will
+  be denied access, even if they are specified in --allow-env.
+- **--deny-sys=\<API_NAME\>** Deny access to APIs that provide information about
+  user's operating system.
+- **--deny-hrtime** Disable high-resolution time measurement. High-resolution
+  time can be used in timing attacks and fingerprinting.
+- **--deny-net=\<IP/HOSTNAME\>** Disable network access. You can specify an
+  optional, comma-separated list of IP addresses or hostnames (optionally with
+  ports) to provide a deny-list of network addresses. Any addresses specified
+  here will be denied access, even if they are specified in --allow-net.
+- **--deny-ffi=\<PATH\>** Deny loading of dynamic libraries. You can specify an
+  optional, comma-separated list of directories or files to provide a deny-list
+  of allowed dynamic libraries to load. Any libraries specified here will be
+  denied access, even if they are specified in --allow-ffi. Please note that
+  --deny-ffi is an unstable feature.
+- **--deny-read=\<PATH\>** Deny file system read access. You can specify an
+  optional, comma-separated list of directories or files to provide a deny-list
+  of allowed file system access. Any paths specified here will be denied access,
+  even if they are specified in --allow-read.
+- **--deny-run=\<PROGRAM_NAME\>** Deny running subprocesses. You can specify an
+  optional, comma-separated list of subprocesses to provide a deny-list of
+  allowed subprocesses. Be aware that subprocesses are not run in a sandbox and
+  therefore do not have the same security restrictions as the Deno process.
+  Therefore, use with caution. Any programs specified here will be denied
+  access, even if they are specified in --allow-run.
+- **--deny-write=\<PATH\>** Deny file system write access. You can specify an
+  optional, comma-separated list of directories or files to provide a deny-list
+  of allowed file system access. Any paths specified here will be denied access,
+  even if they are specified in --allow-write.
+
 ## Configurable permissions
 
 Some permissions allow you to grant access to a specific list of entities
@@ -65,7 +112,7 @@ This example restricts file system access by allowing read-only access to the
 attempting to read a file in the `/etc` directory:
 
 ```shell
-$ deno run --allow-read=/usr https://deno.land/std@$STD_VERSION/examples/cat.ts /etc/passwd
+$ deno run --allow-read=/usr https://deno.land/std@0.198.0/examples/cat.ts /etc/passwd
 error: Uncaught PermissionDenied: read access to "/etc/passwd", run again with the --allow-read flag
 ► $deno$/dispatch_json.ts:40:11
     at DenoError ($deno$/errors.ts:20:5)
@@ -76,7 +123,16 @@ Try it out again with the correct permissions by allowing access to `/etc`
 instead:
 
 ```shell
-deno run --allow-read=/etc https://deno.land/std@$STD_VERSION/examples/cat.ts /etc/passwd
+deno run --allow-read=/etc https://deno.land/std@0.198.0/examples/cat.ts /etc/passwd
+```
+
+You can further restrict some sub-paths to not be accessible, using
+`--deny-read` flag:
+
+```shell
+deno run --allow-read=/etc --deny-read=/etc/hosts https://deno.land/std@0.198.0/examples/cat.ts /etc/passwd
+deno run --allow-read=/etc --deny-read=/etc/hosts https://deno.land/std@0.198.0/examples/cat.ts /etc/hosts
+error: Uncaught PermissionDenied: read access to "/etc/hosts"...
 ```
 
 `--allow-write` works the same as `--allow-read`.
@@ -110,6 +166,14 @@ deno run --allow-net=1.1.1.1:443 fetch.js
 deno run --allow-net=[2606:4700:4700::1111] fetch.js
 ```
 
+You can restrict certain domains to never be accessible by using the
+`--deny-net` flag:
+
+```shell
+# Allow to make network connections to all addresses except myserver.com.
+deno run --allow-net --deny-net=myserver.com fetch.js
+```
+
 If `fetch.js` tries to establish network connections to any hostname or IP not
 explicitly allowed, the relevant call will throw an exception.
 
@@ -139,6 +203,14 @@ deno run --allow-env=HOME env.js
 > Note for Windows users: environment variables are case insensitive on Windows,
 > so Deno also matches them case insensitively (on Windows only).
 
+You can restrict certain env vars to never be accessible by using the
+`--deny-env` flag:
+
+```shell
+# Allow all environment variables except AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
+deno run --allow-env --deny-env=AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY env.js
+```
+
 ### Subprocess permissions
 
 Subprocesses are very powerful, and can be a little scary: they access system
@@ -170,3 +242,11 @@ deno run --allow-run run.js
 You can only limit the executables that are allowed; if permission is granted to
 execute it then any parameters can be passed. For example if you pass
 `--allow-run=cat` then the user can use `cat` to read any file.
+
+You can restrict certain executables to never be accessible by using the
+`--deny-run` flag:
+
+```shell
+# Disallow spawning `git`.
+deno run --allow-run --deny-run=git run.js
+```