@fuman/fetch 0.0.1

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2024 alina sireneva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,13 @@
+# `@fuman/fetch`
+
+no-bullshit minimal wrapper around `window.fetch` that aims to improve dx
+by adding commonly used features, while having low runtime overhead,
+small bundle size and staying close to the web standards.
+
+## features
+- no more `(await fetch(url)).json()` - just `await ffetch(url).json()`
+- sugar for common request body types (json, form, multipart)
+- base url, base headers, etc.
+- retries, timeouts, validation built in
+- basic middlewares
+- **type-safe** compatibility with popular parsing libraries (yup, zod, valibot, etc.)

package/_types.d.ts

@@ -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.cjs

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function urlencode(query) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        search.append(key, String(value[i]));
+      }
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search;
+}
+function setHeader(options, key, value) {
+  if (!options.headers) {
+    if (value === null) return;
+    options.headers = { [key]: value };
+    return;
+  }
+  let { headers } = options;
+  if (Array.isArray(headers)) {
+    if (value === null) {
+      for (let i = 0; i < headers.length; i++) {
+        if (headers[i][0] === key) {
+          headers.splice(i, 1);
+          i -= 1;
+          break;
+        }
+      }
+      return;
+    }
+    headers.push([key, value]);
+    return;
+  } else if (headers instanceof Headers) {
+    if (value === null) {
+      headers.delete(key);
+    } else {
+      headers.set(key, value);
+    }
+    return;
+  }
+  if (Symbol.iterator in headers) {
+    headers = options.headers = Object.fromEntries(headers);
+  }
+  if (value === null) {
+    delete headers[key];
+  } else {
+    headers[key] = value;
+  }
+}
+exports.setHeader = setHeader;
+exports.urlencode = urlencode;

package/addons/_utils.d.ts

@@ -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/_utils.js

@@ -0,0 +1,54 @@
+function urlencode(query) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        search.append(key, String(value[i]));
+      }
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search;
+}
+function setHeader(options, key, value) {
+  if (!options.headers) {
+    if (value === null) return;
+    options.headers = { [key]: value };
+    return;
+  }
+  let { headers } = options;
+  if (Array.isArray(headers)) {
+    if (value === null) {
+      for (let i = 0; i < headers.length; i++) {
+        if (headers[i][0] === key) {
+          headers.splice(i, 1);
+          i -= 1;
+          break;
+        }
+      }
+      return;
+    }
+    headers.push([key, value]);
+    return;
+  } else if (headers instanceof Headers) {
+    if (value === null) {
+      headers.delete(key);
+    } else {
+      headers.set(key, value);
+    }
+    return;
+  }
+  if (Symbol.iterator in headers) {
+    headers = options.headers = Object.fromEntries(headers);
+  }
+  if (value === null) {
+    delete headers[key];
+  } else {
+    headers[key] = value;
+  }
+}
+export {
+  setHeader,
+  urlencode
+};

package/addons/bundle.cjs

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const form = require("./form.cjs");
+const multipart = require("./multipart.cjs");
+const addon = require("./parse/addon.cjs");
+const query = require("./query.cjs");
+const rateLimit = require("./rate-limit.cjs");
+const retry = require("./retry.cjs");
+const timeout = require("./timeout.cjs");
+exports.form = form.form;
+exports.multipart = multipart.multipart;
+exports.parser = addon.parser;
+exports.query = query.query;
+exports.rateLimitHandler = rateLimit.rateLimitHandler;
+exports.RetriesExceededError = retry.RetriesExceededError;
+exports.retry = retry.retry;
+exports.TimeoutError = timeout.TimeoutError;
+exports.timeout = timeout.timeout;

package/addons/bundle.d.ts

@@ -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/bundle.js

@@ -0,0 +1,18 @@
+import { form } from "./form.js";
+import { multipart } from "./multipart.js";
+import { parser } from "./parse/addon.js";
+import { query } from "./query.js";
+import { rateLimitHandler } from "./rate-limit.js";
+import { RetriesExceededError, retry } from "./retry.js";
+import { TimeoutError, timeout } from "./timeout.js";
+export {
+  RetriesExceededError,
+  TimeoutError,
+  form,
+  multipart,
+  parser,
+  query,
+  rateLimitHandler,
+  retry,
+  timeout
+};

