tanstack-fetch 1.0.0 → 1.0.2

package/dist/client.type-Btgj3NQn.d.ts

@@ -0,0 +1,156 @@
+import { M as MaybePromise, C as ClientSource, I as IncomingHeaders, b as HttpInterceptor, P as PluginName, A as AuthConfig, S as StatusHandler, g as StatusHandlers, c as HttpMethod, h as PathParams, Q as QueryParams, a as FetchErrorInfo, F as FetchResult } from './config.type-eG_cuxpu.js';
+
+type SseEvent<T = unknown> = {
+    event?: string;
+    data: T;
+    id?: string;
+    retry?: number;
+};
+type SseSubscription = {
+    /** Stop the stream. */
+    close: () => void;
+};
+type SseHandlers<T = unknown> = {
+    /** Simple path — only the payload. */
+    onMessage?: (data: T, event: SseEvent<T>) => void;
+    /** Full SSE event (`event`, `data`, `id`). */
+    onEvent?: (event: SseEvent<T>) => void;
+    onOpen?: () => void;
+    onError?: (error: unknown) => void;
+    onClose?: () => void;
+};
+
+type UploadProgressEvent = {
+    loaded: number;
+    total?: number;
+    /** `loaded / total` when `total` is known (0–1). */
+    progress?: number;
+};
+type UploadProgressHandler = (event: UploadProgressEvent) => void;
+type FormDataPrimitive = string | number | boolean | Blob;
+type FormDataFieldValue = FormDataPrimitive | null | undefined | FormDataPrimitive[];
+type FormDataFields = Record<string, FormDataFieldValue>;
+type UploadBody = FormData | Blob | ArrayBuffer | URLSearchParams | string;
+type UploadOptions = {
+    /** Pre-built body (`FormData`, `Blob`, `File`, …). */
+    body?: UploadBody;
+    /** Single file — appended as `fieldName` (default `"file"`). */
+    file?: Blob;
+    /** Multiple files — same field name repeated. */
+    files?: Blob[];
+    /** Extra multipart fields (strings, numbers, Blobs). */
+    fields?: FormDataFields;
+    /** Form field name for `file` / `files`. Default `"file"`. */
+    fieldName?: string;
+    /** HTTP method. Default `POST`. */
+    method?: 'POST' | 'PUT' | 'PATCH';
+    onUploadProgress?: UploadProgressHandler;
+};
+
+type RequestInterceptorConfig = {
+    use?: HttpInterceptor[];
+    eject?: string[];
+};
+type RequestOptions = {
+    params?: PathParams;
+    query?: QueryParams;
+    body?: unknown;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Default `true` — matches TanStack Query `queryFn` (throw on HTTP error). */
+    throwOnError?: boolean;
+    parseAs?: 'json' | 'text' | 'blob';
+    operation?: string;
+    interceptors?: RequestInterceptorConfig;
+    /** Browser-only — uses XHR under the hood when set (fetch has no upload progress). */
+    onUploadProgress?: UploadProgressHandler;
+};
+type CreateFetchOptions = {
+    baseUrl?: string;
+    headers?: HeadersInit | (() => MaybePromise<HeadersInit>);
+    source?: ClientSource;
+    incoming?: IncomingHeaders | (() => MaybePromise<IncomingHeaders>);
+    timeoutMs?: number;
+    /** Default `true` for TanStack Query. Set `false` to get `FetchResult`. */
+    throwOnError?: boolean;
+    interceptors?: HttpInterceptor[];
+    plugins?: PluginName[];
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+    maxRetries?: number;
+    /** Simple auth: attach Bearer token on every request. */
+    getToken?: () => MaybePromise<string | null | undefined>;
+    /** Advanced auth config (overrides `getToken` when both set via `auth`). */
+    auth?: AuthConfig;
+    /** Called on HTTP 401 before the error is thrown / returned. */
+    onUnauthorized?: StatusHandler;
+    /** Called on HTTP 403. */
+    onForbidden?: StatusHandler;
+    /** Called on HTTP 404. */
+    onNotFound?: StatusHandler;
+    /** Called on HTTP 5xx (500–599). */
+    onServerError?: StatusHandler;
+    /** Advanced per-status map (`401`, `403`, `4xx`, `5xx`, `default`, …). */
+    onStatus?: StatusHandlers;
+};
+type ThrowingOptions = Omit<RequestOptions, 'throwOnError'> & {
+    throwOnError?: true;
+};
+type ResultOptions = Omit<RequestOptions, 'throwOnError'> & {
+    throwOnError: false;
+};
+type FetchMethod = {
+    <T>(path: string, options?: ThrowingOptions): Promise<T>;
+    <T, E = FetchErrorInfo>(path: string, options: ResultOptions): Promise<FetchResult<T, E>>;
+};
+type FetchRequest = {
+    <T>(method: HttpMethod, path: string, options?: ThrowingOptions): Promise<T>;
+    <T, E = FetchErrorInfo>(method: HttpMethod, path: string, options: ResultOptions): Promise<FetchResult<T, E>>;
+};
+type UploadCallOptions = Omit<RequestOptions, 'body' | 'onUploadProgress'> & UploadOptions;
+type UploadMethod = {
+    <T>(path: string, options?: UploadCallOptions & {
+        throwOnError?: true;
+    }): Promise<T>;
+    <T, E = FetchErrorInfo>(path: string, options: UploadCallOptions & {
+        throwOnError: false;
+    }): Promise<FetchResult<T, E>>;
+};
+type SseCallOptions<T = unknown> = RequestOptions & SseHandlers<T> & {
+    lastEventId?: string;
+};
+type FetchClient = {
+    use: (name: string, interceptor: Omit<HttpInterceptor, 'name'> & {
+        name?: string;
+    }, config?: {
+        order?: number;
+    }) => void;
+    eject: (name: string) => void;
+    request: FetchRequest;
+    get: FetchMethod;
+    post: FetchMethod;
+    put: FetchMethod;
+    patch: FetchMethod;
+    delete: FetchMethod;
+    /** Multipart / file upload — returns the same typed response body as `post`. */
+    upload: UploadMethod;
+    /**
+     * Simple: pass `onMessage` / `onEvent` → returns `{ close }`.
+     * Advanced: no handlers → `AsyncIterable` for `for await`.
+     */
+    sse: {
+        <T>(path: string, options: SseCallOptions<T> & ({
+            onMessage: SseHandlers<T>['onMessage'];
+        } | {
+            onEvent: SseHandlers<T>['onEvent'];
+        })): SseSubscription;
+        <T>(path: string, options?: SseCallOptions<T>): AsyncIterable<SseEvent<T>>;
+    };
+};
+/** @deprecated Use CreateFetchOptions */
+type CreateClientOptions = CreateFetchOptions;
+/** @deprecated Use FetchClient */
+type HttpClient = FetchClient;
+
+export type { CreateFetchOptions as C, FetchClient as F, HttpClient as H, RequestOptions as R, SseCallOptions as S, UploadCallOptions as U, FormDataFields as a, CreateClientOptions as b, FormDataFieldValue as c, SseEvent as d, SseHandlers as e, SseSubscription as f, UploadOptions as g, UploadProgressEvent as h, UploadProgressHandler as i };

