@blueprint-ts/core 4.1.0-beta.2 → 4.1.0-beta.4

package/docs/services/requests/file-uploads.md

@@ -1,168 +0,0 @@
-# File Uploads
-
-Use `FormDataFactory` for multipart uploads with fields, and use `BinaryBodyFactory` when the endpoint expects a raw
-binary body such as a chunk `PUT`. Use `XMLHttpRequestDriver` when the consuming application needs upload progress for a
-progress bar.
-
-Choose the body factory based on the wire format your endpoint expects:
-
-- Use `FormDataFactory` when the request includes normal fields plus one or more files.
-- Use `BinaryBodyFactory` when the request body itself is the file or chunk.
-- Use `FetchDriver` if you just need to send the upload.
-- Use `XMLHttpRequestDriver` if you also need upload progress events.
-
-## 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()
-```
-
-## Raw Chunk Uploads
-
-```typescript
-import {
-    BaseRequest,
-    BinaryBodyFactory,
-    JsonResponse,
-    RequestMethodEnum,
-    XMLHttpRequestDriver
-} from '@blueprint-ts/core/requests'
-
-interface UploadPartResponse {
-    etag: string
-}
-
-class UploadPartRequest extends BaseRequest<
-        boolean,
-        { message: string },
-        UploadPartResponse,
-        JsonResponse<UploadPartResponse>,
-        Uint8Array
-> {
-    public method(): RequestMethodEnum {
-        return RequestMethodEnum.PUT
-    }
-
-    public url(): string {
-        return '/api/v1/uploads/part'
-    }
-
-    public getResponse(): JsonResponse<UploadPartResponse> {
-        return new JsonResponse<UploadPartResponse>()
-    }
-
-    public override getRequestBodyFactory() {
-        return new BinaryBodyFactory<Uint8Array>('application/octet-stream')
-    }
-
-    public override requestHeaders() {
-        return {
-            'X-Part-Number': '1'
-        }
-    }
-
-    protected override getRequestDriver() {
-        return new XMLHttpRequestDriver()
-    }
-}
-```
-
-In this example, `setBody(...)` can receive a `Blob`, `ArrayBuffer`, `Uint8Array`, or another typed-array/data-view
-payload supported by `BinaryBodyFactory`.
-
-## 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.
-- `BinaryBodyFactory` only sets `Content-Type` automatically when the body is a `Blob` with a non-empty `type`.
-  For `ArrayBuffer` and typed-array uploads, pass the expected content type explicitly.
-- `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/getting-started.md

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

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

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

@@ -1,89 +0,0 @@
-# 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>()
-}
-```
-
-If you want to show upload progress for multipart file uploads, see [File Uploads](/services/requests/file-uploads).
-
-## Raw Binary Bodies
-
-Use `BinaryBodyFactory` when the request body should be sent as raw binary instead of multipart form data. This is a
-better fit for chunk uploads, binary artifact pushes, and endpoints that expect the request body as-is:
-
-```typescript
-import { BinaryBodyFactory } from '@blueprint-ts/core/requests'
-
-public override getRequestBodyFactory() {
-    return new BinaryBodyFactory<ArrayBuffer>('application/octet-stream')
-}
-```
-
-`BinaryBodyFactory` supports:
-
-- `Blob`
-- `ArrayBuffer`
-- typed-array and view values such as `Uint8Array` or `DataView`
-
-`Content-Type` resolution works like this:
-
-- If you pass a content type to `BinaryBodyFactory`, Blueprint sends that `Content-Type` header.
-- Otherwise, if the body is a `Blob` with a non-empty `type`, Blueprint uses `Blob.type`.
-- Otherwise, Blueprint does not add a `Content-Type` header for you.
-
-`BinaryBodyFactory` works with both `FetchDriver` and `XMLHttpRequestDriver`. Choose `XMLHttpRequestDriver` only when
-the consuming application needs upload progress events.
-
-## 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

@@ -1,34 +0,0 @@
-# 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')
-```

package/docs/services/support/deferred-promise.md

@@ -1,63 +0,0 @@
-# DeferredPromise
-
-`DeferredPromise` exposes a Promise along with `resolve`, `reject`, and a `state` property you can inspect.
-
-```typescript
-import { DeferredPromise } from '@blueprint-ts/core/support'
-
-const deferred = new DeferredPromise<string>()
-
-deferred.then((value) => {
-    console.log(value)
-})
-
-deferred.resolve('Done')
-```
-
-State values:
-
-- `pending`
-- `fulfilled`
-- `rejected`
-
-## Example: Defer Component Rendering
-
-Use a `DeferredPromise` to delay rendering of a Vue component until the slideover is opened and has received the props as non undefined:
-
-```vue
-<template>
-  <SlideOver v-model="isOpen">
-    <template v-if="resolvedresource">
-      <UpdateForm :options="options" :resource="resolvedresource" />
-    </template>
-  </SlideOver>
-</template>
-
-<script setup lang="ts">
-import { ref, onMounted } from 'vue'
-import { DeferredPromise } from '@blueprint-ts/core/support'
-
-const props = defineProps<{ resource?: Resource }>()
-const isOpen = defineModel<boolean>('isOpen', { default: false })
-
-const readyPromise = new DeferredPromise<Resource>()
-const resolvedresource = ref<Resource>(undefined)
-let options: UpdateFormOptionsContract | undefined
-
-readyPromise.then((contract) => {
-  options = new UpdateFormOptions(contract)
-})
-
-onMounted(() => {
-  readyPromise.then((resource: Resource) => {
-      resolvedresource.value = resource
-  })
-})
-
-watch(isOpen, (open) => {
-  if (open && props.resource) {
-    readyPromise.resolve(props.resource)
-  }
-})
-</script>
-```