aspi 1.2.1 → 2.0.1

package/dist/index.cjs

@@ -103,7 +103,7 @@ var CustomError = class extends Error {
   }
 };
 var isAspiError = (error) => {
-  return error instanceof AspiError;
+  return error instanceof AspiError && error.tag === "aspiError";
 };
 var isCustomError = (error) => {
   return error instanceof CustomError;
@@ -315,19 +315,17 @@ var Request = class {
   #shouldBeResult = false;
   #bodySchemaIssues = [];
   #throwOnError = false;
-  constructor(method, path, {
-    requestConfig,
-    retryConfig,
-    middlewares,
-    errorCbs,
-    throwOnError
-  }) {
+  constructor(method, path, requestOptions) {
     this.#path = path;
-    this.#middlewares = middlewares || [];
-    this.#localRequestInit = { ...requestConfig, method };
-    this.#retryConfig = retryConfig;
-    this.#customErrorCbs = errorCbs || {};
-    this.#throwOnError = throwOnError || false;
+    this.#middlewares = requestOptions.middlewares || [];
+    this.#localRequestInit = {
+      ...requestOptions.requestConfig,
+      method
+    };
+    this.#retryConfig = requestOptions.retryConfig;
+    this.#customErrorCbs = requestOptions.errorCbs || {};
+    this.#throwOnError = requestOptions.throwOnError || false;
+    this.#shouldBeResult = requestOptions.shouldBeResult || false;
   }
   /**
    * Sets the base URL for the request.
@@ -362,18 +360,25 @@ var Request = class {
     return this;
   }
   /**
-   * Sets multiple headers for the request.
-   * @param headers An object containing header key-value pairs
-   * @returns The request instance for chaining
+   * Merges the provided headers into the request configuration.
+   *
+   * @param {HeadersInit} headers - An object or iterable containing header name/value pairs.
+   *   Existing headers are retained unless a key in this object overwrites them.
+   * @returns {this} The current {@link Request} instance for method chaining.
+   *
    * @example
+   * // Set common JSON headers
    * const request = new Request('/users', config);
    * request.setHeaders({
    *   'Content-Type': 'application/json',
-   *   'Accept': 'application/json'
+   *   'Accept': 'application/json',
    * });
    */
   setHeaders(headers) {
-    this.#localRequestInit.headers = headers;
+    this.#localRequestInit.headers = {
+      ...this.#localRequestInit.headers ?? {},
+      ...headers
+    };
     return this;
   }
   /**
@@ -387,7 +392,7 @@ var Request = class {
    */
   setHeader(key, value) {
     this.#localRequestInit.headers = {
-      ...this.#localRequestInit.headers,
+      ...this.#localRequestInit.headers ?? {},
       [key]: value
     };
     return this;
@@ -449,6 +454,8 @@ var Request = class {
       } else {
         this.#localRequestInit.body = JSON.stringify(body);
       }
+    } else {
+      this.#localRequestInit.body = JSON.stringify(body);
     }
     return this;
   }