package/dist/config.type-eG_cuxpu.d.cts

@@ -0,0 +1,132 @@
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+type ClientSource = 'browser' | 'ssr' | 'edge';
+type IncomingHeaders = {
+    cookie?: string;
+    authorization?: string;
+    requestId?: string;
+};
+type PathParams = Record<string, string | number>;
+type QueryParams = Record<string, string | number | boolean | undefined | null>;
+type PluginName = 'trace' | 'ssr-forward' | 'retry-idempotent' | 'sse-resume';
+type MaybePromise<T> = T | Promise<T>;
+
+type OkResult<T> = {
+    ok: true;
+    status: number;
+    data: T;
+    headers: Headers;
+};
+type ErrResult<E> = {
+    ok: false;
+    status: number;
+    error: E;
+    headers: Headers;
+};
+type FetchResult<T, E = FetchErrorInfo> = OkResult<T> | ErrResult<E>;
+type FetchErrorInfo = {
+    status: number;
+    code: string;
+    message: string;
+    body: unknown;
+};
+/** @deprecated Use FetchResult */
+type HttpResult<T, E = FetchErrorInfo> = FetchResult<T, E>;
+/** @deprecated Use FetchErrorInfo */
+type HttpError = FetchErrorInfo;
+
+type RequestContext = {
+    request: {
+        method: HttpMethod;
+        url: URL;
+        headers: Headers;
+        body?: unknown;
+        signal?: AbortSignal;
+    };
+    response?: Response;
+    data?: unknown;
+    error?: FetchErrorInfo;
+    incoming?: IncomingHeaders;
+    meta: {
+        attempt: number;
+        maxRetries: number;
+        source: ClientSource;
+        operation?: string;
+        requestId?: string;
+        lastEventId?: string;
+    };
+};
+type SseEventContext<T = unknown> = RequestContext & {
+    event: {
+        event?: string;
+        data: T;
+        id?: string;
+        retry?: number;
+    };
+};
+type InterceptorDecision<T> = {
+    action: 'continue';
+    context?: T;
+} | {
+    action: 'skip';
+} | {
+    action: 'drop';
+} | {
+    action: 'retry';
+    delayMs?: number;
+} | {
+    action: 'short-circuit';
+    result: FetchResult<unknown, unknown>;
+};
+type InterceptorHandler<T> = (context: T) => MaybePromise<InterceptorDecision<T> | void>;
+type HttpInterceptor = {
+    name: string;
+    order?: number;
+    match?: {
+        operation?: string;
+        method?: HttpMethod;
+        pathPrefix?: string;
+        status?: number;
+    };
+    onRequest?: InterceptorHandler<RequestContext>;
+    onRequestError?: InterceptorHandler<RequestContext>;
+    onResponse?: InterceptorHandler<RequestContext>;
+    onResponseError?: InterceptorHandler<RequestContext>;
+    onSseOpen?: InterceptorHandler<RequestContext>;
+    onSseEvent?: InterceptorHandler<SseEventContext>;
+    onSseError?: InterceptorHandler<RequestContext>;
+    onSseReconnect?: InterceptorHandler<RequestContext>;
+};
+
+type StatusHandlerInput = {
+    status: number;
+    error: FetchErrorInfo;
+    context: RequestContext;
+};
+type StatusHandlerResult = void | {
+    action: 'continue';
+} | {
+    action: 'retry';
+    delayMs?: number;
+};
+type StatusHandler = (input: StatusHandlerInput) => MaybePromise<StatusHandlerResult>;
+type StatusHandlers = {
+    401?: StatusHandler;
+    403?: StatusHandler;
+    404?: StatusHandler;
+    500?: StatusHandler;
+    '4xx'?: StatusHandler;
+    '5xx'?: StatusHandler;
+    default?: StatusHandler;
+} & {
+    [status: number]: StatusHandler | undefined;
+};
+type AuthConfig = {
+    /** Return access token (or null/undefined to skip). */
+    getToken: () => MaybePromise<string | null | undefined>;
+    /** Header name. Default: `authorization`. */
+    header?: string;
+    /** Prefix before token. Default: `Bearer`. Use `''` for raw token. */
+    scheme?: string;
+};
+
+export type { AuthConfig as A, ClientSource as C, FetchResult as F, HttpError as H, IncomingHeaders as I, MaybePromise as M, PluginName as P, QueryParams as Q, RequestContext as R, StatusHandler as S, FetchErrorInfo as a, HttpInterceptor as b, HttpMethod as c, HttpResult as d, StatusHandlerInput as e, StatusHandlerResult as f, StatusHandlers as g, PathParams as h };

