Deno Node.js compatibility

This module is meant to have a compatibility layer for the Node.js standard library.

Warning: Any function of this module should not be referred anywhere in the Deno standard library as it's a compatibility module.

Supported modules

assert
assert/strict partly
async_hooks partly
buffer
child_process partly
cluster partly
console partly
constants partly
crypto partly
dgram partly
diagnostics_channel partly
dns partly
events
fs partly
fs/promises partly
http partly
http2
https partly
inspector partly
module
net
os partly
path
path/posix
path/win32
perf_hooks
process partly
punycode
querystring
readline
repl partly
stream
stream/promises
stream/web partly
string_decoder
sys
timers
timers/promises
tls
trace_events
tty partly
url
util partly
util/types partly
v8
vm partly
wasi
webcrypto
worker_threads
zlib

node globals partly

Deprecated

These modules are deprecated in Node.js and will probably not be polyfilled:

domain
freelist

Experimental

These modules are experimental in Node.js and will not be polyfilled until they are stable:

diagnostics_channel
async_hooks
policies
trace_events
wasi
webcrypto

CommonJS modules loading

createRequire(...) is provided to create a require function for loading CJS modules. It also sets supported globals.

import { createRequire } from "https://deno.land/std@$STD_VERSION/node/module.ts";

const require = createRequire(import.meta.url);
// Loads native module polyfill.
const path = require("path");
// Loads extensionless module.
const cjsModule = require("./my_mod");
// Visits node_modules.
const leftPad = require("left-pad");

Contributing

Setting up the test runner and running tests

See tools/node_compat/README.md.

Best practices

When converting from promise-based to callback-based APIs, the most obvious way is like this:

promise.then((value) => callback(null, value)).catch(callback);

This has a subtle bug - if the callback throws an error, the catch statement will also catch that error, and the callback will be called twice. The correct way to do it is like this:

promise.then((value) => callback(null, value), callback);

The second parameter of then can also be used to catch errors, but only errors from the existing promise, not the new one created by the callback.

If the Deno equivalent is actually synchronous, there's a similar problem with try/catch statements:

try {
  const value = process();
  callback(null, value);
} catch (err) {
  callback(err);
}

Since the callback is called within the try block, any errors from it will be caught and call the callback again.

The correct way to do it is like this:

let err, value;
try {
  value = process();
} catch (e) {
  err = e;
}
if (err) {
  callback(err); // Make sure arguments.length === 1
} else {
  callback(null, value);
}

It's not as clean, but prevents the callback being called twice.

Remaining Tests

Node compatibility can be measured by how many native Node tests pass. If you'd like to know what you can work on, check out the list of Node tests remaining here.

3.6 KiB Raw Blame History