Deno 1.24 Release Notes

Deno 1.24 has been tagged and released with the following new features and changes:

Type checking and emitting performance improvements
unhandledrejection event
beforeunload event
import.meta.resolve() API
FFI API improvements
deno test improvements
Updates to new subprocess API
LSP improvements
Addition of semver module
Improvement of typings in flags module
Addition of variable expansion in dotenv module

If you already have Deno installed, you can upgrade to 1.24 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

Type checking and emitting performance improvements

Previously, Deno internally converted TypeScript code to JavaScript using the TypeScript compiler when the --check flag was specified and otherwise it used swc. In this release, all emitting is done with swc, which is much faster.

Additionally due to some architectural refactors:

Emitting no longer occurs with deno check.
The cache used to store the emitted JavaScript is more robust.
Deno is smarter about not type checking if it has successfully type checked some code in the past.

Overall, these improvements should have a considerable performance improvement, but will vary depending on the codebase. For example, type checking oak’s repository without a cache is 20% faster on the first run of deno check, then 70% faster on subsequent runs when there was a change to the code. In some cases, it’s over 90% faster because Deno got better at identifying it previously type checked successfully.

`unhandledrejection` event

This release adds support for the unhandledrejection event. This event is fired when a promise that has no rejection handler is rejected, ie. a promise that has no .catch() handler or a second argument to .then().

Example:

// unhandledrejection.js
globalThis.addEventListener("unhandledrejection", (e) => {
  console.log("unhandled rejection at:", e.promise, "reason:", e.reason);
  e.preventDefault();
});

function Foo() {
  this.bar = Promise.reject(new Error("bar not available"));
}

new Foo();
Promise.reject();

Running this program will print:

