From 1a58ce4649e3f80a1499b2e638b31ccb27c4d70c Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 22 Jul 2025 11:07:56 +0100
Subject: [PATCH] Simplify declaration of `ResponseType` (#4926)

Currently, this is looking for a `json` property on `IHttpOpts`. There is no
such property, so that part of the declaration is completely redundant, and we
may as well remove it.

I looked into making it check `IRequestOpts`, which *does* have a `json`
property, but couldn't make it work.

Also add some docs, while we're there.
---
 src/http-api/fetch.ts | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/http-api/fetch.ts b/src/http-api/fetch.ts
index e6728fbd9..b909c3b03 100644
--- a/src/http-api/fetch.ts
+++ b/src/http-api/fetch.ts
@@ -37,11 +37,17 @@ interface TypedResponse<T> extends Response {
     json(): Promise<T>;
 }
 
-export type ResponseType<T, O extends IHttpOpts> = O extends { json: false }
-    ? string
-    : O extends { onlyData: true } | undefined
-      ? T
-      : TypedResponse<T>;
+/**
+ * The type returned by {@link FetchHttpApi.request}, etc.
+ *
+ * If {@link IHttpOpts.onlyData} is unset or false, then the request methods return a
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Response Response} object,
+ * which we abstract via `TypedResponse`. Otherwise, we just cast it to `T`.
+ *
+ * @typeParam T - The type (specified by the application on the request method) that we will cast the response to.
+ * @typeParam O - The type of the options object on the {@link FetchHttpApi} instance.
+ */
+export type ResponseType<T, O extends IHttpOpts> = O extends { onlyData: true } | undefined ? T : TypedResponse<T>;
 
 export class FetchHttpApi<O extends IHttpOpts> {
     private abortController = new AbortController();