package/addons/form.cjs

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const _utils = require("./_utils.cjs");
+function defaultSerialize(data) {
+  return _utils.urlencode(data).toString();
+}
+function form(options = {}) {
+  const { serialize = defaultSerialize } = options;
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.form != null || ctx.baseOptions.form != null) {
+        if (ctx.options.body != null) {
+          throw new Error("Cannot set both form and body");
+        }
+        const obj = ctx.options.form ?? ctx.baseOptions.form;
+        ctx.options.body = serialize(obj);
+        ctx.options.method ??= "POST";
+        _utils.setHeader(ctx.options, "Content-Type", "application/x-www-form-urlencoded");
+      }
+    }
+  };
+}
+exports.form = form;

package/addons/form.d.ts

@@ -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/form.js

@@ -0,0 +1,23 @@
+import { setHeader, urlencode } from "./_utils.js";
+function defaultSerialize(data) {
+  return urlencode(data).toString();
+}
+function form(options = {}) {
+  const { serialize = defaultSerialize } = options;
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.form != null || ctx.baseOptions.form != null) {
+        if (ctx.options.body != null) {
+          throw new Error("Cannot set both form and body");
+        }
+        const obj = ctx.options.form ?? ctx.baseOptions.form;
+        ctx.options.body = serialize(obj);
+        ctx.options.method ??= "POST";
+        setHeader(ctx.options, "Content-Type", "application/x-www-form-urlencoded");
+      }
+    }
+  };
+}
+export {
+  form
+};

package/addons/index.d.ts

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

package/addons/multipart.cjs

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const _utils = require("./_utils.cjs");
+function defaultSerialize(data) {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(data)) {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        formData.append(key, String(value[i]));
+      }
+    } else if (value instanceof File) {
+      formData.append(key, value, value.name);
+    } else {
+      formData.append(key, String(value));
+    }
+  }
+  return formData;
+}
+function multipart(options = {}) {
+  const { serialize = defaultSerialize } = options;
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.multipart != null || ctx.baseOptions.multipart != null) {
+        if (ctx.options.body != null) {
+          throw new Error("Cannot set both multipart and body");
+        }
+        const obj = ctx.options.multipart ?? ctx.baseOptions.multipart;
+        ctx.options.body = serialize(obj);
+        ctx.options.method ??= "POST";
+        _utils.setHeader(ctx.options, "Content-Type", null);
+      }
+    }
+  };
+}
+exports.multipart = multipart;

package/addons/multipart.d.ts

@@ -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/multipart.js

@@ -0,0 +1,35 @@
+import { setHeader } from "./_utils.js";
+function defaultSerialize(data) {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(data)) {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        formData.append(key, String(value[i]));
+      }
+    } else if (value instanceof File) {
+      formData.append(key, value, value.name);
+    } else {
+      formData.append(key, String(value));
+    }
+  }
+  return formData;
+}
+function multipart(options = {}) {
+  const { serialize = defaultSerialize } = options;
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.multipart != null || ctx.baseOptions.multipart != null) {
+        if (ctx.options.body != null) {
+          throw new Error("Cannot set both multipart and body");
+        }
+        const obj = ctx.options.multipart ?? ctx.baseOptions.multipart;
+        ctx.options.body = serialize(obj);
+        ctx.options.method ??= "POST";
+        setHeader(ctx.options, "Content-Type", null);
+      }
+    }
+  };
+}
+export {
+  multipart
+};

package/addons/parse/_types.d.ts

@@ -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.ts

@@ -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/yup.d.ts

@@ -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.ts

@@ -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.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function parser(parser2) {
+  return {
+    response: {
+      async parsedJson(schema) {
+        return parser2.parse(schema, await this.json());
+      }
+    }
+  };
+}
+exports.parser = parser;

package/addons/parse/addon.d.ts

@@ -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/parse/addon.js

