@blueprint-ts/core 4.0.0 → 4.1.0-beta.1

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 4.1.0-beta.1 - 2026-03-21 (beta)
+
+# [4.1.0-beta.1](/compare/v4.0.0...v4.1.0-beta.1) (2026-03-21)
+
+
+### Bug Fixes
+
+* **requests:** export HeaderValue type 15e55c1
+
+
+### Features
+
+* **requests:** add XMLHttpRequest upload progress support 19123df
 ## v4.0.0 - 2026-03-01
 
 # [4.0.0](/compare/v4.0.0-beta.10...v4.0.0) (2026-03-01)

package/docs/.vitepress/config.ts

@@ -24,6 +24,7 @@ export default defineConfig({
               { text: 'Drivers', link: '/services/requests/drivers' },
               { text: 'Responses', link: '/services/requests/responses' },
               { text: 'Request Bodies', link: '/services/requests/request-bodies' },
+              { text: 'File Uploads', link: '/services/requests/file-uploads' },
               { text: 'Headers', link: '/services/requests/headers' },
               { text: 'Concurrency', link: '/services/requests/concurrency' },
               { text: 'Aborting Requests', link: '/services/requests/abort-requests' },

package/docs/services/requests/drivers.md

@@ -1,9 +1,9 @@
 # Drivers
 
-Requests are executed by a request driver. The library includes a default fetch-based driver and lets you provide your
-own by implementing `RequestDriverContract`.
+Requests are executed by a request driver. The library includes a `FetchDriver`, an `XMLHttpRequestDriver`, and also
+lets you provide your own by implementing `RequestDriverContract`.
 
-## Default Fetch Driver
+## Fetch Driver
 
 ```typescript
 import { BaseRequest, FetchDriver } from '@blueprint-ts/core/requests'
@@ -17,6 +17,71 @@ The `FetchDriver` supports:
 - `corsWithCredentials` configuration
 - `AbortSignal` via request config
 
+## XMLHttpRequest Driver
+
+Use `XMLHttpRequestDriver` when you need upload progress events for file uploads:
+
+```typescript
+import { BaseRequest, XMLHttpRequestDriver } from '@blueprint-ts/core/requests'
+
+BaseRequest.setRequestDriver(new XMLHttpRequestDriver())
+```
+
+It supports the same configuration as `FetchDriver` and additionally forwards upload progress through
+`RequestEvents.UPLOAD_PROGRESS`.
+
+That includes:
+
+- `corsWithCredentials`
+- `headers`
+- dynamic header callbacks such as `() => getCookie('XSRF-TOKEN')`
+
+## Request-Defined Driver
+
+If a specific request class should always use a different driver, define it inside the request:
+
+```typescript
+import {
+    BaseRequest,
+    FetchDriver,
+    JsonResponse,
+    RequestMethodEnum,
+    XMLHttpRequestDriver
+} from '@blueprint-ts/core/requests'
+
+BaseRequest.setRequestDriver(new FetchDriver())
+
+class UploadAvatarRequest extends BaseRequest<boolean, { message: string }, { ok: true }, JsonResponse<{ ok: true }>> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.POST
+    }
+
+    public url(): string {
+        return '/api/v1/avatar'
+    }
+
+    public getResponse(): JsonResponse<{ ok: true }> {
+        return new JsonResponse<{ ok: true }>()
+    }
+
+    protected override getRequestDriver() {
+        return new XMLHttpRequestDriver({
+            corsWithCredentials: true,
+            headers: {
+                'X-XSRF-TOKEN': () => getCookie('XSRF-TOKEN')
+            }
+        })
+    }
+}
+```
+
+This keeps the driver choice encapsulated inside the request class while still allowing the application to keep a
+global default driver for everything else.
+
+Important: request-defined drivers do not inherit configuration from the globally registered driver instance. If your
+upload request needs credential support or shared headers, configure them on the `XMLHttpRequestDriver` you return from
+`getRequestDriver()`.
+
 ## Custom Driver
 
 To implement your own driver, implement `RequestDriverContract` and return a `ResponseHandlerContract`:

package/docs/services/requests/events.md

@@ -5,6 +5,7 @@ Requests can emit lifecycle events via `BaseRequest.on(...)`.
 ## Available Events
 
 - `RequestEvents.LOADING`: Emits `true` when a request starts and `false` when it finishes.
+- `RequestEvents.UPLOAD_PROGRESS`: Emits upload progress for drivers that support it, such as `XMLHttpRequestDriver`.
 
 ## Loading Event
 
@@ -29,3 +30,24 @@ request.on<boolean>(RequestEvents.LOADING, (isLoading) => {
     // isLoading is typed as boolean
 })
 ```
