Module

std/node/README.md

Deno standard library
denoland/deno_std
Go to Latest
File

Deno Node compatibility

This module is meant to have a compatibility layer for the NodeJS 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 Builtins

  • assert partly
  • buffer
  • child_process
  • cluster
  • console
  • constants partly
  • crypto partly
  • dgram
  • dns
  • events
  • fs partly
  • http
  • http2
  • https
  • module
  • net
  • os partly
  • path
  • perf_hooks
  • process partly
  • querystring
  • readline
  • repl
  • stream
  • string_decoder
  • sys
  • timers
  • tls
  • tty partly
  • url
  • util partly
  • v8 can’t implement
  • vm
  • worker_threads
  • zlib
  • node globals partly

Deprecated

These builtins are deprecated in NodeJS v13 and will probably not be polyfilled:

  • domain
  • freelist
  • punycode

Experimental

These builtins are experimental in NodeJS v13 and will not be polyfilled until they are stable:

  • async_hooks
  • inspector
  • policies
  • report
  • trace_events
  • wasi

CommonJS Module 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

This library contains automated tests pulled directly from the Node repo in order ensure compatibility.

Setting up the test runner is as simple as running the node/_tools/setup.ts file, this will pull the configured tests in and then add them to the test workflow.

To enable new tests, simply add a new entry inside node/_tools/config.json under the tests property. The structure this entries must have has to resemble a path inside https://github.com/nodejs/node/tree/master/test.

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.