util: add util.sleep()

doc/api/util.md

@@ -936,6 +936,15 @@ added: v8.0.0
 * {symbol} that can be used to declare custom promisified variants of functions,
 see [Custom promisified functions][].
 
+## util.sleep(msec)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `msec` {integer} The number of milliseconds to sleep for.
+
+Causes the calling thread to sleep for `msec` milliseconds.
+
 ## Class: util.TextDecoder
 <!-- YAML
 added: v8.3.0

lib/util.js

@@ -49,7 +49,7 @@ const {
   inspect
 } = require('internal/util/inspect');
 const { debuglog } = require('internal/util/debuglog');
-const { validateNumber } = require('internal/validators');
+const { validateNumber, validateUint32 } = require('internal/validators');
 const { TextDecoder, TextEncoder } = require('internal/encoding');
 const { isBuffer } = require('buffer').Buffer;
 const types = require('internal/util/types');
@@ -59,6 +59,7 @@ const {
   getSystemErrorName: internalErrorName,
   promisify
 } = require('internal/util');
+const { sleep: _sleep } = internalBinding('util');
 
 let internalDeepEqual;
 
@@ -232,6 +233,11 @@ function getSystemErrorName(err) {
   return internalErrorName(err);
 }
 
+function sleep(msec) {
+  validateUint32(msec, 'msec');
+  _sleep(msec);
+}
+
 // Keep the `exports =` so that various functions can still be monkeypatched
 module.exports = {
   _errnoException: errnoException,
@@ -269,6 +275,7 @@ module.exports = {
   isPrimitive,
   log,
   promisify,
+  sleep,
   TextDecoder,
   TextEncoder,
   types

src/node_util.cc

@@ -161,6 +161,12 @@ static void SetHiddenValue(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(maybe_value.FromJust());
 }
 
+static void Sleep(const FunctionCallbackInfo<Value>& args) {
+  CHECK(args[0]->IsUint32());
+  uint32_t msec = args[0].As<Uint32>()->Value();
+  uv_sleep(msec);
+}
+
 void ArrayBufferViewHasBuffer(const FunctionCallbackInfo<Value>& args) {
   CHECK(args[0]->IsArrayBufferView());
   args.GetReturnValue().Set(args[0].As<ArrayBufferView>()->HasBuffer());
@@ -282,6 +288,7 @@ void Initialize(Local<Object> target,
   env->SetMethodNoSideEffect(target, "getOwnNonIndexProperties",
                                      GetOwnNonIndexProperties);
   env->SetMethodNoSideEffect(target, "getConstructorName", GetConstructorName);
+  env->SetMethod(target, "sleep", Sleep);
 
   env->SetMethod(target, "arrayBufferViewHasBuffer", ArrayBufferViewHasBuffer);
   Local<Object> constants = Object::New(env->isolate());

test/parallel/test-util-sleep.js

@@ -0,0 +1,18 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+const { sleep } = require('util');
+
+[undefined, null, '', {}, true, false].forEach((value) => {
+  assert.throws(
+    () => { sleep(value); },
+    /The "msec" argument must be of type number/
+  );
+});
+
+[-1, 3.14, NaN, 4294967296].forEach((value) => {
+  assert.throws(
+    () => { sleep(value); },
+    /The value of "msec" is out of range/
+  );
+});