package/dist/config.type-eG_cuxpu.d.ts

@@ -0,0 +1,132 @@
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+type ClientSource = 'browser' | 'ssr' | 'edge';
+type IncomingHeaders = {
+    cookie?: string;
+    authorization?: string;
+    requestId?: string;
+};
+type PathParams = Record<string, string | number>;
+type QueryParams = Record<string, string | number | boolean | undefined | null>;
+type PluginName = 'trace' | 'ssr-forward' | 'retry-idempotent' | 'sse-resume';
+type MaybePromise<T> = T | Promise<T>;
+
+type OkResult<T> = {
+    ok: true;
+    status: number;
+    data: T;
+    headers: Headers;
+};
+type ErrResult<E> = {
+    ok: false;
+    status: number;
+    error: E;
+    headers: Headers;
+};
+type FetchResult<T, E = FetchErrorInfo> = OkResult<T> | ErrResult<E>;
+type FetchErrorInfo = {
+    status: number;
+    code: string;
+    message: string;
+    body: unknown;
+};
+/** @deprecated Use FetchResult */
+type HttpResult<T, E = FetchErrorInfo> = FetchResult<T, E>;
+/** @deprecated Use FetchErrorInfo */
+type HttpError = FetchErrorInfo;
+
+type RequestContext = {
+    request: {
+        method: HttpMethod;
+        url: URL;
+        headers: Headers;
+        body?: unknown;
+        signal?: AbortSignal;
+    };
+    response?: Response;
+    data?: unknown;
+    error?: FetchErrorInfo;
+    incoming?: IncomingHeaders;
+    meta: {
+        attempt: number;
+        maxRetries: number;
+        source: ClientSource;
+        operation?: string;
+        requestId?: string;
+        lastEventId?: string;
+    };
+};
+type SseEventContext<T = unknown> = RequestContext & {
+    event: {
+        event?: string;
+        data: T;
+        id?: string;
+        retry?: number;
+    };
+};
+type InterceptorDecision<T> = {
+    action: 'continue';
+    context?: T;
+} | {
+    action: 'skip';
+} | {
+    action: 'drop';
+} | {
+    action: 'retry';
+    delayMs?: number;
+} | {
+    action: 'short-circuit';
+    result: FetchResult<unknown, unknown>;
+};
+type InterceptorHandler<T> = (context: T) => MaybePromise<InterceptorDecision<T> | void>;
+type HttpInterceptor = {
+    name: string;
+    order?: number;
+    match?: {
+        operation?: string;
+        method?: HttpMethod;
+        pathPrefix?: string;
+        status?: number;
+    };
+    onRequest?: InterceptorHandler<RequestContext>;
+    onRequestError?: InterceptorHandler<RequestContext>;
+    onResponse?: InterceptorHandler<RequestContext>;
+    onResponseError?: InterceptorHandler<RequestContext>;
+    onSseOpen?: InterceptorHandler<RequestContext>;
+    onSseEvent?: InterceptorHandler<SseEventContext>;
+    onSseError?: InterceptorHandler<RequestContext>;
+    onSseReconnect?: InterceptorHandler<RequestContext>;
+};
+
+type StatusHandlerInput = {
+    status: number;
+    error: FetchErrorInfo;
+    context: RequestContext;
+};
+type StatusHandlerResult = void | {
+    action: 'continue';
+} | {
+    action: 'retry';
+    delayMs?: number;
+};
+type StatusHandler = (input: StatusHandlerInput) => MaybePromise<StatusHandlerResult>;
+type StatusHandlers = {
+    401?: StatusHandler;
+    403?: StatusHandler;
+    404?: StatusHandler;
+    500?: StatusHandler;
+    '4xx'?: StatusHandler;
+    '5xx'?: StatusHandler;
+    default?: StatusHandler;
+} & {
+    [status: number]: StatusHandler | undefined;
+};
+type AuthConfig = {
+    /** Return access token (or null/undefined to skip). */
+    getToken: () => MaybePromise<string | null | undefined>;
+    /** Header name. Default: `authorization`. */
+    header?: string;
+    /** Prefix before token. Default: `Bearer`. Use `''` for raw token. */
+    scheme?: string;
+};
+
+export type { AuthConfig as A, ClientSource as C, FetchResult as F, HttpError as H, IncomingHeaders as I, MaybePromise as M, PluginName as P, QueryParams as Q, RequestContext as R, StatusHandler as S, FetchErrorInfo as a, HttpInterceptor as b, HttpMethod as c, HttpResult as d, StatusHandlerInput as e, StatusHandlerResult as f, StatusHandlers as g, PathParams as h };