Cosrx

A lightweight promise-based HTTP client built on top of the native Fetch API, providing an Axios-style API with retries, interceptors, cancellation, request deduplication, and flexible configuration.

It is designed to stay close to web standards while offering the ergonomics required for real-world applications.

Features
Installation
Quick Start
Creating an Instance
HTTP Methods
Request Configuration
Query Parameters
Request Body Serialization
Response Structure
Response Types
Interceptors
Retry
Timeout
Request Deduplication
Cancellation
Custom Status Validation
Error Handling
Authentication
Cookies
TypeScript
Next.js
Design Philosophy

Features

Built on the native Fetch API no extra dependencies
Axios-style API: get, post, put, patch, delete, head, options
Request and response interceptors with eject and clear support
Built-in retry with exponential backoff, fixed delay, and jitter
Request cancellation via CancelController or any AbortSignal
Request deduplication only the latest in-flight request with a given key survives
Configurable timeout using AbortController internally
Automatic body serialization (JSON, FormData, URLSearchParams, Blob, ArrayBuffer, strings)
Flexible query parameter serialization: repeat, comma, bracket, and dot-notation for nested objects
Multiple response types: json, text, blob, arrayBuffer, stream, auto
Typed errors via CosrxError with isHttpError, status, response, and config
baseURL validation at instance creation time
Full TypeScript support with generics
Works in browsers, Node.js 18+, and Next.js (client and server)

Installation

npm install @cosrx/core

yarn add @cosrx/core

pnpm add @cosrx/core

Quick Start

import cosrx from "@cosrx/core";

const res = await cosrx.get("https://api.example.com/users");
console.log(res.data);

Creating an Instance

Use cosrx.create() to create isolated instances with their own base configuration, interceptors, and in-flight request tracking.

import cosrx from "@cosrx/core";

const api = cosrx.create({
  baseURL: "https://api.example.com",
  timeout: 5000,
  headers: {
    "Content-Type": "application/json",
    "X-App-Version": "1.0.0",
  },
});

Or import the Cosrx class directly for subclassing or manual instantiation:

import { Cosrx } from "@cosrx/core";

const api = new Cosrx({
  baseURL: "https://api.example.com",
  timeout: 5000,
});

Note: baseURL must be an absolute URL with http or https protocol. An invalid baseURL throws a CosrxError immediately at construction time not at request time.

// Throws CosrxError immediately
const api = new Cosrx({ baseURL: "not-a-valid-url" });

// Also throws ftp, ws, etc. are not accepted
const api = new Cosrx({ baseURL: "ftp://files.example.com" });

Each instance maintains its own:

Base configuration (headers, timeout, retry, etc.)
Request and response interceptors
In-flight request map (for deduplication)

HTTP Methods

No-body methods

api.get("/users");
api.head("/health");
api.delete("/users/1");
api.options("/users");

Body methods

api.post("/users", { name: "Vinod" });
api.put("/users/1", { name: "Updated Name" });
api.patch("/users/1", { active: false });

Data can also be passed via config.data:

api.post("/users", undefined, { data: { name: "Vinod" } });

When both data argument and config.data are provided, the data argument takes precedence.

Request Configuration

Every method accepts an optional config object that extends the native RequestInit:

api.get("/users", {
  params: { page: 1, limit: 20 },
  timeout: 3000,
  responseType: "json",
  headers: {
    "X-Request-ID": "abc-123",
  },
});

Full Configuration Reference

interface CosrxConfig extends RequestInit {
  // URL
  url?: string;
  baseURL?: string;

  // Query parameters
  params?: Record<string, ParamValue>;
  arrayFormat?: "repeat" | "comma" | "bracket";

  // Request body
  data?: unknown;

  // Timing
  timeout?: number;

  // Response
  responseType?: "json" | "text" | "blob" | "arrayBuffer" | "stream" | "auto";
  validateStatus?: (status: number) => boolean;

  // Deduplication
  dedupeKey?: string;

  // Retry
  retry?: RetryConfig | false;

  // Cancellation (any AbortSignal)
  signal?: AbortSignal;

  // All native fetch options are also accepted:
  // credentials, cache, mode, redirect, referrerPolicy, etc.
}

All unrecognized options are forwarded directly to fetch.

Query Parameters

Primitive values

api.get("/search", {
  params: {
    q: "typescript",
    page: 2,
    active: true,
  },
});
// → /search?q=typescript&page=2&active=true

Arrays

Control how arrays are serialized with arrayFormat:

// repeat (default) → ids=1&ids=2&ids=3
api.get("/items", {
  params: { ids: [1, 2, 3] },
  arrayFormat: "repeat",
});

