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

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 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)
+## v4.0.0-beta.10 - 2026-02-28 (beta)
+
+# [4.0.0-beta.10](/compare/v4.0.0-beta.9...v4.0.0-beta.10) (2026-02-28)
+
+
+### Features
+
+* **pagination:** support local row removal without reload 3a66689
 ## v4.0.0-beta.9 - 2026-02-28 (beta)
 
 # [4.0.0-beta.9](/compare/v4.0.0-beta.8...v4.0.0-beta.9) (2026-02-28)

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/pagination/index.md

@@ -38,7 +38,7 @@ If you are using Vue, the library provides `VuePaginationDriverFactory` and `Vue
 - `flush`: clears existing data before applying the next page
 - `replace`: replaces existing data instead of appending (useful for infinite scroll)
 
-`updateRows` is available on all paginators. See [Updating Rows](./updating-rows).
+`updateRows` and `removeRows` are available on all paginators. See [Updating Rows](./updating-rows).
 
 ## Using Laravel Pagination
 

package/docs/services/pagination/updating-rows.md

@@ -34,3 +34,19 @@ const updated = paginator.updateRows(
     (row) => ({ ...row, updatedAt: new Date().toISOString() })
 )
 ```
+
+## Removing Rows
+
+Use `removeRows` to delete items from the current page data without reloading. By default it also decrements `total`
+by the number of removed rows. Set `adjustTotal: false` to skip that behavior.
+
+```typescript
+// Remove a single item
+const removed = paginator.removeRows((row) => row.id === targetId)
+
+// Remove all drafts without adjusting total
+const removedDrafts = paginator.removeRows(
+    (row) => row.status === 'draft',
+    { adjustTotal: false }
+)
+```

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-beta.9",
+  "version": "4.1.0-beta.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/release-tool.json

@@ -20,7 +20,7 @@
       "subdir": "",
       "commit_message": "docs: publish {tag}",
       "add_nojekyll": true,
-      "force_push": false
+      "force_push": true
     }
   }
 }

package/src/pagination/BasePaginator.ts

@@ -55,6 +55,25 @@ export abstract class BasePaginator<ResourceInterface, ViewDriver extends BaseVi
     return updated
   }
 
+  public removeRows(
+    predicate: (row: ResourceInterface, index: number, data: ResourceInterface[]) => boolean,
+    options?: { adjustTotal?: boolean }
+  ): number {
+    const data = this.viewDriver.getData()
+    const next = data.filter((row, index) => !predicate(row, index, data))
+    const removed = data.length - next.length
+
+    if (removed > 0) {
+      this.viewDriver.setData(next)
+
+      if (options?.adjustTotal ?? true) {
+        this.viewDriver.setTotal(Math.max(0, this.viewDriver.getTotal() - removed))
+      }
+    }
+
+    return removed
+  }
+
   public getTotal(): number {
     return this.viewDriver.getTotal()
   }

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'
@@ -113,7 +115,8 @@ export abstract class BaseRequest<
   }
 
   public buildUrl(): URL {
-    const url = this.params !== undefined && Object.keys(this.params).length === 0 ? this.url() : this.url() + '?' + qs.stringify(this.params)
+    const hasParams = this.params !== undefined && Object.keys(this.params).length > 0
+    const url = hasParams ? this.url() + '?' + qs.stringify(this.params) : this.url()
 
     return new URL(url, this.baseUrl() ?? BaseRequest.defaultBaseUrl)
   }
@@ -163,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(),
@@ -173,7 +177,7 @@ export abstract class BaseRequest<
           ...this.requestHeaders()
         },
         requestBody,
-        this.getConfig()
+        requestConfig
       )
       .then(async (responseHandler: ResponseHandlerContract) => {
         if (useLatest && !this.isLatestSequence(concurrencyKey, sequence)) {
@@ -274,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
+  }
+}