reqcraft

Why reqcraft?

Install

npm install reqcraft

pnpm add reqcraft

yarn add reqcraft

Quick Start

import { createClient } from "reqcraft";

const api = createClient({
  baseURL: "https://api.example.com",
  headers: { Authorization: "Bearer token" },
  timeout: 5000,
});

// GET with typed response
const { data } = await api.get<User[]>("/users");

// POST — JSON auto-serialized
await api.post("/users", { name: "John", email: "[email protected]" });

// PUT
await api.put("/users/1", { name: "Jane" });

// DELETE
await api.delete("/users/1");

Default Instance

import reqcraft from "reqcraft";

const { data } = await reqcraft.get<User[]>("https://api.example.com/users");

Features

Query Parameters

api.get("/search", { params: { q: "reqcraft", page: 1, active: true } });
// GET /search?q=reqcraft&page=1&active=true

Timeout

const api = createClient({ timeout: 5000 });

// Override per request
api.get("/slow-endpoint", { timeout: 15000 });

Request Cancellation

const controller = new AbortController();

api.get("/users", { signal: controller.signal });

controller.abort();

Retry with Backoff

api.get("/flaky-endpoint", {
  retry: 3,
  retryDelay: 300, // 300ms, 600ms, 900ms (linear backoff)
});

Interceptors

// Add auth header to every request
api.interceptors.request.use((config) => {
  config.headers = {
    ...config.headers,
    "X-Request-Id": crypto.randomUUID(),
  };
  return config;
});

// Log every response
api.interceptors.response.use((response) => {
  console.log(`${response.config.method} ${response.config.url} → ${response.status}`);
  return response;
});

// Remove an interceptor
const id = api.interceptors.request.use(fn);
api.interceptors.request.eject(id);

Error Handling

import { isReqcraftError } from "reqcraft";
import type { ReqcraftError } from "reqcraft";

try {
  await api.get("/not-found");
} catch (err) {
  if (isReqcraftError(err)) {
    console.log(err.status);     // 404
    console.log(err.statusText); // "Not Found"
    console.log(err.data);       // Response body
  }
}

Response Types

// JSON (default)
const { data } = await api.get<User>("/user/1");

// Blob
const { data: blob } = await api.get<Blob>("/file.pdf", { responseType: "blob" });

// ArrayBuffer
const { data: buffer } = await api.get<ArrayBuffer>("/binary", { responseType: "arraybuffer" });

// Text
const { data: html } = await api.get<string>("/page", { responseType: "text" });

// ReadableStream
const { data: stream } = await api.get<ReadableStream>("/stream", { responseType: "stream" });

Download Progress

api.get("/large-file", {
  responseType: "blob",
  onDownloadProgress: ({ loaded, total, percent }) => {
    console.log(`${percent}% downloaded (${loaded}/${total} bytes)`);
  },
});

Transform Request / Response

const api = createClient({
  transformRequest: [(data) => {
    // Modify data before sending
    return { ...data, timestamp: Date.now() };
  }],
  transformResponse: [(data) => {
    // Transform response data
    return data;
  }],
});

Validate Status

const api = createClient({
  validateStatus: (status) => status < 500, // treat 4xx as success
});

FormData & File Uploads

const form = new FormData();
form.append("avatar", fileInput.files[0]);
form.append("name", "John");

await api.post("/upload", form);
// FormData is auto-detected — no manual content-type needed

Plugins

import { createClient, usePlugin } from "reqcraft";
import type { ReqcraftPlugin } from "reqcraft";

const logger: ReqcraftPlugin = {
  name: "logger",
  install(instance) {
    instance.interceptors.request.use((config) => {
      console.log(`→ ${config.method} ${config.url}`);
      return config;
    });
    instance.interceptors.response.use((response) => {
      console.log(`← ${response.status}`);
      return response;
    });
  },
};

const api = createClient({ baseURL: "https://api.example.com" });
usePlugin(api, logger);

API Reference

createClient(defaults?)

HTTP Methods

Config Options

Utilities

Coming from axios?

Security

License