node: add util.callbackify (denoland/deno#5415)

This adds [Node's `util.callbackify`][0] to `node/util.ts`.

I lifted most of this from the [original Node source code][1] (and [its
tests][2]). I tried to make minimal modifications to the source.

I made a few arbitrary decisions:

- I was unable to do the function's types elegantly. I made overloads
  for functions that have 0 to 5 (inclusive) arguments, excluding the
  callback. I would love to know a better way to do this. (It seems that
  the folks at DefinitelyTyped [were also stumped][3], though maybe
  their solution is deliberate.)
- There are a few edge cases that cause custom Node errors to be
  produced. Instead of re-implementing those errors completely, I
  created simplified classes. These are mostly correct but are not
  identical to the real Node errors.
- The tests implement a possibly-arcane `TestQueue` class. I originally
  used a lot of inline promises but found it too repetitive.

Closes [denoland/deno#5366][4].

[0]: https://nodejs.org/api/util.html#util_util_callbackify_original
[1]: https://github.com/nodejs/node/blob/47804933012841f2dc90626bdcc161adf34569a5/lib/util.js#L183-L226
[2]: https://github.com/nodejs/node/blob/47804933012841f2dc90626bdcc161adf34569a5/test/parallel/test-util-callbackify.js
[3]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/7d24857ddb07ab637dfa8c477d13352f8a8206fc/types/node/util.d.ts#L61-L84
[4]: denoland/deno#5366

node/_util/_util_callbackify.ts

@@ -0,0 +1,125 @@
+// Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
+//
+// Adapted from Node.js. Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+// These are simplified versions of the "real" errors in Node.
+class NodeFalsyValueRejectionError extends Error {
+  public reason: unknown;
+  public code = "ERR_FALSY_VALUE_REJECTION";
+  constructor(reason: unknown) {
+    super("Promise was rejected with falsy value");
+    this.reason = reason;
+  }
+}
+class NodeInvalidArgTypeError extends TypeError {
+  public code = "ERR_INVALID_ARG_TYPE";
+  constructor(argumentName: string) {
+    super(`The ${argumentName} argument must be of type function.`);
+  }
+}
+
+type Callback<ResultT> =
+  | ((err: Error) => void)
+  | ((err: null, result: ResultT) => void);
+
+function callbackify<ResultT>(
+  fn: () => PromiseLike<ResultT>
+): (callback: Callback<ResultT>) => void;
+function callbackify<ArgT, ResultT>(
+  fn: (arg: ArgT) => PromiseLike<ResultT>
+): (arg: ArgT, callback: Callback<ResultT>) => void;
+function callbackify<Arg1T, Arg2T, ResultT>(
+  fn: (arg1: Arg1T, arg2: Arg2T) => PromiseLike<ResultT>
+): (arg1: Arg1T, arg2: Arg2T, callback: Callback<ResultT>) => void;
+function callbackify<Arg1T, Arg2T, Arg3T, ResultT>(
+  fn: (arg1: Arg1T, arg2: Arg2T, arg3: Arg3T) => PromiseLike<ResultT>
+): (arg1: Arg1T, arg2: Arg2T, arg3: Arg3T, callback: Callback<ResultT>) => void;
+function callbackify<Arg1T, Arg2T, Arg3T, Arg4T, ResultT>(
+  fn: (
+    arg1: Arg1T,
+    arg2: Arg2T,
+    arg3: Arg3T,
+    arg4: Arg4T
+  ) => PromiseLike<ResultT>
+): (
+  arg1: Arg1T,
+  arg2: Arg2T,
+  arg3: Arg3T,
+  arg4: Arg4T,
+  callback: Callback<ResultT>
+) => void;
+function callbackify<Arg1T, Arg2T, Arg3T, Arg4T, Arg5T, ResultT>(
+  fn: (
+    arg1: Arg1T,
+    arg2: Arg2T,
+    arg3: Arg3T,
+    arg4: Arg4T,
+    arg5: Arg5T
+  ) => PromiseLike<ResultT>
+): (
+  arg1: Arg1T,
+  arg2: Arg2T,
+  arg3: Arg3T,
+  arg4: Arg4T,
+  arg5: Arg5T,
+  callback: Callback<ResultT>
+) => void;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function callbackify(original: any): any {
+  if (typeof original !== "function") {
+    throw new NodeInvalidArgTypeError('"original"');
+  }
+
+  const callbackified = function (this: unknown, ...args: unknown[]): void {
+    const maybeCb = args.pop();
+    if (typeof maybeCb !== "function") {
+      throw new NodeInvalidArgTypeError("last");
+    }
+    const cb = (...args: unknown[]): void => {
+      maybeCb.apply(this, args);
+    };
+    original.apply(this, args).then(
+      (ret: unknown) => {
+        setTimeout(cb.bind(this, null, ret), 0);
+      },
+      (rej: unknown) => {
+        rej = rej || new NodeFalsyValueRejectionError(rej);
+        queueMicrotask(cb.bind(this, rej));
+      }
+    );
+  };
+
+  const descriptors = Object.getOwnPropertyDescriptors(original);
+  // It is possible to manipulate a functions `length` or `name` property. This
+  // guards against the manipulation.
+  if (typeof descriptors.length.value === "number") {
+    descriptors.length.value++;
+  }
+  if (typeof descriptors.name.value === "string") {
+    descriptors.name.value += "Callbackified";
+  }
+  Object.defineProperties(callbackified, descriptors);
+  return callbackified;
+}
+
+export { callbackify };