@fuman/fetch 0.0.4 → 0.0.6

package/_types.d.cts

@@ -0,0 +1,8 @@
+import { Middleware } from '@fuman/utils';
+import { FfetchAddon } from './addons/types.js';
+export type FetchLike = (req: Request) => Promise<Response>;
+export type FfetchMiddleware = Middleware<Request, Response>;
+export type CombineAddons<ResponseMixins extends FfetchAddon<any, any>[], AccRequest = {}, AccResponse = {}> = ResponseMixins extends [FfetchAddon<infer RequestMixin, infer ResponseMixin>, ...infer Rest extends FfetchAddon<any, any>[]] ? CombineAddons<Rest, AccRequest & RequestMixin, AccResponse & ResponseMixin> : {
+    readonly request: AccRequest;
+    readonly response: AccResponse;
+};

package/addons/_utils.d.cts

@@ -0,0 +1,3 @@
+import { FfetchOptions } from '../ffetch.js';
+export declare function urlencode(query: Record<string, unknown>): URLSearchParams;
+export declare function setHeader(options: FfetchOptions, key: string, value: string | null): void;

package/addons/bundle.d.cts

@@ -0,0 +1,7 @@
+export * from './form.js';
+export * from './multipart.js';
+export * from './parse/addon.js';
+export * from './query.js';
+export * from './rate-limit.js';
+export * from './retry.js';
+export * from './timeout.js';

package/addons/form.d.cts

@@ -0,0 +1,22 @@
+import { FfetchAddon } from './types.js';
+export interface FormAddon {
+    /**
+     * shorthand for sending form body,
+     * mutually exclusive with other body options
+     *
+     * if form is passed in base options, passing one
+     * in the request options will override it completely
+     */
+    form?: Record<string, unknown>;
+}
+export interface FormAddonOptions {
+    /**
+     * serializer for the form data.
+     * given the form data it should return the serialized data
+     *
+     * @defaults `URLSearchParams`-based serializer
+     * @example `serialize({ a: 123, b: 'hello' }) => 'a=123&b=hello'`
+     */
+    serialize?: (data: Record<string, unknown>) => BodyInit;
+}
+export declare function form(options?: FormAddonOptions): FfetchAddon<FormAddon, object>;

package/addons/index.d.cts

@@ -0,0 +1,3 @@
+import * as ffetchAddons from './bundle.js';
+export { ffetchAddons };
+export * from './types.js';

package/addons/multipart.d.cts

@@ -0,0 +1,22 @@
+import { FfetchAddon } from './types.js';
+export interface MultipartAddon {
+    /**
+     * shorthand for sending multipart form body,
+     * useful for file uploads and similar.
+     * mutually exclusive with other body options
+     *
+     * if multipart is passed in base options, passing one
+     * in the request options will override it completely
+     */
+    multipart?: Record<string, unknown>;
+}
+export interface MultipartAddonOptions {
+    /**
+     * serializer for the form data.
+     * given the form data it should return the body
+     *
+     * @defaults basic `FormData`-based serializer
+     */
+    serialize?: (data: Record<string, unknown>) => FormData;
+}
+export declare function multipart(options?: MultipartAddonOptions): FfetchAddon<MultipartAddon, object>;

package/addons/parse/_types.d.cts

@@ -0,0 +1,11 @@
+export interface FfetchTypeProvider {
+    readonly schema: unknown;
+    readonly parsed: unknown;
+}
+export interface FfetchParser<TypeProvider extends FfetchTypeProvider> {
+    readonly _provider: TypeProvider;
+    parse: (schema: unknown, value: unknown) => unknown | Promise<unknown>;
+}
+export type CallTypeProvider<TypeProvider extends FfetchTypeProvider, Schema> = (TypeProvider & {
+    schema: Schema;
+})['parsed'];

package/addons/parse/adapters/valibot.d.cts

@@ -0,0 +1,8 @@
+import { BaseIssue, BaseSchema, BaseSchemaAsync, Config, InferOutput } from 'valibot';
+import { FfetchParser, FfetchTypeProvider } from '../_types.js';
+export interface ValibotTypeProvider extends FfetchTypeProvider {
+    readonly parsed: this['schema'] extends (BaseSchema<unknown, unknown, BaseIssue<unknown>> | BaseSchemaAsync<unknown, unknown, BaseIssue<unknown>>) ? InferOutput<this['schema']> : never;
+}
+export declare function ffetchValibotAdapter({ async, ...rest }?: Partial<Config<BaseIssue<unknown>>> & {
+    async?: boolean;
+}): FfetchParser<ValibotTypeProvider>;

