Deno 1.10 Release Notes

Deno 1.10 has been tagged and released. It contains new features, performance improvements, and bug fixes.

Most notably:

• Improvements to the built-in test runner
• Structured clone supported in Web Workers
• Web Storage API added
• Support for remote import maps

If you already have Deno installed you can upgrade to 1.10 by running deno upgrade. If you are installing Deno for the first time, you can use one of the methods listed below:

# Using Shell (macOS and Linux):
curl -fsSL https://deno.land/x/install/install.sh | sh

# Using PowerShell (Windows):
iwr https://deno.land/x/install/install.ps1 -useb | iex

# Using Homebrew (macOS):
brew install deno

# Using Scoop (Windows):
scoop install deno

# Using Chocolatey (Windows):
choco install deno

Improvements to deno test

Deno 1.10 brings a major overhaul to built-in test runner.

Isolated and parallel execution of tests: Before this release, Deno ran all tests serially inside a single runtime instance. Now all discovered test modules are run in isolation using a new instance of a runtime for each of the modules. deno test now supports the --jobs flag that allows one to specify how many threads should be used when running tests. By default all tests are still run serially.

Configurable permissions for tests: Deno has a number of flags that allow to specify permissions a program is allowed to use. To ease testing of your program under different permissions sets, Deno.test now supports permissions option that allows to specify exact permissions to be applied to a test case.

Deno.test({
  name: "write only",
  permissions: { write: true, read: false },
  async fn() {
    await Deno.writeTextFile("./foo.txt", "I can write!");
    console.log(await Deno.readTextFile("./foo.txt"));
  },
});

Note we get the expected failure despite providing --allow-read:

$ deno test --allow-read --allow-write --unstable test_permissions.ts
Check file:///Users/ry/src/deno/test_permissions.ts
running 1 test from file:///Users/ry/src/deno/test_permissions.ts
test write only ... FAILED (5ms)

failures:

write only
PermissionDenied: Requires read access to "./foo.txt", run again with the --allow-read flag
    at deno:core/core.js:86:46
    at unwrapOpResult (deno:core/core.js:106:13)
    at async open (deno:runtime/js/40_files.js:46:17)
    at async Object.readTextFile (deno:runtime/js/40_read_file.js:40:18)
    at async fn (file:///Users/ry/src/deno/test_permissions.ts:6:17)
    at async asyncOpSanitizer (deno:runtime/js/40_testing.js:21:9)
    at async resourceSanitizer (deno:runtime/js/40_testing.js:58:7)
    at async exitSanitizer (deno:runtime/js/40_testing.js:85:9)
    at async runTest (deno:runtime/js/40_testing.js:199:7)
    at async Object.runTests (deno:runtime/js/40_testing.js:244:7)

failures:

    write only

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out (37ms)

Keep in mind, permissions requested by a test case cannot exceed permissions granted to the process using --allow-* flags. If a key is omitted in permissions object then it inherits its value from the respective --allow-* flag.

This feature requires use of --unstable flag.

Better test runner output: When running a test suite a prompt will be displayed for each discovered module with number of tests and origin of those tests.

running 4 tests from file:///dev/deno/cli/tests/unit/tty_test.ts
test consoleSizeFile ... ok (11ms)
test consoleSizeError ... ok (4ms)
test isatty ... ok (4ms)
test isattyError ... ok (3ms)
running 6 tests from file:///dev/deno/cli/tests/unit/rename_test.ts
test renameSyncSuccess ... ok (17ms)
test renameSyncReadPerm ... ok (5ms)
test renameSyncWritePerm ... ok (6ms)
test renameSuccess ... ok (13ms)
test renameSyncErrorsUnix ... ok (34ms)
test renameSyncErrorsWin ... ignored (1ms)
...

Type check examples in documentation: Ensuring documentation stays up to date is crucial for all projects. It is easy to forget to update code samples after changing the API, leading to stale code samples. To prevent such situations deno test now supports the --doc flag that will type check code examples in the documentation comments.

/**
 * ```
 * import { example } from "./test_docs.ts";
 *
 * console.assert(example() == 42);
 * ```
 */
export function example(): string {
  return "example";
}

Try it yourself:

$ deno test --doc https://deno.com/blog/v1.10/test_docs.ts

Check file:///dev/test_docs.ts:2-7
error: TS2367 [ERROR]: This condition will always return 'false' since the types 'string' and 'number' have no overlap.
console.assert(example() == 42);
               ~~~~~~~~~~~~~~~
    at file:///dev/test_docs.ts:2-7.ts:3:16

In the future releases we plan to add support for running code examples as regular tests.

Watch for file changes when running tests: deno test now supports the --watch flag that will keep the process alive after finishing tests and watch for file changes to re-run relevant test cases.

As in other subcommands that support --watch flag, the files that are needed to be watched are automatically discovered by Deno.

Thank you to Casper Beyer and Liam Murphy who contributed these features.

Worker.postMessage supports structured clone algorithm

Web Workers are the parallelization primitive of the web. They allow you to run multiple bits of JavaScript, TypeScript, or WASM concurrently, in separate execution environments (isolates). You can communicate between these workers and the main thread by passing messages from one to another.

Deno has supported web workers ever since our initial 1.0 release, but there was a major limitation: until now Worker.postMessage() used non-spec compliant algorithm that internally JSON-stringified messages. This solution led to some surprising pitfalls for users, because not all values and objects were serialized properly. This release changes that to allow any data which can be serialized using the structured clone algorithm.

Here is an example of sending a recursive JavaScript object to a Worker, which previously would have thrown an error:

const obj = { hello: "world" };
obj.self = obj;

const worker = new Worker(
  "data:application/javascript,self.onmessage = (e) => self.postMessage(e.data);",
  { type: "module" },
);

worker.onmessage = (e) => {
  console.log("Received event:", e.data);
};
worker.postMessage(obj);

Thank you to Tim Ramlot who contributed this feature.

Support for Web Storage API

This release adds support for the Web Storage API. This API consists of localStorage and sessionStorage, which can be used to store a small amount of data persistently, without direct file system access. Data is keyed by origin (which in Deno can be set with --location). You can make use of localStorage and sessionStorage without requiring any permissions.

The underlying storage layer and persistence is opaque to applications, and thus not security relevant.

The API works just like in the browser: localStorage can be used to persistently store up to 5 MB of data across process restarts, while sessionStorage can be used to store a small amount of data for the duration of the process.

Here is an example:

// kv.ts

const key = Deno.args[0];

if (key === undefined) {
  // if user passes no args, display number of entries
  console.log(localStorage.length);
} else {
  const value = Deno.args[1];

  if (value === undefined) {
    // if no value is specified, return value of the key
    console.log(localStorage.getItem(key));
  } else {
    // if value is specified, set the value
    localStorage.setItem(key, value);
  }
}

$ deno run --location https://example.com ./kv.ts
0
$ deno run --location https://example.com ./kv.ts foo bar
$ deno run --location https://example.com ./kv.ts foo
bar
$ deno run --location https://example.com ./kv.ts
1

Thank you to crowlKats who contributed this feature.

Support denoD;fmt-ignore-file directive for Markdown files

deno fmt is a formatter based on dprint that is able to format JavaScript, TypeScript, JSON and Markdown files.

To skip formatting of a file one can use deno&#002D;fmt-ignore-file directive in a form of comment at the top of the file. Previously those directives were not working in Markdown files, but from 1.10 they are now supported.

To skip formatting a Markdown file use <!-- deno&#002D;fmt-ignore-file --> at the top of the file.

Enable support for shared WASM memory

This release enables support for atomics and shared memory in WebAssembly. This feature is already enabled by default in Chrome and Firefox, and now also in Deno.

Setting the shared to true in the WebAssembly.Memory constructor enables atomics, and allows for shared array buffers as WASM memory the backing store.

const memory = new WebAssembly.Memory({
  initial: 1,
  maximum: 10,
  shared: true,
});
console.assert(memory.buffer instanceof SharedArrayBuffer);

WASM threading is not yet possible in Deno, because of the lack of support for transferring (shared) array buffers to workers. This is a feature we want to introduce soon. To learn more about WASM threads, you can read this blog post from Alex Danilo.

Support remote import maps

Deno stabilized import maps in Deno v1.8, after they were stabilized in Chrome 89. In 1.10 we have enabled the use of remote import maps. This means that import maps now do not have to be stored on the local file system, they can also be loaded over HTTP:

$ deno install --import-map=https://example.com/import_map.json -n example https://example.com/mod.ts

Updated plugin API

This release refreshes the plugin interface and allows them to leverage serde_v8 for interfacing between runtime and the native plugin. This update provides all necessary utilities to dispatch ops from native plugins without needing to use third party code. Additionally plugins are now allowed to access ResourceTable to store Rust objects inside the runtime infrastructure. Refer to the test_plugin example for how to use those APIs. The plugin system still requires the --unstable flag, as it’s an experimental feature.

Thank you to Elias Sjögreen who contributed this refactor.

Remove unstable flag for CLI features

Some parts of Deno are not yet stable and might undergo breaking changes before being stabilized - this refers mostly to JavaScript APIs. To use those APIs it is required to specify --unstable flag when running Deno. However this flag was also used to mark some of CLI features that were not yet stable (like deno lint). In 1.10 we have removed requirement to use --unstable flag for CLI features, and thus, from now on --unstable flag controls only the availability of unstable runtime APIs. Some of the CLI features that are still considered unstable have appropriate comments in their help text (UNSTABLE:). However they no longer require to use --unstable flag to run the subcommand, eg. deno compile, deno lint.