// comma → ids=1,2,3
api.get("/items", {
  params: { ids: [1, 2, 3] },
  arrayFormat: "comma",
});

// bracket → ids[]=1&ids[]=2&ids[]=3
api.get("/items", {
  params: { ids: [1, 2, 3] },
  arrayFormat: "bracket",
});

Nested objects

Nested objects are flattened using dot notation:

api.get("/users", {
  params: {
    filter: { role: "admin", active: true },
  },
});
// → /users?filter.role=admin&filter.active=true

Null and undefined values

null and undefined param values are silently skipped and never appended to the URL:

api.get("/users", {
  params: { role: "admin", page: undefined, limit: null },
});
// → /users?role=admin

Request Body Serialization

Cosrx automatically serializes the request body based on the data type:

Data Type	Serialization	`Content-Type` header
Plain object / array	`JSON.stringify`	`application/json`
`FormData`	Sent as-is	Removed (browser sets it with boundary)
`URLSearchParams`	Sent as-is	Removed (browser sets it)
`Blob`	Sent as-is	Removed (browser sets it)
`ArrayBuffer` / typed array	Sent as-is	Not modified
`string`	Sent as-is	Not modified

// JSON — automatic
api.post("/users", { name: "Vinod", role: "admin" });

// FormData
const form = new FormData();
form.append("avatar", file);
api.post("/upload", form);

// URLSearchParams
const params = new URLSearchParams({ grant_type: "password" });
api.post("/oauth/token", params);

// Typed array
const buffer = new Uint8Array([1, 2, 3]).buffer;
api.post("/binary", buffer);

// Raw string
api.post("/raw", "plain text body");

Note: For FormData and URLSearchParams, Cosrx removes any existing Content-Type header so the browser or runtime can set the correct value (including multipart boundary) automatically.

Response Structure

All methods resolve with a CosrxRes object:

interface CosrxRes<T = unknown> {
  data: T;               // Parsed response body
  status: number;        // HTTP status code
  statusText: string;    // HTTP status text
  headers: Headers;      // Native Headers object
  config: CosrxConfig;   // The config used for the request
  rawResponse: Response; // The original fetch Response
}

const res = await api.get<User>("/users/1");

console.log(res.data);                          // User object
console.log(res.status);                        // 200
console.log(res.statusText);                    // "OK"
console.log(res.headers.get("content-type"));   // "application/json"
console.log(res.rawResponse);                   // native Response

Response Types

Control how the response body is parsed with responseType:

// JSON (explicit)
const res = await api.get("/data", { responseType: "json" });

// Plain text
const res = await api.get("/readme", { responseType: "text" });

// Blob (file downloads)
const res = await api.get<Blob>("/image.png", { responseType: "blob" });
const url = URL.createObjectURL(res.data);

// ArrayBuffer (binary processing)
const res = await api.get<ArrayBuffer>("/binary", { responseType: "arrayBuffer" });

// ReadableStream
const res = await api.get("/stream", { responseType: "stream" });
const reader = (res.data as ReadableStream).getReader();

// auto (default)
// Inspects Content-Type: parses as JSON if application/json, otherwise as text
const res = await api.get("/anything");

Interceptors

Interceptors let you transform requests before they are sent and transform or handle responses before they reach your code.

Request interceptors

Interceptors run in reverse order of registration (last registered, first executed).

const id = api.interceptors.request.use((config) => {
  config.headers = {
    ...config.headers,
    Authorization: `Bearer ${getAccessToken()}`,
    "X-Request-Time": Date.now().toString(),
  };
  return config;
});

Response interceptors

Response interceptors run in the order they were registered.

api.interceptors.response.use(
  (res) => {
    // Transform successful responses
    return res;
  },
  (err) => {
    // Handle or rethrow errors
    console.error("Response error:", err);
    throw err;
  },
);

Ejecting an interceptor

use() returns a numeric ID that can be used to remove the interceptor later:

const requestInterceptorId = api.interceptors.request.use((config) => {
  config.headers = { ...config.headers, "X-Debug": "true" };
  return config;
});

// Remove just this interceptor
api.interceptors.request.eject(requestInterceptorId);

Clearing all interceptors

api.interceptors.request.clear();
api.interceptors.response.clear();

Refresh token pattern

A safe implementation that avoids infinite retry loops:

import { isCosrxError } from "@cosrx/core";

api.interceptors.response.use(
  (res) => res,
  async (err) => {
    if (isCosrxError(err) && err.status === 401 && !err.config?._retry) {
      err.config._retry = true;
      await refreshAccessToken();
      return api.request(err.config);
    }
    throw err;
  },
);

Retry