package/addons/parse/adapters/valita.d.cts

@@ -0,0 +1,8 @@
+import { FfetchParser, FfetchTypeProvider } from '../_types.js';
+import type * as v from '@badrap/valita';
+export interface ValitaTypeProvider extends FfetchTypeProvider {
+    readonly parsed: this['schema'] extends v.Type<any> ? v.Infer<this['schema']> : never;
+}
+type ParseOptions = NonNullable<Parameters<v.Type<any>['parse']>[1]>;
+export declare function ffetchValitaAdapter(options?: ParseOptions): FfetchParser<ValitaTypeProvider>;
+export {};

package/addons/parse/adapters/yup.d.cts

@@ -0,0 +1,13 @@
+import { CastOptions, InferType, ISchema, ValidateOptions } from 'yup';
+import { FfetchParser, FfetchTypeProvider } from '../_types.js';
+export interface YupTypeProvider extends FfetchTypeProvider {
+    readonly parsed: this['schema'] extends ISchema<any, any> ? InferType<this['schema']> : never;
+}
+export type FfetchYupAdapterOptions = {
+    action: 'cast';
+    options?: CastOptions;
+} | {
+    action: 'validate';
+    options?: ValidateOptions;
+};
+export declare function ffetchYupAdapter({ action, options, }?: FfetchYupAdapterOptions): FfetchParser<YupTypeProvider>;

package/addons/parse/adapters/zod.d.cts

@@ -0,0 +1,6 @@
+import { ParseParams, z } from 'zod';
+import { FfetchParser, FfetchTypeProvider } from '../_types.js';
+export interface ZodTypeProvider extends FfetchTypeProvider {
+    readonly parsed: this['schema'] extends z.ZodTypeAny ? z.infer<this['schema']> : never;
+}
+export declare function ffetchZodAdapter({ async, ...rest }?: Partial<ParseParams>): FfetchParser<ZodTypeProvider>;

package/addons/parse/addon.d.cts

@@ -0,0 +1,6 @@
+import { FfetchAddon } from '../types.js';
+import { CallTypeProvider, FfetchParser, FfetchTypeProvider } from './_types.js';
+export { FfetchParser, FfetchTypeProvider };
+export declare function parser<TypeProvider extends FfetchTypeProvider>(parser: FfetchParser<TypeProvider>): FfetchAddon<object, {
+    parsedJson: <Schema>(schema: Schema) => Promise<CallTypeProvider<TypeProvider, Schema>>;
+}>;

package/addons/query.d.cts

@@ -0,0 +1,17 @@
+import { FfetchAddon } from './types.js';
+export interface QueryAddon {
+    /** query params to be appended to the url */
+    query?: Record<string, unknown>;
+}
+export interface QueryAddonOptions {
+    /**
+     * serializer for the query params.
+     * given the query params and the url, it should return the serialized url
+     * with the query params added
+     *
+     * @defaults `URLSearchParams`-based serializer, preserving all existing query params
+     * @example `serialize({ a: 123, b: 'hello' }, 'https://example.com/api') => 'https://example.com/api?a=123&b=hello'`
+     */
+    serialize?: (query: Record<string, unknown>, url: string) => string;
+}
+export declare function query(options?: QueryAddonOptions): FfetchAddon<QueryAddon, object>;

package/addons/rate-limit.d.cts

