@blueprint-ts/core 4.0.0-beta.7 → 4.0.0-beta.9

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 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)
+## v4.0.0-beta.8 - 2026-02-28 (beta)
+
+# [4.0.0-beta.8](/compare/v4.0.0-beta.7...v4.0.0-beta.8) (2026-02-28)
+
+
+### Features
+
+* **requests:** add concurrency policy, stale-response handling, and docs 5feb49d
 ## v4.0.0-beta.7 - 2026-02-27 (beta)
 
 # [4.0.0-beta.7](/compare/v4.0.0-beta.6...v4.0.0-beta.7) (2026-02-27)

package/docs/.vitepress/config.ts

@@ -25,6 +25,7 @@ export default defineConfig({
               { text: 'Responses', link: '/services/requests/responses' },
               { text: 'Request Bodies', link: '/services/requests/request-bodies' },
               { text: 'Headers', link: '/services/requests/headers' },
+              { text: 'Concurrency', link: '/services/requests/concurrency' },
               { text: 'Aborting Requests', link: '/services/requests/abort-requests' },
               { text: 'Events', link: '/services/requests/events' },
               { text: 'Bulk Requests', link: '/services/requests/bulk-requests' },

package/docs/services/pagination/infinite-scroller.md

@@ -1,6 +1,7 @@
 # Infinite Scroll
 
-Use `InfiniteScroller` when you want to append pages to the existing list:
+Use `InfiniteScroller` when you want to append pages to the existing list. It extends `PageAwarePaginator`, so all
+page-aware features and helpers are available.
 
 ```typescript
 import { InfiniteScroller } from '@blueprint-ts/core/pagination'
@@ -11,8 +12,8 @@ await scroller.load()
 await scroller.toNextPage()
 ```
 
-`InfiniteScroller` uses the same view driver factory as `PageAwarePaginator`. You can pass `{ flush: true }` or
-`{ replace: true }` to `load()` or `setPageNumber()` to control how data is merged.
+You can pass `{ flush: true }` to clear existing data before loading a page. In addition, `InfiniteScroller` supports
+`{ replace: true }` to replace the current list instead of appending.
 
 ## Scroll Detection Helper
 

package/docs/services/pagination/page-aware.md

@@ -40,6 +40,11 @@ await paginator.setPageSize(25).load()
 Page navigation helpers (`toNextPage`, `toPreviousPage`, `toFirstPage`, `toLastPage`) update the page number and load
 the new page in one call.
 
+## Concurrency
+
+If the underlying request uses concurrency mode `LATEST` or `REPLACE_LATEST`, stale responses are ignored. In that case,
+`load()` resolves with the current page data without updating the view, so older responses cannot overwrite newer ones.
+
 
 ## Updating Rows
 

package/docs/services/requests/abort-requests.md

@@ -2,6 +2,8 @@
 
 Requests can be aborted by passing an `AbortSignal` to the request.
 
+If you want the request library to abort previous in-flight requests automatically, see [Concurrency](/services/requests/concurrency).
+
 ## Using AbortController
 
 ```typescript
@@ -16,6 +18,8 @@ const promise = request.send()
 controller.abort()
 ```
 
+Note: If you enable request concurrency with `REPLACE` or `REPLACE_LATEST`, the request will assign its own abort signal and override this one. See [Concurrency](/services/requests/concurrency) for details.
+
 ## Bulk Requests
 
 `BulkRequestSender` internally manages an `AbortController` for its requests. You can abort the entire bulk operation:

package/docs/services/requests/concurrency.md

@@ -0,0 +1,58 @@
+# Request Concurrency
+
+Concurrent requests can cause two common problems:
+
+1. A slower, older response overwrites newer data ("stale results").
+2. Loading state flickers because earlier requests finish after later ones.
+
+To solve this, `BaseRequest` supports an optional concurrency policy that can abort older requests and/or ignore stale responses.
+
+## Basic Usage
+
+```typescript
+import { RequestConcurrencyMode } from '@blueprint-ts/core/requests'
+
+const request = new ExpenseIndexRequest()
+
+request.setConcurrency({
+  mode: RequestConcurrencyMode.REPLACE_LATEST,
+  key: 'expense-search'
+})
+
+request.send()
+```
+
+## Modes
+
+- `ALLOW` (default): no aborts and no stale-response filtering.
+- `REPLACE`: aborts any in-flight request with the same key.
+- `LATEST`: ignores stale responses; only the most recent response is applied.
+- `REPLACE_LATEST`: aborts older requests and ignores stale responses.
+
+## Abort Signals
+
+When using `REPLACE` or `REPLACE_LATEST`, the request creates and assigns its own `AbortController` for the concurrency key. This replaces any previously configured abort signal on that request instance. If you need to preserve a custom abort signal, apply it per request without using replace modes.
+
+## Keys
+
+The `key` lets you coordinate concurrency across multiple request instances. If you omit it, the request instance ID is used.
+
+Use a shared key when multiple instances represent the same logical request stream (for example, a search box that creates new request objects).
+
+## Stale Responses
+
+When `LATEST` or `REPLACE_LATEST` is used, stale responses raise a `StaleResponseException` so the caller can ignore them safely.
+
+If you don't want to handle it explicitly, catch and ignore it:
+
+```typescript
+import { StaleResponseException } from '@blueprint-ts/core/requests'
+
+request.send().catch((error) => {
+  if (error instanceof StaleResponseException) {
+    return
+  }
+
+  throw error
+})
+```

package/docs/services/requests/error-handling.md

@@ -13,6 +13,22 @@ When a request fails, `BaseRequest.send()` routes error responses through the re
 
 ## Catching Errors
 
+When using request concurrency (see [Concurrency](/services/requests/concurrency)), `BaseRequest` can throw a `StaleResponseException` for outdated responses. These should usually be ignored:
+
+```typescript
+import { StaleResponseException } from '@blueprint-ts/core/requests'
+
+try {
+    await request.send()
+} catch (error: unknown) {
+    if (error instanceof StaleResponseException) {
+        return
+    }
+
+    throw error
+}
+```
+
 - `400` -> `BadRequestException`
 - `401` -> `UnauthorizedException`
 - `403` -> `ForbiddenException`

package/docs/upgrading/v3-to-v4.md

@@ -170,6 +170,22 @@ export class MyConfirmOptions implements ConfirmDialogOptions {
 }
 ```
 
+## BaseRequestContract Requires `setConcurrency`
+
+`BaseRequestContract` now includes `setConcurrency(...)` so requests can opt into concurrency handling (e.g., latest-wins or replace-latest).
+If you implemented `BaseRequestContract` directly (instead of extending `BaseRequest`), TypeScript will now require this method.
+
+### How to Fix
+
+Add the method to your custom request implementation:
+
+```typescript
+setConcurrency(options?: RequestConcurrencyOptions): this {
+  // no-op by default; use options if your implementation needs them
+  return this
+}
+```
+
 ## Laravel Packages Moved
 
 Laravel modules moved from `@blueprint-ts/core/service/laravel/*` to `@blueprint-ts/core/laravel/*`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0-beta.9",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -74,8 +74,8 @@
     "vue-router": "^4.3.2"
   },
   "dependencies": {
-    "lodash-es": "^4.17.21",
-    "qs": "^6.12.0",
-    "uuid": "^11.1.0"
+    "lodash-es": "^4.17.23",
+    "qs": "^6.15.0",
+    "uuid": "^13.0.0"
   }
 }

package/src/pagination/BasePaginator.ts

@@ -68,4 +68,8 @@ export abstract class BasePaginator<ResourceInterface, ViewDriver extends BaseVi
     this.viewDriver.setTotal(dto.getTotal())
     this.initialized = true
   }
+
+  protected handleStaleResponse(): PaginationDataDto<ResourceInterface[]> {
+    return new PaginationDataDto<ResourceInterface[]>(this.viewDriver.getData(), this.viewDriver.getTotal())
+  }
 }

package/src/pagination/PageAwarePaginator.ts

@@ -4,6 +4,7 @@ import { type ViewDriverFactoryContract } from './contracts/ViewDriverFactoryCon
 import { type PaginatorLoadDataOptions } from './contracts/PaginatorLoadDataOptions'
 import { type PaginationDataDriverContract } from './contracts/PaginationDataDriverContract'
 import { BasePaginator } from './BasePaginator'
+import { StaleResponseException } from '../requests/exceptions/StaleResponseException'
 
 export interface PageAwarePaginatorOptions {
   viewDriverFactory?: ViewDriverFactoryContract
@@ -113,10 +114,19 @@ export class PageAwarePaginator<ResourceInterface> extends BasePaginator<Resourc
   }
 
   protected loadData(pageNumber: number, pageSize: number, options?: PaginatorLoadDataOptions): Promise<PaginationDataDto<ResourceInterface[]>> {
-    return this.dataDriver.get(pageNumber, pageSize).then((value: PaginationDataDto<ResourceInterface[]>) => {
-      this.passDataToViewDriver(value, options)
-
-      return value
-    })
+    return this.dataDriver
+      .get(pageNumber, pageSize)
+      .then((value: PaginationDataDto<ResourceInterface[]>) => {
+        this.passDataToViewDriver(value, options)
+
+        return value
+      })
+      .catch((error) => {
+        if (error instanceof StaleResponseException) {
+          return this.handleStaleResponse()
+        }
+
+        throw error
+      })
   }
 }

package/src/requests/BaseRequest.ts

@@ -4,6 +4,7 @@ import { RequestEvents } from './RequestEvents.enum'
 import { RequestMethodEnum } from './RequestMethod.enum'
 import { BaseResponse } from './responses/BaseResponse'
 import { ResponseException } from './exceptions/ResponseException'
+import { StaleResponseException } from './exceptions/StaleResponseException'
 import { type DriverConfigContract } from './contracts/DriverConfigContract'
 import { type BodyFactoryContract } from './contracts/BodyFactoryContract'
 import { type RequestLoaderContract } from './contracts/RequestLoaderContract'
@@ -13,6 +14,8 @@ import { type BaseRequestContract, type EventHandlerCallback } from './contracts
 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 { RequestConcurrencyMode } from './RequestConcurrencyMode.enum'
 import { mergeDeep } from '../support/helpers'
 import { v4 as uuidv4 } from 'uuid'
 
@@ -29,6 +32,7 @@ export abstract class BaseRequest<
   protected requestBody: RequestBodyInterface | undefined = undefined
   protected requestLoader: RequestLoaderContract<RequestLoaderLoadingType> | undefined = undefined
   protected abortSignal: AbortSignal | undefined = undefined
+  protected concurrencyOptions: RequestConcurrencyOptions | undefined = undefined
   /* @ts-expect-error Ignore generics */
   protected events: { [key in RequestEvents]?: EventHandlerCallback[] } = {}
 
@@ -36,6 +40,9 @@ export abstract class BaseRequest<
 
   protected static requestDriver: RequestDriverContract
   protected static requestLoaderFactory: RequestLoaderFactoryContract<unknown>
+  protected static concurrencySequenceByKey: Map<string, number> = new Map()
+  protected static concurrencyAbortControllerByKey: Map<string, AbortController> = new Map()
+  protected static concurrencyInFlightByKey: Map<string, number> = new Map()
 
   public constructor() {
     if (BaseRequest.requestLoaderFactory !== undefined) {
@@ -61,6 +68,12 @@ export abstract class BaseRequest<
     return this
   }
 
+  public setConcurrency(options?: RequestConcurrencyOptions): this {
+    this.concurrencyOptions = options
+
+    return this
+  }
+
   public getRequestId(): string {
     return this.requestId
   }
@@ -124,6 +137,25 @@ export abstract class BaseRequest<
   }
 
   public async send(): Promise<ResponseClass> {
+    const concurrencyMode: RequestConcurrencyMode = this.concurrencyOptions?.mode ?? RequestConcurrencyMode.ALLOW
+    const concurrencyKey = this.concurrencyOptions?.key ?? this.requestId
+    const useReplace = concurrencyMode === RequestConcurrencyMode.REPLACE || concurrencyMode === RequestConcurrencyMode.REPLACE_LATEST
+    const useLatest = concurrencyMode === RequestConcurrencyMode.LATEST || concurrencyMode === RequestConcurrencyMode.REPLACE_LATEST
+    const sequence = this.bumpConcurrencySequence(concurrencyKey)
+    this.incrementConcurrencyInFlight(concurrencyKey)
+
+    if (useReplace) {
+      const previousController = BaseRequest.concurrencyAbortControllerByKey.get(concurrencyKey)
+
+      if (previousController) {
+        previousController.abort()
+      }
+
+      const controller = new AbortController()
+      BaseRequest.concurrencyAbortControllerByKey.set(concurrencyKey, controller)
+      this.setAbortSignal(controller.signal)
+    }
+
     this.dispatch<boolean>(RequestEvents.LOADING, true)
 
     this.requestLoader?.setLoading(true)
@@ -144,11 +176,23 @@ export abstract class BaseRequest<
         this.getConfig()
       )
       .then(async (responseHandler: ResponseHandlerContract) => {
+        if (useLatest && !this.isLatestSequence(concurrencyKey, sequence)) {
+          throw new StaleResponseException()
+        }
+
         await responseSkeleton.setResponse(responseHandler)
 
         return responseSkeleton
       })
       .catch(async (error) => {
+        if (useLatest && !this.isLatestSequence(concurrencyKey, sequence)) {
+          throw new StaleResponseException('Stale response ignored', error)
+        }
+
+        if (error instanceof StaleResponseException) {
+          throw error
+        }
+
         if (error instanceof ResponseException) {
           const handler = new ErrorHandler<ResponseErrorBody>(error.getResponse())
 
@@ -160,8 +204,14 @@ export abstract class BaseRequest<
         throw error
       })
       .finally(() => {
-        this.dispatch<boolean>(RequestEvents.LOADING, false)
-        this.requestLoader?.setLoading(false)
+        const isStale = useLatest && !this.isLatestSequence(concurrencyKey, sequence)
+
+        if (!isStale) {
+          this.dispatch<boolean>(RequestEvents.LOADING, false)
+          this.requestLoader?.setLoading(false)
+        }
+
+        this.decrementConcurrencyInFlight(concurrencyKey)
       })
   }
 
@@ -185,6 +235,41 @@ export abstract class BaseRequest<
     return this
   }
 
+  protected bumpConcurrencySequence(key: string): number {
+    const next = (BaseRequest.concurrencySequenceByKey.get(key) ?? 0) + 1
+    BaseRequest.concurrencySequenceByKey.set(key, next)
+
+    return next
+  }
+
+  protected isLatestSequence(key: string, sequence: number): boolean {
+    return (BaseRequest.concurrencySequenceByKey.get(key) ?? 0) === sequence
+  }
+
+  protected incrementConcurrencyInFlight(key: string): void {
+    const next = (BaseRequest.concurrencyInFlightByKey.get(key) ?? 0) + 1
+    BaseRequest.concurrencyInFlightByKey.set(key, next)
+  }
+
+  protected decrementConcurrencyInFlight(key: string): void {
+    const current = BaseRequest.concurrencyInFlightByKey.get(key)
+
+    if (current === undefined) {
+      return
+    }
+
+    const next = current - 1
+
+    if (next <= 0) {
+      BaseRequest.concurrencyInFlightByKey.delete(key)
+      BaseRequest.concurrencySequenceByKey.delete(key)
+      BaseRequest.concurrencyAbortControllerByKey.delete(key)
+      return
+    }
+
+    BaseRequest.concurrencyInFlightByKey.set(key, next)
+  }
+
   protected baseUrl(): undefined {
     return undefined
   }

package/src/requests/RequestConcurrencyMode.enum.ts

@@ -0,0 +1,6 @@
+export enum RequestConcurrencyMode {
+  ALLOW = 'allow',
+  REPLACE = 'replace',
+  LATEST = 'latest',
+  REPLACE_LATEST = 'replace-latest'
+}

package/src/requests/contracts/BaseRequestContract.ts

@@ -2,6 +2,7 @@ import { RequestMethodEnum } from '../RequestMethod.enum'
 import { RequestEvents } from '../RequestEvents.enum'
 import { type BodyFactoryContract } from './BodyFactoryContract'
 import { type HeadersContract } from './HeadersContract'
+import { type RequestConcurrencyOptions } from '../types/RequestConcurrencyOptions'
 
 export type EventHandlerCallback<T> = (value: T) => void
 
@@ -33,4 +34,6 @@ export interface BaseRequestContract<RequestLoaderLoadingType, RequestBodyInterf
   getResponse(): ResponseClass
 
   setAbortSignal(signal: AbortSignal): this
+
+  setConcurrency(options?: RequestConcurrencyOptions): this
 }

