@molecule/app-http 1.1.0 → 1.1.1

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-15T09:31:18.498Z
+Generated: 2026-10-16T00:35:00.541Z
 -->
 
 # @molecule/app-http
@@ -49,29 +49,6 @@ npm install @molecule/app-http @molecule/app-bond @molecule/app-i18n @molecule/a
 
 ### Interfaces
 
-#### `FullRequestConfig`
-
-Full request configuration including method and URL.
-
-```typescript
-interface FullRequestConfig extends RequestConfig {
-  /**
-   * HTTP method.
-   */
-  method: HttpMethod
-
-  /**
-   * Request URL (can be relative or absolute).
-   */
-  url: string
-
-  /**
-   * Request body data.
-   */
-  data?: unknown
-}
-```
-
 #### `HttpClient`
 
 HTTP client interface.
@@ -192,39 +169,6 @@ interface HttpClientConfig {
 }
 ```
 
-#### `HttpResponse`
-
-Parsed HTTP response with status code, headers, and typed body data.
-
-```typescript
-interface HttpResponse<T = unknown> {
-  /**
-   * Response data.
-   */
-  data: T
-
-  /**
-   * HTTP status code.
-   */
-  status: number
-
-  /**
-   * HTTP status text.
-   */
-  statusText: string
-
-  /**
-   * Response headers.
-   */
-  headers: Record<string, string>
-
-  /**
-   * Original request config.
-   */
-  config: FullRequestConfig
-}
-```
-
 #### `RequestConfig`
 
 HTTP request options (headers, query params, timeout, credentials, response type, abort signal).
@@ -273,25 +217,64 @@ interface RequestConfig {
 }
 ```
 
-### Types
-
-#### `ErrorInterceptor`
+#### `FullRequestConfig`
 
-Intercepts HTTP errors to transform, retry, or rethrow them.
-Throwing from this interceptor propagates the error to the caller.
+Full request configuration including method and URL.
 
 ```typescript
-type ErrorInterceptor = (error: HttpError) => HttpError | Promise<HttpError> | never
+interface FullRequestConfig extends RequestConfig {
+  /**
+   * HTTP method.
+   */
+  method: HttpMethod
+
+  /**
+   * Request URL (can be relative or absolute).
+   */
+  url: string
+
+  /**
+   * Request body data.
+   */
+  data?: unknown
+}
 ```
 
-#### `HttpMethod`
+#### `HttpResponse`
 
-HTTP request method.
+Parsed HTTP response with status code, headers, and typed body data.
 
 ```typescript
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
+interface HttpResponse<T = unknown> {
+  /**
+   * Response data.
+   */
+  data: T
+
+  /**
+   * HTTP status code.
+   */
+  status: number
+
+  /**
+   * HTTP status text.
+   */
+  statusText: string
+
+  /**
+   * Response headers.
+   */
+  headers: Record<string, string>
+
+  /**
+   * Original request config.
+   */
+  config: FullRequestConfig
+}
 ```
 
+### Types
+
 #### `RequestInterceptor`
 
 Intercepts outgoing requests to modify headers, URL, or body
@@ -303,6 +286,8 @@ type RequestInterceptor = (
 ) => FullRequestConfig | Promise<FullRequestConfig>
 ```
 
+- `config` — The full request configuration to transform.
+
 #### `ResponseInterceptor`
 
 Intercepts incoming responses to transform data, check status,
@@ -314,12 +299,44 @@ type ResponseInterceptor<T = unknown> = (
 ) => HttpResponse<T> | Promise<HttpResponse<T>>
 ```
 
+#### `ErrorInterceptor`
+
+Intercepts HTTP errors to transform, retry, or rethrow them.
+Throwing from this interceptor propagates the error to the caller.
+
+```typescript
+type ErrorInterceptor = (error: HttpError) => HttpError | Promise<HttpError> | never
+```
+
+#### `HttpMethod`
+
+HTTP request method.
+
+```typescript
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
+```
+
 ### Classes
 
 #### `HttpError`
 
 HTTP error with response details.
 
