@wordpress/api-fetch 7.29.0 → 7.29.1-next.e256d081a.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/api-fetch",
-	"version": "7.29.0",
+	"version": "7.29.1-next.e256d081a.0",
 	"description": "Utility to make WordPress REST API requests.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -30,11 +30,11 @@
 	"types": "build-types",
 	"dependencies": {
 		"@babel/runtime": "7.25.7",
-		"@wordpress/i18n": "^6.2.0",
-		"@wordpress/url": "^4.29.0"
+		"@wordpress/i18n": "^6.2.1-next.e256d081a.0",
+		"@wordpress/url": "^4.29.1-next.e256d081a.0"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "445ede01e8abc8e49a1101b21a3651adbe852120"
+	"gitHead": "7d529ba9a461795d5f1572d3856de33f744287c2"
 }

package/src/{index.js → index.ts}

@@ -19,14 +19,17 @@ import {
 	parseResponseAndNormalizeError,
 	parseAndThrowError,
 } from './utils/response';
+import type {
+	APIFetchMiddleware,
+	APIFetchOptions,
+	FetchHandler,
+} from './types';
 
 /**
  * Default set of header values which should be sent with every request unless
  * explicitly provided through apiFetch options.
- *
- * @type {Record<string, string>}
  */
-const DEFAULT_HEADERS = {
+const DEFAULT_HEADERS: APIFetchOptions[ 'headers' ] = {
 	// The backend uses the Accept header as a condition for considering an
 	// incoming request as a REST request.
 	//
@@ -37,20 +40,12 @@ const DEFAULT_HEADERS = {
 /**
  * Default set of fetch option values which should be sent with every request
  * unless explicitly provided through apiFetch options.
- *
- * @type {Object}
  */
-const DEFAULT_OPTIONS = {
+const DEFAULT_OPTIONS: APIFetchOptions = {
 	credentials: 'include',
 };
 
-/** @typedef {import('./types').APIFetchMiddleware} APIFetchMiddleware */
-/** @typedef {import('./types').APIFetchOptions} APIFetchOptions */
-
-/**
- * @type {import('./types').APIFetchMiddleware[]}
- */
-const middlewares = [
+const middlewares: Array< APIFetchMiddleware > = [
 	userLocaleMiddleware,
 	namespaceEndpointMiddleware,
 	httpV1Middleware,
@@ -60,9 +55,9 @@ const middlewares = [
 /**
  * Register a middleware
  *
- * @param {import('./types').APIFetchMiddleware} middleware
+ * @param middleware
  */
-function registerMiddleware( middleware ) {
+function registerMiddleware( middleware: APIFetchMiddleware ) {
 	middlewares.unshift( middleware );
 }
 
@@ -70,10 +65,10 @@ function registerMiddleware( middleware ) {
  * Checks the status of a response, throwing the Response as an error if
  * it is outside the 200 range.
  *
- * @param {Response} response
- * @return {Response} The response if the status is in the 200 range.
+ * @param response
+ * @return The response if the status is in the 200 range.
  */
-const checkStatus = ( response ) => {
+const checkStatus = ( response: Response ) => {
 	if ( response.status >= 200 && response.status < 300 ) {
 		return response;
 	}
@@ -81,12 +76,7 @@ const checkStatus = ( response ) => {
 	throw response;
 };
 
-/** @typedef {(options: import('./types').APIFetchOptions) => Promise<any>} FetchHandler*/
-
-/**
- * @type {FetchHandler}
- */
-const defaultFetchHandler = ( nextOptions ) => {
+const defaultFetchHandler: FetchHandler = ( nextOptions ) => {
 	const { url, path, data, parse = true, ...remainingOptions } = nextOptions;
 	let { body, headers } = nextOptions;
 
@@ -134,32 +124,48 @@ const defaultFetchHandler = ( nextOptions ) => {
 	);
 };
 
-/** @type {FetchHandler} */
 let fetchHandler = defaultFetchHandler;
 
 /**
  * Defines a custom fetch handler for making the requests that will override
  * the default one using window.fetch
  *
- * @param {FetchHandler} newFetchHandler The new fetch handler
+ * @param newFetchHandler The new fetch handler
  */
-function setFetchHandler( newFetchHandler ) {
+function setFetchHandler( newFetchHandler: FetchHandler ) {
 	fetchHandler = newFetchHandler;
 }
 
+interface apiFetch {
+	< T, Parse extends boolean = true >(
+		options: APIFetchOptions< Parse >
+	): Promise< Parse extends true ? T : Response >;
+	nonceEndpoint?: string;
+	nonceMiddleware?: ReturnType< typeof createNonceMiddleware >;
+	use: ( middleware: APIFetchMiddleware ) => void;
+	setFetchHandler: ( newFetchHandler: FetchHandler ) => void;
+	createNonceMiddleware: typeof createNonceMiddleware;
+	createPreloadingMiddleware: typeof createPreloadingMiddleware;
+	createRootURLMiddleware: typeof createRootURLMiddleware;
+	fetchAllMiddleware: typeof fetchAllMiddleware;
+	mediaUploadMiddleware: typeof mediaUploadMiddleware;
+	createThemePreviewMiddleware: typeof createThemePreviewMiddleware;
+}
+
 /**
- * @template T
- * @param {import('./types').APIFetchOptions} options
- * @return {Promise<T>} A promise representing the request processed via the registered middlewares.
+ * Fetch
+ *
+ * @param options The options for the fetch.
+ * @return A promise representing the request processed via the registered middlewares.
  */
-function apiFetch( options ) {
+const apiFetch: apiFetch = ( options ) => {
 	// creates a nested function chain that calls all middlewares and finally the `fetchHandler`,
 	// converting `middlewares = [ m1, m2, m3 ]` into:
 	// ```
 	// opts1 => m1( opts1, opts2 => m2( opts2, opts3 => m3( opts3, fetchHandler ) ) );
 	// ```
-	const enhancedHandler = middlewares.reduceRight(
-		( /** @type {FetchHandler} */ next, middleware ) => {
+	const enhancedHandler = middlewares.reduceRight< FetchHandler >(
+		( next, middleware ) => {
 			return ( workingOptions ) => middleware( workingOptions, next );
 		},
 		fetchHandler
@@ -171,20 +177,16 @@ function apiFetch( options ) {
 		}
 
 		// If the nonce is invalid, refresh it and try again.
-		return (
-			window
-				// @ts-ignore
-				.fetch( apiFetch.nonceEndpoint )
-				.then( checkStatus )
-				.then( ( data ) => data.text() )
-				.then( ( text ) => {
-					// @ts-ignore
-					apiFetch.nonceMiddleware.nonce = text;
-					return apiFetch( options );
-				} )
-		);
+		return window
+			.fetch( apiFetch.nonceEndpoint! )
+			.then( checkStatus )
+			.then( ( data ) => data.text() )
+			.then( ( text ) => {
+				apiFetch.nonceMiddleware!.nonce = text;
+				return apiFetch( options );
+			} );
 	} );
-}
+};
 
 apiFetch.use = registerMiddleware;
 apiFetch.setFetchHandler = setFetchHandler;
@@ -197,3 +199,4 @@ apiFetch.mediaUploadMiddleware = mediaUploadMiddleware;
 apiFetch.createThemePreviewMiddleware = createThemePreviewMiddleware;
 
 export default apiFetch;
+export * from './types';

package/src/middlewares/{fetch-all-middleware.js → fetch-all-middleware.ts}

@@ -7,15 +7,19 @@ import { addQueryArgs } from '@wordpress/url';
  * Internal dependencies
  */
 import apiFetch from '..';
+import type { APIFetchMiddleware, APIFetchOptions } from '../types';
 
 /**
  * Apply query arguments to both URL and Path, whichever is present.
  *
- * @param {import('../types').APIFetchOptions} props
- * @param {Record<string, string | number>}    queryArgs
- * @return {import('../types').APIFetchOptions} The request with the modified query args
+ * @param {APIFetchOptions}                   props     The request options
+ * @param {Record< string, string | number >} queryArgs
+ * @return  The request with the modified query args
  */
-const modifyQuery = ( { path, url, ...options }, queryArgs ) => ( {
+const modifyQuery = (
+	{ path, url, ...options }: APIFetchOptions,
+	queryArgs: Record< string, string | number >
+): APIFetchOptions => ( {
 	...options,
 	url: url && addQueryArgs( url, queryArgs ),
 	path: path && addQueryArgs( path, queryArgs ),
@@ -24,17 +28,17 @@ const modifyQuery = ( { path, url, ...options }, queryArgs ) => ( {
 /**
  * Duplicates parsing functionality from apiFetch.
  *
- * @param {Response} response
- * @return {Promise<any>} Parsed response json.
+ * @param response
+ * @return Parsed response json.
  */
-const parseResponse = ( response ) =>
+const parseResponse = ( response: Response ) =>
 	response.json ? response.json() : Promise.reject( response );
 
 /**
- * @param {string | null} linkHeader
- * @return {{ next?: string }} The parsed link header.
+ * @param linkHeader
+ * @return The parsed link header.
  */
-const parseLinkHeader = ( linkHeader ) => {
+const parseLinkHeader = ( linkHeader: string | null ) => {
 	if ( ! linkHeader ) {
 		return {};
 	}
@@ -47,19 +51,19 @@ const parseLinkHeader = ( linkHeader ) => {
 };
 
 /**
- * @param {Response} response
- * @return {string | undefined} The next page URL.
+ * @param response
+ * @return  The next page URL.
  */
-const getNextPageUrl = ( response ) => {
+const getNextPageUrl = ( response: Response ) => {
 	const { next } = parseLinkHeader( response.headers.get( 'link' ) );
 	return next;
 };
 
 /**
- * @param {import('../types').APIFetchOptions} options
- * @return {boolean} True if the request contains an unbounded query.
+ * @param options
+ * @return True if the request contains an unbounded query.
  */
-const requestContainsUnboundedQuery = ( options ) => {
+const requestContainsUnboundedQuery = ( options: APIFetchOptions ) => {
 	const pathIsUnbounded =
 		!! options.path && options.path.indexOf( 'per_page=-1' ) !== -1;
 	const urlIsUnbounded =
@@ -71,10 +75,10 @@ const requestContainsUnboundedQuery = ( options ) => {
  * The REST API enforces an upper limit on the per_page option. To handle large
  * collections, apiFetch consumers can pass `per_page=-1`; this middleware will
  * then recursively assemble a full response array from all available pages.
- *
- * @type {import('../types').APIFetchMiddleware}
+ * @param options
+ * @param next
  */
-const fetchAllMiddleware = async ( options, next ) => {
+const fetchAllMiddleware: APIFetchMiddleware = async ( options, next ) => {
 	if ( options.parse === false ) {
 		// If a consumer has opted out of parsing, do not apply middleware.
 		return next( options );
@@ -108,7 +112,7 @@ const fetchAllMiddleware = async ( options, next ) => {
 	}
 
 	// Iteratively fetch all remaining pages until no "next" header is found.
-	let mergedResults = /** @type {any[]} */ ( [] ).concat( results );
+	let mergedResults = ( [] as Array< any > ).concat( results );
 	while ( nextPage ) {
 		const nextResponse = await apiFetch( {
 			...options,

package/src/middlewares/{http-v1.js → http-v1.ts}

@@ -1,7 +1,10 @@
+/**
+ * Internal dependencies
+ */
+import type { APIFetchMiddleware } from '../types';
+
 /**
  * Set of HTTP methods which are eligible to be overridden.
- *
- * @type {Set<string>}
  */
 const OVERRIDE_METHODS = new Set( [ 'PATCH', 'PUT', 'DELETE' ] );
 
@@ -12,8 +15,6 @@ const OVERRIDE_METHODS = new Set( [ 'PATCH', 'PUT', 'DELETE' ] );
  * is `GET`."
  *
  * @see  https://fetch.spec.whatwg.org/#requests
- *
- * @type {string}
  */
 const DEFAULT_METHOD = 'GET';
 
@@ -21,9 +22,10 @@ const DEFAULT_METHOD = 'GET';
  * API Fetch middleware which overrides the request method for HTTP v1
  * compatibility leveraging the REST API X-HTTP-Method-Override header.
  *
- * @type {import('../types').APIFetchMiddleware}
+ * @param options
+ * @param next
  */
-const httpV1Middleware = ( options, next ) => {
+const httpV1Middleware: APIFetchMiddleware = ( options, next ) => {
 	const { method = DEFAULT_METHOD } = options;
 	if ( OVERRIDE_METHODS.has( method.toUpperCase() ) ) {
 		options = {

package/src/middlewares/{media-upload.js → media-upload.ts}

@@ -10,12 +10,13 @@ import {
 	parseAndThrowError,
 	parseResponseAndNormalizeError,
 } from '../utils/response';
+import type { APIFetchOptions, APIFetchMiddleware } from '../types';
 
 /**
- * @param {import('../types').APIFetchOptions} options
- * @return {boolean} True if the request is for media upload.
+ * @param options
+ * @return True if the request is for media upload.
  */
-function isMediaUploadRequest( options ) {
+function isMediaUploadRequest( options: APIFetchOptions ) {
 	const isCreateMethod = !! options.method && options.method === 'POST';
 	const isMediaEndpoint =
 		( !! options.path && options.path.indexOf( '/wp/v2/media' ) !== -1 ) ||
@@ -26,10 +27,10 @@ function isMediaUploadRequest( options ) {
 
 /**
  * Middleware handling media upload failures and retries.
- *
- * @type {import('../types').APIFetchMiddleware}
+ * @param options
+ * @param next
  */
-const mediaUploadMiddleware = ( options, next ) => {
+const mediaUploadMiddleware: APIFetchMiddleware = ( options, next ) => {
 	if ( ! isMediaUploadRequest( options ) ) {
 		return next( options );
 	}
@@ -38,10 +39,10 @@ const mediaUploadMiddleware = ( options, next ) => {
 	const maxRetries = 5;
 
 	/**
-	 * @param {string} attachmentId
-	 * @return {Promise<any>} Processed post response.
+	 * @param attachmentId
+	 * @return Processed post response.
 	 */
-	const postProcess = ( attachmentId ) => {
+	const postProcess = ( attachmentId: string ): Promise< any > => {
 		retries++;
 		return next( {
 			path: `/wp/v2/media/${ attachmentId }/post-process`,

package/src/middlewares/{namespace-endpoint.js → namespace-endpoint.ts}

@@ -1,7 +1,12 @@
 /**
- * @type {import('../types').APIFetchMiddleware}
+ * Internal dependencies
  */
-const namespaceAndEndpointMiddleware = ( options, next ) => {
+import type { APIFetchMiddleware } from '../types';
+
+const namespaceAndEndpointMiddleware: APIFetchMiddleware = (
+	options,
+	next
+) => {
 	let path = options.path;
 	let namespaceTrimmed, endpointTrimmed;
 

package/src/middlewares/{nonce.js → nonce.ts}

@@ -1,12 +1,20 @@
 /**
- * @param {string} nonce
- * @return {import('../types').APIFetchMiddleware & { nonce: string }} A middleware to enhance a request with a nonce.
+ * Internal dependencies
  */
-function createNonceMiddleware( nonce ) {
-	/**
-	 * @type {import('../types').APIFetchMiddleware & { nonce: string }}
-	 */
-	const middleware = ( options, next ) => {
+import type { APIFetchMiddleware } from '../types';
+
+/**
+ * @param nonce
+ *
+ * @return  A middleware to enhance a request with a nonce.
+ */
+function createNonceMiddleware(
+	nonce: string
+): APIFetchMiddleware & { nonce: string } {
+	const middleware: APIFetchMiddleware & { nonce: string } = (
+		options,
+		next
+	) => {
 		const { headers = {} } = options;
 
 		// If an 'X-WP-Nonce' header (or any case-insensitive variation

package/src/middlewares/{preloading.js → preloading.ts}

@@ -4,10 +4,17 @@
 import { addQueryArgs, getQueryArgs, normalizePath } from '@wordpress/url';
 
 /**
- * @param {Record<string, any>} preloadedData
- * @return {import('../types').APIFetchMiddleware} Preloading middleware.
+ * Internal dependencies
  */
-function createPreloadingMiddleware( preloadedData ) {
+import type { APIFetchMiddleware } from '../types';
+
+/**
+ * @param preloadedData
+ * @return Preloading middleware.
+ */
+function createPreloadingMiddleware(
+	preloadedData: Record< string, any >
+): APIFetchMiddleware {
 	const cache = Object.fromEntries(
 		Object.entries( preloadedData ).map( ( [ path, data ] ) => [
 			normalizePath( path ),
@@ -17,7 +24,6 @@ function createPreloadingMiddleware( preloadedData ) {
 
 	return ( options, next ) => {
 		const { parse = true } = options;
-		/** @type {string | void} */
 		let rawPath = options.path;
 		if ( ! rawPath && options.url ) {
 			const { rest_route: pathFromQuery, ...queryArgs } = getQueryArgs(
@@ -63,11 +69,14 @@ function createPreloadingMiddleware( preloadedData ) {
 /**
  * This is a helper function that sends a success response.
  *
- * @param {Record<string, any>} responseData
- * @param {boolean}             parse
- * @return {Promise<any>} Promise with the response.
+ * @param responseData
+ * @param parse
+ * @return Promise with the response.
  */
-function prepareResponse( responseData, parse ) {
+function prepareResponse(
+	responseData: Record< string, any >,
+	parse: boolean
+) {
 	if ( parse ) {
 		return Promise.resolve( responseData.body );
 	}
@@ -82,12 +91,13 @@ function prepareResponse( responseData, parse ) {
 		);
 	} catch {
 		// See: https://github.com/WordPress/gutenberg/issues/67358#issuecomment-2621163926.
-		Object.entries( responseData.headers ).forEach( ( [ key, value ] ) => {
+		Object.entries(
+			responseData.headers as Record< string, string >
+		).forEach( ( [ key, value ] ) => {
 			if ( key.toLowerCase() === 'link' ) {
 				responseData.headers[ key ] = value.replace(
 					/<([^>]+)>/,
-					( /** @type {any} */ _, /** @type {string} */ url ) =>
-						`<${ encodeURI( url ) }>`
+					( _, url ) => `<${ encodeURI( url ) }>`
 				);
 			}
 		} );

package/src/middlewares/root-url.ts

@@ -0,0 +1,47 @@
+/**
+ * Internal dependencies
+ */
+import type { APIFetchMiddleware } from '../types';
+import namespaceAndEndpointMiddleware from './namespace-endpoint';
+
+/**
+ * @param rootURL
+ * @return  Root URL middleware.
+ */
+const createRootURLMiddleware =
+	( rootURL: string ): APIFetchMiddleware =>
+	( options, next ) => {
+		return namespaceAndEndpointMiddleware( options, ( optionsWithPath ) => {
+			let url = optionsWithPath.url;
+			let path = optionsWithPath.path;
+			let apiRoot;
+
+			if ( typeof path === 'string' ) {
+				apiRoot = rootURL;
+
+				if ( -1 !== rootURL.indexOf( '?' ) ) {
+					path = path.replace( '?', '&' );
+				}
+
+				path = path.replace( /^\//, '' );
+
+				// API root may already include query parameter prefix if site is
+				// configured to use plain permalinks.
+				if (
+					'string' === typeof apiRoot &&
+					-1 !== apiRoot.indexOf( '?' )
+				) {
+					path = path.replace( '?', '&' );
+				}
+
+				url = apiRoot + path;
+			}
+
+			return next( {
+				...optionsWithPath,
+				url,
+			} );
+		} );
+	};
+
+export default createRootURLMiddleware;

package/src/middlewares/test/{fetch-all-middleware.js → fetch-all-middleware.ts}

@@ -19,7 +19,7 @@ describe( 'Fetch All Middleware', () => {
 		expect.hasAssertions();
 		const originalOptions = { url: '/posts?per_page=-1' };
 		let counter = 1;
-		jest.doMock( '../../index.js', () => ( options ) => {
+		jest.doMock( '../../index.ts', () => ( options ) => {
 			const expectedUrl =
 				counter === 1
 					? '/posts?per_page=100'

package/src/middlewares/test/{http-v1.js → http-v1.ts}

@@ -1,15 +1,18 @@
 /**
  * Internal dependencies
  */
+import type { FetchHandler } from '../../types';
 import httpV1Middleware from '../http-v1';
 
 describe( 'HTTP v1 Middleware', () => {
 	it( 'should use a POST for a PUT requests', () => {
 		expect.hasAssertions();
 
-		const callback = ( options ) => {
+		const callback: FetchHandler = async ( options ) => {
 			expect( options.method ).toBe( 'POST' );
-			expect( options.headers[ 'X-HTTP-Method-Override' ] ).toBe( 'PUT' );
+			expect( options.headers![ 'X-HTTP-Method-Override' ] ).toBe(
+				'PUT'
+			);
 		};
 
 		httpV1Middleware( { method: 'PUT', data: {} }, callback );
@@ -19,7 +22,7 @@ describe( 'HTTP v1 Middleware', () => {
 		expect.hasAssertions();
 
 		const requestOptions = { method: 'GET', path: '/wp/v2/posts' };
-		const callback = ( options ) => {
+		const callback: FetchHandler = async ( options ) => {
 			expect( options ).toBe( requestOptions );
 		};
 
@@ -30,7 +33,7 @@ describe( 'HTTP v1 Middleware', () => {
 		expect.hasAssertions();
 
 		const requestOptions = { path: '/wp/v2/posts' };
-		const callback = ( options ) => {
+		const callback: FetchHandler = async ( options ) => {
 			expect( options ).toBe( requestOptions );
 		};
 

package/src/middlewares/test/{media-upload.js → media-upload.ts}

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import type { FetchHandler } from '../../types';
 import mediaUploadMiddleware from '../media-upload';
 
 describe( 'Media Upload Middleware', () => {
@@ -8,7 +9,7 @@ describe( 'Media Upload Middleware', () => {
 		expect.hasAssertions();
 
 		const originalOptions = { path: '/wp/v2/media' };
-		const next = ( options ) => {
+		const next: FetchHandler = async ( options ) => {
 			expect( options ).toBe( originalOptions );
 		};
 

package/src/middlewares/test/{namespace-endpoint.js → namespace-endpoint.ts}

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import type { FetchHandler } from '../../types';
 import namespaceEndpointMiddleware from '../namespace-endpoint';
 
 describe( 'Namespace & Endpoint middleware', () => {
@@ -12,7 +13,7 @@ describe( 'Namespace & Endpoint middleware', () => {
 			namespace: '/wp/v2',
 			endpoint: '/posts',
 		};
-		const callback = ( options ) => {
+		const callback: FetchHandler = async ( options ) => {
 			expect( options.path ).toBe( 'wp/v2/posts' );
 			expect( options.namespace ).toBeUndefined();
 			expect( options.endpoint ).toBeUndefined();

package/src/middlewares/test/{nonce.js → nonce.ts}

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import type { FetchHandler } from '../../types';
 import createNonceMiddleware from '../nonce';
 
 describe( 'Nonce middleware', () => {
@@ -13,8 +14,8 @@ describe( 'Nonce middleware', () => {
 			method: 'GET',
 			path: '/wp/v2/posts',
 		};
-		const callback = ( options ) => {
-			expect( options.headers[ 'X-WP-Nonce' ] ).toBe( nonce );
+		const callback: FetchHandler = async ( options ) => {
+			expect( options.headers![ 'X-WP-Nonce' ] ).toBe( nonce );
 		};
 
 		nonceMiddleware( requestOptions, callback );
@@ -31,8 +32,8 @@ describe( 'Nonce middleware', () => {
 			headers: { 'X-WP-Nonce': 'existing nonce' },
 		};
 
-		const callback = ( options ) => {
-			expect( options.headers[ 'X-WP-Nonce' ] ).toBe( 'new nonce' );
+		const callback: FetchHandler = async ( options ) => {
+			expect( options.headers![ 'X-WP-Nonce' ] ).toBe( 'new nonce' );
 		};
 
 		nonceMiddleware( requestOptions, callback );