Cosrx has a built-in retry mechanism with support for fixed delay, exponential backoff, and jitter.

api.get("/unstable-endpoint", {
  retry: {
    times: 3,
    delay: 300,
    backoff: "exponential",
    jitter: true,
    on: [408, 429, 500, 502, 503, 504],
  },
});

Retry configuration

interface RetryConfig {
  times: number;                      // Number of retry attempts (required)
  delay?: number;                     // Base delay in ms (default: 300)
  backoff?: "exponential" | "fixed";  // Delay growth strategy (default: exponential)
  jitter?: boolean;                   // Randomize delay ±25% (default: true)
  on?: number[];                      // HTTP status codes to retry on
}

Defaults

Option	Default
`delay`	`300` ms
`backoff`	`"exponential"`
`jitter`	`true`
`on`	`[408, 429, 500, 502, 503, 504]`

Backoff behavior

With backoff: "exponential" and delay: 300:

Attempt	Base delay	With jitter (approx.)
1	300 ms	225 – 450 ms
2	600 ms	450 – 900 ms
3	1200 ms	900 – 1800 ms

With backoff: "fixed" and delay: 300, every retry waits exactly 300 ms (with ±25% jitter if jitter is true).

Retries are automatically skipped for:

Requests that were aborted or cancelled
Status codes not in the on list
Network errors with no response are retried by default

Disabling retry per-request

Pass retry: false to opt out on a specific request, even if a default is configured on the instance:

api.get("/no-retry", { retry: false });

Timeout

Timeouts are implemented with AbortController internally. A timed-out request throws a CosrxError with message: "Request aborted".

// Instance-level default
const api = cosrx.create({
  baseURL: "https://api.example.com",
  timeout: 5000,
});

// Per-request override
await api.get("/slow", { timeout: 10000 });

// Disable timeout for one request
await api.get("/long-poll", { timeout: 0 });

When both timeout and signal are set, Cosrx combines them internally — whichever fires first cancels the request.

Request Deduplication

When the same request is fired multiple times in quick succession, use dedupeKey to abort the previous in-flight request with the same key. Only the latest request survives.

function searchUsers(query: string) {
  return api.get("/users/search", {
    params: { q: query },
    dedupeKey: "user-search",
  });
}

// Rapid successive calls — only the last one resolves
searchUsers("v");
searchUsers("vi");
searchUsers("vin"); // only this one resolves

Note: On retry attempts, dedupeKey is intentionally stripped so retries do not cancel themselves.

Cancellation

Using `CancelController`

CancelController wraps AbortController with a cancel reason and convenience helpers.

import { CancelController } from "@cosrx/core";

const controller = new CancelController();

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

// Cancel the request
controller.cancel("User navigated away");

// Inspect state
console.log(controller.isCancelled); // true
console.log(controller.reason);      // "User navigated away"

Checking for cancel errors

Use the static CancelController.isCancelError() helper:

try {
  await api.get("/users", { signal: controller.signal });
} catch (err) {
  if (CancelController.isCancelError(err)) {
    console.log("Request was cancelled");
  }
}

Or with isCosrxError:

import { isCosrxError } from "@cosrx/core";

try {
  await api.get("/users", { signal: controller.signal });
} catch (err) {
  if (isCosrxError(err) && err.message === "Request aborted") {
    console.log("Request was cancelled or timed out");
  }
}

Using a native `AbortSignal`

Cosrx accepts any AbortSignal:

// Native AbortController
const ac = new AbortController();
api.get("/users", { signal: ac.signal });
ac.abort();

// AbortSignal.timeout (Node 17.3+ / modern browsers)
api.get("/users", { signal: AbortSignal.timeout(3000) });

Custom Status Validation

By default, Cosrx throws for any response where response.ok is false (status outside 200–299). Override this with validateStatus:

// Treat anything below 500 as success
api.get("/might-404", {
  validateStatus: (status) => status < 500,
});

// Treat only exactly 200 as success
api.get("/strict", {
  validateStatus: (status) => status === 200,
});

// Never throw always resolve
api.get("/always-resolve", {
  validateStatus: () => true,
});

Error Handling

Cosrx throws a typed CosrxError for all failure cases: HTTP errors, network errors, timeouts, and aborts.

import { CosrxError, isCosrxError } from "@cosrx/core";

try {
  await api.get("/users");
} catch (err) {
  if (err instanceof CosrxError) {
    console.log(err.message);      // Human-readable error message
    console.log(err.status);       // HTTP status (undefined if no response)
    console.log(err.isHttpError);  // true if a response was received
    console.log(err.response);     // CosrxRes | null
    console.log(err.config);       // The config used for the request
  }
}

