fetchbasequery 0.2.1 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 h41ku
+Copyright (c) 2026 h41ku
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,13 @@
 # fetchBaseQuery
 
 Library for easily make HTTP queries without mass of boilerplate code.
+It works fine in any environment that supports `Fetch API`.
+
+## Features
+
+- Lightweight modular typescript ready code
+- Supports middleware programming pattern
+- Using only modern API, has no any legacy code
 
 ## Installation
 
@@ -18,70 +25,289 @@ pnpm add fetchbasequery
 
 ## Usage
 
-Build base query function:
+### Basic usage
+
+Use a factory function, which enhance a bare `fetch()`:
 
 ```js
-import fetchBaseQuery, { baseQuery, encodeBody, accessToken, jsonReply, commonReply } from 'fetchbasequery'
+import fetchBaseQuery from 'fetchbasequery'
 
 const query = fetchBaseQuery({
     // main options ...
-    baseUrl: 'https://api.example.org/v1'
-    baseQuery,
+    baseUrl: 'https://api.example.org/v1',
     timeout: 10000, // in milliseconds
-    logErrors: true,
+    fetch: globalThis.fetch, // it is possible to use a custom `fetch()` here
     // add some defaults for `fetch()` ...
     mode: 'cors',
     credentials: 'include',
     cache: 'reload',
-    // middlewares
-    middlewares: [
-        encodeBody(),
-        accessToken({
-            getAccessToken: () => localStorage.getItem('access_token'),
-            setAccessToken: (token) => localStorage.setItem('access_token', token),
-            removeAccessToken: (token) => localStorage.removeItem('access_token'),
-            getUpdatedAccessToken: async (response) => response.headers.get('X-Access-Token')
+    // ... see `RequestInit` for more options ...
+})
+```
+
+Then use the returned function instead of bare `fetch()`:
+
+```js
+const resource = `/users/${id}` // full or short URL
+const options = { // define some options, see `RequestInit`
+    headers: { 'Authorization': '...' }
+}
+const response = await query(resource, options) // all options defined in `fetchBaseQuery()` will be passed into request
+```
+
+Function returns an abortable promise described using type `AbortablePromise<T>`.
+So it is possible to abort the request at any time.
+
+```js
+const promise = query(...)
+// ...
+promise.abort('Component was unmounted...') // `reason` message is optional
+```
+
+Options of factory function described by type `FetchBaseQueryOptions`:
+
+```ts
+export type FetchBaseQueryOptions = RequestInit & {
+    baseUrl?: string, // origin or prefix, used for URLs without it
+    timeout?: number, // default timeout in milliseconds
+    fetch?: BaseFetchFunction, // by default this is reference to `globalThis.fetch()`
+    middlewares?: Middleware[] // list of middleware functions
+};
+```
+
+### Using middlewares
+
+```js
+import fetchBaseQuery from 'fetchbasequery'
+import { retryOnError } from 'fetchbasequery/middlewares'
+
+const query = fetchBaseQuery({
+    // ... options ...
+    middlewares: [ // add some middlewares
+        retryOnError({
+            maxNumAttempts: 5
         }),
-        jsonReply(),
-        commonReply()
+        // ...
     ]
 })
 ```
 
-Now get easy to make queries:
+### Using decorators
 
 ```js
-const response = await query({ url: '/users/me', timeout: 3000 }) // don't worry about catching errors
-const { status, success, error } = response
-if (success) {
-    setUser(response.data)
-} else if (error) {
-    setError(response.message)
-} else {
-    setError(`Unexpected status code: ${status}`)
+import fetchBaseQuery from 'fetchbasequery'
+import { json } from 'fetchbasequery/decorators'
+
+const query = json(fetchBaseQuery({
+    // ... options ...
+}))
+
+// Now `query()` accepts plain object as body and stringify it automatically.
+// Also response has a `data` property, which contains parsed json returned by backend.
+const { data } = await query('/articles', {
+    method: 'post',
+    body: { 
+        title: '...',
+        poster: '...',
+        // ...
+    }
+})
+```
+
+### Writing a custom middleware
+
+Middleware described by type `Middleware`:
+
+```ts
+export type Middleware = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
+```
+
+Every middleware follows the simple pattern. Get `request`, do something with request,
+then call `next(request)` to get `response`, do something with response and return it.
+
+Let's create simple middleware for example:
+
+```js
+// Add to the request a CSRF-token as a custom header `X-CSRF-Token`
+async function useCsrfToken(request, next) {
+    const token = await getCsrfToken() // an abstract function just for example
+    // modify the request
+    const headers = new Headers(request.headers)
+    headers.set('X-CSRF-Token', token)
+    const modifiedRequest = new Request(request, { headers })
+    // make a query using the modified request
+    const response = await next(modifiedRequest)
+    // it is possible to modify response too, but in this example we does not need it
+    return response // just return the response as is
 }
 ```
 
