@autometa/http 1.4.20 → 2.0.0-rc.0

package/README.md

@@ -1,3 +1,108 @@
-# Introduction
+<!-- cspell:disable -->
 
-There's nothing here yet
+# @autometa/http
+
+Composable HTTP client utilities with transport adapters, fluent request builders, and batteries-included behaviors (error mapping, retries, logging, streaming).
+
+## Installation
+
+```bash
+pnpm add @autometa/http
+```
+
+## Quick Start
+
+```ts
+import { http } from "@autometa/http";
+
+const client = http().baseUrl("https://api.example.com");
+
+const response = await client
+	.get("/users")
+	.query({ limit: 25 })
+	.execute();
+
+console.log(response.status); // 200
+console.log(response.body);   // Parsed JSON payload
+```
+
+## Features
+
+- Typed error hierarchy (`HTTPError`, `HTTPTransportError`, `HTTPSchemaValidationError`) with rich metadata
+- AbortSignal propagation for cancellable requests
+- Configurable retry policies (max attempts, delays, custom retry predicate)
+- Scoped timeouts via `sharedTimeout()` / `timeout()` with automatic aborts
+- Plugin system with logging hooks (see `createHttpLogger`)
+- Streaming responses via `stream()`/`asStream()` without JSON parsing
+
+## Error Handling
+
+Errors thrown by the client expose status, request metadata, and transport details. Catch specific subclasses when you need to branch logic:
+
+```ts
+import { HTTPTransportError } from "@autometa/http";
+
+try {
+	await http().get("/slow").execute();
+} catch (error) {
+	if (error instanceof HTTPTransportError) {
+		console.error("Transport failure", error.transport);
+	}
+}
+```
+
+## Retries & Delays
+
+```ts
+await http()
+	.get("/flaky")
+	.retry(config =>
+		config
+			.maxAttempts(3)
+			.delay(fn => fn.exponential({ base: 100, max: 2000 }))
+			.shouldRetry(({ response }) => response?.status === 503)
+	)
+	.execute();
+```
+
+## Streaming Responses
+## Timeouts
+
+Apply timeouts without wiring your own `AbortController`. Timeouts compose with existing signals and respect retries:
+
+```ts
+await http()
+	.timeout(5000)
+	.get();
+
+// combine with a per-request signal
+const controller = new AbortController();
+await http()
+	.timeout(2000)
+	.get({ signal: controller.signal });
+```
+
+Timeouts use `AbortController` under the hood and can be shared (`sharedTimeout`) or scoped per request.
+
+Set `stream()` when you want the raw response stream. Transports bypass JSON parsing and validation so you can pipe the body directly:
+
+```ts
+const stream = await http()
+	.get("/events")
+	.stream()
+	.execute();
+
+for await (const chunk of stream.body) {
+	process.stdout.write(chunk);
+}
+```
+
+## Testing
+
+The package ships with Vitest unit suites and integration tests that exercise the fluent builder against live-like transports. Run everything with:
+
+```bash
+pnpm --filter @autometa/http test
+```
+
+Integration tests are the recommended place to add coverage for additional transport behaviors (such as verifying streaming support end-to-end).

package/dist/assertions/http-adapters.d.ts

@@ -0,0 +1,35 @@
+type HeadersLike = {
+    get(name: string): string | null;
+    has?(name: string): boolean;
+    entries?: () => IterableIterator<[string, string]>;
+    [Symbol.iterator]?: () => IterableIterator<[string, string]>;
+};
+type HeaderSource = HeadersLike | Record<string, unknown>;
+export type HttpResponseLike = {
+    status: number;
+    statusText?: string;
+    headers: HeaderSource;
+    data?: unknown;
+    raw?: unknown;
+};
+/**
+ * Adapts an @autometa/http `HTTPResponse` (or any similarly-shaped object) into a
+ * stable `HttpResponseLike` for HTTP assertions.
+ */
+export declare function fromHttpResponse<T extends {
+    headers: Record<string, string>;
+}>(response: T & {
+    status: number;
+    statusText?: string;
+    data?: unknown;
+}): HttpResponseLike;
+/**
+ * Adapts a fetch-style response (or any similarly-shaped object) into a stable
+ * `HttpResponseLike` for HTTP assertions.
+ */
+export declare function fromFetchResponse(response: {
+    status: number;
+    statusText?: string;
+    headers: HeadersLike;
+}, data?: unknown): HttpResponseLike;
+export {};