package/src/requests/exceptions/StaleResponseException.ts

@@ -0,0 +1,13 @@
+export class StaleResponseException extends Error {
+  public readonly cause: unknown
+
+  public constructor(message: string = 'Stale response ignored', cause?: unknown) {
+    super(message)
+    this.name = 'StaleResponseException'
+    this.cause = cause
+  }
+
+  public getCause(): unknown {
+    return this.cause
+  }
+}

package/src/requests/index.ts

@@ -8,6 +8,7 @@ import { ErrorHandler } from './ErrorHandler'
 import { RequestErrorRouter } from './RequestErrorRouter'
 import { RequestEvents } from './RequestEvents.enum'
 import { RequestMethodEnum } from './RequestMethod.enum'
+import { RequestConcurrencyMode } from './RequestConcurrencyMode.enum'
 import { JsonBodyFactory } from './factories/JsonBodyFactory'
 import { FormDataFactory } from './factories/FormDataFactory'
 import { type BodyContract } from './contracts/BodyContract'
@@ -19,7 +20,9 @@ import { type BodyFactoryContract } from './contracts/BodyFactoryContract'
 import { type ResponseHandlerContract } from './drivers/contracts/ResponseHandlerContract'
 import { type BaseRequestContract } from './contracts/BaseRequestContract'
 import { ResponseException } from './exceptions/ResponseException'