@@ -0,0 +1,62 @@
+import { FfetchAddon } from './types.js';
+import { MaybePromise } from '@fuman/utils';
+export interface RateLimitAddon {
+    rateLimit?: {
+        /**
+         * check if the request was rejected due to rate limit
+         *
+         * @default `res => res.status === 429`
+         */
+        isRejected?: (res: Response) => MaybePromise<boolean>;
+        /**
+         * getter for the unix timestamp of the next reset
+         * can either be a unix timestamp in seconds or an ISO 8601 date string
+         *
+         * @default `res => res.headers.get('x-ratelimit-reset')`
+         */
+        getReset?: (res: Response) => MaybePromise<string | number | null>;
+        /**
+         * when the rate limit is exceeded (i.e. `isRejected` returns true),
+         * but the reset time is unknown (i.e. `getReset` returns `null`),
+         * what is the default time to wait until the rate limit is reset?
+         * in milliseconds
+         *
+         * @default `30_000`
+         */
+        defaultWaitTime?: number;
+        /**
+         * number of milliseconds to add to the reset time when the rate limit is exceeded,
+         * to account for network latency and other factors
+         *
+         * @default `5000`
+         */
+        jitter?: number;
+        /**
+         * when the rate limit has exceeded (i.e. `isRejected` returns true),
+         * what is the maximum acceptable time to wait until the rate limit is reset?
+         * in milliseconds
+         *
+         * @default `300_000`
+         */
+        maxWaitTime?: number;
+        /**
+         * maximum number of retries
+         *
+         * @default `3`
+         */
+        maxRetries?: number;
+        /**
+         * function that will be called when the rate limit is exceeded (i.e. `isRejected` returns true),
+         * but before starting the wait timer
+         *
+         * @param res the response that caused the rate limit to be exceeded
+         * @param waitTime the time to wait until the rate limit is reset (in milliseconds)
+         */
+        onRateLimitExceeded?: (res: Response, waitTime: number) => void;
+    };
+}
+/**
+ * ffetch addon that handles "rate limit exceeded" errors,
+ * and waits until the rate limit is reset
+ */
+export declare function rateLimitHandler(): FfetchAddon<RateLimitAddon, object>;

package/addons/retry.d.cts

@@ -0,0 +1,59 @@
+import { FfetchAddon } from './types.js';
+export declare class RetriesExceededError extends Error {
+    readonly retries: number;
+    readonly request: Request;
+    constructor(retries: number, request: Request);
+}
+export interface RetryOptions {
+    /**
+     * max number of retries
+     * @default 5
+     */
+    maxRetries?: number;
+    /**
+     * delay between retries
+     * @default retryCount * 1000, up to 5000
+     */
+    retryDelay?: number | ((retryCount: number) => number);
+    /**
+     * function that will be called before starting the retry loop.
+     * if it returns false, the retry loop will be skipped and
+     * the error will be thrown immediately
+     *
+     * @default () => false
+     */
+    skip?: (request: Request) => boolean;
+    /**
+     * function that will be called before a retry is attempted,
+     * and can be used to modify the request before proceeding
+     *
+     * @param attempt  current retry attempt (starts at 0)
+     */
+    onRetry?: (attempt: number, request: Request) => Request | void;
+    /**
+     * function that will be called whenever a response is received,
+     * and should return whether the response is valid (i.e. should be returned and not retried)
+     *
+     * @default  `response => response.status < 500`
+     */
+    onResponse?: (response: Response, request: Request) => boolean;
+    /**
+     * function that will be called if an error is thrown while calling
+     * the rest of the middleware chain,
+     * and should return whether the error should be retried
+     *
+     * @default  `() => true`
+     */
+    onError?: (err: unknown, request: Request) => boolean;
+    /**
+     * if true, the last response will be returned if the number of retries is exceeded
+     * instead of throwing {@link RetriesExceededError}
+     *
+     * @default false
+     */
+    returnLastResponse?: boolean;
+}
+export interface RetryAddon {
+    retry?: RetryOptions | false;
+}
+export declare function retry(): FfetchAddon<RetryAddon, object>;

package/addons/retry.d.ts

@@ -53,6 +53,7 @@ export interface RetryOptions {
      */
     returnLastResponse?: boolean;
 }
-export declare function retry(): FfetchAddon<{
+export interface RetryAddon {
     retry?: RetryOptions | false;
-}, object>;
+}
+export declare function retry(): FfetchAddon<RetryAddon, object>;

package/addons/timeout.d.cts

@@ -0,0 +1,25 @@
+import { FetchAddonCtx, FfetchAddon } from './types.js';
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(timeout: number);
+}
+export interface TimeoutAddon {
+    /**
+     * timeout for the request in ms
+     *
+     * pass `Infinity` or `0` to disable the default timeout from the base options
+     *
+     * when the timeout is reached, the request will be aborted
+     * and the promise will be rejected with a TimeoutError
+     */
+    timeout?: number | ((ctx: FetchAddonCtx<TimeoutAddon>) => number);
+}
+/**
+ * ffetch addon that allows setting a timeout for the request.
+ * when the timeout is reached, the request will be aborted
+ * and the promise will be rejected with a TimeoutError
+ *
+ * **note**: it is important to put this addon as the last one,
+ * otherwise other middlewares might be counted towards the timeout
+ */
+export declare function timeout(): FfetchAddon<TimeoutAddon, object>;

