liaise 0.0.0 → 5.0.0

package/dist/result.d.ts

@@ -0,0 +1,178 @@
+import type { Result, SuccessResult, ErrorResult } from './types.js';
+/**
+ * What category of failure an {@link ApiError} represents.
+ *
+ * Branch on this rather than on `status`: `'network'`, `'abort'` and
+ * `'timeout'` all carry `status: 0`, and they call for completely different
+ * handling — retry, ignore, and report respectively.
+ *
+ * `'parse'` is produced for a response body that failed to parse according to
+ * the request's `responseType`. Since 4.2.0 it also covers an optional
+ * `schema` on the request: a validator that refuses the body (`body` is its
+ * issues array) or one that throws (`body` is the thrown value).
+ *
+ * `'middleware'` means a middleware threw rather than the request itself
+ * failing — a bug in consumer code you would fix, not a transient failure
+ * you would retry.
+ */
+export type ApiErrorKind = 'http' | 'network' | 'abort' | 'timeout' | 'parse' | 'middleware';
+/**
+ * Properties required to construct an ApiError instance.
+ *
+ * This interface exists to keep the ApiError constructor clean — instead of
+ * positional arguments, we use a single options object for clarity at call sites.
+ */
+interface ApiErrorOptions {
+    /** HTTP status code (e.g., 404, 500). Use 0 for network errors and aborts. */
+    status: number;
+    /** What category of failure this is. */
+    kind: ApiErrorKind;
+    /** HTTP status text (e.g., 'Not Found'). Use '' for network errors and aborts. */
+    statusText: string;
+    /**
+     * The parsed response body from the server.
+     *
+     * For HTTP errors, this is whatever the server returned (often a JSON error object).
+     * For network errors, this is the native Error that fetch threw.
+     * For aborted requests, this is a DOMException with name 'AbortError'.
+     */
+    body: unknown;
+    /**
+     * Response headers from the server.
+     * For network errors (no response), this should be an empty Headers object.
+     */
+    headers: Headers;
+    /**
+     * Metadata about the request that caused this error.
+     * Useful for logging, debugging, and error reporting.
+     */
+    request: {
+        method: string;
+        url: string;
+        params: unknown;
+    };
+    /**
+     * Data the server returned alongside the errors.
+     *
+     * GraphQL allows partial success — a nullable field errors while the rest of
+     * the query resolves. That data lives here rather than in `Result.data` so
+     * the Result stays a clean discriminated union: `data` is non-null if and
+     * only if `error` is null.
+     *
+     * `undefined` for every REST error and for GraphQL responses carrying no data.
+     */
+    partialData?: unknown;
+}
+/**
+ * Structured error returned in `Result.error` for both HTTP and network failures.
+ *
+ * This is NOT a subclass of `Error` — it's a plain class that stores error
+ * details in a structured way. This is intentional: ApiError represents an
+ * API-level error (not a programming error), and we don't need stack traces
+ * or error inheritance for that use case.
+ *
+ * Two categories of errors produce an ApiError:
+ *
+ * **HTTP errors** (server responded with 4xx or 5xx):
+ * - `status` is the HTTP status code (e.g., 404, 500)
+ * - `statusText` is the HTTP status text (e.g., 'Not Found')
+ * - `body` is the parsed response body (e.g., `{ message: 'Not found' }`)
+ * - `headers` contains the response headers
+ *
+ * **Network errors** (no HTTP response at all):
+ * - `status` is 0 (convention for "no HTTP status")
+ * - `statusText` is '' (empty string)
+ * - `body` is the native Error or DOMException that caused the failure
+ * - `headers` is an empty Headers object
+ *
+ * @example
+ * ```ts
+ * const { error } = await api.getUser({ id: '42' })
+ * if (error) {
+ *   if (error.status === 0) {
+ *     // Network error — user is probably offline
+ *   } else if (error.status === 404) {
+ *     // User not found
+ *   }
+ * }
+ * ```
+ */
+export declare class ApiError {
+    /** HTTP status code, or 0 for network errors and aborted requests. */
+    readonly status: number;
+    /** What category of failure this is. */
+    readonly kind: ApiErrorKind;
+    /** HTTP status text, or '' for network errors and aborted requests. */
+    readonly statusText: string;
+    /**
+     * Parsed response body, Error for network failures, DOMException for aborts.
+     * The type is `unknown` because the server can return anything.
+     */
+    readonly body: unknown;
+    /**
+     * Response headers. Empty Headers object when no HTTP response exists
+     * (network errors, aborts).
+     */
+    readonly headers: Headers;
+    /**
+     * Metadata about the request that caused this error.
+     * Includes the method, fully resolved URL, and the original params object.
+     */
+    readonly request: {
+        method: string;
+        url: string;
+        params: unknown;
+    };
+    /**
+     * Data the server returned alongside the errors.
+     *
+     * GraphQL allows partial success — a nullable field errors while the rest of
+     * the query resolves. That data lives here rather than in `Result.data` so
+     * the Result stays a clean discriminated union: `data` is non-null if and
+     * only if `error` is null.
+     *
+     * `undefined` for every REST error and for GraphQL responses carrying no data.
+     */
+    readonly partialData?: unknown;
+    constructor(options: ApiErrorOptions);
+}
+/**
+ * Create a successful Result with parsed response data.
+ *
+ * Used when the HTTP response has a 2xx status code and the body was
+ * successfully parsed according to the request's `responseType`.
+ *
+ * @typeParam TResponse - The type of the parsed response data.
+ * @param data - The parsed response data.
+ * @param response - The raw HTTP Response object (for status, headers, etc.).
+ * @param retry - Function to re-execute the request from the outermost middleware.
+ * @returns A Result with `data` populated and `error` as null.
+ */
+export declare function createSuccessResult<TResponse>(data: TResponse, response: Response, retry: () => Promise<Result<TResponse>>): SuccessResult<TResponse>;
+/**
+ * Create an error Result for HTTP errors (server responded, but with an error status).
+ *
+ * Used when the HTTP response has a non-2xx status code (4xx, 5xx).
+ * The raw Response is still available because the server DID respond — the
+ * caller might need response headers or want to inspect the raw body.
+ *
+ * @typeParam TResponse - The expected response type (data will be null).
+ * @param error - The structured ApiError with status, body, and request metadata.
+ * @param response - The raw HTTP Response object.
+ * @param retry - Function to re-execute the request from the outermost middleware.
+ * @returns A Result with `error` populated and `data` as null.
+ */
+export declare function createErrorResult<TResponse>(error: ApiError, response: Response, retry: () => Promise<Result<TResponse>>): ErrorResult<TResponse>;
+/**
+ * Create an error Result for network failures (no HTTP response exists).
+ *
+ * Used when fetch itself throws — DNS failure, offline, CORS error, abort, etc.
+ * The `response` field is null because no HTTP response was received.
+ *
+ * @typeParam TResponse - The expected response type (data will be null).
+ * @param error - The structured ApiError (status 0, body is the native Error).
+ * @param retry - Function to re-execute the request from the outermost middleware.
+ * @returns A Result with `error` populated and both `data` and `response` as null.
+ */
+export declare function createNetworkErrorResult<TResponse>(error: ApiError, retry: () => Promise<Result<TResponse>>): ErrorResult<TResponse>;
+export {};