package/dist/assertions/http-assertions-plugin.d.ts

@@ -0,0 +1,16 @@
+import type { AssertionPlugin, EnsureOptions } from "@autometa/assertions";
+import type { HTTPResponse } from "../http-response";
+import { type HttpEnsureChain, type HttpResponseLike } from "./http-ensure";
+/**
+ * Callable facet attached as `ensure.http(...)`.
+ *
+ * Supports plugin-level negation: `ensure.not.http(response)`.
+ * Also supports chain-level negation: `ensure.http(response).not...`.
+ */
+export type HttpAssertionsFacet = <T = unknown>(response: HttpResponseLike | HTTPResponse<T>, options?: EnsureOptions) => HttpEnsureChain<HttpResponseLike>;
+/**
+ * Assertion plugin that provides HTTP response matchers as a facet.
+ *
+ * This keeps the base `ensure(value)` matcher chain domain-agnostic.
+ */
+export declare const httpAssertionsPlugin: <World>() => AssertionPlugin<World, HttpAssertionsFacet>;

package/dist/assertions/http-ensure.d.ts

@@ -0,0 +1,42 @@
+import { type EnsureOptions } from "@autometa/assertions";
+type HeadersLike = {
+    get(name: string): string | null;
+    has?(name: string): boolean;
+    entries?: () => IterableIterator<[string, string]>;
+    [Symbol.iterator]?: () => IterableIterator<[string, string]>;
+};
+type HeaderSource = HeadersLike | Record<string, unknown>;
+export type HttpResponseLike = {
+    status: number;
+    statusText?: string;
+    headers: HeaderSource;
+    data?: unknown;
+    raw?: unknown;
+};
+export type StatusExpectation = number | `${1 | 2 | 3 | 4 | 5}xx` | readonly [number, number] | {
+    readonly min: number;
+    readonly max: number;
+} | ((status: number) => boolean);
+export type HeaderExpectation = string | RegExp | readonly string[] | ((value: string) => boolean);
+export interface CacheControlExpectation {
+    readonly cacheability?: "public" | "private";
+    readonly maxAge?: number | {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    readonly sMaxAge?: number;
+    readonly revalidate?: boolean;
+    readonly immutable?: boolean;
+}
+export interface HttpEnsureChain<T extends HttpResponseLike = HttpResponseLike> {
+    readonly value: T;
+    readonly not: HttpEnsureChain<T>;
+    toHaveStatus(expectation: StatusExpectation): HttpEnsureChain<T>;
+    toHaveHeader(name: string, expectation?: HeaderExpectation): HttpEnsureChain<T>;
+    toBeCacheable(expectation?: CacheControlExpectation): HttpEnsureChain<T>;
+    toHaveCorrelationId(headerName?: string): HttpEnsureChain<T>;
+}
+export declare function ensureHttp<T extends HttpResponseLike>(response: T, options?: EnsureOptions & {
+    readonly negated?: boolean;
+}): HttpEnsureChain<T>;
+export {};

package/dist/axios-transport.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+import type { HTTPTransport } from "./transport";
+export interface AxiosRequestConfigLike extends Record<string, unknown> {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string | number | boolean | null | undefined>;
+    params?: Record<string, unknown>;
+    data?: unknown;
+    validateStatus?: (status: number) => boolean;
+    signal?: AbortSignal;
+    responseType?: string;
+}
+export interface AxiosResponseLike<T = unknown> {
+    status: number;
+    statusText: string;
+    data: T;
+    headers?: Record<string, string | string[]>;
+}
+export interface AxiosLike {
+    request<T = unknown, R = AxiosResponseLike<T>>(config: AxiosRequestConfigLike): Promise<R>;
+}
+export declare function createAxiosTransport(axios: AxiosLike): HTTPTransport<AxiosRequestConfigLike>;

package/dist/default-schema.d.ts

@@ -0,0 +1,8 @@
+export declare function AnySchema<T = unknown>(data: T): T;
+export declare function EmptySchema(data: unknown): null | undefined;
+export declare function NullSchema(data: unknown): null;
+export declare function UndefinedSchema(data: unknown): undefined;
+export declare function BooleanSchema(data: unknown): boolean;
+export declare function NumberSchema(data: unknown): number;
+export declare function StringSchema(data: unknown): string;
+export declare function JSONSchema<T = unknown>(data: unknown): T;

package/dist/fetch-transport.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="node" />
+import type { HTTPTransport } from "./transport";
+export interface FetchRequestOptions extends Record<string, unknown> {
+    headers?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    method?: string;
+    signal?: AbortSignal;
+    streamResponse?: boolean;
+}
+export interface FetchResponseLike {
+    status: number;
+    statusText: string;
+    headers: HeadersLike;
+    text(): Promise<string>;
+    body?: unknown;
+}
+export interface HeadersLike {
+    forEach(callback: (value: string, key: string) => void): void;
+}
+export type FetchLike = (input: string, init?: FetchRequestOptions) => Promise<FetchResponseLike>;
+export declare function createFetchTransport(fetchImpl?: FetchLike): HTTPTransport<FetchRequestOptions>;

package/dist/http-request.d.ts

@@ -0,0 +1,109 @@
+import type { HTTPMethod, QueryParamSerializationOptions, QueryParamValue, QueryParamPrimitive } from "./types";
+export type HeaderPrimitive = string | number | boolean | null | undefined;
+export type HeaderFactory = (() => HeaderPrimitive | Promise<HeaderPrimitive>) | undefined;
+export type ParamPrimitive = QueryParamPrimitive;
+export type ParamDictionary = Record<string, ParamValue>;
+export type ParamValue = QueryParamValue | undefined;
+export interface RequestConfigBasic<T = unknown> {
+    headers?: Record<string, string>;
+    params?: Record<string, ParamValue>;
+    baseUrl?: string;
+    route?: string[];
+    method?: HTTPMethod;
+    data?: T;
+    queryOptions?: QueryParamSerializationOptions;
+}
+/**
+ * Represents the request payload sent via {@link HTTP} including URL, headers and metadata.
+ */
+export declare class HTTPRequest<T = unknown> {
+    /**
+     * Normalised header collection that will be sent with the request.
+     */
+    headers: Record<string, string>;
+    params: Record<string, ParamValue>;
+    baseUrl: string | undefined;
+    route: string[];
+    method: HTTPMethod | undefined;
+    data: T | undefined;
+    queryOptions: QueryParamSerializationOptions;
+    constructor(config?: RequestConfigBasic<T>);
+    /**
+     * Full request URL derived from {@link baseUrl}, {@link route} and {@link params}.
+     */
+    get fullUrl(): string;
+    /**
+     * Creates a deep copy of an existing request instance.
+     */
+    static derive<T>(original: HTTPRequest<T>): HTTPRequest<T>;
+}
+/**
+ * Fluent utility used to construct {@link HTTPRequest} instances while keeping internal state safe.
+ */
+export declare class HTTPRequestBuilder<T extends HTTPRequest<unknown>> {
+    private requestInstance;
+    private dynamicHeaders;
+    private queryOptions;
+    constructor(request?: T | (() => T));
+    /**
+     * Initializes a new builder for the default {@link HTTPRequest} type.
+     */
+    static create<T extends HTTPRequest<unknown>>(): HTTPRequestBuilder<T>;
+    /**
+     * Exposes the underlying request without defensive cloning.
+     */
+    get request(): T;
+    /**
+     * Resolves asynchronous header factories into concrete header values on demand.
+     */
+    resolveDynamicHeaders(request?: HTTPRequest): Promise<this>;
+    /**
+     * Sets the root URL (protocol, host and optional base path).
+     */
+    url(url: string): this;
+    /**
+     * Appends one or more path segments to the current request route.
+     */
+    route(...segments: (string | number | boolean)[]): this;
+    /**
+     * Adds or removes a query parameter value.
+     */
+    param(name: string, value: ParamValue): this;
+    /**
+     * Merges a dictionary of query parameters into the request.
+     */
+    params(dict: Record<string, unknown>): this;
+    queryFormat(options: QueryParamSerializationOptions): this;
+    /**
+     * Sets the request body payload. Passing `undefined` removes the body.
+     */
+    data<K>(data: K | undefined): this;
+    /**
+     * Sets a single header using direct values or a lazy factory.
+     */
+    header(name: string, value: HeaderPrimitive | HeaderPrimitive[] | (() => HeaderPrimitive | Promise<HeaderPrimitive>)): this;
+    /**
+     * Replaces or merges multiple headers in one call.
+     */
+    headers(dict: Record<string, HeaderPrimitive | HeaderPrimitive[]>): this;
+    /**
+     * Stores the HTTP verb ensuring consistent casing.
+     */
+    method(method: HTTPMethod): this;
+    /**
+     * Returns a copy-on-write builder pointing at the same request state.
+     */
+    derive(): HTTPRequestBuilder<T>;
+    /**
+     * Produces a deep copy of the builder and the underlying request.
+     */
+    clone(): HTTPRequestBuilder<T>;
+    /**
+     * Returns the current request without resolving header factories.
+     */
+    build(): HTTPRequest<T>;
+    /**
+     * Resolves lazy headers before returning the request.
+     */
+    buildAsync(): Promise<HTTPRequest<T>>;
+}

package/dist/http-response.d.ts

@@ -0,0 +1,77 @@
+import type { HTTPRequest } from "./http-request";
+import type { StatusCode } from "./types";
+/**
+ * Immutable view of a completed HTTP response produced by {@link HTTP}.
+ *
+ * Use {@link HTTPResponseBuilder} to clone or modify instances in a safe way.
+ */
+export declare class HTTPResponse<T = unknown> {
+    /**
+     * HTTP status code returned by the remote service.
+     */
+    status: StatusCode;
+    /**
+     * Human-readable text accompanying {@link status}.
+     */
+    statusText: string;
+    /**
+     * Response payload after all transformations and schema validation.
+     */
+    data: T;
+    /**
+     * Normalised response headers keyed by lowercase header names.
+     */
+    headers: Record<string, string>;
+    /**
+     * Original request that produced this response.
+     */
+    request: HTTPRequest<unknown>;
+    /**
+     * Creates a shallow clone from an existing response instance.
+     */
+    static fromRaw<T>(response: HTTPResponse<T>): HTTPResponse<T>;
+    mapData<K>(value: K): HTTPResponse<K>;
+    mapData<K>(transform: (response: T) => K): HTTPResponse<K>;
+}
+/**
+ * Fluent builder used by {@link HTTP} to create {@link HTTPResponse} instances.
+ */
+export declare class HTTPResponseBuilder {
+    private response;
+    /**
+     * Creates a new empty builder.
+     */
+    static create(): HTTPResponseBuilder;
+    /**
+     * Produces a new builder seeded with the current response state.
+     */
+    derive(): HTTPResponseBuilder;
+    /**
+     * Sets the response status code.
+     */
+    status(code: StatusCode): this;
+    /**
+     * Sets the textual status message.
+     */
+    statusText(text: string): this;
+    /**
+     * Attaches the response payload.
+     */
+    data<T>(data: T): this;
+    /**
+     * Replaces the entire headers collection.
+     */
+    headers(dict: Record<string, string>): this;
+    /**
+     * Sets or overrides a single response header.
+     */
+    header(name: string, value: string): this;
+    /**
+     * References the originating request.
+     */
+    request(request: HTTPRequest<unknown>): this;
+    /**
+     * Builds the immutable {@link HTTPResponse} instance.
+     */
+    build(): HTTPResponse<unknown>;
+}