package/addons/tough-cookie.d.cts

@@ -0,0 +1,7 @@
+import { CookieJar } from 'tough-cookie';
+import { FfetchAddon } from './types.js';
+export interface FfetchToughCookieAddon {
+    /** cookie jar to use */
+    cookies?: CookieJar;
+}
+export declare function toughCookieAddon(): FfetchAddon<FfetchToughCookieAddon, object>;

package/addons/types.d.cts

@@ -0,0 +1,30 @@
+import { FfetchOptions, FfetchResult } from '../ffetch.js';
+/**
+ * context that is passed to each addon in the order they were added
+ * you can safely modify anything in this object
+ */
+export interface FetchAddonCtx<RequestMixin extends object> {
+    /** url of the request (with baseUrl already applied) */
+    url: string;
+    /** options of this specific request */
+    options: FfetchOptions & RequestMixin;
+    /** base options passed to `createFfetch` */
+    baseOptions: FfetchOptions & RequestMixin;
+}
+/** internals that are exposed to the functions in response mixin */
+export type FfetchResultInternals<RequestMixin extends object> = FfetchResult & {
+    /** final url of the request */
+    _url: string;
+    /** request init object that will be passed to fetch */
+    _init: RequestInit;
+    /** finalized and merged options */
+    _options: FfetchOptions & RequestMixin;
+    /** finalized and merged headers */
+    _headers?: Record<string, string>;
+};
+export interface FfetchAddon<RequestMixin extends object, ResponseMixin extends object> {
+    /** function that will be called before each request */
+    beforeRequest?: (ctx: FetchAddonCtx<RequestMixin>) => void;
+    /** mixin functions that will be added to the response promise */
+    response?: ResponseMixin;
+}

package/default.cjs

@@ -5,11 +5,13 @@ const timeout = require("./addons/timeout.cjs");
 const query = require("./addons/query.cjs");
 const form = require("./addons/form.cjs");
 const multipart = require("./addons/multipart.cjs");