package/dist/result.js

@@ -0,0 +1,20 @@
+export class ApiError {
+    constructor(options) {
+        this.status = options.status;
+        this.kind = options.kind;
+        this.statusText = options.statusText;
+        this.body = options.body;
+        this.headers = options.headers;
+        this.request = options.request;
+        this.partialData = options.partialData;
+    }
+}
+export function createSuccessResult(data, response, retry) {
+    return { data, error: null, response, retry };
+}
+export function createErrorResult(error, response, retry) {
+    return { data: null, error, response, retry };
+}
+export function createNetworkErrorResult(error, retry) {
+    return { data: null, error, response: null, retry };
+}

package/dist/testing.d.ts

@@ -0,0 +1,51 @@
+import type { Result } from './types.js';
+/** A JSON response with the right content-type, for use as a route value. */
+export declare function jsonResponse(body: unknown, init?: ResponseInit): Response;
+export interface RouteContext {
+    params: Record<string, string>;
+    request: Request;
+}
+export type RouteHandler = (ctx: RouteContext) => Response | Promise<Response>;
+export type RouteValue = Response | RouteHandler | Array<Response | RouteHandler>;
+export interface RecordedCall {
+    method: string;
+    url: string;
+    headers: Headers;
+    body: unknown;
+}
+/**
+ * A `fetch` stub that routes by `"METHOD /path"`, with `:token` capture.
+ *
+ * Stubs at the fetch boundary rather than the api boundary on purpose: URL
+ * building, path substitution, header merging, body serialization, response
+ * parsing and the consumer's own middleware all stay live. A test that passes
+ * while a `path: '/users/:userId'` typo ships is not doing its job.
+ *
+ * Framework-agnostic — `fetch` is a plain function, so install it whichever
+ * way your runner prefers.
+ *
+ * Honours `init.signal` as real `fetch` does: an already-aborted signal
+ * rejects with its `reason`, and so does one that aborts while a handler is
+ * still pending. That is what lets a consumer test their own timeout and
+ * cancellation handling through the stub. An aborted call is still recorded
+ * in `calls` and counted by `callCount`, but does not advance a response
+ * sequence.
+ */
+export declare function mockFetch(routes: Record<string, RouteValue>): {
+    fetch: typeof globalThis.fetch;
+    calls: RecordedCall[];
+    callCount: (key: string) => number;
+    lastCall: (key: string) => RecordedCall | undefined;
+    install(): void;
+    restore(): void;
+};
+/**
+ * A success `Result`, for consumers stubbing at the api level.
+ *
+ * Worth using rather than hand-rolling `{ data, error: null, ... }`: 3.0.0
+ * turns `Result` into a discriminated union where `response` is non-null on
+ * success, so a hand-rolled literal breaks on that upgrade and this does not.
+ */
+export declare function successResult<T>(data: T, init?: ResponseInit): Result<T>;
+/** An error `Result` with the given HTTP status. */
+export declare function errorResult<T>(status: number, body?: unknown): Result<T>;