$ deno run unhandledrejection.js
unhandled rejection at: Promise {
  <rejected> Error: bar not available
    at new Foo (file:///dev/unhandled_rejection.js:7:29)
    at file:///dev/unhandled_rejection.js:10:1
} reason: Error: bar not available
    at new Foo (file:///dev/unhandled_rejection.js:7:29)
    at file:///dev/unhandled_rejection.js:10:1
unhandled rejection at: Promise { <rejected> undefined } reason: undefined

This API will allow us to polyfill process.on("unhandledRejection") in the Node compatibility layer in future releases.

`beforeunload` event

This release adds support for the beforeunload event. This event is fired when the event loop has no more work to do and is about to exit. Scheduling more asynchronous work (like timers or network requests) will cause the program to continue.

Example:

// beforeunload.js
let count = 0;

console.log(count);

globalThis.addEventListener("beforeunload", (e) => {
  console.log("About to exit...");
  if (count < 4) {
    e.preventDefault();
    console.log("Scheduling more work...");
    setTimeout(() => {
      console.log(count);
    }, 100);
  }

  count++;
});

globalThis.addEventListener("unload", (e) => {
  console.log("Exiting");
});

count++;
console.log(count);

setTimeout(() => {
  count++;
  console.log(count);
}, 100);

Running this program will print:

$ deno run beforeunload.js
0
1
2
About to exit...
Scheduling more work...
3
About to exit...
Scheduling more work...
4
About to exit...
Exiting

This has allowed us to polyfill process.on("beforeExit") in the Node compatibility layer.

`import.meta.resolve()` API

Deno supported import.meta since v1.0. Two available options were import.meta.url to tell the URL of the current module and import.meta.main to let you know if the current module is the entry point to your program. This release adds support for the import.meta.resolve() API, which lets you resolve specifiers relative to the current module.

Before:

const worker = new Worker(new URL("./worker.ts", import.meta.url).href);

After:

const worker = new Worker(import.meta.resolve("./worker.ts"));

The advantage of this API over the URL API is that it takes into account the currently applied import map, which gives you the ability to resolve “bare” specifiers as well.

With such import map loaded…

{
  "imports": {
    "fresh": "https://deno.land/x/[email protected]/dev.ts"
  }
}

…you can now resolve:

// resolve.js
console.log(import.meta.resolve("fresh"));

$ deno run resolve.js
https://deno.land/x/[email protected]/dev.ts

FFI API improvements

This release adds new features and performance improvements in the unstable Foreign Function Interface API

Callbacks

FFI calls now support passing JS callbacks as thread-safe C functions.

The new Deno.UnsafeCallback class is used to prepare a JS function to be used as an argument:

// type AddFunc = extern "C" fn (a: u32, b: u32) -> u32;
//
// #[no_mangle]
// extern "C" fn add(js_func: AddFunc) -> u32 {
//   js_func(2, 3)
// }
//
const { symbols: { add } } = Deno.dlopen("libtest.so", {
  add: {
    parameters: ["function"],
    return: "u32",
    // Use `callback: true` indicate that this call might
    // callback into JS.
    callback: true,
  }
});

const jsAdd(a, b) { return a + b };

const cFunction = new Deno.UnsafeCallback({
  parameters: ["u32", "u32"],
  result: ["u32"]
}, jsAdd);

const result = add(cFunction.pointer); // 5

Thank you to Aapo Alasuutari for implementing this feature.

Improved FFI call performance

Many FFI calls are now ~200x faster in this release. This is achieved through a combination of V8 fast api calls and JIT trampolines. Deno dynamically generates optimized JIT code for calling into FFI alongside leveraging V8 fast api calls.

Before:

cpu: Apple M1
runtime: deno 1.23.0 (aarch64-apple-darwin)

file:///ffi_bench.js
benchmark                              time (avg)             (min … max)       p75       p99      p995
------------------------------------------------------------------------- -----------------------------
nop()                              436.71 ns/iter   (403.72 ns … 1.26 µs) 408.97 ns 968.96 ns   1.26 µs
add_u32()                          627.42 ns/iter (619.14 ns … 652.66 ns) 630.02 ns 652.66 ns 652.66 ns

After:

cpu: Apple M1
runtime: deno 1.24.0 (aarch64-apple-darwin)

file:///ffi_bench.js
benchmark                              time (avg)             (min … max)       p75       p99      p995
------------------------------------------------------------------------- -----------------------------
nop()                                2.23 ns/iter    (2.18 ns … 12.32 ns)    2.2 ns   2.36 ns   2.67 ns
add_u32()                            4.79 ns/iter     (4.7 ns … 11.91 ns)   4.73 ns   5.77 ns  10.05 ns

In future, we will expand this optimization to work for TypedArrays and safe number pointers.

See denoland/deno#15125 and denoland/deno#15139 for more information.

Removed `Deno.UnsafePointer`

Before, pointers in Deno were represented using an indirect class Deno.UnsafePointer. Deno.UnsafePointer has been removed in favor of bigint.

Hence, Deno.UnsafePointer.of now returns a bigint:

const ptr: bigint = Deno.UnsafePointer.of(new Uint8Array([1, 2, 3]));
call_symbol(ptr, 3);

`deno test` improvements

Including and excluding paths in the configuration file

Previously when running deno test, if you wanted to include or exclude specific paths this needed to be specified as CLI arguments.

For example:

# only test these paths
deno test src/fetch_test.ts src/signal_test.ts
# exclude testing this path
deno test --ignore=out/

Needing to provide this on the command line each time is not so ideal in some projects, so in this release you can specify these options in the Deno configuration file:

{
  "test": {
    "files": {
      "include": [
        "src/fetch_test.ts",
        "src/signal_test.ts"
      ]
    }
  }
}

Or more likely:

{
  "test": {
    "files": {
      "exclude": ["out/"]
    }
  }
}

Then running deno test in the same directory tree as the configuration file will take these options into account.

Thanks to @roj1512 who contributed this feature.

`--parallel` flag

In previous releases, it was possible to run tests in parallel by using the --jobs CLI flag:

deno test --jobs
# or specify the amount of parallelism
deno test --jobs 4

This name was not very discoverable though. Additionally, it had an oversight in its design where --jobs did not require an equals sign after it when providing a numeric value (ex. --jobs=4), meaning that if you didn’t provide a value then the flag needed to be the last argument provided (ex. deno test --jobs my_test_file.ts would error parsing “my_test_file.ts” as a number, so you would need to write deno test my_test_file.ts --jobs).

In this release, the --jobs flag has been soft deprecated with a warning and a new --parallel flag has been added.

deno test --parallel

Also, there is no longer a way to restrict the max amount of parallelism as a CLI arg as this value was often dependent on the system. For this reason, it’s been moved to the DENO_JOBS environment variable (ex. DENO_JOBS=4).

Thanks to Mark Ladyshau who contributed this feature.

Updates to new subprocess API

In Deno v1.21 we introduced a new unstable subprocess API. This release brings a significant update to this API.

First, we changed types of stdio streams; instead of complicated generic types describing which streams are available, they are now simple, always available streams. If you try to access one of these streams and it’s not set to “piped”, a TypeError will be thrown. The defaults are documented here.

Before:

// spawn.ts
const child = Deno.spawnChild("echo", {
  args: ["hello"],
  stdout: "piped",
  stderr: "null",
});
const readableStdout = child.stdout.pipeThrough(new TextDecoderStream());
const readableStderr = child.stderr.pipeThrough(new TextDecoderStream());

$ deno check --unstable spawn.ts
Check file:///dev/spawn.ts
error: TS2531 [ERROR]: Object is possibly 'null'.
const readableStderr = child.stderr.pipeThrough(new TextDecoderStream());
                       ~~~~~~~~~~~~
    at file:///dev/spawn.ts:7:24

$ deno run --allow-run --unstable spawn.ts
error: Uncaught TypeError: Cannot read properties of null (reading 'pipeThrough')
const readableStderr = child.stderr.pipeThrough(new TextDecoderStream());
                                    ^
    at file:///dev/spawn.ts:7:37

After:

const child = Deno.spawnChild("echo", {
  args: ["hello"],
  stdout: "piped",
  stderr: "null",
});
const readableStdout = child.stdout.pipeThrough(new TextDecoderStream());
const readableStderr = child.stderr.pipeThrough(new TextDecoderStream());

$ deno check --unstable spawn.ts
Check file:///dev/spawn.ts

$ deno run --allow-run --unstable spawn.ts
error: Uncaught TypeError: stderr is not piped
const readableStderr = child.stderr.pipeThrough(new TextDecoderStream());
                             ^
    at Child.get stderr (deno:runtime/js/40_spawn.js:107:15)
    at file:///dev/spawn.ts:7:30

Next, we changed to signature of the SpawnOutput type to extend ChildStatus instead of embedding it as a field.

Before:

const { status, stdout } = await Deno.spawn("echo", {
  args: ["hello"],
});
console.log(status.success);
console.log(status.code);
console.log(status.signal);
console.log(stdout);

After:

const { success, code, signal, stdout } = await Deno.spawn("echo", {
  args: ["hello"],
});
console.log(success);
console.log(code);
console.log(signal);
console.log(stdout);

Finally, two new methods Child.ref() and Child.unref() were added that allow you to tell Deno that it shouldn’t wait for subprocess completion before exiting your program. These APIs are useful for programs that need to run subprocesses in the background. For example, you might want to spawn esbuild in the background to be able to transpile files on demand, but you don’t want that subprocess to prevent your program exiting.

Thank you Nayeem Rahman for contributing this feature!

LSP improvements

This release features better auto-import support in the editor and no longer requires restarting the LSP after caching dependencies as was previously necessary in some scenarios.

Import map quick fix and diagnostics

The LSP now provides a quick fix to convert absolute specifiers to use an entry in the import map, if one exists.

For example, given the following import map:

{
  "imports": {
    "std/": "https://deno.land/[email protected]/"
  }
}

The quick fix will change an import specifier such as "https://deno.land/[email protected]/path/mod.ts" to "std/path/mod.ts".

Additionally, import map diagnostics are now surfaced in the LSP to help catch issues more quickly.

Addition of `semver` module

In this release, the semver module has been added to the standard modules.

You can validate, compare, and manipulate semver strings with this module.

import * as semver from "https://deno.land/[email protected]/semver/mod.ts";

semver.valid("1.2.3"); // "1.2.3"
semver.valid("a.b.c"); // null
semver.gt("1.2.3", "9.8.7"); // false
semver.lt("1.2.3", "9.8.7"); // true
semver.inc("1.2.3", "patch"); // "1.2.4"
semver.inc("1.2.3", "minor"); // "1.3.0"
semver.inc("1.2.3", "major"); // "2.0.0"

The module also supports the handling of semver ranges. The notations are compatible with node-semver npm module.

semver.satisfies("1.2.3", "1.x || >=2.5.0 || 5.0.0 - 7.2.3"); // true
semver.minVersion(">=1.0.0"); // "1.0.0"

This module is a fork of node-semver with addition of appropriate typings.

Thanks @justjavac for contributing this feature.

Improvement of typings in `flags` module

In this release, the type definition of the parse method in the flags standard module has been largely improved. Now the parsed object has correctly typed properties depending on the given option.

For example, let’s see the below example:

import { parse } from "https://deno.land/[email protected]/flags/mod.ts";

const args = parse(Deno.args, {
  boolean: ["help"],
  string: ["n"],
});

This example defines help as a boolean argument and n as a string argument. The parsed object args has the below type:

type Result = {
  [x: string]: unknown;
  n?: string | undefined;
  help: boolean;
  _: (string | number)[];
};

Here n and help are correctly typed based on the given option object.

Thanks Benjamin Fischer for contributing this feature.

Addition of variable expansion in `dotenv` module

In this release, variable expansion has been enabled in the dotenv standard module.

Now a .env file like the below is valid:

FOO=example
BAR=${FOO}
BAZ=http://${FOO}.com/
QUX=/path/to/${QUUX:-main}

This .env file works like the following:

import "https://deno.land/[email protected]/dotenv/load.ts";

console.log(Deno.env.get("FOO"));
console.log(Deno.env.get("BAR"));
console.log(Deno.env.get("BAZ"));
console.log(Deno.env.get("QUX"));

The above outputs:

example
example
http://example.com/
/path/to/main

Thanks @sevenwithawp for contributing this feature.

Deno 1.24 Release Notes

Type checking and emitting performance improvements

unhandledrejection event

beforeunload event

import.meta.resolve() API

FFI API improvements

Callbacks

Improved FFI call performance

Removed Deno.UnsafePointer

deno test improvements

Including and excluding paths in the configuration file

--parallel flag

Updates to new subprocess API

LSP improvements

Import map quick fix and diagnostics

Addition of semver module

Improvement of typings in flags module

Addition of variable expansion in dotenv module

`unhandledrejection` event

`beforeunload` event

`import.meta.resolve()` API

Removed `Deno.UnsafePointer`

`deno test` improvements

`--parallel` flag

Addition of `semver` module

Improvement of typings in `flags` module

Addition of variable expansion in `dotenv` module