@blueprint-ts/core 3.0.0 → 4.0.0-beta.10

package/docs/services/persistence/index.md

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

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

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

@@ -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/drivers.md

@@ -0,0 +1,50 @@
+# 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`.
+
+## Default 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
+
+## 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

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

@@ -0,0 +1,31 @@
+# Events
+
+Requests can emit lifecycle events via `BaseRequest.on(...)`.
+
+## Available Events
+
+- `RequestEvents.LOADING`: Emits `true` when a request starts and `false` when it finishes.
+
+## 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
+})
+```

package/docs/services/requests/getting-started.md

@@ -0,0 +1,201 @@
+# Getting Started
+
+Each API endpoint is represented as a separate class that extends `BaseRequest`. This class specifies the HTTP Method,
+URL, and the expected request/response types.
+
+## Request Handling
+
+The library leverages a fetch-based driver to perform HTTP requests. The following sections explain how to initialize
+the request driver and define custom requests.
+
+## Initializing the Request Driver
+
+Before making any requests, you must initialize the appropriate request driver. This is done during your application's
+boot process by using the static `setRequestDriver` method.
+
+### Using the Fetch Driver
+
+To set up the fetch driver, import `BaseRequest` and `FetchDriver` from '@blueprint-ts/core/requests' and initialize
+the driver as shown:
+
+```typescript
+import { BaseRequest, FetchDriver } from '@blueprint-ts/core/requests'
+
+BaseRequest.setRequestDriver(new FetchDriver())
+```
+
+### Enabling Credential Support
+
+If your requests need to include credentials (e.g., cookies for cross-origin requests), enable credential support as
+follows:
+
+```typescript
+BaseRequest.setRequestDriver(new FetchDriver({
+    corsWithCredentials: true,
+}))
+```
+
+### Adding Global Headers
+
+To include headers such as a CSRF token with every request, define them globally:
+
+```typescript
+BaseRequest.setRequestDriver(new FetchDriver({
+    headers: {
+        'X-XSRF-TOKEN': "<token>",
+    },
+}))
+```
+
+Sometimes you want to refetch the header when the request is sent. You may specify a callback for this:
+
+```typescript
+BaseRequest.setRequestDriver(new FetchDriver({
+    headers: {
+        'X-XSRF-TOKEN': () => getCookie('XSRF-TOKEN')
+    },
+}))
+```
+
+### Specifying a Base URL
+
+In case your backend lives on a separate domain, you may specify a default base url, which is prepended to every request url:
+
+```typescript
+BaseRequest.setDefaultBaseUrl('https://example.com')
+```
+
+## Example: Expense Index Request
+
+The following example demonstrates how to define a GET request to the `/api/v1/expenses` endpoint:
+
+```typescript
+import { BaseRequest, RequestMethodEnum, JsonResponse } from '@blueprint-ts/core/requests'
+
+export interface GenericResponseErrorInterface {
+    message: string
+}
+
+export interface ExpenseIndexRequestParams {
+    filter?: {
+        search_text?: string
+    };
+}
+
+export interface ExpenseResource {
+    id: string;
+    // other data fields
+}
+
+export interface ExpenseIndexRequestResponseBody {
+    data: ExpenseResource[]
+}
+
+export class ExpenseIndexRequest extends BaseRequest<
+        boolean, // Generic RequestLoaderLoadingType
+        GenericResponseErrorInterface, // Generic ResponseErrorBody
+        ExpenseIndexRequestResponseBody, // Generic ResponseBodyInterface
+        JsonResponse<ExpenseIndexRequestResponseBody>, // Generic ResponseClass
+        undefined, // Generic RequestBodyInterface
+        ExpenseIndexRequestParams // RequestParamsInterface
+> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.GET
+    }
+
+    public url(): string {
+        return '/api/v1/expenses'
+    }
+}
+```
+
+### Explanation
+
+- **HTTP Method**: Uses `GET` to retrieve data from the `/api/v1/expenses` endpoint.
+- **Error Handling**: On failure (4XX/5XX status codes), the response will conform to `GenericResponseErrorInterface`.
+- **Success Response**: A successful response is expected to follow the `ExpenseIndexRequestResponseBody` interface.
+- **Response Format**: The response is of type JSON, as indicated by `JsonResponse`.
+- **Request Body**: Since this is a GET request, the body is `undefined`.
+- **Query Parameters**: Accepts query parameters that match the `ExpenseIndexRequestParams` interface.
+
+### Sending the Request
+
+Once the request is defined, you can send it using the following code:
+
+```typescript
+const request = new ExpenseIndexRequest()
+
+// The response type and body are inferred automatically.
+const response: JsonResponse<ExpenseIndexRequestResponseBody> = await request.send()
+
+const body = response.getBody() // Type: ExpenseIndexRequestResponseBody
+```
+
+## Example: Create Expense Request (POST)
+
+This example demonstrates a POST request that sends a JSON body by overriding `getRequestBodyFactory()`:
+
+```typescript
+import {
+    BaseRequest,
+    RequestMethodEnum,
+    JsonResponse,
+    JsonBodyFactory
+} from '@blueprint-ts/core/requests'
+
+export interface CreateExpensePayload {
+    title: string
+    amount: number
+}
+
+export interface CreateExpenseResponseBody {
+    id: string
+}
+
+export class CreateExpenseRequest extends BaseRequest<
+        boolean,
+        GenericResponseErrorInterface,
+        CreateExpenseResponseBody,
+        JsonResponse<CreateExpenseResponseBody>,
+        CreateExpensePayload
+> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.POST
+    }
+
+    public url(): string {
+        return '/api/v1/expenses'
+    }
+
+    public getResponse(): JsonResponse<CreateExpenseResponseBody> {
+        return new JsonResponse<CreateExpenseResponseBody>()
+    }
+
+    public override getRequestBodyFactory() {
+        return new JsonBodyFactory<CreateExpensePayload>()
+    }
+}
+```
+
+### Explanation
+
+- **HTTP Method**: Uses `POST` to create a new expense.
+- **Error Handling**: On failure (4XX/5XX status codes), the response will conform to `GenericResponseErrorInterface`.
+- **Success Response**: A successful response is expected to follow the `CreateExpenseResponseBody` interface.
+- **Response Format**: The response is of type JSON, as indicated by `JsonResponse`.
+- **Request Body**: Uses `JsonBodyFactory` to send JSON with `Content-Type: application/json`.
+
+### Sending the Request
+
+```typescript
+const request = new CreateExpenseRequest()
+
+const response = await request.setBody({
+    title: 'Office supplies',
+    amount: 42
+}).send()
+
+const body = response.getBody() // Type: CreateExpenseResponseBody
+```
+
+Note: If you use Laravel or an API that wraps payloads under a `data` key, consider using `JsonBaseRequest` from the Laravel integration.

package/docs/services/requests/headers.md

@@ -0,0 +1,40 @@
+# Headers
+
+Requests assemble headers from multiple sources before sending:
+
+1. **Driver defaults** (global headers set on the driver)
+2. **Request headers** returned by `requestHeaders()`
+3. **Body headers** from the request body factory (e.g., `Content-Type`)
+
+Later sources override earlier ones. Header values can be strings or callbacks that resolve at send time.
+
+## Global Headers (Driver)
+
+Set headers once when you configure the driver:
+
+```typescript
+BaseRequest.setRequestDriver(new FetchDriver({
+    headers: {
+        'X-XSRF-TOKEN': () => getCookie('XSRF-TOKEN')
+    },
+}))
+```
+
+## Per-Request Headers
+
+Override `requestHeaders()` on a request to add headers per request:
+
+```typescript
+import { type HeadersContract } from '@blueprint-ts/core/requests'
+
+public override requestHeaders(): HeadersContract {
+    return {
+        Authorization: `Bearer ${this.accessToken}`
+    }
+}
+```
+
+## Body Headers
+
+Request body factories can set headers such as `Content-Type`. For example, `JsonBodyFactory` sets
+`Content-Type: application/json`.