Using the isCosrxError type guard:

try {
  await api.post("/users", { name: "Vinod" });
} catch (err) {
  if (isCosrxError(err)) {
    if (err.status === 422) {
      console.log("Validation error:", err.response?.data);
    } else if (err.status === 401) {
      redirectToLogin();
    } else if (!err.isHttpError) {
      console.log("Network or abort error:", err.message);
    }
  }
}

Error scenarios

Scenario	`err.isHttpError`	`err.status`	`err.message`
HTTP 4xx / 5xx response	`true`	e.g. `404`	`"Request failed with status 404"`
Network failure	`false`	`undefined`	`"Network error"`
Timeout / cancellation	`false`	`undefined`	`"Request aborted"`

Authentication

Bearer token (per-request)

api.get("/me", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

Bearer token via interceptor

api.interceptors.request.use((config) => {
  config.headers = {
    ...config.headers,
    Authorization: `Bearer ${getAccessToken()}`,
  };
  return config;
});

Basic Auth

const credentials = btoa("username:password");

api.get("/protected", {
  headers: {
    Authorization: `Basic ${credentials}`,
  },
});

Cookies

Same-origin requests (browser)

Cookies are sent automatically no configuration required.

cosrx.get("/api/me");

Cross-origin requests (browser)

Pass credentials: "include". The server must respond with Access-Control-Allow-Credentials: true and a specific (non-wildcard) origin in Access-Control-Allow-Origin.

cosrx.get("https://api.example.com/me", {
  credentials: "include",
});

TypeScript

All methods accept a type parameter for the response body:

interface User {
  id: number;
  name: string;
  email: string;
}

const res = await api.get<User>("/users/1");
// res.data is typed as User

const listRes = await api.get<User[]>("/users");
// listRes.data is typed as User[]

const created = await api.post<User>("/users", { name: "Vinod" });
// created.data is typed as User

Exported types

import type {
  CosrxConfig,    // Full request configuration interface
  CosrxRes,       // Response structure interface
  CosrxInstance,  // Interface describing a Cosrx instance
  RetryConfig,    // Retry configuration interface
} from "@cosrx/core";

Next.js

Client components

Cookies behave exactly as in the browser. For cross-origin requests, pass credentials: "include":

"use client";
import cosrx from "@cosrx/core";

const res = await cosrx.get("https://api.example.com/me", {
  credentials: "include",
});

Server components and Route Handlers

Cookies are not forwarded automatically in server-side environments. Forward them manually:

import { cookies } from "next/headers";
import cosrx from "@cosrx/core";

export async function GET() {
  const res = await cosrx.get("https://api.example.com/me", {
    headers: {
      Cookie: cookies().toString(),
    },
  });
  return Response.json(res.data);
}

Default vs Named Export

import cosrx from "@cosrx/core";     // Default instance with .create() method attached
import { Cosrx } from "@cosrx/core"; // Class for new Cosrx(...) or subclassing

The default export is a pre-constructed Cosrx instance ready to use without any configuration. cosrx.create() creates new isolated instances from it.

Design Philosophy

Stay close to Fetch. Cosrx does not abstract away browser or runtime behavior it extends it.
Explicit over implicit. No hidden auth injection, no silent cookie handling, no magic defaults.
No opinionated auth. You decide how credentials are attached and managed.
Small surface area. Every exported API is intentional and typed.
Standards-first. Built on fetch, AbortController, AbortSignal, and Headers all native platform APIs.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
docs		docs
examples		examples
src		src
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
rollup.config.ts		rollup.config.ts
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Cosrx

Table of Contents

Features

Installation

Quick Start

Creating an Instance

HTTP Methods

No-body methods

Body methods

Request Configuration

Full Configuration Reference

Query Parameters

Primitive values

Arrays

Nested objects

Null and undefined values

Request Body Serialization

Response Structure

Response Types

Interceptors

Request interceptors

Response interceptors

Ejecting an interceptor

Clearing all interceptors

Refresh token pattern

Retry

Retry configuration

Defaults

Backoff behavior

Retries are automatically skipped for:

Disabling retry per-request

Timeout

Request Deduplication

Cancellation

Using CancelController

Checking for cancel errors

Using a native AbortSignal

Custom Status Validation

Error Handling

Error scenarios

Authentication

Bearer token (per-request)

Bearer token via interceptor

Basic Auth

Cookies

Same-origin requests (browser)

Cross-origin requests (browser)

TypeScript

Exported types

Next.js

Client components

Server components and Route Handlers

Default vs Named Export

Design Philosophy

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Using `CancelController`

Using a native `AbortSignal`

Packages