@@ -583,29 +590,54 @@ var Request = class {
     return this.error("internalServerError", "INTERNAL_SERVER_ERROR", cb);
   }
   /**
-   * Sets a custom error handler for a specific HTTP status code.
-   * @param tag A string identifier for the error type
-   * @param status The HTTP error status to handle
-   * @param cb The callback function to handle the error
-   * @returns The request instance for chaining
+   * Register a custom error handler for a specific HTTP status code.
+   *
+   * When the response matches the provided `status`, the supplied callback `cb`
+   * is invoked and its return value is wrapped in a {@link CustomError} with the
+   * given `tag`. The method also augments the request's generic `Opts['error']`
+   * type so that the custom error is reflected in the resulting `Result`
+   * union.
+   *
+   * @template Tag - A string literal used as the error tag.
+   * @template A   - The shape of the data returned by the callback.
+   *
+   * @param {Tag} tag
+   *   A unique identifier for the custom error. This value becomes the `tag`
+   *   property of the {@link CustomError} produced by the handler.
+   *
+   * @param {HttpErrorStatus} status
+   *   The HTTP status code (e.g. `'BAD_REQUEST'`, `'NOT_FOUND'`) that should
+   *   trigger the custom handler.
+   *
+   * @param {CustomErrorCb<TRequest, A>} cb
+   *   A callback that receives the failing request and response objects and
+   *   returns an object describing the error payload.
+   *
+   * @returns {Request<Method, TRequest, Merge<Omit<Opts, 'error'>, { error: { [K in Tag | keyof Opts['error']]: K extends Tag ? CustomError<Tag, A> : Opts['error'][K]; } }>>}
+   *   The same {@link Request} instance, now typed with the newly added error
+   *   variant, allowing method‑chaining.
+   *
    * @example
+   * ```ts
    * const request = new Request('/users', config);
+   *
+   * // Attach a custom handler for a 400 Bad Request response
    * request
-      .withResult()
-      .error('customError', 'BAD_REQUEST', (error) => {
-   *   console.log('Bad request error:', error);
-   *   return {
-   *     message: 'Invalid input',
-   *     details: error.response.responseData
-   *   };
-   * });
+   *  withResult()
+   *   .error('customError', 'BAD_REQUEST', (ctx) => {
+   *     console.log('Bad request error:', ctx);
+   *     return {
+   *       message: 'Invalid input',
+   *       details: ctx.response.responseData,
+   *     };
+   *   });
    *
-   * // Later when making the request:
+   * // Later, when executing the request:
    * const result = await request.json();
-   * if (Result.isErr(result)) {
-   *   if(result.tag === 'customError') {
+   * if (Result.isErr(result) && result.tag === 'customError') {
    *   console.log(result.error.data.message); // 'Invalid input'
    * }
+   * ```
    */
   error(tag, status, cb) {
     this.#customErrorCbs[httpErrors[status]] = {
@@ -615,58 +647,106 @@ var Request = class {
     return this;
   }
   /**
-   * Sets query parameters for the request URL.
-   * @param params An object containing query parameter key-value pairs
-   * @returns The request instance for chaining
+   * Sets the query parameters for the request URL.
+   *
+   * Accepts any value that can be passed to the `URLSearchParams` constructor:
+   * - an object mapping keys to string values,
+   * - an iterable of `[key, value]` tuples,
+   * - a raw query string, or
+   * - an existing {@link URLSearchParams} instance.
+   *
+   * The supplied parameters replace any previously defined query parameters.
+   *
+   * @template T - The concrete type of the supplied parameters.
+   * @param {T} params - The query parameters to apply.
+   * @returns {this} The request instance for method‑chaining.
+   *
    * @example
    * const request = new Request('/users', config);
    * request.setQueryParams({
    *   page: '1',
    *   limit: '10',
-   *   sort: 'desc'
+   *   sort: 'desc',
    * });
+   *
+   * // Using a raw query string
+   * request.setQueryParams('page=1&limit=10');
+   *
+   * // Using an array of entries
+   * request.setQueryParams([['page', '1'], ['limit', '10']]);
+   *
+   * // Using an existing URLSearchParams instance
+   * const qp = new URLSearchParams({ page: '1' });
+   * request.setQueryParams(qp);
    */
   setQueryParams(params) {
     this.#queryParams = new URLSearchParams(params);
     return this;
   }
   /**
-   * Sets the output schema for validating the response data using Zod.
-   * @param schema The Zod schema to validate the response
-   * @returns The request instance for chaining
+   * Sets a validation schema for the response data.
+   *
+   * The provided {@link StandardSchemaV1} schema will be used to validate the
+   * response payload when the request is executed. If validation fails, a
+   * `parseError` is added to the request's error type.
+   *
+   * @template TSchema - A type extending {@link StandardSchemaV1}
+   * @param schema - The schema used to validate the response data
+   * @returns The request instance for chaining with an updated generic type that
+   * includes the schema and a possible `parseError` in the error union
+   *
    * @example
+   * ```ts
    * import { z } from 'zod';
    *
    * const userSchema = z.object({
    *   id: z.number(),
    *   name: z.string(),
-   *   email: z.string().email()
+   *   email: z.string().email(),
    * });
    *
    * const request = new Request('/users', config);
    * const result = await request
    *   .withResult()
-   *   .output(userSchema)
+   *   .schema(userSchema)
    *   .json();
    *
    * if (Result.isOk(result)) {
    *   const user = result.value; // Typed and validated user data
    * }
+   * ```
    */
   schema(schema) {
     this.#schema = schema;
     return this;
   }
   /**
-   * Sets the request to throw an error if the response status is not successful.
-   * @returns The request instance for chaining
+   * Configures the request to **throw** an exception when the response status
+   * indicates a failure (i.e., `!response.ok`). This disables the “Result”
+   * mode (`withResult`) and enables “throwable” mode, causing
+   * `await request.json()` (or other response helpers) to either resolve with
+   * the successful payload **or** reject with an `AspiError`/`CustomError`.
+   *
+   * Use this when you prefer traditional `try / catch` error handling over
+   * the explicit `Result` type returned by {@link withResult}.
+   *
+   * @returns This {@link Request} instance, now typed with `throwable: true` and
+   *          `withResult: false` for proper chaining.
+   *
    * @example
+   * ```ts
    * const request = new Request('/users', config);
-   * const result = await request
-   *   .withResult()
-   *   .throwable()
-   *   .json();
    *
+   * try {
+   *   const user = await request
+   *     .throwable()   // Enable throwing on HTTP errors
+   *     .json<User>(); // Will throw if the response is not ok
+   *   console.log(user);
+   * } catch (err) {
+   *   // err is either AspiError or a CustomError returned by a custom handler
+   *   console.error('Request failed:', err);
+   * }
+   * ```
    */
   throwable() {
     this.#shouldBeResult = false;
@@ -674,43 +754,100 @@ var Request = class {
     return this;
   }
   /**
-   * Executes the request and returns the JSON response.
-   * @returns A Promise containing the Result type with either successful data or error information
+   * Sends the request and parses the response body as JSON.
+   *
+   * The resolved value of the returned promise varies based on the request mode:
+   *
+   * - **Result mode** (`withResult()`): resolves to a {@link Result.Result} that
+   *   contains either an {@link AspiResultOk} with the parsed payload or a union
+   *   of possible error types (HTTP errors, custom errors, JSON‑parse errors,
+   *   schema‑validation errors, etc.).
+   *
+   * - **Throwable mode** (`throwable()`): resolves directly to the successful
+   *   payload (`AspiPlainResponse`) and throws a {@link AspiError} or
+   *   {@link CustomError} on failure.
+   *
+   * - **Default mode** (no explicit mode): resolves to a tuple
+   *   `[value, error]` where exactly one element is non‑null.
+   *
+   * @template T - The inferred output type of the response schema (if a schema
+   *   was supplied via {@link schema}). When no schema is provided `T` defaults
+   *   to `any`.
+   *
+   * @returns A promise whose shape depends on the selected mode (see description).
+   *   In Result mode it is `Result<ResultOk<…>, …>`, in throwable mode it is
+   *   `AspiPlainResponse<…>`, and otherwise a tuple
+   *   `[AspiResultOk<…> | null, Error | null]`.
+   *
    * @example
+   * // Using the Result API
    * const request = new Request('/users', config);
    * const result = await request
    *   .setQueryParams({ id: '123' })
-   *   .
-   withResult()
-   *   .notFound((error) => ({ message: 'User not found' }))
+   *   .withResult()
+   *   .notFound(() => ({ message: 'User not found' }))
    *   .json<User>();
    *
    * if (Result.isOk(result)) {
-   *   const user = result.value; // User data
+   *   // `result.value` has type `User`
+   *   console.log(result.value);
    * } else {
-   *   console.error(result.error); // Error handling
+   *   console.error(result.error);
    * }
    */
   async json() {
-    const output = await this.#makeRequest(
-      async (response) => response.json().catch(
+    const output = await this.#makeRequest(async (response) => {
+      if (response.status === 204 || response.status >= 300 && response.status < 400) {
+        return null;
+      }
+      return response.json().catch(
         (e) => new CustomError("jsonParseError", {
           message: e instanceof Error ? e.message : "Failed to parse JSON"
         })
-      ),
-      true
-    );
+      );
+    }, true);
     return this.#mapResponse(output);
   }
   /**
-   * Executes the request and returns the response as plain text.
-   * @returns A Promise containing the Result type with either successful text data or error information
+   * Executes the request and returns the response body as plain text.
+   *
+   * The method respects the request mode:
+   *
+   * - **Result mode** (`withResult()`): resolves to a {@link Result.Result}
+   *   containing either an {@link AspiResultOk} with the text payload or an
+   *   error variant.
+   * - **Throwable mode** (`throwable()`): resolves directly to the text string
+   *   and throws on error.
+   * - **Default mode**: resolves to a tuple `[value, error]` where exactly one
+   *   element is `null`.
+   *
+   * @returns {Promise<
+   *   Opts['withResult'] extends true
+   *     ? Result.Result<
+   *         AspiResultOk<TRequest, string>,
+   *         AspiError<TRequest> |
+   *         (Opts extends { error: any } ? Opts['error'][keyof Opts['error']] : never)
+   *       >
+   *     : Opts['throwable'] extends true
+   *       ? AspiPlainResponse<TRequest, string>
+   *       : [
+   *           AspiResultOk<TRequest, string> | null,
+   *           (
+   *             | AspiError<TRequest>
+   *             | (Opts extends { error: any } ? Opts['error'][keyof Opts['error']] : never)
+   *             | null
+   *           )
+   *         ]
+   * }>
+   *   A promise that resolves according to the selected request mode.
+   *
    * @example
+   * ```ts
    * const request = new Request('/data.txt', config);
    * const result = await request
    *   .setQueryParams({ version: '1' })
    *   .withResult()
-   *   .notFound((error) => ({ message: 'Text file not found' }))
+   *   .notFound(() => ({ message: 'Text file not found' }))
    *   .text();
    *
    * if (Result.isOk(result)) {
@@ -718,22 +855,58 @@ var Request = class {
    * } else {
    *   console.error(result.error); // Error handling
    * }
+   * ```
    */
   async text() {
-    const output = await this.#makeRequest(
-      (response) => response.text()
-    );
+    const output = await this.#makeRequest((response) => {
+      return response.text();
+    });
     return this.#mapResponse(output);
   }
   /**
-   * Executes the request and returns the response as a Blob.
-   * @returns A Promise containing the Result type with either successful Blob data or error information
+   * Executes the request and returns the response body as a {@link Blob}.
+   *
+   * The shape of the returned {@link Promise} depends on the request mode:
+   *
+   * - **Result mode** (`withResult()`): resolves to a {@link Result.Result} containing
+   *   either an {@link AspiResultOk} with `Blob` data or an error variant.
+   * - **Throwable mode** (`throwable()`): resolves directly to a {@link Blob}
+   *   (wrapped in {@link AspiPlainResponse}) and throws on failure.
+   * - **Default mode**: resolves to a tuple `[value, error]` where exactly one element
+   *   is `null`.
+   *
+   * @returns {Promise<
+   *   Opts['withResult'] extends true
+   *     ? Result.Result<
+   *         AspiResultOk<TRequest, Blob>,
+   *         | AspiError<TRequest>
+   *         | (Opts extends { error: any }
+   *             ? Opts['error'][keyof Opts['error']]
+   *             : never)
+   *       >
+   *     : Opts['throwable'] extends true
+   *       ? AspiPlainResponse<TRequest, Blob>
+   *       : [
+   *           AspiResultOk<TRequest, Blob> | null,
+   *           (
+   *             | (
+   *                 | AspiError<TRequest>
+   *                 | (Opts extends { error: any }
+   *                     ? Opts['error'][keyof Opts['error']]
+   *                     : never)
+   *               )
+   *             | null
+   *           ),
+   *         ]
+   * }>
+   *
    * @example
+   * ```ts
    * const request = new Request('/image.jpg', config);
    * const result = await request
    *   .setQueryParams({ size: 'large' })
    *   .withResult()
-   *   .notFound((error) => ({ message: 'Image not found' }))
+   *   .notFound(() => ({ message: 'Image not found' }))
    *   .blob();
    *
    * if (Result.isOk(result)) {
@@ -741,43 +914,77 @@ var Request = class {
    * } else {
    *   console.error(result.error); // Error handling
    * }
+   * ```
    */
   async blob() {
     const output = await this.#makeRequest((response) => response.blob());
     return this.#mapResponse(output);
   }
   #url() {