+
+## Upload Progress Event
+
+Use `RequestEvents.UPLOAD_PROGRESS` to drive file upload progress indicators:
+
+```typescript
+import { RequestEvents, type RequestUploadProgress } from '@blueprint-ts/core/requests'
+
+request.on<RequestUploadProgress>(RequestEvents.UPLOAD_PROGRESS, (progress) => {
+    console.log(progress.loaded, progress.total, progress.progress)
+})
+```
+
+The payload contains:
+
+- `loaded`: Bytes uploaded so far.
+- `total`: Total bytes when the browser can compute it.
+- `lengthComputable`: Whether `total` is reliable.
+- `progress`: A normalized value between `0` and `1` when `total` is known.
+
+Note: The default `FetchDriver` does not emit upload progress. Use `XMLHttpRequestDriver` for upload progress support.

package/docs/services/requests/file-uploads.md

@@ -0,0 +1,105 @@
+# File Uploads
+
+Use `FormDataFactory` to build multipart payloads, and use `XMLHttpRequestDriver` when the consuming application needs
+upload progress for a progress bar.
+
+## Request Definition
+
+```typescript
+import {
+    BaseRequest,
+    FormDataFactory,
+    JsonResponse,
+    RequestMethodEnum,
+    XMLHttpRequestDriver
+} from '@blueprint-ts/core/requests'
+
+interface UploadAvatarPayload {
+    avatar: File
+}
+
+interface UploadAvatarResponse {
+    id: string
+    url: string
+}
+
+class UploadAvatarRequest extends BaseRequest<
+        boolean,
+        { message: string },
+        UploadAvatarResponse,
+        JsonResponse<UploadAvatarResponse>,
+        UploadAvatarPayload
+> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.POST
+    }
+
+    public url(): string {
+        return '/api/v1/avatar'
+    }
+
+    public getResponse(): JsonResponse<UploadAvatarResponse> {
+        return new JsonResponse<UploadAvatarResponse>()
+    }
+
+    public override getRequestBodyFactory() {
+        return new FormDataFactory<UploadAvatarPayload>()
+    }
+
+    protected override getRequestDriver() {
+        return new XMLHttpRequestDriver({
+            corsWithCredentials: true,
+            headers: {
+                'X-XSRF-TOKEN': () => getCookie('XSRF-TOKEN')
+            }
+        })
+    }
+}
+```
+
+## Global Default Driver
+
+You can keep `FetchDriver` as the application default. The upload request above will still use `XMLHttpRequestDriver`
+because it defines its own driver internally:
+
+```typescript
+import { BaseRequest, FetchDriver } from '@blueprint-ts/core/requests'
+
+BaseRequest.setRequestDriver(new FetchDriver())
+```
+
+Important: the upload request's `XMLHttpRequestDriver` does not inherit config from the global `FetchDriver`. If the
+upload request needs credentials or shared headers, define them on the `XMLHttpRequestDriver` returned by
+`getRequestDriver()`.
+
+## Listening for Upload Progress
+
+```typescript
+import { RequestEvents, type RequestUploadProgress } from '@blueprint-ts/core/requests'
+
+const request = new UploadAvatarRequest()
+
+request.on<RequestUploadProgress>(RequestEvents.UPLOAD_PROGRESS, (progress) => {
+    if (!progress.lengthComputable || progress.progress === undefined) {
+        return
+    }
+
+    progressBar.value = progress.progress * 100
+})
+
+await request.setBody({
+    avatar: fileInput.files![0],
+}).send()
+```
+
+## Notes
+
+- Upload progress requires `XMLHttpRequestDriver`. The default `FetchDriver` does not emit upload progress events.
+- Define `XMLHttpRequestDriver` inside the upload request class when that request should always support progress.
+- `XMLHttpRequestDriver` supports the same `corsWithCredentials` and `headers` options as `FetchDriver`, including
+  header callbacks.
+- Request-defined drivers do not automatically inherit config from the globally registered driver.
+- Some browsers cannot compute a reliable total size for every upload. Check `lengthComputable` before rendering a
+  percentage.
+- Upload event listeners may cause CORS preflight requests on cross-origin uploads. Ensure the server is configured
+  accordingly.

