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

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/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,137 @@
+# 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
+
+- `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`.

package/docs/services/requests/loading.md

@@ -0,0 +1,63 @@
+# Loading
+
+Requests can expose loading state through a request loader. You register a loader factory once, and each `BaseRequest`
+instance will ask the factory for a loader.
+
+Note: For Vue apps, the library provides `VueRequestLoader` and `VueRequestLoaderFactory` in `@blueprint-ts/core/vue/requests`.
+
+## Registering a Loader Factory
+
+Use `BaseRequest.setRequestLoaderFactory()` to register a factory that implements `RequestLoaderFactoryContract` and
+returns a `RequestLoaderContract`:
+
+```typescript
+import {
+    BaseRequest,
+    type RequestLoaderContract,
+    type RequestLoaderFactoryContract
+} from '@blueprint-ts/core/requests'
+
+class BooleanLoader implements RequestLoaderContract<boolean> {
+    private loading = false
+
+    public isLoading(): boolean {
+        return this.loading
+    }
+
+    public setLoading(value: boolean): void {
+        this.loading = value
+    }
+}
+
+class BooleanLoaderFactory implements RequestLoaderFactoryContract<boolean> {
+    public make(): RequestLoaderContract<boolean> {
+        return new BooleanLoader()
+    }
+}
+
+BaseRequest.setRequestLoaderFactory(new BooleanLoaderFactory())
+```
+
+## Reading Loading State
+
+Once a loader factory is registered, every request created from `BaseRequest` can read loading state:
+
+```typescript
+const request = new ExpenseIndexRequest()
+
+request.send()
+
+const isLoading = request.isLoading()
+```
+
+## Override Loader
+
+You can override the loader per request with `setRequestLoader`:
+
+```typescript
+const request = new ExpenseIndexRequest()
+
+request.setRequestLoader(customLoader)
+```
+
+This lets you create or share a loader before the request exists, which is useful when loading state must be wired up ahead of time.

package/docs/services/requests/request-bodies.md

@@ -0,0 +1,59 @@
+# Request Bodies
+
+Request body factories control how outgoing request bodies are serialized and which `Content-Type` header is sent.
+They are separate from response parsing (response classes control `Accept` and how the response body is parsed).
+
+## How It Works
+
+When you call `send()`, `BaseRequest` uses the request body factory to build a `BodyContract`:
+
+- `getRequestBodyFactory()` returns a `BodyFactoryContract`
+- `BodyFactoryContract.make()` returns a `BodyContract`
+- `BodyContract.getHeaders()` provides headers (like `Content-Type`)
+- `BodyContract.getContent()` provides the serialized body
+
+If you call `setBody(...)` without providing a body factory, the body is not sent.
+
+## JSON Bodies
+
+Use `JsonBodyFactory` to send JSON and set `Content-Type: application/json`:
+
+```typescript
+import { BaseRequest, JsonBodyFactory, RequestMethodEnum } from '@blueprint-ts/core/requests'
+
+class CreateExpenseRequest extends BaseRequest<boolean, GenericResponseErrorInterface, ExpenseResource, JsonResponse<ExpenseResource>, CreateExpensePayload> {
+    public method(): RequestMethodEnum {
+        return RequestMethodEnum.POST
+    }
+
+    public url(): string {
+        return '/api/v1/expenses'
+    }
+
+    public getResponse(): JsonResponse<ExpenseResource> {
+        return new JsonResponse<ExpenseResource>()
+    }
+
+    public override getRequestBodyFactory() {
+        return new JsonBodyFactory<CreateExpensePayload>()
+    }
+}
+```
+
+If you are using the Laravel integration, `JsonBaseRequest` already configures the JSON body factory for you.
+
+## FormData Bodies
+
+Use `FormDataFactory` for multipart requests (uploads, mixed fields):
+
+```typescript
+import { FormDataFactory } from '@blueprint-ts/core/requests'
+
+public override getRequestBodyFactory() {
+    return new FormDataFactory<FormPayload>()
+}
+```
+
+## Custom Body Factories
+
+You can implement your own body factory by returning a `BodyContract` with custom headers and serialization logic.

package/docs/services/requests/responses.md

@@ -0,0 +1,34 @@
+# Responses
+
+Requests return a response class that controls the `Accept` header and how the body is parsed.
+
+## JsonResponse
+
+Use `JsonResponse<T>` for JSON APIs. It sets `Accept: application/json` and parses the body with `response.json()`:
+
+```typescript
+import { JsonResponse } from '@blueprint-ts/core/requests'
+
+// In your request generic parameters:
+// JsonResponse<ExpenseIndexRequestResponseBody>
+```
+
+## PlainTextResponse
+
+Use `PlainTextResponse` for endpoints that return plain text. It sets `Accept: text/plain` and parses the body with
+`response.text()`:
+
+```typescript
+import { PlainTextResponse } from '@blueprint-ts/core/requests'
+```
+
+## BlobResponse
+
+Use `BlobResponse` for binary responses like files. It sets `Accept` to the provided MIME type (default
+`application/octet-stream`) and parses the body with `response.blob()`:
+
+```typescript
+import { BlobResponse } from '@blueprint-ts/core/requests'
+
+const response = new BlobResponse('application/pdf')
+```