-    const baseUrl = this.#localRequestInit.baseUrl?.replace(/\/+$/, "") ?? "";
+    const passedBaseUrl = typeof this.#localRequestInit.baseUrl === "string" ? this.#localRequestInit.baseUrl : this.#localRequestInit.baseUrl.toString();
+    const baseUrl = passedBaseUrl.replace(/\/+$/, "") ?? "";
     const path = this.#path.replace(/^\/+/, "/");
     const queryString = this.#queryParams ? `?${this.#queryParams.toString()}` : "";
     const url = [baseUrl, path, queryString].filter(Boolean).join("");
     return url;
   }
   /**
-   * Returns the complete URL for the request including base URL, path, and query parameters.
-   * @returns The complete URL string
+   * Returns the fully‑qualified URL that will be used for the request.
+   *
+   * The URL is constructed from the configured base URL, the request path,
+   * and any query parameters added via {@link setQueryParams}.
+   *
+   * @returns {string} The complete request URL.
+   *
    * @example
+   * ```ts
    * const request = new Request('/users', config);
    * request.setBaseUrl('https://api.example.com');
    * request.setQueryParams({ id: '123' });
-   * console.log(request.url()); // 'https://api.example.com/users?id=123'
+   *
+   * console.log(request.url());
+   * // => 'https://api.example.com/users?id=123'
+   * ```
    */
   url() {
     return this.#url();
   }
   /**
-   * Configures the request to return a Result type instead of a tuple.
-   * @returns The request instance for chaining with Result type return value
+   * Switches the request into **Result** mode.
+   *
+   * In Result mode the response helpers (`json`, `text`, `blob`, …) resolve to a
+   * {@link Result.Result} instance instead of the default tuple
+   * `[value, error]`. This allows callers to use pattern matching
+   * (`Result.isOk`, `Result.isErr`) to handle success and failure.
+   *
+   * Calling `withResult` disables the “throwable” behaviour (see {@link throwable}).
+   *
+   * @returns {Request<
+   *   Method,
+   *   TRequest,
+   *   Merge<
+   *     Omit<Opts, 'withResult' | 'throwable'>,
+   *     {
+   *       withResult: true;
+   *       throwable: false;
+   *     }
+   *   >
+   * >} The same {@link Request} instance, now typed with `withResult: true` and
+   * `throwable: false` for fluent chaining.
+   *
    * @example
+   * ```ts
    * const request = new Request('/users', config);
+   *
    * const result = await request
-   *   .withResult()
+   *   .withResult() // enable Result mode
    *   .json<User>();
    *
-   * // Returns Result type instead of tuple
    * if (Result.isOk(result)) {
-   *   const user = result.value;
+   *   // `result.value` is of type `User`
+   *   console.log(result.value);
    * }
+   * ```
    */
   withResult() {
     this.#throwOnError = false;
@@ -797,6 +1004,9 @@ var Request = class {
       return [null, getErrorOrNull(value)];
     }
   }
