From b6cd1475c66155f44261e2e875afb3f46f56852c Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 29 Mar 2021 14:36:09 -0700
Subject: [PATCH] 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>
---
 .eslintrc.js                                |  1 +
 doc/api/globals.md                          | 50 +++++++++++++++++++++
 lib/internal/bootstrap/node.js              | 14 ++++++
 test/common/index.js                        |  3 ++
 test/parallel/test-requestanimationframe.js | 13 ++++++
 5 files changed, 81 insertions(+)
 create mode 100644 test/parallel/test-requestanimationframe.js

diff --git a/.eslintrc.js b/.eslintrc.js
index 3f47ddf45d0534..64258302468ab1 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -331,5 +331,6 @@ module.exports = {
     globalThis: 'readable',
     btoa: 'readable',
     atob: 'readable',
+    requestAnimationFrame: 'readable',
   },
 };
diff --git a/doc/api/globals.md b/doc/api/globals.md
index 831ef06bec6094..6ec441bfc020cf 100644
--- a/doc/api/globals.md
+++ b/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()`][].
diff --git a/lib/internal/bootstrap/node.js b/lib/internal/bootstrap/node.js
index d8f5c18d12d79b..ae52aaf7e4ea8f 100644
--- a/lib/internal/bootstrap/node.js
+++ b/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);
+    timers.setImmediate(() => callback(performance.now()));
+  }
+  defineOperation(global, 'requestAnimationFrame', requestAnimationFrame);
+  defineOperation(global, 'cancelAnimationFrame', timers.clearImmediate);
 }
 
 // Set the per-Environment callback that will be called
diff --git a/test/common/index.js b/test/common/index.js
index 03eec756d0a19a..1dc41bdbb7be38 100644
--- a/test/common/index.js
+++ b/test/common/index.js
@@ -261,6 +261,8 @@ function platformTimeout(ms) {
   return ms; // ARMv8+
 }
 
+const requestAnimationFrame = globalThis.requestAnimationFrame;
+
 let knownGlobals = [
   atob,
   btoa,
@@ -268,6 +270,7 @@ let knownGlobals = [
   clearInterval,
   clearTimeout,
   global,
+  requestAnimationFrame,
   setImmediate,
   setInterval,
   setTimeout,
diff --git a/test/parallel/test-requestanimationframe.js b/test/parallel/test-requestanimationframe.js
new file mode 100644
index 00000000000000..ebe218bc54a83f
--- /dev/null
+++ b/test/parallel/test-requestanimationframe.js
@@ -0,0 +1,13 @@
+'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);