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

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 4.1.0-beta.2 - 2026-03-25 (beta)
+
+# [4.1.0-beta.2](/compare/4.1.0-beta.1...4.1.0-beta.2) (2026-03-25)
+
+
+### Bug Fixes
+
+* Tighten response header typing f767572
+
+
+### Features
+
+* Support Blob and ArrayBuffer bodies a265df3
+## 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,168 @@
+# File Uploads
+
+Use `FormDataFactory` for multipart uploads with fields, and use `BinaryBodyFactory` when the endpoint expects a raw
+binary body such as a chunk `PUT`. Use `XMLHttpRequestDriver` when the consuming application needs upload progress for a
+progress bar.
+
+Choose the body factory based on the wire format your endpoint expects:
+
+- Use `FormDataFactory` when the request includes normal fields plus one or more files.
+- Use `BinaryBodyFactory` when the request body itself is the file or chunk.
+- Use `FetchDriver` if you just need to send the upload.
+- Use `XMLHttpRequestDriver` if you also need upload progress events.
+
+## 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()
+```
+
+## Raw Chunk Uploads
+
+```typescript
+import {
+    BaseRequest,
+    BinaryBodyFactory,
+    JsonResponse,
+    RequestMethodEnum,
+    XMLHttpRequestDriver
+} from '@blueprint-ts/core/requests'
+
+interface UploadPartResponse {
+    etag: string
+}
+
+class UploadPartRequest extends BaseRequest<
+        boolean,
+        { message: string },
+        UploadPartResponse,
+        JsonResponse<UploadPartResponse>,
+        Uint8Array
+> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.PUT
+    }
+
+    public url(): string {
+        return '/api/v1/uploads/part'
+    }
+
+    public getResponse(): JsonResponse<UploadPartResponse> {
+        return new JsonResponse<UploadPartResponse>()
+    }
+
+    public override getRequestBodyFactory() {
+        return new BinaryBodyFactory<Uint8Array>('application/octet-stream')
+    }
+
+    public override requestHeaders() {
+        return {
+            'X-Part-Number': '1'
+        }
+    }
+
+    protected override getRequestDriver() {
+        return new XMLHttpRequestDriver()
+    }
+}
+```
+
+In this example, `setBody(...)` can receive a `Blob`, `ArrayBuffer`, `Uint8Array`, or another typed-array/data-view
+payload supported by `BinaryBodyFactory`.
+
+## 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.
+- `BinaryBodyFactory` only sets `Content-Type` automatically when the body is a `Blob` with a non-empty `type`.
+  For `ArrayBuffer` and typed-array uploads, pass the expected content type explicitly.
+- `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,36 @@ public override getRequestBodyFactory() {
 }
 ```
 
+If you want to show upload progress for multipart file uploads, see [File Uploads](/services/requests/file-uploads).
+
+## Raw Binary Bodies
+
+Use `BinaryBodyFactory` when the request body should be sent as raw binary instead of multipart form data. This is a
+better fit for chunk uploads, binary artifact pushes, and endpoints that expect the request body as-is:
+
+```typescript
+import { BinaryBodyFactory } from '@blueprint-ts/core/requests'
+
+public override getRequestBodyFactory() {
+    return new BinaryBodyFactory<ArrayBuffer>('application/octet-stream')
+}
+```
+
+`BinaryBodyFactory` supports:
+
+- `Blob`
+- `ArrayBuffer`
+- typed-array and view values such as `Uint8Array` or `DataView`
+
+`Content-Type` resolution works like this:
+
+- If you pass a content type to `BinaryBodyFactory`, Blueprint sends that `Content-Type` header.
+- Otherwise, if the body is a `Blob` with a non-empty `type`, Blueprint uses `Blob.type`.
+- Otherwise, Blueprint does not add a `Content-Type` header for you.
+
+`BinaryBodyFactory` works with both `FetchDriver` and `XMLHttpRequestDriver`. Choose `XMLHttpRequestDriver` only when
+the consuming application needs upload progress events.
+
 ## 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.2",
   "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/bodies/BinaryBody.ts

@@ -0,0 +1,31 @@
+import { type BodyContent, type BodyContract } from '../contracts/BodyContract'
+import { type HeadersContract } from '../contracts/HeadersContract'
+
+export class BinaryBody<RequestBody extends Exclude<BodyContent, string | FormData>> implements BodyContract {
+  public constructor(
+    protected data: RequestBody,
+    protected contentType?: string
+  ) {}
+
+  public getHeaders(): HeadersContract {
+    const contentType = this.resolveContentType()
+
+    return contentType === undefined ? {} : { 'Content-Type': contentType }
+  }
+
+  public getContent(): RequestBody {
+    return this.data
+  }
+
+  protected resolveContentType(): string | undefined {
+    if (this.contentType !== undefined) {
+      return this.contentType
+    }
+
+    if (typeof Blob !== 'undefined' && this.data instanceof Blob && this.data.type !== '') {
+      return this.data.type
+    }
+
+    return undefined
+  }
+}

package/src/requests/contracts/BodyContract.ts

@@ -1,7 +1,9 @@
 import { type HeadersContract } from './HeadersContract'
 
+export type BodyContent = string | FormData | Blob | ArrayBuffer | ArrayBufferView<ArrayBuffer>
+
 export interface BodyContract {
-  getContent(): string | FormData
+  getContent(): BodyContent
 
   getHeaders(): HeadersContract
 }

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/contracts/HeadersContract.ts

@@ -3,3 +3,7 @@ export type HeaderValue = string | (() => string)
 export interface HeadersContract {
   [key: string]: HeaderValue
 }
+
+export interface ResolvedHeadersContract {
+  [key: string]: string
+}

package/src/requests/drivers/contracts/ResponseHandlerContract.ts

@@ -1,8 +1,8 @@
-import { type HeadersContract } from '../../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../../contracts/HeadersContract'
 
 export interface ResponseHandlerContract {
   getStatusCode(): number | undefined
-  getHeaders(): HeadersContract
+  getHeaders(): ResolvedHeadersContract
   getRawResponse(): Response
   json<ResponseBodyInterface>(): Promise<ResponseBodyInterface>
   text(): Promise<string>

package/src/requests/drivers/fetch/FetchDriver.ts

@@ -2,7 +2,7 @@ import { ResponseException } from '../../exceptions/ResponseException'
 import { FetchResponse } from './FetchResponse'
 import { RequestMethodEnum } from '../../RequestMethod.enum'
 import { type HeadersContract, type HeaderValue } from '../../contracts/HeadersContract'
-import { type BodyContract } from '../../contracts/BodyContract'
+import { type BodyContent, type BodyContract } from '../../contracts/BodyContract'
 import { type RequestDriverContract } from '../../contracts/RequestDriverContract'
 import { type DriverConfigContract } from '../../contracts/DriverConfigContract'
 import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
@@ -17,7 +17,7 @@ interface FetchDriverConfig {
   headers: HeadersContract
   credentials?: FetchDriverCredentialConfigEnum | undefined
   signal?: AbortSignal | undefined
-  body?: string | FormData | Blob | ArrayBuffer | ArrayBufferView | URLSearchParams | undefined
+  body?: BodyContent | URLSearchParams | undefined
 }
 
 export class FetchDriver implements RequestDriverContract {

package/src/requests/drivers/fetch/FetchResponse.ts

@@ -1,4 +1,4 @@
-import { type HeadersContract } from '../../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../../contracts/HeadersContract'
 import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
 
 export class FetchResponse implements ResponseHandlerContract {
@@ -8,7 +8,7 @@ export class FetchResponse implements ResponseHandlerContract {
     return this.response.status
   }
 
-  public getHeaders(): HeadersContract {
+  public getHeaders(): ResolvedHeadersContract {
     return Object.fromEntries(this.response.headers)
   }
 

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 ResolvedHeadersContract } from '../../contracts/HeadersContract'
+import { type ResponseHandlerContract } from '../contracts/ResponseHandlerContract'
+
+export class XMLHttpRequestResponse implements ResponseHandlerContract {
+  protected response: Response
+  protected headers: ResolvedHeadersContract
+
+  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(): ResolvedHeadersContract {
+    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): ResolvedHeadersContract {
+    const headers: ResolvedHeadersContract = {}
+    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/factories/BinaryBodyFactory.ts

@@ -0,0 +1,13 @@
+import { BinaryBody } from '../bodies/BinaryBody'
+import { type BodyFactoryContract } from '../contracts/BodyFactoryContract'
+import { type BodyContent, type BodyContract } from '../contracts/BodyContract'
+
+export type BinaryBodyContent = Exclude<BodyContent, string | FormData>
+
+export class BinaryBodyFactory<RequestBodyInterface extends BinaryBodyContent> implements BodyFactoryContract<RequestBodyInterface> {
+  public constructor(protected contentType?: string) {}
+
+  public make(body: RequestBodyInterface): BodyContract {
+    return new BinaryBody<RequestBodyInterface>(body, this.contentType)
+  }
+}

package/src/requests/index.ts

@@ -9,9 +9,11 @@ import { RequestErrorRouter } from './RequestErrorRouter'
 import { RequestEvents } from './RequestEvents.enum'
 import { RequestMethodEnum } from './RequestMethod.enum'
 import { RequestConcurrencyMode } from './RequestConcurrencyMode.enum'
+import { BinaryBody } from './bodies/BinaryBody'
 import { JsonBodyFactory } from './factories/JsonBodyFactory'
+import { BinaryBodyFactory, type BinaryBodyContent } from './factories/BinaryBodyFactory'
 import { FormDataFactory } from './factories/FormDataFactory'
-import { type BodyContract } from './contracts/BodyContract'
+import { type BodyContent, type BodyContract } from './contracts/BodyContract'
 import { type RequestLoaderContract } from './contracts/RequestLoaderContract'
 import { type RequestDriverContract } from './contracts/RequestDriverContract'
 import { type RequestLoaderFactoryContract } from './contracts/RequestLoaderFactoryContract'
@@ -21,8 +23,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, type ResolvedHeadersContract } from './contracts/HeadersContract'
 import { type RequestConcurrencyOptions } from './types/RequestConcurrencyOptions'
+import { type RequestUploadProgress } from './types/RequestUploadProgress'
+import { XMLHttpRequestDriver } from './drivers/xhr/XMLHttpRequestDriver'
 
 export {
   FetchDriver,
@@ -38,11 +42,16 @@ export {
   RequestConcurrencyMode,
   ResponseException,
   StaleResponseException,
+  BinaryBody,
   JsonBodyFactory,
-  FormDataFactory
+  BinaryBodyFactory,
+  FormDataFactory,
+  XMLHttpRequestDriver
 }
 
 export type {
+  BodyContent,
+  BinaryBodyContent,
   RequestDriverContract,
   RequestLoaderContract,
   BodyContract,
@@ -51,6 +60,9 @@ export type {
   BodyFactoryContract,
   ResponseHandlerContract,
   BaseRequestContract,
+  HeaderValue,
   HeadersContract,
-  RequestConcurrencyOptions
+  ResolvedHeadersContract,
+  RequestConcurrencyOptions,
+  RequestUploadProgress
 }

package/src/requests/responses/BaseResponse.ts

@@ -1,5 +1,5 @@
 import { type ResponseHandlerContract } from '../drivers/contracts/ResponseHandlerContract'
-import { type HeadersContract } from '../contracts/HeadersContract'
+import { type ResolvedHeadersContract } from '../contracts/HeadersContract'
 import { type ResponseContract } from '../contracts/ResponseContract'
 
 export abstract class BaseResponse<ResponseInterface> implements ResponseContract<ResponseInterface> {
@@ -27,7 +27,7 @@ export abstract class BaseResponse<ResponseInterface> implements ResponseContrac
     return this.response?.getStatusCode()
   }
 
-  public getHeaders(): HeadersContract | undefined {
+  public getHeaders(): ResolvedHeadersContract | undefined {
     return this.response?.getHeaders()
   }
 

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/BodiesAndFactories.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from 'vitest'
+import { BinaryBody } from '../../../src/requests/bodies/BinaryBody'
 import { JsonBody } from '../../../src/requests/bodies/JsonBody'
+import { BinaryBodyFactory } from '../../../src/requests/factories/BinaryBodyFactory'
 import { JsonBodyFactory } from '../../../src/requests/factories/JsonBodyFactory'
 import { FormDataFactory } from '../../../src/requests/factories/FormDataFactory'
 import { FormDataBody } from '../../../src/requests/bodies/FormDataBody'
@@ -19,6 +21,28 @@ describe('Request bodies and factories', () => {
     expect(body).toBeInstanceOf(JsonBody)
   })
 
+  it('BinaryBody returns explicit content type and binary content', () => {
+    const body = new BinaryBody(new Uint8Array([1, 2, 3]), 'application/octet-stream')
+
+    expect(body.getHeaders()).toEqual({ 'Content-Type': 'application/octet-stream' })
+    expect(body.getContent()).toEqual(new Uint8Array([1, 2, 3]))
+  })
+
+  it('BinaryBody uses Blob mime type when no explicit content type is given', () => {
+    const blob = new Blob(['hello'], { type: 'application/custom-binary' })
+    const body = new BinaryBody(blob)
+
+    expect(body.getHeaders()).toEqual({ 'Content-Type': 'application/custom-binary' })
+    expect(body.getContent()).toBe(blob)
+  })
+
+  it('BinaryBodyFactory returns BinaryBody', () => {
+    const factory = new BinaryBodyFactory<Uint8Array>('application/octet-stream')
+    const body = factory.make(new Uint8Array([4, 5, 6]))
+
+    expect(body).toBeInstanceOf(BinaryBody)
+  })
+
   it('FormDataFactory returns FormDataBody', () => {
     const factory = new FormDataFactory<{ name: string }>()
     const body = factory.make({ name: 'alice' })

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/fetch/FetchDriver.test.ts

@@ -3,10 +3,10 @@ import { FetchDriver } from '../../../../src/requests/drivers/fetch/FetchDriver'
 import { FetchResponse } from '../../../../src/requests/drivers/fetch/FetchResponse'
 import { RequestMethodEnum } from '../../../../src/requests/RequestMethod.enum'
 import { ResponseException } from '../../../../src/requests/exceptions/ResponseException'
-import type { BodyContract } from '../../../../src/requests/contracts/BodyContract'
+import type { BodyContent, BodyContract } from '../../../../src/requests/contracts/BodyContract'
 
-const createBody = (content: string): BodyContract => ({
-  getHeaders: () => ({ 'Content-Type': 'application/json' }),
+const createBody = (content: BodyContent, headers: Record<string, string> = { 'Content-Type': 'application/json' }): BodyContract => ({
+  getHeaders: () => headers,
   getContent: () => content,
 })
 
@@ -65,6 +65,24 @@ describe('FetchDriver', () => {
     expect(config.body).toBeUndefined()
   })
 
+  it('passes Blob bodies through to fetch unchanged', async () => {
+    const response = new Response('ok', { status: 200 })
+    ;(global.fetch as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(response)
+
+    const blob = new Blob(['chunk'], { type: 'application/octet-stream' })
+    const driver = new FetchDriver()
+
+    await driver.send(
+      'https://example.com',
+      RequestMethodEnum.PUT,
+      {},
+      createBody(blob, { 'Content-Type': 'application/octet-stream' })
+    )
+
+    const [, config] = (global.fetch as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(config.body).toBe(blob)
+  })
+
   it('throws ResponseException when response is not ok', async () => {
     const response = new Response('fail', { status: 500 })
     ;(global.fetch as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(response)

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

@@ -0,0 +1,197 @@
+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 { BodyContent, BodyContract } from '../../../../src/requests/contracts/BodyContract'
+
+const createBody = (content: BodyContent, headers: Record<string, string> = { 'Content-Type': 'application/json' }): BodyContract => ({
+  getHeaders: () => headers,
+  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('passes typed array bodies through to xhr unchanged', async () => {
+    const driver = new XMLHttpRequestDriver()
+    const chunk = new Uint8Array([1, 2, 3, 4])
+
+    const promise = driver.send(
+      'https://example.com',
+      RequestMethodEnum.PUT,
+      {},
+      createBody(chunk, { 'Content-Type': 'application/octet-stream' })
+    )
+
+    const request = MockXMLHttpRequest.instances[0]
+    request.triggerLoad()
+
+    await promise
+
+    expect(request.sentBody).toBe(chunk)
+  })
+
+  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)
+  })
+})