xior

library0.8.3jsnpmunverified

A lightweight HTTP request library (~6KB, Gzip ~3KB) built on the Fetch API with a plugin system and an API similar to axios. Current stable version is 0.8.3 (released August 2024), with frequent updates (multiple releases per month). Key differentiators: supports error retry, throttling, deduplication, and caching via plugins; works seamlessly in edge runtimes, Tauri, and traditional Node.js; has built-in cancelation via AbortController; and provides TypeScript types. Unlike axios, it does not rely on XMLHttpRequest, making it suitable for modern environments. However, it is not a drop-in replacement: error handling, response shape, and browser compatibility differ.

devops

npm install xior

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XIOR

xior

devopsjavascriptv0.8.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

xior

✓ import xior from 'xior'

✗ const xior = require('xior')

Default export only. ESM-only; CommonJS require() will fail.

XiorInstance

✓ import type { XiorInstance } from 'xior'

✗ import { XiorInstance } from 'xior'

Type import only; not a runtime value.

XiorResponse

✓ import type { XiorResponse } from 'xior'

✗ import { XiorResponse } from 'xior'

Type import; interface for response objects.

create

✓ import xior from 'xior'; const instance = xior.create({})

✗ import { create } from 'xior'

create is a static method on the default export, not a named export.

Shows creating an instance with baseURL and timeout, making GET/POST requests, error handling, and interceptor usage.

import xior from 'xior'; async function main() { const instance = xior.create({ baseURL: 'https://api.example.com', timeout: 5000, headers: { 'X-Custom-Header': 'foobar' }, }); // GET request try { const response = await instance.get('/data', { params: { id: 1 }, }); console.log(response.data); } catch (error) { console.error(error); } // POST with JSON body const postResponse = await instance.post('/items', { name: 'New Item', }); console.log(postResponse.status); // Using interceptors instance.interceptors.request.use((config) => { config.headers.Authorization = `Bearer ${process.env.API_KEY ?? ''}`; return config; }); instance.interceptors.response.use( (response) => response.data, (error) => Promise.reject(error) ); } main();

Debug

Known issues

breakingxior is built on the Fetch API and does not support Node.js built-in http module or XMLHttpRequest, so it will not work in older browsers or Node.js versions <18 that do not have native fetch.

fix

Use a fetch polyfill like 'isomorphic-fetch' or 'node-fetch' in older environments, or switch to axios if full backward compatibility is required.

affects: >=0.0.0

breakingxior's response object shape differs from axios: response.data is already parsed JSON (like axios), but error handling requires checking error.response.status rather than error.response.data in some cases; also error may be a generic Error with no response property for network failures.

fix

In catch blocks, check for error.response existence and then error.response.status. Use type narrowing: if (error instanceof xior.XiorError) { const err = error; ... }

affects: >=0.0.0

deprecatedThe built-in 'auth refresh token' plugin (imported from 'xior/plugins/auth-refresh') is in beta and may have breaking changes in future versions.

fix

Consider using the community version 'xior-auth-refresh-plugin' for more stability, or pin exact version in package.json.

affects: >=0.7.0

gotchaxior uses AbortController for cancelation. Calling .abort() on the signal will reject the promise with an AbortError, not a custom cancel error like axios. This can break code expecting error.code === 'ERR_CANCELED'.

fix

Check error.name === 'AbortError' to detect canceled requests.

affects: >=0.0.0

gotchaWhen using the cache plugin, cached responses include the original xior response object. If you mutate the response (e.g., response.data = ...), subsequent cache hits will return the mutated data. This is a common footgun in mutable environments.

fix

Clone response data before caching or use the 'clone' option in cache plugin config.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: xior.create is not a function (or xior is not a function)

Importing incorrectly, e.g., using named import instead of default import.

fix

Use: import xior from 'xior'

Uncaught (in promise) TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation

Using xior in a Node.js environment that does not have a global fetch (Node <18).

fix

Install node-fetch and set global fetch: globalThis.fetch = require('node-fetch')

xior: request timeout of 5000 ms exceeded

The request took longer than the configured timeout. xior does not have a built-in timeout, it uses AbortSignal.timeout (which may not be supported in older Node).

fix

Ensure your environment supports AbortSignal.timeout (Node >=15, modern browsers). Alternatively, use a polyfill.

Cannot read properties of undefined (reading 'status') when using async/await

Catching a network error where error.response is undefined.

fix

Check if error.response exists before accessing properties: if (error.response) { console.log(error.response.status); }

Upgrade

Version history

0.8.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/suhaotian/xior ↗

packagexior ↗

homepagehttps://github.com/suhaotian/xior ↗