+import { StaleResponseException } from './exceptions/StaleResponseException'
 import { type HeadersContract } from './contracts/HeadersContract'
+import { type RequestConcurrencyOptions } from './types/RequestConcurrencyOptions'
 
 export {
   FetchDriver,
@@ -32,7 +35,9 @@ export {
   RequestErrorRouter,
   RequestEvents,
   RequestMethodEnum,
+  RequestConcurrencyMode,
   ResponseException,
+  StaleResponseException,
   JsonBodyFactory,
   FormDataFactory
 }
@@ -46,5 +51,6 @@ export type {
   BodyFactoryContract,
   ResponseHandlerContract,
   BaseRequestContract,
-  HeadersContract
+  HeadersContract,
+  RequestConcurrencyOptions
 }

package/src/requests/types/RequestConcurrencyOptions.ts

@@ -0,0 +1,6 @@
+import { RequestConcurrencyMode } from '../RequestConcurrencyMode.enum'
+
+export type RequestConcurrencyOptions = {
+  mode?: RequestConcurrencyMode
+  key?: string
+}

package/src/vue/forms/PropertyAwareArray.ts

@@ -25,7 +25,6 @@ export type PropertyAware<T> = {
 export class PropertyAwareArray<T = unknown> extends Array<T> {
   // Private brand to prevent plain arrays from being assignable to PropertyAwareArray.
   // This keeps conditional types from treating normal arrays as property-aware.
-  // eslint-disable-next-line @typescript-eslint/no-unused-private-class-members
   private readonly __propertyAwareArrayBrand!: void
   /**
    * Creates a new PropertyAwareArray instance