lib: add requestAnimationFrame global

Adds the browser API `requestAnimationFrame()` as an isomorphic
wrapper around `setImmediate()`. Marked Legacy with a clear
indication that code targeting Node.js should use `setImmediate()`
instead.

Signed-off-by: James M Snell <jasnell@gmail.com>

Author: jasnell

.eslintrc.js

@@ -331,5 +331,7 @@ module.exports = {
     globalThis: 'readable',
     btoa: 'readable',
     atob: 'readable',
+    requestAnimationFrame: 'readable',
+    cancelAnimationFrame: 'readable',
   },
 };

doc/api/globals.md

@@ -164,6 +164,29 @@ added: REPLACEME
 
 Global alias for [`buffer.btoa()`][].
 
+## `cancelAnimationFrame(immediateObject)`
+<!-- YAML
+added: REPLACEME
+-->
+
+<!--type=global-->
+
+> Stability: 3 - Legacy: Use clearImmediate() instead.
+
+* `immediateObject` {Object} The return value of `requestAnimationFrame()`
+  identifying the request being canceled.
+
+```js
+const req = requestAnimationFrame((ts) => {
+  console.log(`called at ${ts}`);
+});
+
+cancelAnimationFrame(req);
+```
+
+In Node.js, `cancelAnimationFrame()` is an alias for `clearImmediate()`.
+Code specifically targeting Node.js should use `clearImmediate()` instead.
+
 ## `clearImmediate(immediateObject)`
 <!-- YAML
 added: v0.9.1
@@ -329,6 +352,33 @@ DataHandler.prototype.load = async function load(key) {
 };
 ```
 
+## `requestAnimationFrame(callback)`
+<!-- YAML
+added: REPLACEME
+-->
+
+<!--type=global-->
+
+> Stability: 3 - Legacy: Use the setImmediate() instead.
+
+* `callback` {Function}
+* Returns {Object}
+
+Registers a function with `setImmediate()` that is invoked with a single
+argument set to the value of `perf_hooks.performance.now()`.
+
+```js
+requestAnimationFrame((ts) => {
+  console.log(`called at ${ts}`);
+});
+```
+
+Node.js does not implement the same timing and event loop frame semantics
+as Web Browsers and does not include any notion of rendering or "animation".
+The `requestAnimationFrame()` method should be considered a close approximation
+to enable cross-environment portable JavaScript code to be written. Code
+specifically targeting Node.js should use `setImmediate()` instead.
+
 ## `require()`
 
 This variable may appear to be global but is not. See [`require()`][].

lib/internal/bootstrap/node.js

@@ -239,6 +239,20 @@ if (!config.noBrowserGlobals) {
   // Non-standard extensions:
   defineOperation(global, 'clearImmediate', timers.clearImmediate);
   defineOperation(global, 'setImmediate', timers.setImmediate);
+
+  function requestAnimationFrame(callback) {
+    const { performance } = require('perf_hooks');
+    const {
+      codes: {
+        ERR_INVALID_ARG_TYPE,
+      },
+    } = require('internal/errors');
+    if (typeof callback !== 'function')
+      throw new ERR_INVALID_ARG_TYPE('callback', 'Function', callback);
+    return timers.setImmediate(() => callback(performance.now()));
+  }
+  defineOperation(global, 'requestAnimationFrame', requestAnimationFrame);
+  defineOperation(global, 'cancelAnimationFrame', timers.clearImmediate);
 }
 
 // Set the per-Environment callback that will be called

test/common/index.js

@@ -261,13 +261,16 @@ function platformTimeout(ms) {
   return ms; // ARMv8+
 }
 
+const requestAnimationFrame = globalThis.requestAnimationFrame;
+
 let knownGlobals = [
   atob,
   btoa,
   clearImmediate,
   clearInterval,
   clearTimeout,
   global,
+  requestAnimationFrame,
   setImmediate,
   setInterval,
   setTimeout,

test/parallel/test-requestanimationframe.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const common = require('../common');
+const { strictEqual } = require('assert');
+
+let called = false;
+
+requestAnimationFrame(common.mustCall((ts) => {
+  called = true;
+  strictEqual(typeof ts, 'number');
+}));
+
+strictEqual(called, false);
+
+const req = requestAnimationFrame(common.mustNotCall());
+cancelAnimationFrame(req);