-Using instance of `Request`:
+Usage:
 
 ```js
-// for example inside ServiceWorker
-addEventListener('fetch', evt => {
-    const { request } = evt
-    return evt.respondWith(query({ request }))
+const query = fetchBaseQuery({
+    baseUrl: 'https://...', // an abstract
+    // ...
+    middlewares: [
+        // ...
+        useCsrfToken,
+        // ...
+    ]
+})
+// ...
+const formData = getFormData() // an abstract
+// post the form to the protected route
+const response = await query('/articles', {
+    method: 'post',
+    body: formData
 })
 ```
 
-Aborting query:
+### Writing a custom decorators
 
-```js
-const promise = query({ url: '/users/me' })
-promise.abort()
+Decorators can extends logic and redefine types of request and response.
+
+There are no restrictions for a decorator. It just a get original function and
+return it's enhanced version. That's all.
+
+Let's create a simple example:
+
+```ts
+import type { FetchFunction, AbortablePromise } from 'fetchbasequery';
+import fetchBaseQuery from 'fetchbasequery';
+
+export type XmlResponse = Response & { document?: XMLDocument };
+
+// Parses automatically XML documents provided by a raw response
+export function withXmlParser(query: FetchFunction<Response>) {
+    const supportedTypes = [
+        'application/xml',
+        'text/xml',
+    ]
+    return function (
+        resource: string | Request,
+        { signal: initSignal, ...options }: RequestInit = {}
+    ): AbortablePromise<XmlResponse> {
+        const abortController = new AbortController()
+        const signal = AbortSignal.any([
+            abortController.signal,
+            ...(initSignal instanceof AbortSignal ? [ initSignal ] : [])
+        ])
+        const promise = (async () => {
+            const response = (await query(resource, { signal, ...options })) as XmlResponse
+            const contentType = String(response.headers.get('content-type')).split(';')[0]
+            if (supportedTypes.includes(contentType)) { // if the response contains XML document
+                // then parse content into special property `.document`
+                const parser = new DOMParser()
+                response.document = parser.parseFromString(await response.text(), 'application/xml')
+            }
+            return response
+        })() as AbortablePromise<XmlResponse>;
+        promise.abort = (reason) => { abortController.abort(reason) }
+        return promise
+    }
+}
+```
+
+Usage:
+
+```ts
+const query = withXmlParser(fetchBaseQuery({
+    baseUrl: 'https://...', // an abstract
+    // ...
+}))
+const response = await query('/sitemap.xml')
+console.log('Status:', response.status)
+console.log('Content-Type:', response.headers.get('content-type'))
+console.log('Document:', response.document)
+```
+
+## List of provided middlewares
+
+### `muteErrors()`
+
+Catch any error thrown by `next()` mute it and returns `Response.error()`.
+Typically usage: use conditional statements instead of using `try-catch` statements.
+
+### `retryOnError(options?: RetryOnErrorOptions)`
+
+Retry to make a query when an error was thrown by `next()`.
+Typically usage: repeat the request in case of a temporary loss of connection.
+
+Options:
+
+```ts
+export type RetryOnErrorOptions = {
+    maxNumAttempts?: number = 5, // the maximum number of attempts
+    backoffTime?: (attempt: number) => number, // delay time in milliseconds
+};
 ```
 
-It works fine both on frontend and backend sides. For backend side usage Node.js v18+ is required,
-because the middleware `baseQuery` based on `Fetch API`. But it can be replaced with your own
-implementation based on another API (e.g. based on `axios` etc).
+### `retryOn429(options?: RetryOn429Options)`
+
+Retry to make a query when server returns status `429 Too Many Requests`.
+Typically usage: repeat the request in case when servers busy or when rate limit was reached.
+
+Options:
+
+```ts
+export type RetryOn429Options = {
+    maxNumAttempts?: number = 5, // the maximum number of attempts
+    maxBackoffTime?: number = Infinity, // the maximum permissible delay time
+    backoffTime?: (attempt: number, response: Response) => number, // delay time in milliseconds
+};
+```
+
+## List of provided decorators
+
+### `json<T>(query: FetchFunction<Response>): JsonFetchFunction<JsonResponse<T>>`
+
+Allows to pass a plain objects as `body` and automatically serialize plain objects into JSON.
+It also automatically parse JSON documents provided by a raw response into special property `.data`.
+
+Usage:
+```ts
+import fetchBaseQuery from 'fetchbasequery'
+import { json } from 'fetchbasequery/decorators'
+
+const query = json(fetchBaseQuery({
+    // ...
+}))
+// ...
+const response = await query('https://...', {
+    method: 'put',
+    body: { // decorator allows to pass a plain objects as body
+        title: '...',
+        // ...
+    }
+})
+console.log('Status:', response.status)
+console.log('Data:', response.data) // decorator also parses body returned as json
+```
+
+## Testing
+
+Running tests:
+
+```sh
+npm run test
+```
+
+## TODO
+
+- Chaining methods of `AbortablePromise<T>` (`.then()`, `.catch()` and `.finally()`)
+  must returns instance of `AbortablePromise<T>` not pure `Promise<T>`;
+- Add static methods to `AbortablePromise<T>` (`.all()`, `.any()`, `.race()`, etc);
+- Describe and export utility function `sleep()` - abortable sleep function;
+- Add, describe and export utility function `mergeHeaders()` to helps to write a middleware;
+
+## References
+
+- [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+- [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+- [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+- [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)
+- [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429)
 
 ## License
 

package/jsconfig.json

@@ -0,0 +1,12 @@
+{
+    "compilerOptions": {
+        "checkJs": true,
+        "noImplicitAny": false,
+        "strict": false,
+        "types": ["node"]
+    },
+    "exclude": [
+        "node_modules",
+        "**/node_modules/*"
+    ]
+}

package/package.json

@@ -1,19 +1,39 @@
 {
   "name": "fetchbasequery",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "description": "Library for easily make HTTP queries without mass of boilerplate code.",
   "type": "module",
   "main": "src/fetchBaseQuery.js",
-  "types": "types/index.d.ts",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./decorators": {
+      "types": "./src/decorators/index.d.ts",
+      "import": "./src/decorators/index.js"
+    },
+    "./middlewares": {
+      "types": "./src/middlewares/index.d.ts",
+      "import": "./src/middlewares/index.js"
+    }
+  },
   "scripts": {
+    "test": "node tests/index.js"
   },
   "keywords": [
-    "fetch", "fetchBaseQuery"
+    "fetch",
+    "fetchBaseQuery",
+    "middleware",
+    "retry",
+    "retryOnError",
+    "retryOn429",
+    "muteErrors",
+    "json"
   ],
-  "author": "h41ku <h41ku.c0de@ya.ru>",
   "license": "MIT",
-  "dependencies": {
-  },
   "devDependencies": {
+    "@types/node": "^26.6.5"
   }
 }

package/src/decorators/index.d.ts

@@ -0,0 +1,10 @@
+import type { AbortablePromise, FetchFunction } from "../index.d.ts";
+
+type Override<T, U> = Omit<T, keyof U> & U;
+
+export type PlainObject = Record<string, any>;
+export type JsonRequestInit = Override<RequestInit, { body?: BodyInit | PlainObject }>;
+export type JsonResponse<T> = Response & { data?: T };
+export type JsonFetchFunction<T> = (resource: string | Request, options?: JsonRequestInit) => AbortablePromise<T>;
+
+export declare function json<T>(query: FetchFunction<Response>): JsonFetchFunction<JsonResponse<T>>;

package/src/decorators/index.js

@@ -0,0 +1 @@
+export { json } from './json.js'

package/src/decorators/json.js

@@ -0,0 +1,107 @@
+/**
+ * @typedef {import('../index.d.ts').FetchFunction<T>} FetchFunction
+ * @template T
+ */
+
+/**
+ * @typedef {import('./index.d.ts').JsonFetchFunction<T>} JsonFetchFunction
+ * @template T
+ */
+
+/**
+ * @typedef {import('./index.d.ts').PlainObject} PlainObject
+ */
+
+/**
+ * @typedef {import('./index.d.ts').JsonRequestInit} JsonRequestInit
+ */
+
+/**
+ * @typedef {import('../index.d.ts').AbortablePromise<T>} AbortablePromise
+ * @template T
+ */
+
+/**
+ * @typedef {import('./index.d.ts').JsonResponse<T>} JsonResponse
+ * @template T
+ */
+
+/**
+ * 
+ * @param {BodyInit | PlainObject} value 
+ * @returns {value is PlainObject}
+ */
+function isPlainObject(value) {
+    return (
+        typeof value === 'object'
+        //&& value !== null
+        && !ArrayBuffer.isView(value)
+        && !(value instanceof FormData)
+        && !(value instanceof Blob)
+        && !(value instanceof ReadableStream)
+        && !(value instanceof URLSearchParams)
+    )
+}
+
+/**
+ * 
+ * @param {PlainObject} body 
+ * @returns {string}
+ */
+function modifyBody(body) {
+    return JSON.stringify(body, (key, value) => {
+        if (value instanceof Error) {
+            return value.stack.split(/\r?\n/g)
+        } else if (typeof value === 'bigint') {
+            return value.toString()
+        }
+        return value
+    })
+}
+
+/**
+ * 
+ * @param {HeadersInit} headers 
+ * @returns {Headers}
+ */
+function modifyHeaders(headers) {
+    const result = new Headers(headers)
+    if (!result.has('content-type'))
+        result.set('content-type', 'application/json; charset=utf-8')
+    return result
+}
+
+/**
+ * 
+ * @param {FetchFunction<Response>} query 
+ * @returns {JsonFetchFunction<JsonResponse<T>>}
+ * @template T
+ */
+export function json(query) {
+
+    /**
+     * @param {string | Request} resource
+     * @param {JsonRequestInit} [options = {}]
+     */
+    return (resource, { body: initBody, headers: initHeaders, signal: initSignal, ...options } = {}) => {
+        const abortController = new AbortController()
+        const signal = AbortSignal.any([
+            abortController.signal,
+            ...(initSignal instanceof AbortSignal ? [ initSignal ] : [])
+        ])
+        /**
+         * @type {AbortablePromise<JsonResponse<T>>}
+         */
+        const promise = (async () => {
+            const isJson = isPlainObject(initBody)
+            const body = isJson ? modifyBody(initBody) : initBody
+            const headers = isJson ? modifyHeaders(initHeaders) : initHeaders
+            const response = /** @type {JsonResponse<T>} */ (await query(resource, { body, headers, signal, ...options }))
+            if (/^application\/json(\;| |$)/.test(String(response.headers.get('content-type'))))
+                response.data = await (response.clone().json())
+            return response
+        })();
+        promise.abort = (reason) => { abortController.abort(reason) }
+        return promise
+    }
+}

package/src/fetchBaseQuery.js

@@ -1,15 +1,102 @@
-// const pipeAsync = (...fns) => (input) => fns.reduce((chain, func) => chain.then(func), Promise.resolve(input))
-import abortable from './helpers/abortable.js'
-import pipe from './helpers/pipe.js'
-import defaultBaseQuery from './baseQuery.js'
-
-export default ({ baseQuery, middlewares, ...defaultOptions } = {}) => {
-    const pipedQuery = pipe(...(middlewares || []).map(abortable))(baseQuery || defaultBaseQuery)
-    return options => pipedQuery({
-        ...defaultOptions,
-        ...options
-    })
-}
+/**
+ * @typedef {import('./index.d.ts').FetchBaseQueryOptions} FetchBaseQueryOptions
+ */
+
+/**
+ * @typedef {import('./index.d.ts').AbortablePromise<T>} AbortablePromise<T>
+ * @template T
+ */
+
+/**
+ * @typedef {import('./index.d.ts').FetchFunction<T>} FetchFunction<T>
+ * @template T
+ */
+
+/**
+ * 
+ * @param {import('./index.d.ts').FetchBaseQueryOptions} options 
+ * @returns {FetchFunction<T>}
+ * @template T
+ */
+export function fetchBaseQuery({
+    baseUrl = '',
+    timeout = Number.MAX_SAFE_INTEGER,
+    fetch = globalThis.fetch,
+    middlewares = [],
+    ...baseOptions
+} = {}) {
 
-export { defaultBaseQuery as baseQuery }
-export * from './middlewares/index.js'
+    const abortController = new AbortController()
+
+    /**
+     * 
+     * @param {number} index 
+     * @param {Request} request
+     * @returns {Promise<Response>}
+     */
+    const runChain = (index, request) => {
+        if (index === middlewares.length) {
+            return fetch(request)
+        }
+        /**
+         * @param {Request} request 
+         * @returns {Promise<Response>}
+         */
+        const next = (request) => runChain(index + 1, request)
+        return middlewares[index](request, next)
+    }
+
+    /**
+     * 
+     * @param {string} endpoint 
+     * @returns {string}
+     */
+    const useBaseUrl = (endpoint) => {
+        let url, origin, prefix = '/'
+        if (baseUrl) {
+            const url = new URL(baseUrl)
+            origin = url.origin
+            prefix = url.pathname
+        }
+        try {
+            url = new URL(endpoint)
+        } catch (error) {
+            url = new URL(
+                /\/$/.test(prefix) && /^\//.test(endpoint)
+                    ? prefix + endpoint.substring(1)
+                    : prefix + endpoint,
+                origin
+            )
+        }
+        return url.toString()
+    }
+
+    /**
+     * 
+     * @param {string | Request} resource 
+     * @param {RequestInit} [options = {}]
+     * @returns {AbortablePromise<T>}
+     */
+    return (resource, options = {}) => {
+        const signalByTimeout = timeout !== Number.MAX_SAFE_INTEGER ? AbortSignal.timeout(timeout) : undefined
+        const signalFromRequest = resource instanceof Request ? resource.signal : undefined
+        const { signal: signalFromOptions, ...otherOptions } = options
+        const target = resource instanceof Request ? resource : useBaseUrl(resource)
+        const request = new Request(target, {
+            ...baseOptions,
+            signal: AbortSignal.any([
+                abortController.signal,
+                signalByTimeout,
+                signalFromRequest,
+                signalFromOptions
+            ].filter(signal => signal instanceof AbortSignal)),
+            ...otherOptions
+        })
+        const promise = /** @type {AbortablePromise<T>} */ (runChain(0, request))
+        /**
+         * @param {string} reason 
+         */
+        promise.abort = (reason) => { abortController.abort(reason) }
+        return promise
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,19 @@
+export type AbortablePromise<T> = Promise<T> & {
+    abort: (reason?: string) => void
+};
+
+export type Middleware = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
+
+export type BaseFetchFunction = (resource: string | Request, options?: RequestInit) => Promise<Response>;
+export type FetchBaseQueryOptions = RequestInit & {
+    baseUrl?: string, // origin or prefix, used for URLs without it
+    timeout?: number, // default timeout in milliseconds
+    fetch?: BaseFetchFunction, // by default this is reference to `globalThis.fetch()`
+    middlewares?: Middleware[] // list of middleware functions
+};
+
+export type FetchFunction<T> = (resource: string | Request, options?: RequestInit) => AbortablePromise<T>;
+
+export declare function fetchBaseQuery<T>(options?: FetchBaseQueryOptions): FetchFunction<T>;
+
+export default fetchBaseQuery

package/src/index.js

@@ -0,0 +1,4 @@
+import { fetchBaseQuery } from './fetchBaseQuery.js'
+export { fetchBaseQuery }
+
+export default fetchBaseQuery

package/src/middlewares/index.d.ts

@@ -0,0 +1,14 @@
+export type RetryOnErrorOptions = {
+    maxNumAttempts?: number = 5, // the maximum number of attempts
+    backoffTime?: (attempt: number) => number, // delay time in milliseconds
+};
+
+export type RetryOn429Options = {
+    maxNumAttempts?: number = 5, // the maximum number of attempts
+    maxBackoffTime?: number = Infinity, // the maximum permissible delay time
+    backoffTime?: (attempt: number, response: Response) => number, // delay time in milliseconds
+};
+
+export declare function muteErrors(): Middleware;
+export declare function retryOn429(options?: RetryOn429Options): Middleware;
+export declare function retryOnError(options?: RetryOnErrorOptions): Middleware;