api-fetch: Add types to media-upload middleware (#29901)

* api-fetch: Add types to media-upload middleware

* Remove runtime changes and denormalize return type

* Add descriptions to functions missing them

packages/api-fetch/src/middlewares/media-upload.js

@@ -14,22 +14,23 @@ import {
 /**
  * Middleware handling media upload failures and retries.
  *
- * @param {Object}   options Fetch options.
- * @param {Function} next    [description]
- *
- * @return {*} The evaluated result of the remaining middleware chain.
+ * @type {import('../types').ApiFetchMiddleware}
  */
-function mediaUploadMiddleware( options, next ) {
+const mediaUploadMiddleware = ( options, next ) => {
 	const isMediaUploadRequest =
 		( options.path && options.path.indexOf( '/wp/v2/media' ) !== -1 ) ||
 		( options.url && options.url.indexOf( '/wp/v2/media' ) !== -1 );
 
 	if ( ! isMediaUploadRequest ) {
-		return next( options, next );
+		return next( options );
 	}
 	let retries = 0;
 	const maxRetries = 5;
 
+	/**
+	 * @param {string} attachmentId
+	 * @return {Promise<any>} Processed post response.
+	 */
 	const postProcess = ( attachmentId ) => {
 		retries++;
 		return next( {
@@ -78,6 +79,6 @@ function mediaUploadMiddleware( options, next ) {
 		.then( ( response ) =>
 			parseResponseAndNormalizeError( response, options.parse )
 		);
-}
+};
 
 export default mediaUploadMiddleware;

packages/api-fetch/src/utils/response.js

@@ -9,7 +9,7 @@ import { __ } from '@wordpress/i18n';
  * @param {Response} response
  * @param {boolean}  shouldParseResponse
  *
- * @return {Promise} Parsed response
+ * @return {Promise<any> | null | Response} Parsed response.
  */
 const parseResponse = ( response, shouldParseResponse = true ) => {
 	if ( shouldParseResponse ) {
@@ -23,6 +23,13 @@ const parseResponse = ( response, shouldParseResponse = true ) => {
 	return response;
 };
 
+/**
+ * Calls the `json` function on the Response, throwing an error if the response
+ * doesn't have a json function or if parsing the json itself fails.
+ *
+ * @param {Response} response
+ * @return {Promise<any>} Parsed response.
+ */
 const parseJsonAndNormalizeError = ( response ) => {
 	const invalidJsonError = {
 		code: 'invalid_json',
@@ -44,7 +51,7 @@ const parseJsonAndNormalizeError = ( response ) => {
  * @param {Response} response
  * @param {boolean}  shouldParseResponse
  *
- * @return {Promise} Parsed response.
+ * @return {Promise<any>} Parsed response.
  */
 export const parseResponseAndNormalizeError = (
 	response,
@@ -55,6 +62,13 @@ export const parseResponseAndNormalizeError = (
 	).catch( ( res ) => parseAndThrowError( res, shouldParseResponse ) );
 };
 
+/**
+ * Parses a response, throwing an error if parsing the response fails.
+ *
+ * @param {Response} response
+ * @param {boolean} shouldParseResponse
+ * @return {Promise<any>} Parsed response.
+ */
 export function parseAndThrowError( response, shouldParseResponse = true ) {
 	if ( ! shouldParseResponse ) {
 		throw response;

packages/api-fetch/tsconfig.json

@@ -8,11 +8,13 @@
 		{ "path": "../url" }
 	],
 	"include": [
+		"src/middlewares/media-upload.js",
 		"src/middlewares/namespace-endpoint.js",
 		"src/middlewares/nonce.js",
 		"src/middlewares/preloading.js",
 		"src/middlewares/root-url.js",
 		"src/middlewares/user-locale.js",
+		"src/utils/**/*",
 		"src/types.ts"
 	]
 }