typings: improve primordials typings

aduh95 · danielleadams · commit 78b79c02201f · 2023-04-10T20:55:11.000-04:00
PR-URL: #46970 Reviewed-By: Moshe Atlow <moshe@atlow.co.il> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
diff --git a/lib/internal/per_context/primordials.js b/lib/internal/per_context/primordials.js
@@ -307,9 +307,21 @@ const {
   WeakSet,
 } = primordials;
 
-// Because these functions are used by `makeSafe`, which is exposed
-// on the `primordials` object, it's important to use const references
-// to the primordials that they use:
+
+/**
+ * Creates a class that can be safely iterated over.
+ *
+ * Because these functions are used by `makeSafe`, which is exposed on the
+ * `primordials` object, it's important to use const references to the
+ * primordials that they use.
+ *
+ * @template {Iterable} T
+ * @template {*} TReturn
+ * @template {*} TNext
+ * @param {(self: T) => IterableIterator<T>} factory
+ * @param {(...args: [] | [TNext]) => IteratorResult<T, TReturn>} next
+ * @returns {Iterator<T, TReturn, TNext>}
+ */
 const createSafeIterator = (factory, next) => {
   class SafeIterator {
     constructor(iterable) {
@@ -617,6 +629,10 @@ class RegExpLikeForStringSplitting {
 }
 ObjectSetPrototypeOf(RegExpLikeForStringSplitting.prototype, null);
 
+/**
+ * @param {RegExp} pattern
+ * @returns {RegExp}
+ */
 primordials.hardenRegExp = function hardenRegExp(pattern) {
   ObjectDefineProperties(pattern, {
     [SymbolMatch]: {
@@ -706,6 +722,11 @@ primordials.hardenRegExp = function hardenRegExp(pattern) {
 };
 
 
+/**
+ * @param {string} str
+ * @param {RegExp} regexp
+ * @returns {number}
+ */
 primordials.SafeStringPrototypeSearch = (str, regexp) => {
   regexp.lastIndex = 0;
   const match = RegExpPrototypeExec(regexp, str);
diff --git a/typings/primordials.d.ts b/typings/primordials.d.ts
@@ -597,4 +597,7 @@ declare namespace primordials {
   export const PromisePrototypeThen: UncurryThis<typeof Promise.prototype.then>
   export const PromisePrototypeCatch: UncurryThis<typeof Promise.prototype.catch>
   export const PromisePrototypeFinally: UncurryThis<typeof Promise.prototype.finally>
+  export import Proxy = globalThis.Proxy
+  import _globalThis = globalThis
+  export { _globalThis as globalThis }
 }