@@ -0,0 +1,12 @@
+function parser(parser2) {
+  return {
+    response: {
+      async parsedJson(schema) {
+        return parser2.parse(schema, await this.json());
+      }
+    }
+  };
+}
+export {
+  parser
+};

package/addons/query.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const _utils = require("./_utils.cjs");
+function defaultSerialize(query2, url) {
+  const params = _utils.urlencode(query2);
+  return url + (url.includes("?") ? "&" : "?") + params.toString();
+}
+function query(options = {}) {
+  const { serialize = defaultSerialize } = options;
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.query || ctx.baseOptions.query) {
+        const obj = ctx.baseOptions.query && ctx.options.query ? {
+          ...ctx.baseOptions.query,
+          ...ctx.options.query
+        } : ctx.options.query;
+        ctx.url = serialize(obj ?? {}, ctx.url);
+      }
+    }
+  };
+}
+exports.query = query;

package/addons/query.d.ts

@@ -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/query.js

@@ -0,0 +1,22 @@
+import { urlencode } from "./_utils.js";
+function defaultSerialize(query2, url) {
+  const params = urlencode(query2);
+  return url + (url.includes("?") ? "&" : "?") + params.toString();
+}
+function query(options = {}) {
+  const { serialize = defaultSerialize } = options;
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.query || ctx.baseOptions.query) {
+        const obj = ctx.baseOptions.query && ctx.options.query ? {
+          ...ctx.baseOptions.query,
+          ...ctx.options.query
+        } : ctx.options.query;
+        ctx.url = serialize(obj ?? {}, ctx.url);
+      }
+    }
+  };
+}
+export {
+  query
+};

package/addons/rate-limit.cjs

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+const defaultIsRejected = (res) => res.status === 429;
+const defaultGetReset = (res) => res.headers.get("x-ratelimit-reset");
+function tryParseDate(str) {
+  if (str == null) return null;
+  if (typeof str === "number") return str * 1e3;
+  const asNum = Number(str);
+  if (!Number.isNaN(asNum)) return asNum * 1e3;
+  const asDate = new Date(str);
+  if (asDate.toString() === "Invalid Date") return null;
+  return asDate.getTime();
+}
+function rateLimitMiddleware(options) {
+  const {
+    isRejected = defaultIsRejected,
+    getReset = defaultGetReset,
+    defaultWaitTime = 3e4,
+    maxWaitTime = 3e5,
+    jitter = 5e3,
+    maxRetries = 5,
+    onRateLimitExceeded
+  } = options;
+  return async (req, next) => {
+    let attempts = 0;
+    while (true) {
+      if (attempts > maxRetries) throw new Error("Rate limit exceeded, maximum retries exceeded");
+      attempts += 1;
+      const res = await next(req);
+      const rejected = await isRejected(res);
+      if (!rejected) return res;
+      const reset = tryParseDate(await getReset(res));
+      let waitTime;
+      if (reset == null) {
+        waitTime = defaultWaitTime;
+      } else {
+        waitTime = reset - Date.now() + jitter;
+        if (waitTime < 0) {
+          waitTime = void 0;
+        } else if (waitTime > maxWaitTime) {
+          throw new Error(`Rate limit exceeded, reset time is too far in the future: ${new Date(reset).toISOString()}`, { cause: res });
+        }
+      }
+      if (waitTime == null) {
+        onRateLimitExceeded?.(res, 0);
+        continue;
+      }
+      onRateLimitExceeded?.(res, waitTime);
+      await utils.sleep(waitTime);
+    }
+  };
+}
+function rateLimitHandler() {
+  return {
+    beforeRequest: (ctx) => {
+      if (ctx.options.rateLimit != null || ctx.baseOptions.rateLimit != null) {
+        const options = { ...ctx.baseOptions.rateLimit, ...ctx.options.rateLimit };
+        ctx.options.middlewares ??= [];
+        ctx.options.middlewares?.push(rateLimitMiddleware(options));
+      }
+    }
+  };
+}
+exports.rateLimitHandler = rateLimitHandler;

package/addons/rate-limit.d.ts

@@ -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>;