+  #isSuccessResponse(response) {
+    return response.ok || response.status >= 300 && response.status < 400;
+  }
   async #makeRequest(responseParser, isJson = false) {
     if (this.#bodySchemaIssues.length) {
       return err(new CustomError("parseError", this.#bodySchemaIssues));
@@ -807,20 +1017,23 @@ var Request = class {
       const requestInit = request.requestInit;
       const url = this.#url();
       let attempts = 1;
-      let response;
-      let responseData;
+      let response = new Response(null, {
+        status: 500,
+        statusText: "Internal Server Error"
+      });
+      let responseData = null;
       while (attempts <= retries) {
         try {
           response = await fetch(url, requestInit);
           responseData = await responseParser(response);
-          if (responseData instanceof CustomError) {
+          if (responseData instanceof Error) {
             return err(responseData);
           }
           const retryWhileCondition = retryWhile ? await retryWhile(
             request,
             this.#makeResponse(response, responseData)
           ) : false;
-          if (response.ok || !retryOn.includes(response.status) && !retryWhileCondition) {
+          if (this.#isSuccessResponse(response) || !retryOn.includes(response.status) && !retryWhileCondition) {
             break;
           }
           if (response.status in this.#customErrorCbs && attempts === retries) {
@@ -843,9 +1056,31 @@ var Request = class {
               request,
               this.#makeResponse(response, responseData)
             ) : retryDelay;
-            await new Promise((resolve) => setTimeout(resolve, delay));
+            await this.#abortDelay(delay, request);
           }
         } catch (e) {
+          if (e instanceof Error && e.name === "AbortError") {
+            if (500 in this.#customErrorCbs) {
+              const result = this.#customErrorCbs[response.status].cb({
+                request,
+                response: this.#makeResponse(response, responseData)
+              });
+              return err(
+                new CustomError(
+                  // @ts-ignore
+                  this.#customErrorCbs[response.status].tag,
+                  result
+                )
+              );
+            }
+            return err(
+              new AspiError(
+                e.message,
+                this.#request(),
+                this.#makeResponse(response, responseData)
+              )
+            );
+          }
           if (attempts === retries) throw e;
           const delay = typeof retryDelay === "function" ? await retryDelay(
             retries - attempts - 1,
@@ -853,14 +1088,14 @@ var Request = class {
             request,
             this.#makeResponse(response, responseData)
           ) : retryDelay;
-          await new Promise((resolve) => setTimeout(resolve, delay));
+          await this.#abortDelay(delay, request);
         }
         if (onRetry) {
           onRetry(request, this.#makeResponse(response, responseData));
         }
         attempts++;
       }
-      if (!response.ok) {
+      if (!this.#isSuccessResponse(response)) {
         if (response.status in this.#customErrorCbs) {
           const result = this.#customErrorCbs[response.status].cb({
             request,
@@ -930,17 +1165,38 @@ var Request = class {
       );
     }
   }
+  #abortDelay(ms, request) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(resolve, ms);
+      const signal = request.requestInit.signal;
+      if (signal) {
+        if (signal.aborted) {
+          clearTimeout(timer);
+          reject(new DOMException("The user aborted a request.", "AbortError"));
+        } else {
+          const abortHandler = () => {
+            clearTimeout(timer);
+            reject(
+              new DOMException("The user aborted a request.", "AbortError")
+            );
+          };
+          signal.addEventListener("abort", abortHandler, { once: true });
+        }
+      }
+    });
+  }
   #request() {
     let requestInit = this.#localRequestInit;
     for (const middleware of this.#middlewares) {
-      requestInit = middleware(this.#localRequestInit);
+      requestInit = middleware(requestInit);
     }
     return {
-      requestInit,
-      baseUrl: this.#localRequestInit.baseUrl,
+      requestInit: {
+        ...requestInit,
+        retryConfig: this.#sanitisedRetryConfig()
+      },
       path: this.#path,
-      queryParams: this.#queryParams || null,
-      retryConfig: this.#sanitisedRetryConfig()
+      queryParams: this.#queryParams || null
     };
   }
   #sanitisedRetryConfig() {
@@ -965,6 +1221,68 @@ var Request = class {
       responseData
     };
   }
+  /**
+   * Returns the underlying {@link AspiRequest} object that will be used for the fetch call.
+   *
+   * This method does not perform any network activity; it simply builds and returns the
+   * request configuration, including any applied middlewares, query parameters, etc.
+   *
+   * @returns {AspiRequest<TRequest>} The constructed request object.
+   */
+  getRequest() {
+    return this.#request();
+  }
+  /**
+   * Retrieves the registry of custom error callbacks that have been
+   * registered via {@link error}. The returned object maps HTTP status
+   * codes to their corresponding callback functions and tags.
+   *
+   * @returns {ErrorCallbacks} A shallow copy of the internal error callback registry.
+   */
+  getErrorCallbackRegistry() {
+    return { ...this.#customErrorCbs };
+  }
+  /**
+   * Returns whether the request is configured to return a {@link Result.Result}
+   * instead of the default tuple or throwing.
+   *
+   * @returns {boolean} `true` when {@link withResult} has been called.
+   */
+  isResult() {
+    return this.#shouldBeResult;
+  }
+  /**
+   * Returns whether the request is configured to throw on HTTP errors.
+   *
+   * @returns {boolean} `true` when {@link throwable} has been called.
+   */
+  isThrowable() {
+    return this.#throwOnError;
+  }
+  /**
+   * Returns the effective retry configuration for this request, including defaulted values.
+   *
+   * The returned object contains:
+   * - `retries` – number of retry attempts (default 1)
+   * - `retryDelay` – delay between attempts in milliseconds or a function that returns a delay
+   * - `retryOn` – array of HTTP status codes that should trigger a retry
+   * - `retryWhile` – optional custom predicate executed after each response
+   * - `onRetry` – optional callback invoked after a retry attempt
+   *
+   * A shallow copy is returned to avoid accidental mutation of the internal state.
+   *
+   * @returns {{
+   *   retries: number;
+   *   retryDelay: number | ((attempt: number, maxAttempts: number, request: AspiRequest<TRequest>, response: AspiResponse<any, true>) => number);
+   *   retryOn: number[];
+   *   retryWhile?: (request: AspiRequest<TRequest>, response: AspiResponse<any, true>) => boolean | Promise<boolean>;
+   *   onRetry?: (request: AspiRequest<TRequest>, response: AspiResponse<any, true>) => void;
+   * }}
+   */
+  getRetryConfig() {
+    const cfg = this.#sanitisedRetryConfig();
+    return { ...cfg };
+  }
 };
 
 // src/aspi.ts
@@ -974,15 +1292,20 @@ var Aspi2 = class {
   #retryConfig;
   #customErrorCbs = {};
   #throwOnError = false;
+  #shouldBeResult = false;
   constructor(config) {
-    const { retryConfig, ...requestConfig } = config;
-    this.#globalRequestInit = requestConfig;
+    const { retryConfig, ...requestInit } = config;
+    this.#globalRequestInit = requestInit;
     this.#retryConfig = retryConfig;
   }
   /**
-   * Sets the base URL for all API requests
-   * @param {string} url - The base URL to be set
-   * @returns {Aspi} The Aspi instance for chaining
+   * Sets or overrides the base URL used for all subsequent API requests.
+   *
+   * Accepts either a string or a `URL` instance. If a `URL` object is provided,
+   * it is converted to its string representation.
+   *
+   * @param url - The new base URL.
+   * @returns The current {@link Aspi} instance for chaining.
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
    * api.setBaseUrl('https://api.newdomain.com');
@@ -1011,17 +1334,17 @@ var Aspi2 = class {
     };
     return this;
   }
-  #createRequest(method, path, body) {
+  #createRequest(method, path) {
     return new Request(method, path, {
       requestConfig: {
         ...this.#globalRequestInit,
-        method,
-        body
+        method
       },
-      retryConfig: this.#retryConfig,
       middlewares: this.#middlewares,
       errorCbs: this.#customErrorCbs,
-      throwOnError: this.#throwOnError
+      throwOnError: this.#throwOnError,
+      shouldBeResult: this.#shouldBeResult,
+      retryConfig: this.#retryConfig
     });
   }
   /**
@@ -1036,40 +1359,39 @@ var Aspi2 = class {
     return this.#createRequest("GET", path);
   }
   /**
-   * Makes a POST request to the specified path with an optional body
-   * @param {string} path - The path to make the request to
-   * @param {BodyInit} [body] - The body of the request
-   * @returns {Request} A Request instance for chaining
+   * Makes a POST request to the specified path.
+   *
+   * @param {string} path - The path to make the request to.
+   * @returns {Request} A Request instance for chaining.
+   *
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-   * const response = await api.post('/users', { name: 'John' }).json();
+   * const response = await api.post('/users').json();
    */
-  post(path, body) {
-    return this.#createRequest("POST", path, body);
+  post(path) {
+    return this.#createRequest("POST", path);
   }
   /**
-   * Makes a PUT request to the specified path with an optional body
-   * @param {string} path - The path to make the request to
-   * @param {BodyInit} [body] - The body of the request
-   * @returns {Request} A Request instance for chaining
+   * Makes a PUT request to the specified path.
+   * @param {string} path - The path to make the request to.
+   * @returns {Request} A Request instance for chaining.
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-   * const response = await api.put('/users/1', { name: 'John' }).json();
+   * const response = await api.put('/users/1').json();
    */
-  put(path, body) {
-    return this.#createRequest("PUT", path, body);
+  put(path) {
+    return this.#createRequest("PUT", path);
   }
   /**
-   * Makes a PATCH request to the specified path with an optional body
-   * @param {string} path - The path to make the request to
-   * @param {BodyInit} [body] - The body of the request
-   * @returns {Request} A Request instance for chaining
+   * Makes a PATCH request to the specified path.
+   * @param {string} path - The path to make the request to.
+   * @returns {Request} A Request instance for chaining.
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-   * const response = await api.patch('/users/1', { name: 'John' }).json();
+   * const response = await api.patch('/users/1').json();
    */
-  patch(path, body) {
-    return this.#createRequest("PATCH", path, body);
+  patch(path) {
+    return this.#createRequest("PATCH", path);
   }
   /**
    * Makes a DELETE request to the specified path
@@ -1105,8 +1427,9 @@ var Aspi2 = class {
     return this.#createRequest("OPTIONS", path);
   }
   /**
-   * Sets multiple headers for all API requests
-   * @param {Record<string, string>} headers - An object containing header key-value pairs
+   * Sets multiple headers for all API requests. Existing headers are preserved
+   * and new ones are merged, overriding any duplicate keys.
+   * @param {HeadersInit} headers - An object containing header key-value pairs
    * @returns {Aspi} The Aspi instance for chaining
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
@@ -1116,21 +1439,26 @@ var Aspi2 = class {
    * });
    */
   setHeaders(headers) {
-    this.#globalRequestInit.headers = headers;
+    this.#globalRequestInit.headers = {
+      ...this.#globalRequestInit.headers ?? {},
+      ...headers
+    };
     return this;
   }
   /**
-   * Sets a single header for all API requests
-   * @param {string} key - The header key
-   * @param {string} value - The header value
-   * @returns {Aspi} The Aspi instance for chaining
+   * Sets a single header for all API requests.
+   *
+   * @param key - The header name.
+   * @param value - The header value.
+   * @returns This {@link Aspi} instance for chaining.
+   *
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
    * api.setHeader('Content-Type', 'application/json');
    */
   setHeader(key, value) {
     this.#globalRequestInit.headers = {
-      ...this.#globalRequestInit.headers,
+      ...this.#globalRequestInit.headers ?? {},
       [key]: value
     };
     return this;
@@ -1147,18 +1475,28 @@ var Aspi2 = class {
     return this.setHeader("Authorization", `Bearer ${token}`);
   }
   /**
-   * Use a middleware function to transform requests
-   * @param {Middleware<T, U>} fn - The middleware function to apply
-   * @returns {Aspi<U>} A new Aspi instance with the applied middleware
+   * Register a request‑transformer middleware.
+   *
+   * The supplied function receives the current request initialization object
+   * (`T`) and must return a request initialization of type `U`. The middleware
+   * is added to the internal middleware chain and will be applied to every
+   * request created by this {@link Aspi} instance.
+   *
+   * @template T - The input request type, extending the current {@link Aspi} request init type.
+   * @template U - The output request type after transformation.
+   * @param {RequestTransformer<T, U>} fn - The middleware function that transforms a request configuration.
+   * @returns {Aspi<U>} A new {@link Aspi} instance typed with the transformed request configuration.
    * @example
    * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-   * api.use((req) => {
-   *   // Add custom headers
-   *   req.headers = {
-   *     ...req.headers,
-   *     'x-custom-header': 'custom-value'
+   * const apiWithHeaders = api.use((req) => {
+   *   // Add custom headers to every request
+   *   return {
+   *     ...req,
+   *     headers: {
+   *       ...req.headers,
+   *       'x-custom-header': 'custom-value',
+   *     },
    *   };
-   *   return req;
    * });
    */
   use(fn) {
@@ -1290,6 +1628,16 @@ var Aspi2 = class {
    */
   throwable() {
     this.#throwOnError = true;
+    this.#shouldBeResult = false;
+    return this;
+  }
+  /**
+   * Configures the request to return a Result object instead of just the response body.
+   * @returns The Aspi instance with result handling enabled.
+   */
+  withResult() {
+    this.#shouldBeResult = true;
+    this.#throwOnError = false;
     return this;
   }
 };