tanstack-fetch 1.0.0

package/dist/fetch-error-B10Od9AT.d.cts

@@ -0,0 +1,257 @@
+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;
+};
+
+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 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;
+};
+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 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;
+    /**
+     * 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;
+
+type FetchError = Error & {
+    readonly name: 'FetchError';
+    readonly status: number;
+    readonly code: string;
+    readonly body: unknown;
+    readonly headers: Headers;
+    readonly result: FetchResult<never, FetchErrorInfo>;
+};
+declare const createFetchError: (result: FetchResult<never, FetchErrorInfo>) => FetchError;
+declare const isFetchError: (error: unknown) => error is FetchError;
+declare const isAbortError: (error: unknown) => boolean;
+
+export { type AuthConfig as A, type CreateFetchOptions as C, type FetchClient as F, type HttpInterceptor as H, type IncomingHeaders as I, type PluginName as P, type RequestContext as R, type StatusHandlers as S, type FetchResult as a, type FetchErrorInfo as b, type CreateClientOptions as c, type FetchError as d, type HttpClient as e, type HttpError as f, type HttpMethod as g, type HttpResult as h, type RequestOptions as i, type SseCallOptions as j, type SseEvent as k, type SseHandlers as l, type SseSubscription as m, type StatusHandler as n, type StatusHandlerInput as o, type StatusHandlerResult as p, createFetchError as q, isAbortError as r, isFetchError as s };

package/dist/fetch-error-B10Od9AT.d.ts

@@ -0,0 +1,257 @@
+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;
+};
+
+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 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;
+};
+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 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;
+    /**
+     * 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;
+
+type FetchError = Error & {
+    readonly name: 'FetchError';
+    readonly status: number;
+    readonly code: string;
+    readonly body: unknown;
+    readonly headers: Headers;
+    readonly result: FetchResult<never, FetchErrorInfo>;
+};
+declare const createFetchError: (result: FetchResult<never, FetchErrorInfo>) => FetchError;
+declare const isFetchError: (error: unknown) => error is FetchError;
+declare const isAbortError: (error: unknown) => boolean;
+
+export { type AuthConfig as A, type CreateFetchOptions as C, type FetchClient as F, type HttpInterceptor as H, type IncomingHeaders as I, type PluginName as P, type RequestContext as R, type StatusHandlers as S, type FetchResult as a, type FetchErrorInfo as b, type CreateClientOptions as c, type FetchError as d, type HttpClient as e, type HttpError as f, type HttpMethod as g, type HttpResult as h, type RequestOptions as i, type SseCallOptions as j, type SseEvent as k, type SseHandlers as l, type SseSubscription as m, type StatusHandler as n, type StatusHandlerInput as o, type StatusHandlerResult as p, createFetchError as q, isAbortError as r, isFetchError as s };