package/docs/services/requests/request-bodies.md

@@ -54,6 +54,8 @@ public override getRequestBodyFactory() {
 }
 ```
 
+If you want to show upload progress for multipart file uploads, see [File Uploads](/services/requests/file-uploads).
+
 ## Custom Body Factories
 
 You can implement your own body factory by returning a `BodyContract` with custom headers and serialization logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "4.0.0",
+  "version": "4.1.0-beta.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/requests/BaseRequest.ts

@@ -7,6 +7,7 @@ import { ResponseException } from './exceptions/ResponseException'
 import { StaleResponseException } from './exceptions/StaleResponseException'
 import { type DriverConfigContract } from './contracts/DriverConfigContract'
 import { type BodyFactoryContract } from './contracts/BodyFactoryContract'
+import { type BodyContract } from './contracts/BodyContract'
 import { type RequestLoaderContract } from './contracts/RequestLoaderContract'
 import { type RequestDriverContract } from './contracts/RequestDriverContract'
 import { type RequestLoaderFactoryContract } from './contracts/RequestLoaderFactoryContract'
@@ -15,6 +16,7 @@ import { type HeadersContract } from './contracts/HeadersContract'
 import { type ResponseHandlerContract } from './drivers/contracts/ResponseHandlerContract'
 import { type ResponseContract } from './contracts/ResponseContract'
 import { type RequestConcurrencyOptions } from './types/RequestConcurrencyOptions'
+import { type RequestUploadProgress } from './types/RequestUploadProgress'
 import { RequestConcurrencyMode } from './RequestConcurrencyMode.enum'
 import { mergeDeep } from '../support/helpers'
 import { v4 as uuidv4 } from 'uuid'
@@ -164,8 +166,9 @@ export abstract class BaseRequest<
     const responseSkeleton = this.getResponse()
 
     const requestBody = this.requestBody === undefined ? undefined : this.getRequestBodyFactory()?.make(this.requestBody)
+    const requestConfig = this.buildRequestConfig(requestBody, concurrencyKey, sequence, useLatest)
 
-    return BaseRequest.requestDriver
+    return this.resolveRequestDriver()
       .send(
         this.buildUrl(),
         this.method(),
@@ -174,7 +177,7 @@ export abstract class BaseRequest<
           ...this.requestHeaders()
         },
         requestBody,
-        this.getConfig()
+        requestConfig
       )
       .then(async (responseHandler: ResponseHandlerContract) => {
         if (useLatest && !this.isLatestSequence(concurrencyKey, sequence)) {
@@ -275,9 +278,44 @@ export abstract class BaseRequest<
     return undefined
   }
 
+  protected buildRequestConfig(
+    requestBody: BodyContract | undefined,
+    concurrencyKey: string,
+    sequence: number,
+    useLatest: boolean
+  ): DriverConfigContract {
+    const config = this.getConfig() ?? {}
+    const onUploadProgress = config.onUploadProgress
+
+    if (requestBody === undefined) {
+      return config
+    }
+
+    return {
+      ...config,
+      onUploadProgress: (progress: RequestUploadProgress) => {
+        onUploadProgress?.(progress)
+
+        if (useLatest && !this.isLatestSequence(concurrencyKey, sequence)) {
+          return
+        }
+
+        this.dispatch<RequestUploadProgress>(RequestEvents.UPLOAD_PROGRESS, progress)
+      }
+    }
+  }
+
   protected getConfig(): DriverConfigContract | undefined {
     return {
       abortSignal: this.abortSignal
     }
   }
+
+  protected resolveRequestDriver(): RequestDriverContract {
+    return this.getRequestDriver() ?? BaseRequest.requestDriver
+  }
+
+  protected getRequestDriver(): RequestDriverContract | undefined {
+    return undefined
+  }
 }

package/src/requests/RequestEvents.enum.ts

@@ -1,3 +1,4 @@
 export enum RequestEvents {
-  LOADING = 'loading'
+  LOADING = 'loading',
+  UPLOAD_PROGRESS = 'upload-progress'
 }

package/src/requests/contracts/DriverConfigContract.ts

@@ -1,7 +1,9 @@
 import { type HeadersContract } from './HeadersContract'
+import { type RequestUploadProgress } from '../types/RequestUploadProgress'
 
 export interface DriverConfigContract {
   corsWithCredentials?: boolean | undefined
   abortSignal?: AbortSignal | undefined
   headers?: HeadersContract | undefined
+  onUploadProgress?: ((progress: RequestUploadProgress) => void) | undefined
 }

package/src/requests/drivers/xhr/XMLHttpRequestDriver.ts

@@ -0,0 +1,138 @@
+import { ResponseException } from '../../exceptions/ResponseException'
+import { RequestMethodEnum } from '../../RequestMethod.enum'
+import { type HeadersContract, type HeaderValue } from '../../contracts/HeadersContract'
+import { type BodyContract } from '../../contracts/BodyContract'
+import { type RequestDriverContract } from '../../contracts/RequestDriverContract'
+import { type DriverConfigContract } from '../../contracts/DriverConfigContract'
+import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
+import { XMLHttpRequestResponse } from './XMLHttpRequestResponse'
+
+export class XMLHttpRequestDriver implements RequestDriverContract {
+  public constructor(protected config?: DriverConfigContract) {}
+
+  public async send(
+    url: URL | string,
+    method: RequestMethodEnum,
+    headers: HeadersContract,
+    body?: BodyContract,
+    requestConfig?: DriverConfigContract
+  ): Promise<ResponseHandlerContract> {
+    const mergedConfig: DriverConfigContract = {
+      ...this.config,
+      ...(requestConfig ?? {})
+    }
+
+    const mergedHeaders: HeadersContract = {
+      ...this.config?.headers,
+      ...headers,
+      ...body?.getHeaders()
+    }
+
+    const resolvedHeaders = this.resolveHeaders(mergedHeaders)
+
+    return await new Promise<ResponseHandlerContract>((resolve, reject) => {
+      const request = new XMLHttpRequest()
+      const requestUrl = url instanceof URL ? url.toString() : url
+      const requestBody = [RequestMethodEnum.GET, RequestMethodEnum.HEAD].includes(method) ? undefined : body?.getContent()
+      const abortSignal = mergedConfig.abortSignal
+      const handleAbortSignal = () => request.abort()
+
+      const cleanup = () => {
+        request.onload = null
+        request.onerror = null
+        request.onabort = null
+
+        if (request.upload) {
+          request.upload.onprogress = null
+        }
+
+        abortSignal?.removeEventListener('abort', handleAbortSignal)
+      }
+
+      request.open(method, requestUrl, true)
+      request.responseType = 'blob'
+      request.withCredentials = this.getCorsWithCredentials(mergedConfig.corsWithCredentials)
+
+      for (const key in resolvedHeaders) {
+        request.setRequestHeader(key, resolvedHeaders[key] as string)
+      }
+
+      request.onload = () => {
+        cleanup()
+
+        if (request.status === 0) {
+          reject(new Error('No response received.'))
+          return
+        }
+
+        const response = new XMLHttpRequestResponse(request)
+
+        if (request.status < 200 || request.status >= 300) {
+          reject(new ResponseException(response))
+          return
+        }
+
+        resolve(response)
+      }
+
+      request.onerror = () => {
+        cleanup()
+        reject(new Error('Network request failed.'))
+      }
+
+      request.onabort = () => {
+        cleanup()
+        reject(new DOMException('The operation was aborted.', 'AbortError'))
+      }
+
+      if (request.upload) {
+        request.upload.onprogress = (event: ProgressEvent<EventTarget>) => {
+          const total = event.lengthComputable ? event.total : undefined
+
+          mergedConfig.onUploadProgress?.({
+            loaded: event.loaded,
+            total: total,
+            lengthComputable: event.lengthComputable,
+            progress: total === undefined || total === 0 ? undefined : event.loaded / total
+          })
+        }
+      }
+
+      if (abortSignal?.aborted) {
+        handleAbortSignal()
+        return
+      }
+
+      abortSignal?.addEventListener('abort', handleAbortSignal, { once: true })
+      request.send(requestBody)
+    })
+  }
+
+  protected getCorsWithCredentials(corsWithCredentials: boolean | undefined): boolean {
+    if (corsWithCredentials === true) {
+      return true
+    }
+
+    if (corsWithCredentials === false) {
+      return false
+    }
+
+    return this.config?.corsWithCredentials ?? false
+  }
+
+  protected resolveHeaders(headers: HeadersContract): HeadersContract {
+    const resolved: HeadersContract = {}
+
+    for (const key in headers) {
+      const value: HeaderValue | undefined = headers[key]
+
+      if (value === undefined) {
+        continue
+      }
+
+      resolved[key] = typeof value === 'function' ? value() : value
+    }
+
+    return resolved
+  }
+}

package/src/requests/drivers/xhr/XMLHttpRequestResponse.ts

@@ -0,0 +1,95 @@
+import { type HeadersContract } from '../../contracts/HeadersContract'
+import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
+
+export class XMLHttpRequestResponse implements ResponseHandlerContract {
+  protected response: Response
+  protected headers: HeadersContract
+
+  public constructor(protected request: XMLHttpRequest) {
+    this.headers = this.parseHeaders(request.getAllResponseHeaders())
+    this.response = new Response(this.getResponseBody(), {
+      status: request.status,
+      statusText: request.statusText,
+      headers: Object.entries(this.headers).map(([key, value]) => [key, String(value)])
+    })
+  }
+
+  public getStatusCode(): number | undefined {
+    return this.request.status
+  }
+
+  public getHeaders(): HeadersContract {
+    return this.headers
+  }
+
+  public getRawResponse(): Response {
+    return this.response
+  }
+
+  public async json<ResponseBodyInterface>(): Promise<ResponseBodyInterface> {
+    return await this.response.json()
+  }
+
+  public async text(): Promise<string> {
+    return await this.response.text()
+  }
+
+  public async blob(): Promise<Blob> {
+    return await this.response.blob()
+  }
+
+  protected getResponseBody(): Blob | string | null {
+    if ([204, 205, 304].includes(this.request.status)) {
+      return null
+    }
+
+    if (this.request.response === null || this.request.response === undefined) {
+      return null
+    }
+
+    if (this.isBlobLike(this.request.response) || typeof this.request.response === 'string') {
+      return this.request.response
+    }
+
+    return new Blob([this.request.response])
+  }
+
+  protected isBlobLike(value: unknown): value is Blob {
+    return (
+      value instanceof Blob ||
+      (typeof value === 'object' &&
+        value !== null &&
+        typeof (value as Blob).arrayBuffer === 'function' &&
+        typeof (value as Blob).stream === 'function' &&
+        typeof (value as Blob).text === 'function')
+    )
+  }
+
+  protected parseHeaders(rawHeaders: string): HeadersContract {
+    const headers: HeadersContract = {}
+    const lines = rawHeaders.trim()
+
+    if (lines.length === 0) {
+      return headers
+    }
+
+    for (const line of lines.split(/\r?\n/)) {
+      const separatorIndex = line.indexOf(':')
+
+      if (separatorIndex === -1) {
+        continue
+      }
+
+      const key = line.slice(0, separatorIndex).trim()
+      const value = line.slice(separatorIndex + 1).trim()
+
+      if (key.length === 0) {
+        continue
+      }
+
+      headers[key] = key in headers ? `${String(headers[key])}, ${value}` : value
+    }
+
+    return headers
+  }
+}

package/src/requests/index.ts

@@ -21,8 +21,10 @@ import { type ResponseHandlerContract } from './drivers/contracts/ResponseHandle
 import { type BaseRequestContract } from './contracts/BaseRequestContract'
 import { ResponseException } from './exceptions/ResponseException'
 import { StaleResponseException } from './exceptions/StaleResponseException'
-import { type HeadersContract } from './contracts/HeadersContract'
+import { type HeaderValue, type HeadersContract } from './contracts/HeadersContract'
 import { type RequestConcurrencyOptions } from './types/RequestConcurrencyOptions'
+import { type RequestUploadProgress } from './types/RequestUploadProgress'
+import { XMLHttpRequestDriver } from './drivers/xhr/XMLHttpRequestDriver'
 
 export {
   FetchDriver,
@@ -39,7 +41,8 @@ export {
   ResponseException,
   StaleResponseException,
   JsonBodyFactory,
-  FormDataFactory
+  FormDataFactory,
+  XMLHttpRequestDriver
 }
 
 export type {
@@ -51,6 +54,8 @@ export type {
   BodyFactoryContract,
   ResponseHandlerContract,
   BaseRequestContract,
+  HeaderValue,
   HeadersContract,
-  RequestConcurrencyOptions
+  RequestConcurrencyOptions,
+  RequestUploadProgress
 }

package/src/requests/types/RequestUploadProgress.ts

@@ -0,0 +1,6 @@
+export interface RequestUploadProgress {
+  loaded: number
+  total?: number | undefined
+  lengthComputable: boolean
+  progress?: number | undefined
+}

package/tests/service/requests/BaseRequest.test.ts

@@ -118,6 +118,33 @@ describe('BaseRequest', () => {
     expect(body?.getContent()).toBe('{"name":"Ada"}')
   })
 
+  it('dispatches upload progress events from the driver config callback', async () => {
+    const driver: RequestDriverContract = {
+      send: vi.fn().mockImplementation(async (_url, _method, _headers, _body, requestConfig) => {
+        requestConfig?.onUploadProgress?.({
+          loaded: 5,
+          total: 10,
+          lengthComputable: true,
+          progress: 0.5,
+        })
+
+        return createResponseHandler()
+      }),
+    }
+
+    BaseRequest.setRequestDriver(driver)
+
+    const request = new TestRequest()
+    const progressEvents: Array<number | undefined> = []
+
+    request.on(RequestEvents.UPLOAD_PROGRESS, (value: { progress?: number }) => progressEvents.push(value.progress))
+    request.setBody({ name: 'Ada' })
+
+    await request.send()
+
+    expect(progressEvents).toEqual([0.5])
+  })
+
   it('throws when loading state is requested without a loader', () => {
     const request = new TestRequest()
 
@@ -196,4 +223,28 @@ describe('BaseRequest', () => {
     await expect(request.send()).rejects.toBe(responseException)
     expect(handleSpy).toHaveBeenCalledTimes(1)
   })
+
+  it('uses a request-defined driver when provided', async () => {
+    const globalDriver: RequestDriverContract = {
+      send: vi.fn().mockResolvedValue(createResponseHandler()),
+    }
+    const requestDriver: RequestDriverContract = {
+      send: vi.fn().mockResolvedValue(createResponseHandler()),
+    }
+
+    BaseRequest.setRequestDriver(globalDriver)
+
+    class DriverSpecificRequest extends TestRequest {
+      protected override getRequestDriver(): RequestDriverContract {
+        return requestDriver
+      }
+    }
+
+    const request = new DriverSpecificRequest()
+
+    await request.send()
+
+    expect(requestDriver.send).toHaveBeenCalledTimes(1)
+    expect(globalDriver.send).not.toHaveBeenCalled()
+  })
 })

package/tests/service/requests/Enums.test.ts

@@ -9,6 +9,7 @@ describe('Enums', () => {
   it('exposes expected request enums', () => {
     expect(RequestMethodEnum.GET).toBe('GET')
     expect(RequestEvents.LOADING).toBe('loading')
+    expect(RequestEvents.UPLOAD_PROGRESS).toBe('upload-progress')
     expect(RequestConcurrencyMode.REPLACE_LATEST).toBe('replace-latest')
   })
 

package/tests/service/requests/xhr/XMLHttpRequestDriver.test.ts

@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { XMLHttpRequestDriver } from '../../../../src/requests/drivers/xhr/XMLHttpRequestDriver'
+import { XMLHttpRequestResponse } from '../../../../src/requests/drivers/xhr/XMLHttpRequestResponse'
+import { RequestMethodEnum } from '../../../../src/requests/RequestMethod.enum'
+import { ResponseException } from '../../../../src/requests/exceptions/ResponseException'
+import type { BodyContract } from '../../../../src/requests/contracts/BodyContract'
+
+const createBody = (content: string): BodyContract => ({
+  getHeaders: () => ({ 'Content-Type': 'application/json' }),
+  getContent: () => content,
+})
+
+class MockXMLHttpRequestUpload {
+  public onprogress: ((event: ProgressEvent<EventTarget>) => void) | null = null
+}
+
+class MockXMLHttpRequest {
+  public static instances: MockXMLHttpRequest[] = []
+
+  public method?: string
+  public url?: string
+  public async?: boolean
+  public responseType: XMLHttpRequestResponseType = ''
+  public withCredentials = false
+  public status = 200
+  public statusText = 'OK'
+  public response: Blob | string | ArrayBuffer | null = '{"ok":true}'
+  public onload: (() => void) | null = null
+  public onerror: (() => void) | null = null
+  public onabort: (() => void) | null = null
+  public upload = new MockXMLHttpRequestUpload()
+  public headers: Record<string, string> = {}
+  public responseHeaders: Record<string, string> = {}
+  public sentBody: Document | XMLHttpRequestBodyInit | null | undefined = undefined
+  public aborted = false
+
+  public constructor() {
+    MockXMLHttpRequest.instances.push(this)
+  }
+
+  public open(method: string, url: string, async: boolean): void {
+    this.method = method
+    this.url = url
+    this.async = async
+  }
+
+  public setRequestHeader(key: string, value: string): void {
+    this.headers[key] = value
+  }
+
+  public send(body?: Document | XMLHttpRequestBodyInit | null): void {
+    this.sentBody = body
+  }
+
+  public abort(): void {
+    this.aborted = true
+    this.onabort?.()
+  }
+
+  public getAllResponseHeaders(): string {
+    return Object.entries(this.responseHeaders)
+      .map(([key, value]) => `${key}: ${value}`)
+      .join('\r\n')
+  }
+
+  public triggerLoad(): void {
+    this.onload?.()
+  }
+
+  public triggerError(): void {
+    this.onerror?.()
+  }
+
+  public triggerUploadProgress(loaded: number, total: number, lengthComputable: boolean = true): void {
+    this.upload.onprogress?.({
+      loaded,
+      total,
+      lengthComputable,
+    } as ProgressEvent<EventTarget>)
+  }
+}
+
+describe('XMLHttpRequestDriver', () => {
+  const originalXMLHttpRequest = global.XMLHttpRequest
+
+  beforeEach(() => {
+    MockXMLHttpRequest.instances = []
+    global.XMLHttpRequest = MockXMLHttpRequest as unknown as typeof XMLHttpRequest
+  })
+
+  afterEach(() => {
+    global.XMLHttpRequest = originalXMLHttpRequest
+    vi.restoreAllMocks()
+  })
+
+  it('sends requests with merged headers, body, and upload progress callbacks', async () => {
+    const onUploadProgress = vi.fn()
+    const driver = new XMLHttpRequestDriver({ headers: { 'X-Global': 'a' }, corsWithCredentials: true })
+
+    const promise = driver.send(
+      'https://example.com',
+      RequestMethodEnum.POST,
+      { 'X-Req': 'b', 'X-Fn': () => 'c', 'X-Ignore': undefined },
+      createBody('{"name":"test"}'),
+      { onUploadProgress }
+    )
+
+    const request = MockXMLHttpRequest.instances[0]
+    request.status = 201
+    request.responseHeaders = { 'X-Response': 'yes' }
+    request.triggerUploadProgress(5, 10)
+    request.triggerLoad()
+
+    const result = await promise
+
+    expect(result).toBeInstanceOf(XMLHttpRequestResponse)
+    expect(request.method).toBe('POST')
+    expect(request.url).toBe('https://example.com')
+    expect(request.async).toBe(true)
+    expect(request.responseType).toBe('blob')
+    expect(request.withCredentials).toBe(true)
+    expect(request.headers).toEqual({
+      'X-Global': 'a',
+      'X-Req': 'b',
+      'X-Fn': 'c',
+      'Content-Type': 'application/json',
+    })
+    expect(request.sentBody).toBe('{"name":"test"}')
+    expect(onUploadProgress).toHaveBeenCalledWith({
+      loaded: 5,
+      total: 10,
+      lengthComputable: true,
+      progress: 0.5,
+    })
+    await expect(result.json()).resolves.toEqual({ ok: true })
+  })
+
+  it('omits body for GET and HEAD requests', async () => {
+    const driver = new XMLHttpRequestDriver()
+
+    const promise = driver.send('https://example.com', RequestMethodEnum.GET, {}, createBody('data'))
+
+    const request = MockXMLHttpRequest.instances[0]
+    request.triggerLoad()
+
+    await promise
+
+    expect(request.sentBody).toBeUndefined()
+  })
+
+  it('throws ResponseException when the response status is not ok', async () => {
+    const driver = new XMLHttpRequestDriver()
+
+    const promise = driver.send('https://example.com', RequestMethodEnum.GET, {})
+
+    const request = MockXMLHttpRequest.instances[0]
+    request.status = 500
+    request.response = 'fail'
+    request.triggerLoad()
+
+    await expect(promise).rejects.toBeInstanceOf(ResponseException)
+  })
+
+  it('aborts requests when the AbortSignal is triggered', async () => {
+    const controller = new AbortController()
+    const driver = new XMLHttpRequestDriver()
+
+    const promise = driver.send('https://example.com', RequestMethodEnum.POST, {}, createBody('{"name":"test"}'), {
+      abortSignal: controller.signal,
+    })
+
+    const request = MockXMLHttpRequest.instances[0]
+    controller.abort()
+
+    await expect(promise).rejects.toMatchObject({ name: 'AbortError' })
+    expect(request.aborted).toBe(true)
+  })
+})