package/dist/testing.js

@@ -0,0 +1,135 @@
+import { createSuccessResult, createErrorResult, ApiError } from './result.js';
+export function jsonResponse(body, init = {}) {
+    const headers = new Headers(init.headers);
+    if (!headers.has('content-type'))
+        headers.set('content-type', 'application/json');
+    return new Response(body === null ? '' : JSON.stringify(body), { ...init, headers });
+}
+function matchPath(routeSegments, pathname) {
+    const actual = pathname.split('/').filter(Boolean);
+    if (actual.length !== routeSegments.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < routeSegments.length; i++) {
+        const expected = routeSegments[i];
+        if (expected.startsWith(':')) {
+            params[expected.slice(1)] = decodeURIComponent(actual[i]);
+        }
+        else if (expected !== actual[i]) {
+            return null;
+        }
+    }
+    return params;
+}
+function abortable(pending, signal) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        pending.then(value => { signal.removeEventListener('abort', onAbort); resolve(value); }, (err) => { signal.removeEventListener('abort', onAbort); reject(err); });
+    });
+}
+export function mockFetch(routes) {
+    const parsed = Object.entries(routes).map(([key, value]) => {
+        const spaceAt = key.indexOf(' ');
+        if (spaceAt === -1) {
+            throw new Error(`mockFetch: route key "${key}" must be "METHOD /path" — ` +
+                `an HTTP method, a space, then the path (e.g. "GET /users/:id").`);
+        }
+        return {
+            key,
+            method: key.slice(0, spaceAt).toUpperCase(),
+            segments: key.slice(spaceAt + 1).split('/').filter(Boolean),
+            value,
+            cursor: 0,
+        };
+    });
+    const calls = [];
+    const matchedKeys = [];
+    let previousFetch;
+    let installed = false;
+    const resolveValue = (route) => {
+        if (!Array.isArray(route.value))
+            return route.value;
+        if (route.value.length === 0) {
+            throw new Error(`mockFetch: route "${route.key}" has an empty response array.`);
+        }
+        const index = Math.min(route.cursor, route.value.length - 1);
+        route.cursor++;
+        return route.value[index];
+    };
+    const mockedFetch = async (input, init = {}) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const method = (init.method ?? 'GET').toUpperCase();
+        const pathname = url.startsWith('http') ? new URL(url).pathname : url.split('?')[0];
+        calls.push({
+            method,
+            url,
+            headers: new Headers(init.headers),
+            body: init.body ?? null,
+        });
+        const signal = init.signal;
+        for (const route of parsed) {
+            if (route.method !== method)
+                continue;
+            const params = matchPath(route.segments, pathname);
+            if (!params)
+                continue;
+            matchedKeys.push(route.key);
+            if (signal?.aborted)
+                throw signal.reason;
+            const value = resolveValue(route);
+            if (typeof value !== 'function')
+                return value.clone();
+            const absoluteUrl = url.startsWith('http') ? url : new URL(url, 'http://localhost').href;
+            const request = new Request(absoluteUrl, init);
+            Object.defineProperty(request, 'url', { get: () => url });
+            return abortable(Promise.resolve(value({ params, request })), signal);
+        }
+        matchedKeys.push('');
+        throw new Error(`mockFetch: no route matched ${method} ${url}. ` +
+            `Defined routes: ${parsed.map(r => r.key).join(', ') || '(none)'}`);
+    };
+    return {
+        fetch: mockedFetch,
+        calls,
+        callCount: (key) => matchedKeys.filter(k => k === key).length,
+        lastCall: (key) => {
+            for (let i = matchedKeys.length - 1; i >= 0; i--) {
+                if (matchedKeys[i] === key)
+                    return calls[i];
+            }
+            return undefined;
+        },
+        install() {
+            if (installed)
+                return;
+            previousFetch = globalThis.fetch;
+            installed = true;
+            globalThis.fetch = mockedFetch;
+        },
+        restore() {
+            if (!installed)
+                return;
+            globalThis.fetch = previousFetch;
+            installed = false;
+        },
+    };
+}
+export function successResult(data, init = {}) {
+    const result = createSuccessResult(data, jsonResponse(data, init), async () => result);
+    return result;
+}
+export function errorResult(status, body = null) {
+    const error = new ApiError({
+        kind: 'http',
+        status,
+        statusText: '',
+        body,
+        headers: new Headers(),
+        request: { method: 'GET', url: '', params: {} },
+    });
+    const result = createErrorResult(error, jsonResponse(body, { status }), async () => result);
+    return result;
+}