+const retry = require("./addons/retry.cjs");
 const ffetchDefaultAddons = [
   /* @__PURE__ */ timeout.timeout(),
   /* @__PURE__ */ query.query(),
   /* @__PURE__ */ form.form(),
-  /* @__PURE__ */ multipart.multipart()
+  /* @__PURE__ */ multipart.multipart(),
+  /* @__PURE__ */ retry.retry()
 ];
 const ffetchBase = /* @__PURE__ */ ffetch.createFfetch({
   addons: ffetchDefaultAddons

package/default.d.cts

@@ -0,0 +1,31 @@
+import { FfetchAddon, ffetchAddons } from './addons/index.js';
+import { Ffetch } from './ffetch.js';
+export declare const ffetchDefaultAddons: [
+    FfetchAddon<ffetchAddons.TimeoutAddon, object>,
+    FfetchAddon<ffetchAddons.QueryAddon, object>,
+    FfetchAddon<ffetchAddons.FormAddon, object>,
+    FfetchAddon<ffetchAddons.MultipartAddon, object>,
+    FfetchAddon<ffetchAddons.RetryAddon, object>
+];
+/**
+ * the default ffetch instance with a reasonable default set of addons
+ *
+ * you can use this as a base to create your project-specific fetch instance,
+ * or use this as is.
+ *
+ * this is not exported as `ffetch` because most of the time you will want to extend it,
+ * and exporting it as `ffetch` would make them clash in import suggestions,
+ * and will also make it prone to subtle bugs.
+ *
+ * @example
+ * ```ts
+ * import { ffetchBase } from '@fuman/fetch'
+ *
+ * const ffetch = ffetchBase.extend({
+ *   baseUrl: 'https://example.com',
+ *   headers: { ... },
+ *   addons: [ ... ],
+ * })
+ * ```
+ */
+export declare const ffetchBase: Ffetch<ffetchAddons.TimeoutAddon & ffetchAddons.QueryAddon & ffetchAddons.FormAddon & ffetchAddons.MultipartAddon & ffetchAddons.RetryAddon, object>;

package/default.d.ts

@@ -4,10 +4,11 @@ export declare const ffetchDefaultAddons: [
     FfetchAddon<ffetchAddons.TimeoutAddon, object>,
     FfetchAddon<ffetchAddons.QueryAddon, object>,
     FfetchAddon<ffetchAddons.FormAddon, object>,
-    FfetchAddon<ffetchAddons.MultipartAddon, object>
+    FfetchAddon<ffetchAddons.MultipartAddon, object>,
+    FfetchAddon<ffetchAddons.RetryAddon, object>
 ];
 /**
- * the default ffetch instance with reasonable default set of addons
+ * the default ffetch instance with a reasonable default set of addons
  *
  * you can use this as a base to create your project-specific fetch instance,
  * or use this as is.
@@ -27,4 +28,4 @@ export declare const ffetchDefaultAddons: [
  * })
  * ```
  */
-export declare const ffetchBase: Ffetch<ffetchAddons.TimeoutAddon & ffetchAddons.QueryAddon & ffetchAddons.FormAddon & ffetchAddons.MultipartAddon, object>;
+export declare const ffetchBase: Ffetch<ffetchAddons.TimeoutAddon & ffetchAddons.QueryAddon & ffetchAddons.FormAddon & ffetchAddons.MultipartAddon & ffetchAddons.RetryAddon, object>;

package/default.js

@@ -3,11 +3,13 @@ import { timeout } from "./addons/timeout.js";
 import { query } from "./addons/query.js";
 import { form } from "./addons/form.js";
 import { multipart } from "./addons/multipart.js";
+import { retry } from "./addons/retry.js";
 const ffetchDefaultAddons = [
   /* @__PURE__ */ timeout(),
   /* @__PURE__ */ query(),
   /* @__PURE__ */ form(),
-  /* @__PURE__ */ multipart()
+  /* @__PURE__ */ multipart(),
+  /* @__PURE__ */ retry()
 ];
 const ffetchBase = /* @__PURE__ */ createFfetch({
   addons: ffetchDefaultAddons

package/ffetch.cjs

@@ -7,6 +7,8 @@ class HttpError extends Error {
     super(`HTTP Error ${response.status} ${response.statusText}`);
     this.response = response;
   }
+  body = null;
+  bodyText = null;
 }
 function headersToObject(headers) {
   if (!headers) return {};
@@ -45,15 +47,27 @@ class FfetchResultImpl {
   }
   async #fetchAndValidate() {
     const res = await this.#fetch(new Request(this._url, this._init));
+    let err = null;
     if (this._options.validateResponse === void 0 || this._options.validateResponse !== false) {
       if (typeof this._options.validateResponse === "function") {
         if (!await this._options.validateResponse(res)) {
-          throw new HttpError(res);
+          err = new HttpError(res);
         }
       } else if (!res.ok) {
-        throw new HttpError(res);
+        err = new HttpError(res);
       }
     }
+    if (err != null) {
+      if (this._options.readBodyOnError !== false) {
+        try {
+          ;
+          err.body = new Uint8Array(await res.arrayBuffer());
+          err.bodyText = utils.utf8.decoder.decode(err.body);
+        } catch {
+        }
+      }
+      throw err;
+    }
     return res;
   }
   async raw() {
@@ -142,8 +156,16 @@ function createFfetch(baseOptions = {}) {
     if (options.middlewares !== void 0 && options.middlewares.length > 0) {
       fetcher = utils.composeMiddlewares(options.middlewares, wrappedFetch);
     }
-    if (baseOptions?.baseUrl != null || options.baseUrl != null) {
-      url = new URL(url, options.baseUrl ?? baseOptions?.baseUrl).href;
+    if ((baseOptions?.baseUrl != null || options.baseUrl != null) && !url.includes("://")) {
+      const baseUrl = options.baseUrl ?? baseOptions?.baseUrl;
+      let prepend = baseUrl;
+      if (prepend[prepend.length - 1] !== "/") {
+        prepend += "/";
+      }
+      if (url[0] === "/") {
+        url = url.slice(1);
+      }
+      url = prepend + url;
     }
     let init;
     let headers;

package/ffetch.d.cts

@@ -0,0 +1,115 @@
+import { CombineAddons, FfetchMiddleware } from './_types.js';
+import { FfetchAddon } from './addons/types.js';
+export interface FfetchOptions {
+    /**
+     * http method
+     * @default 'GET'
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | (string & {});
+    /**
+     * whether to throw HttpError on non-2xx responses
+     *
+     * when a function is provided, it will be called with the response
+     * and should return whether the response is valid.
+     * if it returns false, the response will be thrown as an HttpError
+     *
+     * @default true
+     */
+    validateResponse?: false | ((res: Response) => boolean | Promise<boolean>);
+    /**
+     * whether to read the body of the response on HttpError (i.e. when `validateResponse` returns false).
+     * useful for debugging, but may be undesirable in some cases.
+     *
+     * @default true
+     */
+    readBodyOnError?: boolean;
+    /**
+     * base url to be prepended to the url
+     *
+     * this base url is **always** treated as a "base path", i.e. the path passed to `ffetch()`
+     * will always be appended to it (unlike the `new URL()`, which has ambiguous slash semantics)
+     */
+    baseUrl?: string;
+    /** body to be passed to fetch() */
+    body?: BodyInit;
+    /**
+     * shorthand for sending json body.
+     * mutually exclusive with `body`
+     */
+    json?: unknown;
+    /** headers to be passed to fetch() */
+    headers?: HeadersInit;
+    /** middlewares for the requests */
+    middlewares?: FfetchMiddleware[];
+    /** any additional options to be passed to fetch() */
+    extra?: RequestInit;
+}
+export interface FfetchBaseOptions<Addons extends FfetchAddon<any, any>[] = FfetchAddon<any, any>[]> extends FfetchOptions {
+    /** implementation of fetch() */
+    fetch?: typeof fetch;
+    /** addons for the request */
+    addons?: Addons;
+    /**
+     * whether to capture stack trace for errors
+     * may slightly impact performance
+     *
+     * @default true
+     */
+    captureStackTrace?: boolean;
+}
+export interface FfetchResult extends Promise<Response> {
+    raw: () => Promise<Response>;
+    stream: () => Promise<ReadableStream<Uint8Array>>;
+    json: <T = unknown>() => Promise<T>;
+    text: () => Promise<string>;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    blob: () => Promise<Blob>;
+}
+/**
+ * the main function of the library
+ *
+ * @param url  url to fetch (or path, if baseUrl is set)
+ * @param params  options (note that the function may mutate the object, do not rely on its immutability)
+ */
+export interface Ffetch<RequestMixin, ResponseMixin> {
+    (url: string, params?: FfetchOptions & RequestMixin): FfetchResult & ResponseMixin;
+    /** shorthand for making a GET request */
+    get: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /** shorthand for making a POST request */
+    post: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /** shorthand for making a PUT request */
+    put: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /** shorthand for making a DELETE request */
+    delete: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /** shorthand for making a PATCH request */
+    patch: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /** shorthand for making a HEAD request */
+    head: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /** shorthand for making an OPTIONS request */
+    options: (url: string, params?: FfetchOptions & RequestMixin) => FfetchResult & ResponseMixin;
+    /**
+     * extend the base options with the given options
+     *
+     * note: addons, middlewares and headers will be merged with the base options,
+     * the rest of the options will be overridden
+     */
+    extend: <const Addons extends FfetchAddon<any, any>[], Combined extends {
+        request: object;
+        response: object;
+    } = CombineAddons<Addons>>(baseOptions: FfetchBaseOptions<Addons> & Combined['request']) => Ffetch<RequestMixin & Combined['request'], ResponseMixin & Combined['response']>;
+}
+/**
+ * an error that is thrown when the response status is not 2xx,
+ * or `validateResponse` returns false
+ */
+export declare class HttpError extends Error {
+    readonly response: Response;
+    readonly body: Uint8Array | null;
+    readonly bodyText: string | null;
+    constructor(response: Response);
+}
+/** create a new ffetch function with the given base options */
+export declare function createFfetch<const Addons extends FfetchAddon<any, any>[], Combined extends {
+    request: object;
+    response: object;
+} = CombineAddons<Addons>>(baseOptions?: FfetchBaseOptions<Addons> & Combined['request']): Ffetch<Combined['request'], Combined['response']>;

package/ffetch.d.ts

@@ -16,7 +16,19 @@ export interface FfetchOptions {
      * @default true
      */
     validateResponse?: false | ((res: Response) => boolean | Promise<boolean>);
-    /** base url to be prepended to the url */
+    /**
+     * whether to read the body of the response on HttpError (i.e. when `validateResponse` returns false).
+     * useful for debugging, but may be undesirable in some cases.
+     *
+     * @default true
+     */
+    readBodyOnError?: boolean;
+    /**
+     * base url to be prepended to the url
+     *
+     * this base url is **always** treated as a "base path", i.e. the path passed to `ffetch()`
+     * will always be appended to it (unlike the `new URL()`, which has ambiguous slash semantics)
+     */
     baseUrl?: string;
     /** body to be passed to fetch() */
     body?: BodyInit;
@@ -92,6 +104,8 @@ export interface Ffetch<RequestMixin, ResponseMixin> {
  */
 export declare class HttpError extends Error {
     readonly response: Response;
+    readonly body: Uint8Array | null;
+    readonly bodyText: string | null;
     constructor(response: Response);
 }
 /** create a new ffetch function with the given base options */

package/ffetch.js

@@ -1,10 +1,12 @@
-import { composeMiddlewares, unknownToError } from "@fuman/utils";
+import { composeMiddlewares, utf8, unknownToError } from "@fuman/utils";
 const OCTET_STREAM_CONTENT_TYPE = "application/octet-stream";
 class HttpError extends Error {
   constructor(response) {
     super(`HTTP Error ${response.status} ${response.statusText}`);
     this.response = response;
   }
+  body = null;
+  bodyText = null;
 }
 function headersToObject(headers) {
   if (!headers) return {};
@@ -43,15 +45,27 @@ class FfetchResultImpl {
   }
   async #fetchAndValidate() {
     const res = await this.#fetch(new Request(this._url, this._init));
+    let err = null;
     if (this._options.validateResponse === void 0 || this._options.validateResponse !== false) {
       if (typeof this._options.validateResponse === "function") {
         if (!await this._options.validateResponse(res)) {
-          throw new HttpError(res);
+          err = new HttpError(res);
         }
       } else if (!res.ok) {
-        throw new HttpError(res);
+        err = new HttpError(res);
       }
     }
+    if (err != null) {
+      if (this._options.readBodyOnError !== false) {
+        try {
+          ;
+          err.body = new Uint8Array(await res.arrayBuffer());
+          err.bodyText = utf8.decoder.decode(err.body);
+        } catch {
+        }
+      }
+      throw err;
+    }
     return res;
   }
   async raw() {
@@ -140,8 +154,16 @@ function createFfetch(baseOptions = {}) {
     if (options.middlewares !== void 0 && options.middlewares.length > 0) {
       fetcher = composeMiddlewares(options.middlewares, wrappedFetch);
     }
-    if (baseOptions?.baseUrl != null || options.baseUrl != null) {
-      url = new URL(url, options.baseUrl ?? baseOptions?.baseUrl).href;
+    if ((baseOptions?.baseUrl != null || options.baseUrl != null) && !url.includes("://")) {
+      const baseUrl = options.baseUrl ?? baseOptions?.baseUrl;
+      let prepend = baseUrl;
+      if (prepend[prepend.length - 1] !== "/") {
+        prepend += "/";
+      }
+      if (url[0] === "/") {
+        url = url.slice(1);
+      }
+      url = prepend + url;
     }
     let init;
     let headers;

package/index.d.cts

@@ -0,0 +1,4 @@
+export type { FfetchMiddleware } from './_types.js';
+export * from './addons/index.js';
+export * from './default.js';
+export * from './ffetch.js';

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@fuman/fetch",
     "type": "module",
-    "version": "0.0.4",
+    "version": "0.0.6",
     "description": "tiny wrapper over fetch",
     "license": "MIT",
     "dependencies": {

package/tough.d.cts

@@ -0,0 +1 @@
+export * from "./addons/tough-cookie.js"

package/valibot.d.cts

@@ -0,0 +1 @@
+export * from "./addons/parse/adapters/valibot.js"

package/valita.d.cts

@@ -0,0 +1 @@
+export * from "./addons/parse/adapters/valita.js"

package/yup.d.cts

@@ -0,0 +1 @@
+export * from "./addons/parse/adapters/yup.js"

package/zod.d.cts

@@ -0,0 +1 @@
+export * from "./addons/parse/adapters/zod.js"