TypeScript: Fix and improve types for private-apis (WordPress#66667)

* Convert private-apis package to TypeScript

* Convert the usage of private-apis to TypeScript

* Clean up JSDoc

Co-authored-by: manzoorwanijk <[email protected]>
Co-authored-by: tyxla <[email protected]>

packages/private-apis/src/implementation.js → packages/private-apis/src/implementation.ts

@@ -2,7 +2,7 @@
  * wordpress/private-apis – the utilities to enable private cross-package
  * exports of private APIs.
  *
- * This "implementation.js" file is needed for the sake of the unit tests. It
+ * This "implementation.ts" file is needed for the sake of the unit tests. It
  * exports more than the public API of the package to aid in testing.
  */
 
@@ -36,10 +36,8 @@ const CORE_MODULES_USING_PRIVATE_APIS = [
 /**
  * A list of core modules that already opted-in to
  * the privateApis package.
- *
- * @type {string[]}
  */
-const registeredPrivateApis = [];
+const registeredPrivateApis: Array< string > = [];
 
 /*
  * Warning for theme and plugin developers.
@@ -65,13 +63,13 @@ const allowReRegistration = globalThis.IS_WORDPRESS_CORE ? false : true;
  * Called by a @wordpress package wishing to opt-in to accessing or exposing
  * private private APIs.
  *
- * @param {string} consent    The consent string.
- * @param {string} moduleName The name of the module that is opting in.
- * @return {{lock: typeof lock, unlock: typeof unlock}} An object containing the lock and unlock functions.
+ * @param consent    The consent string.
+ * @param moduleName The name of the module that is opting in.
+ * @return An object containing the lock and unlock functions.
  */
 export const __dangerousOptInToUnstableAPIsOnlyForCoreModules = (
-	consent,
-	moduleName
+	consent: string,
+	moduleName: string
 ) => {
 	if ( ! CORE_MODULES_USING_PRIVATE_APIS.includes( moduleName ) ) {
 		throw new Error(
@@ -135,10 +133,10 @@ export const __dangerousOptInToUnstableAPIsOnlyForCoreModules = (
  * // { a: 1 }
  * ```
  *
- * @param {any} object      The object to bind the private data to.
- * @param {any} privateData The private data to bind to the object.
+ * @param object      The object to bind the private data to.
+ * @param privateData The private data to bind to the object.
  */
-function lock( object, privateData ) {
+function lock( object: Record< symbol, WeakKey >, privateData: unknown ) {
 	if ( ! object ) {
 		throw new Error( 'Cannot lock an undefined object.' );
 	}
@@ -168,10 +166,10 @@ function lock( object, privateData ) {
  * // { a: 1 }
  * ```
  *
- * @param {any} object The object to unlock the private data from.
- * @return {any} The private data bound to the object.
+ * @param object The object to unlock the private data from.
+ * @return The private data bound to the object.
  */
-function unlock( object ) {
+function unlock( object: Record< symbol, WeakKey > ) {
 	if ( ! object ) {
 		throw new Error( 'Cannot unlock an undefined object.' );
 	}
@@ -198,9 +196,9 @@ const __private = Symbol( 'Private API ID' );
  * Private function to allow the unit tests to allow
  * a mock module to access the private APIs.
  *
- * @param {string} name The name of the module.
+ * @param name The name of the module.
  */
-export function allowCoreModule( name ) {
+export function allowCoreModule( name: string ) {
 	CORE_MODULES_USING_PRIVATE_APIS.push( name );
 }