[FEATURE] AJAX API accepts native URL and URLSearchParams objects…

… as arguments

The AJAX API (`@typo3/core/ajax/ajax-request`) has been enhanced to
accept native URL-related objects, making usage of the API for
developers a little bit easier.

Resolves: #101970
Releases: main
Change-Id: Ica7c8d5ded7184c5aad6355dbdfa5c4f1f82b0ce
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/81100
Tested-by: core-ci <typo3@b13.com>
Tested-by: Benni Mack <benni@typo3.org>
Tested-by: Garvin Hicking <gh@faktor-e.de>
Reviewed-by: Andreas Fernandez <a.fernandez@scripting-base.de>
Tested-by: Andreas Fernandez <a.fernandez@scripting-base.de>
Reviewed-by: Garvin Hicking <gh@faktor-e.de>
Reviewed-by: Benni Mack <benni@typo3.org>

Build/Sources/TypeScript/core/ajax/ajax-request.ts

@@ -37,8 +37,8 @@ class AjaxRequest {
   private readonly url: URL;
   private readonly abortController: AbortController;
 
-  constructor(url: string) {
-    this.url = new URL(url, window.location.origin + window.location.pathname);
+  constructor(url: URL|string) {
+    this.url = url instanceof URL ? url : new URL(url, window.location.origin + window.location.pathname);
     this.abortController = new AbortController();
   }
 
@@ -48,10 +48,12 @@ class AjaxRequest {
    * @param {string|array|GenericKeyValue} data
    * @return {AjaxRequest}
    */
-  public withQueryArguments(data: string | Array<string> | GenericKeyValue): AjaxRequest {
+  public withQueryArguments(data: string | Array<string> | GenericKeyValue | URLSearchParams): AjaxRequest {
     const clone = this.clone();
 
-    data = new URLSearchParams(InputTransformer.toSearchParams(data));
+    if (!(data instanceof URLSearchParams)) {
+      data = new URLSearchParams(InputTransformer.toSearchParams(data));
+    }
     for (const [key, value] of data.entries()) {
       this.url.searchParams.append(key, value);
     }

Build/Sources/TypeScript/core/tests/ajax/ajax-request-test.ts

@@ -121,7 +121,7 @@ describe('@typo3/core/ajax/ajax-request', (): void => {
         const response = new Response(responseText, { headers: headers });
         promiseHelper.resolve(response);
 
-        (new AjaxRequest('https://example.com')).get().then(async (response: AjaxResponse): Promise<void> => {
+        (new AjaxRequest(new URL('https://example.com'))).get().then(async (response: AjaxResponse): Promise<void> => {
           const data = await response.resolve();
           expect(window.fetch).toHaveBeenCalledWith(new URL('https://example.com/'), jasmine.objectContaining({ method: 'GET' }));
           onfulfill(data, responseText);
@@ -135,13 +135,13 @@ describe('@typo3/core/ajax/ajax-request', (): void => {
     function* urlInputDataProvider(): any {
       yield [
         'absolute url with domain',
-        'https://example.com',
+        new URL('https://example.com'),
         {},
         new URL('https://example.com/'),
       ];
       yield [
         'absolute url with domain, with query parameter',
-        'https://example.com',
+        new URL('https://example.com'),
         { foo: 'bar', bar: { baz: 'bencer' } },
         new URL('https://example.com/?foo=bar&bar%5Bbaz%5D=bencer'),
       ];

typo3/sysext/core/Documentation/Changelog/13.0/Feature-101970-AJAXAPIAcceptsNativeURLAndURLSearchParamsObjectsAsArguments.rst

@@ -0,0 +1,42 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-101970-1695205584:
+
+=======================================================================================
+Feature: #101970 - AJAX API accepts native URL and URLSearchParams objects as arguments
+=======================================================================================
+
+See :issue:`101970`
+
+Description
+===========
+
+The AJAX API (:js:`@typo3/core/ajax/ajax-request`) has been enhanced to accept
+native URL-related objects.
+
+
+Impact
+======
+
+The constructor now accepts a :js:`URL` object as argument, along with the
+already established `string` type. Also, the :js:`withQueryString()` method
+accepts an object of type :js:`URLSearchParams` as argument.
+
+Example
+-------
+
+.. code-block:: javascript
+
+    import AjaxRequest from '@typo3/core/ajax/ajax-request.js';
+
+    const url = new URL('https://example.com/page/1/2/');
+    const queryArguments = new URLSearchParams({
+        foo: 'bar',
+        baz: 'bencer'
+    });
+
+    const request = new AjaxRequest(url).withQueryArguments(queryArguments);
+    request.get().then(/* ... */);
+
+
+.. index:: JavaScript, ext:core