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

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

@@ -1,52 +0,0 @@
-# Updating Rows
-
-All paginators (including `InfiniteScroller`) inherit `updateRows` from `BasePaginator`. It lets you update items in the
-current page data without reloading.
-
-## Usage
-
-`updateRows` accepts:
-
-- a predicate to select rows
-- an updater to mutate or replace them
-
-```typescript
-// Mark a single item as selected
-paginator.updateRows(
-    (row) => row.id === targetId,
-    (row) => {
-        row.selected = true
-    }
-)
-
-// Replace matching items with new objects
-paginator.updateRows(
-    (row) => row.status === 'draft',
-    (row) => ({ ...row, status: 'published' })
-)
-```
-
-It returns the number of rows updated:
-
-```typescript
-const updated = paginator.updateRows(
-    (row) => row.id === targetId,
-    (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/persistence/index.md

@@ -1,46 +0,0 @@
-# Persistence
-
-This service provides simple persistence drivers that implement a common `PersistenceDriver` interface. It is used by `BaseForm`, but can also be used directly.
-
-## Available Drivers
-
-- `NonPersistentDriver` — no persistence (default for `BaseForm`)
-- `SessionStorageDriver` — uses `sessionStorage`
-- `LocalStorageDriver` — uses `localStorage`
-
-All drivers are exported from `@blueprint-ts/core/persistenceDrivers`.
-
-## Using A Driver
-
-```ts
-import { LocalStorageDriver } from '@blueprint-ts/core/persistenceDrivers'
-
-const driver = new LocalStorageDriver('optional-suffix')
-
-driver.set('my-key', { value: 123 })
-const value = driver.get<{ value: number }>('my-key')
-```
-
-## Implementing A Custom Driver
-
-Implement the `PersistenceDriver` interface:
-
-```ts
-import { type PersistenceDriver } from '@blueprint-ts/core/persistenceDrivers'
-
-export class MemoryDriver implements PersistenceDriver {
-  private store = new Map<string, unknown>()
-
-  get<T>(key: string): T | null {
-    return (this.store.get(key) as T) ?? null
-  }
-
-  set<T>(key: string, state: T): void {
-    this.store.set(key, state)
-  }
-
-  remove(key: string): void {
-    this.store.delete(key)
-  }
-}
-```

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

@@ -1,29 +0,0 @@
-# Aborting Requests
-
-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
-const controller = new AbortController()
-
-const request = new ExpenseIndexRequest()
-  .setAbortSignal(controller.signal)
-
-const promise = request.send()
-
-// Later, when you want to abort:
-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:
-
-```typescript
-bulkRequestSenderInstance.abort()
-```

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

@@ -1,70 +0,0 @@
-# Bulk Requests
-
-Bulk requests let you send many requests together with a shared execution mode and retry policy.
-
-## Basic Usage
-
-Wrap each request in a `BulkRequestWrapper`, then send them with `BulkRequestSender`:
-
-```typescript
-import {
-    BulkRequestExecutionMode,
-    BulkRequestSender,
-    BulkRequestWrapper,
-    BulkRequestEventEnum
-} from '@blueprint-ts/core/bulkRequests'
-
-const requests = items.map((item) =>
-    new BulkRequestWrapper(new DeleteRequest(item.id))
-)
-
-const sender = new BulkRequestSender(requests, BulkRequestExecutionMode.PARALLEL, 1)
-
-await sender
-    .on(BulkRequestEventEnum.REQUEST_SUCCESSFUL, () => {
-        // handle success
-    })
-    .on(BulkRequestEventEnum.REQUEST_FAILED, () => {
-        // handle failure
-    })
-    .send()
-```
-
-## Wrapper State
-
-`BulkRequestWrapper` tracks per-request state so you can inspect individual results:
-
-- `wasSent()`
-- `hasError()`
-- `getError()`
-- `getResponse()`
-
-## Sequential vs Parallel
-
-- `BulkRequestExecutionMode.PARALLEL` sends all requests at once.
-- `BulkRequestExecutionMode.SEQUENTIAL` sends requests one after another.
-
-## Retries
-
-Pass a retry count to the sender to retry failed requests:
-
-```typescript
-const sender = new BulkRequestSender(requests, BulkRequestExecutionMode.SEQUENTIAL, 2)
-```
-
-## Results
-
-`send()` resolves with a summary object:
-
-- `getSuccessCount()`
-- `getErrorCount()`
-- `getSuccessfulResponses()`
-- `getFailedResponses()`
-
-## Reusing a Sender
-
-You can reuse a sender instance with a new set of requests:
-
-```typescript
-sender.setRequests(nextRequests)
-```

package/docs/services/requests/concurrency.md

@@ -1,58 +0,0 @@
-# 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/drivers.md

@@ -1,115 +0,0 @@
-# Drivers
-
-Requests are executed by a request driver. The library includes a `FetchDriver`, an `XMLHttpRequestDriver`, and also
-lets you provide your own by implementing `RequestDriverContract`.
-
-## Fetch Driver
-
-```typescript
-import { BaseRequest, FetchDriver } from '@blueprint-ts/core/requests'
-
-BaseRequest.setRequestDriver(new FetchDriver())
-```
-
-The `FetchDriver` supports:
-
-- Global headers
-- `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`:
-
-```typescript
-import { type RequestDriverContract } from '@blueprint-ts/core/requests'
-import { type ResponseHandlerContract } from '@blueprint-ts/core/requests'
-import { type RequestMethodEnum } from '@blueprint-ts/core/requests'
-import { type HeadersContract } from '@blueprint-ts/core/requests'
-import { type BodyContract } from '@blueprint-ts/core/requests'
-import { type DriverConfigContract } from '@blueprint-ts/core/requests'
-
-class CustomDriver implements RequestDriverContract {
-    public async send(
-        url: URL | string,
-        method: RequestMethodEnum,
-        headers: HeadersContract,
-        body?: BodyContract,
-        requestConfig?: DriverConfigContract
-    ): Promise<ResponseHandlerContract> {
-        // Implement your transport here and return a ResponseHandlerContract.
-        throw new Error('Not implemented')
-    }
-}
-```
-
-Register your driver during app boot:
-
-```typescript
-BaseRequest.setRequestDriver(new CustomDriver())
-```

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

@@ -1,153 +0,0 @@
-# Error Handling
-
-When a request fails, `BaseRequest.send()` routes error responses through the request error handler and throws a typed exception.
-
-## Flow Overview
-
-- The request driver throws a `ResponseException` when it receives a non-OK response.
-- `BaseRequest.send()` catches that `ResponseException` and delegates to `ErrorHandler`.
-- `ErrorHandler` parses the response body with `response.json()` into the request's `ResponseErrorBody` generic.
-- If the parsed body is `undefined`, `NoResponseReceivedException` is thrown.
-- Otherwise, the handler maps the HTTP status to a specific exception and throws it.
-- If the error is not a `ResponseException`, `BaseRequest.send()` rethrows the original error.
-
-## 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`
-- `404` -> `NotFoundException`
-- `405` -> `MethodNotAllowedException`
-- `408` -> `RequestTimeoutException`
-- `409` -> `ConflictException`
-- `410` -> `GoneException`
-- `412` -> `PreconditionFailedException`
-- `413` -> `PayloadTooLargeException`
-- `415` -> `UnsupportedMediaTypeException`
-- `419` -> `PageExpiredException`
-- `422` -> `ValidationException`
-- `423` -> `LockedException`
-- `429` -> `TooManyRequestsException`
-- `500` -> `ServerErrorException`
-- `501` -> `NotImplementedException`
-- `502` -> `BadGatewayException`
-- `503` -> `ServiceUnavailableException`
-- `504` -> `GatewayTimeoutException`
-- Any other status -> `ResponseException`
-
-All mapped exceptions extend `ResponseBodyException`, so they provide both `getResponse()` and `getBody()` accessors. `ResponseException` only exposes `getResponse()`.
-Error handling assumes error responses are JSON; if JSON parsing fails, an `InvalidJsonException` is thrown before status mapping runs.
-
-When handling errors, treat the caught error as `unknown` and narrow with `instanceof`:
-
-```typescript
-import {
-    ResponseException,
-    ValidationException,
-    UnauthorizedException
-} from '@blueprint-ts/core/requests/exceptions'
-
-try {
-    await request.send()
-} catch (error: unknown) {
-    if (error instanceof ValidationException) {
-        const response = error.getResponse()
-        const body = error.getBody()
-        // Handle validation errors using response/body.
-    } else if (error instanceof UnauthorizedException) {
-        const response = error.getResponse()
-        const body = error.getBody()
-        // Handle auth errors using response/body.
-    } else if (error instanceof ResponseException) {
-        const response = error.getResponse()
-        // Handle other response errors.
-    }
-}
-```
-
-If you prefer to avoid manual `instanceof` checks, use the fluent `RequestErrorRouter`:
-
-```typescript
-import { RequestErrorRouter } from '@blueprint-ts/core/requests'
-import {
-    ResponseException,
-    ValidationException,
-    UnauthorizedException
-} from '@blueprint-ts/core/requests/exceptions'
-
-try {
-    await request.send()
-} catch (error: unknown) {
-    await new RequestErrorRouter()
-        .on(ValidationException, (exception) => {
-            const response = exception.getResponse()
-            const body = exception.getBody()
-            // Handle validation errors using response/body.
-        })
-        .on(UnauthorizedException, (exception) => {
-            const response = exception.getResponse()
-            const body = exception.getBody()
-            // Handle auth errors using response/body.
-        })
-        .on(ResponseException, (exception) => {
-            const response = exception.getResponse()
-            // Handle other response errors.
-        })
-        .otherwise((exception) => {
-            // Handle non-response errors or rethrow.
-            throw exception
-        })
-        .handle(error)
-}
-```
-
-Handlers run in the order they are registered. Register specific exceptions before base types like `ResponseException`.
-`RequestErrorRouter.handle()` returns `true` when a handler ran and `false` when no handler matched, so you can rethrow or fall back if needed.
-
-## Global Error Handling
-
-You can register a global handler that runs before the normal error mapping:
-
-```typescript
-import { ErrorHandler } from '@blueprint-ts/core/requests'
-
-ErrorHandler.registerHandler((response) => {
-    // Inspect response here.
-    // Return false to indicate that normal handling should be skipped.
-})
-```
-
-Note: the handler only aborts when it explicitly returns `false`. Returning `true`, `undefined`, or nothing continues normal error mapping.
-
-Example: redirect to login on `401` responses:
-
-```typescript
-import { ErrorHandler } from '@blueprint-ts/core/requests'
-import { type ResponseHandlerContract } from '@blueprint-ts/core/requests'
-
-ErrorHandler.registerHandler((response: ResponseHandlerContract) => {
-    if (response.getStatusCode() !== 401) {
-        return
-    }
-    
-    auth.logout()
-
-    router.push({ name: 'login' })
-})
-```

package/docs/services/requests/events.md

@@ -1,53 +0,0 @@
-# Events
-
-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
-
-Use the `RequestEvents.LOADING` event to track request loading state:
-
-```typescript
-import { RequestEvents } from '@blueprint-ts/core/requests'
-
-const request = new ExpenseIndexRequest()
-
-request.on(RequestEvents.LOADING, (isLoading: boolean) => {
-    // Handle loading state
-})
-
-request.send()
-```
-
-You can also pass the event payload type explicitly via the generic:
-
-```typescript
-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

@@ -1,105 +0,0 @@
-# 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.