A lightweight TypeScript fetch wrapper library that provides quality-of-life improvements including explicit path construction, type-safe query parameters, consistent error formatting, and automatic content handling.
A lightweight TypeScript fetch wrapper library that provides quality-of-life improvements including explicit path construction, type-safe query parameters, consistent error formatting, and automatic content handling.
npm install http-plz
yarn add http-plz
pnpm add http-plz
import httpPlz from 'http-plz';
// Create a client instance
const api = httpPlz({
baseURL: 'https://jsonplaceholder.typicode.com',
options: {
headers: {
'Content-Type': 'application/json',
},
},
resolver: 'json', // Default response resolver
});
// Make requests
const users = await api.get({ path: '/users' });
const user = await api.post({
path: '/users',
body: { name: 'John Doe', email: 'john@example.com' },
});
interface Config {
baseURL: string;
options?: RequestInit;
resolver?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData';
}
interface RequestOptions {
path: string;
query?: { [key: string]: string };
opts?: Omit<RequestInit, 'method' | 'body'>;
resolver?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData';
body?: unknown;
}
All methods return a Promise that resolves to an httpResponse<T> object:
// GET request
const response = await api.get<User[]>({
path: '/users',
query: { page: '1', limit: '10' },
});
// POST request
const response = await api.post<User>({
path: '/users',
body: { name: 'Jane Doe', email: 'jane@example.com' },
});
// PUT request
const response = await api.put<User>({
path: '/users/1',
body: { name: 'Jane Smith' },
});
// DELETE request
const response = await api.delete({
path: '/users/1',
});
import httpPlz from 'http-plz';
const api = httpPlz({
baseURL: 'https://api.example.com',
});
const users = await api.get({
path: '/users',
});
console.log(users.data); // Response data
console.log(users.status); // HTTP status code
const users = await api.get({
path: '/users',
query: {
page: '1',
limit: '10',
sort: 'name',
},
});
// Requests: https://api.example.com/users?page=1&limit=10&sort=name
const newUser = await api.post({
path: '/users',
body: {
name: 'John Doe',
email: 'john@example.com',
role: 'admin',
},
});
const api = httpPlz({
baseURL: 'https://api.example.com',
options: {
headers: {
'Authorization': 'Bearer your-token',
'Content-Type': 'application/json',
},
},
});
// Override options per request
const response = await api.get({
path: '/protected-resource',
opts: {
headers: {
'X-Custom-Header': 'custom-value',
},
cache: 'no-cache',
},
});
// JSON response (default)
const jsonData = await api.get({
path: '/data.json',
resolver: 'json',
});
// Text response
const textData = await api.get({
path: '/data.txt',
resolver: 'text',
});
// Blob response (for files)
const fileBlob = await api.get({
path: '/file.pdf',
resolver: 'blob',
});
try {
const response = await api.get({ path: '/users' });
console.log(response.data);
} catch (error) {
if (error instanceof HttpError) {
console.error('Request failed:', {
status: error.response.status,
statusText: error.response.statusText,
body: error.body,
requestOptions: error.requestOptions,
});
}
}
The library provides structured error handling through the HttpError class. When a request fails (non-2xx status codes), the library formats the error and throws it for you to handle as needed.
class HttpError extends Error {
name: string;
response: Response;
body: unknown;
requestOptions: RequestInit;
constructor(req: RequestInit, response: Response, body: unknown) {
super(`HTTP Error: ${response.status} ${response.statusText}`);
this.name = 'HttpError';
this.response = response;
this.body = body;
this.requestOptions = req;
}
}
response: The original Response object from fetchbody: The error response body (parsed as JSON if possible, otherwise as text)requestOptions: The RequestInit options used for the requestmessage: Formatted error message with status code and status textimport { HttpError } from 'http-plz';
try {
const response = await api.get({ path: '/users/999' });
} catch (error) {
if (error instanceof HttpError) {
// Access specific error information
console.error(`Status: ${error.response.status}`);
console.error(`Status Text: ${error.response.statusText}`);
console.error(`Error Body:`, error.body);
console.error(`Request URL: ${error.response.url}`);
// Handle specific status codes
switch (error.response.status) {
case 404:
console.error('Resource not found');
break;
case 401:
console.error('Unauthorized - check your credentials');
break;
case 500:
console.error('Server error - try again later');
break;
default:
console.error('Request failed:', error.message);
}
}
}
The library doesn't perform any automatic error recovery or retries - it simply formats errors consistently and lets you handle them according to your application's needs.
The middleware system in this library is designed to be simple, powerful, and predictable. It's based on "stacks" (execution chains) that clearly separate the request logic from the response logic, much like Axios interceptors, but with a more explicit approach.
The main reason for this architecture is simplicity and clarity. Instead of a single, overloaded interceptor, you have two distinct chains, each with a single, clear responsibility.
For complete control, each stack executes in a specific order, creating a symmetrical "wrapping" effect:
This FILO order for the response is crucial. It means that the first middleware to "wrap" the request is the last one to "unwrap" the response. This creates perfect symmetry, ideal for tasks like timing or logging, ensuring that the start and end of a single feature execute in the correct layers.
Imagine you register two middlewares for each stack to see this behavior in action.
Middleware Definitions:
const requestMiddleware1 = async (options) => {
console.log("1. Request Middleware 1 (Outer Layer)");
return options;
};
const requestMiddleware2 = async (options) => {
console.log("2. Request Middleware 2 (Inner Layer)");
return options;
};
const responseMiddleware1 = async (response) => {
console.log("5. Response Middleware 1 (Outer Layer)");
return response;
};
const responseMiddleware2 = async (response) => {
console.log("4. Response Middleware 2 (Inner Layer)");
return response;
};
// Client registration
const client = createClient({
requestMiddlewares: [requestMiddleware1, requestMiddleware2],
responseMiddlewares: [responseMiddleware1, responseMiddleware2],
});
client.get({ path: '/test' });
Console Output:
1. Request Middleware 1 (Outer Layer)
2. Request Middleware 2 (Inner Layer)
3. [HTTP Request is made]
4. Response Middleware 2 (Inner Layer)
5. Response Middleware 1 (Outer Layer)
As you can see, the flow is like an onion. Request Middleware 1 and Response Middleware 1 act as the outermost layer, while Request Middleware 2 and Response Middleware 2 are the inner layer that directly wraps the fetch call. This FILO order in the response is what guarantees this symmetry, allowing you to manage a "layer's" state or logic predictably.
The library automatically handles request bodies and headers based on the input type, determining the appropriate content type and processing method for each body format.
The library uses the processBody utility to automatically detect and handle different body types:
await api.post({
path: '/users',
body: { name: 'John', email: 'john@example.com' }
// Automatically stringified with Content-Type: application/json
});
const formData = new FormData();
formData.append('name', 'John');
formData.append('file', fileInput);
await api.post({
path: '/upload',
body: formData
// Content-Type: multipart/form-data (set automatically by browser)
});
const params = new URLSearchParams();
params.append('name', 'John');
params.append('email', 'john@example.com');
await api.post({
path: '/form-submit',
body: params
// Content-Type: application/x-www-form-urlencoded
});
await api.post({
path: '/text',
body: 'Plain text content'
// Sent as-is (no automatic Content-Type)
});
const blob = new Blob(['binary data'], { type: 'application/octet-stream' });
await api.post({
path: '/binary',
body: blob
// Sent as-is (Content-Type from blob if available)
});
Headers are merged in the following priority order (highest to lowest):
opts.headers)config.options.headers)const api = httpPlz({
baseURL: 'https://api.example.com',
options: {
headers: {
'Authorization': 'Bearer token',
'Content-Type': 'application/json', // Will be overridden
},
},
});
await api.post({
path: '/upload',
body: formData, // Sets Content-Type: multipart/form-data
opts: {
headers: {
'X-Custom-Header': 'custom-value', // Highest priority
},
},
});
// Final headers:
// - Authorization: Bearer token (from base config)
// - Content-Type: multipart/form-data (automatic, overrides base)
// - X-Custom-Header: custom-value (per-request)
await api.post({
path: '/custom',
body: { data: 'value' },
opts: {
headers: {
'Content-Type': 'application/custom+json', // Override automatic detection
},
},
});
The library handles content processing transparently - you simply provide the body in the format that makes sense for your use case, and the appropriate headers and encoding are applied automatically.
The library returns an enhanced Response object with an additional data property:
interface httpResponse<T = unknown> extends Response {
data?: T;
}
Plugin Architecture: Extend functionality with plugins (not sure if I'll add all of them, but this architecture opens the possibility to create yours)
Built-in Retry Logic: Configurable retry strategies
Request/Response Logging: Debug and monitoring capabilities
# Install dependencies
pnpm install
# Run tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Build the library
pnpm build
# Lint code
pnpm lint:check
# Format code
pnpm format:check
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
If you find this library helpful, please consider giving it a ⭐ on GitHub!
For questions, issues, or feature requests, please open an issue on the GitHub repository.
FAQs
A lightweight TypeScript fetch wrapper library that provides quality-of-life improvements including explicit path construction, type-safe query parameters, consistent error formatting, and automatic content handling.
We found that http-plz demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.