+```typescript
+class HttpError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public response?: HttpResponse,
+    public config?: FullRequestConfig,
+    public errorKey?: string,
+  ) {
+    super(message)
+    this.name = 'HttpError'
+  }
+}
+```
+
 ### Functions
 
 #### `createFetchClient(config)`
@@ -338,31 +355,71 @@ function createFetchClient(config?: HttpClientConfig): HttpClient
 
 **Returns:** A fully configured `HttpClient` instance.
 
-#### `del(url, config)`
+#### `unwrapList(res)`
 
-Makes a DELETE request using the bonded HTTP client.
+Normalize an unknown response body into a typed array.
+
+Accepts:
+
+- a bare array → returned as-is (cast)
+- `{ data: T[] }` envelope → the inner array
+- `HttpResponse<T[]>` (i.e. `{ data: T[], status, ... }`) → the inner array
+- `HttpResponse<{ data: T[] }>` (the response of an envelope-returning
+  endpoint as it arrives from `@molecule/app-http`'s `HttpClient`) → the
+  doubly-nested inner array
+- `HttpResponse<{ data: T[], total, limit, offset }>` (a RICH pagination
+  envelope from a pre-built `@molecule/api-resource-*` list endpoint) → the
+  inner `data` array (the numeric `total`/`limit`/`offset` make the shape
+  unambiguous, so callers can pass the whole HttpResponse and still get the rows)
+- anything else → `[]`
+
+Callers commonly pass either the raw JSON body (e.g. from `fetch().then(r =>
+r.json())`) or the `HttpResponse` returned by `useHttpClient().get(...)`.
+Both shapes are handled here so pages don't have to remember to call
+`unwrapList(res.data)` vs `unwrapList(res)`.
 
 ```typescript
-function del(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
+function unwrapList(res: unknown): T[]
 ```
 
-- `url` — The request URL.
-- `config` — Optional request configuration.
+- `res` — Raw response body OR an `HttpResponse` envelope from `@molecule/app-http`.
 
-**Returns:** The HTTP response with typed data.
+**Returns:** A typed array `T[]`; never `null`/`undefined`.
 
-#### `get(url, config)`
+#### `unwrapSingle(res)`
 
-Makes a GET request using the bonded HTTP client.
+Normalize an unknown response body into a single typed resource.
+
+Accepts:
+
+- a non-empty plain object → returned as-is (cast)
+- `{ data: T }` envelope → the inner value
+- `{ data: null }`, `{ data: undefined }`, `{ data: [] }`, or
+  `{ data: {} }` (mock-server's no-match shape) → `null`
+- an empty object `{}` → `null`
+- arrays, primitives, `null`, `undefined` → `null`
+
+The "envelope contains an array → null" branch handles the case
+where the mock server returns `[]` for unmatched endpoints but the
+caller expects a single resource.
 
 ```typescript
-function get(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
+function unwrapSingle(res: unknown): T | null
 ```
 
-- `url` — The request URL (relative to baseURL if configured).
-- `config` — Optional request configuration (headers, params, timeout).
+- `res` — Raw response body (e.g. `HttpResponse.data` from `@molecule/app-http`).
 
-**Returns:** The HTTP response with typed data.
+**Returns:** The typed resource `T`, or `null` when the response shape indicates "no resource" (including the various empty envelopes above).
+
+#### `setClient(client)`
+
+Registers an HTTP client as the active singleton.
+
+```typescript
+function setClient(client: HttpClient): void
+```
+
+- `client` — The HTTP client implementation to bond.
 
 #### `getClient()`
 
@@ -375,17 +432,16 @@ function getClient(): HttpClient
 
 **Returns:** The active HTTP client instance.
 
-#### `patch(url, data, config)`
+#### `get(url, config)`
 
-Makes a PATCH request using the bonded HTTP client.
+Makes a GET request using the bonded HTTP client.
 
 ```typescript
-function patch(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
+function get(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
 ```
 
-- `url` — The request URL.
-- `data` — The request body (partial update).
-- `config` — Optional request configuration.
+- `url` — The request URL (relative to baseURL if configured).
+- `config` — Optional request configuration (headers, params, timeout).
 
 **Returns:** The HTTP response with typed data.
 
@@ -417,71 +473,32 @@ function put(url: string, data?: unknown, config?: RequestConfig): Promise<HttpR
 
 **Returns:** The HTTP response with typed data.
 
-#### `setClient(client)`
-
-Registers an HTTP client as the active singleton.
-
-```typescript
-function setClient(client: HttpClient): void
-```
-
-- `client` — The HTTP client implementation to bond.
-
-#### `unwrapList(res)`
-
-Normalize an unknown response body into a typed array.
-
-Accepts:
-
-- a bare array → returned as-is (cast)
-- `{ data: T[] }` envelope → the inner array
-- `HttpResponse<T[]>` (i.e. `{ data: T[], status, ... }`) → the inner array
-- `HttpResponse<{ data: T[] }>` (the response of an envelope-returning
-  endpoint as it arrives from `@molecule/app-http`'s `HttpClient`) → the
-  doubly-nested inner array
-- `HttpResponse<{ data: T[], total, limit, offset }>` (a RICH pagination
-  envelope from a pre-built `@molecule/api-resource-*` list endpoint) → the
-  inner `data` array (the numeric `total`/`limit`/`offset` make the shape
-  unambiguous, so callers can pass the whole HttpResponse and still get the rows)
-- anything else → `[]`
+#### `patch(url, data, config)`
 
-Callers commonly pass either the raw JSON body (e.g. from `fetch().then(r =>
-r.json())`) or the `HttpResponse` returned by `useHttpClient().get(...)`.
-Both shapes are handled here so pages don't have to remember to call
-`unwrapList(res.data)` vs `unwrapList(res)`.
+Makes a PATCH request using the bonded HTTP client.
 
 ```typescript
-function unwrapList(res: unknown): T[]
+function patch(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>
 ```
 
-- `res` — Raw response body OR an `HttpResponse` envelope from `@molecule/app-http`.
-
-**Returns:** A typed array `T[]`; never `null`/`undefined`.
-
-#### `unwrapSingle(res)`
-
-Normalize an unknown response body into a single typed resource.
+- `url` — The request URL.
+- `data` — The request body (partial update).
+- `config` — Optional request configuration.
 
-Accepts:
+**Returns:** The HTTP response with typed data.
 
-- a non-empty plain object → returned as-is (cast)
-- `{ data: T }` envelope → the inner value
-- `{ data: null }`, `{ data: undefined }`, `{ data: [] }`, or
-  `{ data: {} }` (mock-server's no-match shape) → `null`
-- an empty object `{}` → `null`
-- arrays, primitives, `null`, `undefined` → `null`
+#### `del(url, config)`
 
-The "envelope contains an array → null" branch handles the case
-where the mock server returns `[]` for unmatched endpoints but the
-caller expects a single resource.
+Makes a DELETE request using the bonded HTTP client.
 
 ```typescript
-function unwrapSingle(res: unknown): T | null
+function del(url: string, config?: RequestConfig): Promise<HttpResponse<T>>
 ```
 
-- `res` — Raw response body (e.g. `HttpResponse.data` from `@molecule/app-http`).
+- `url` — The request URL.
+- `config` — Optional request configuration.
 
-**Returns:** The typed resource `T`, or `null` when the response shape indicates "no resource" (including the various empty envelopes above).
+**Returns:** The HTTP response with typed data.
 
 ### Constants
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-http",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Client HTTP interface for molecule.dev",
   "type": "module",
   "main": "dist/index.js",