ReqMindReqMindGitHub

Getting started ​

Install ​

sh
npm install @reqmind/core

The package ships both ESM and CJS with TypeScript types. Node ≥ 18 (or any runtime with a global fetch).

Create a client ​

ts
import { createClient } from "@reqmind/core";

const api = createClient({
  baseURL: "https://api.example.com",
  headers: { Authorization: "Bearer …", "X-Client": "reqmind" },
  cookies: undefined,            // (fetch handles credentials; pass anything you need here)
  cache: { enabled: true, ttl: 30_000, strategy: "cache-first" },
  retry: { attempts: 3, baseDelay: 1000, maxDelay: 30_000 },
  timeout: 10_000,
  fetch: undefined,              // defaults to the global fetch
});
OptionTypeDefaultDescription
baseURLstring—Resolved before every relative URL
headersRecord<string,string>—Merged into every request
cacheCacheOptions{ enabled: true, ttl: 30_000, strategy: "cache-first" }Cache behavior
retryRetryOptions{ attempts: 3, baseDelay: 1000, maxDelay: 30_000, backoff: "exponential", jitter: true, respectRetryAfter: true }Retry behavior
timeoutnumber—Default timeout in ms (0/absent = none)
fetchtypeof fetchglobal fetchCustom fetch implementation (testing, mocking, adapters)
intelligenceIntelligenceOptions{ enabled: true }Observation + adaptive behaviors (guide)
circuitBreakerCircuitBreakerOptions{ enabled: true, failureThreshold: 5, resetTimeout: 10_000 }Per-endpoint fail isolation (guide)
schedulerSchedulerOptions— (disabled)Opt-in traffic shaping: priority/concurrency/rate limits (guide)

Make requests ​

ts
const users = await api.get<{ id: number }[]>("/users", { params: { page: 1, sort: "name" } });
console.log(users.data, users.status, users.statusText, users.headers);

await api.post("/users", { name: "Moaaz" });
await api.put("/users/1", { name: "Moaaz" });
await api.patch("/users/1", { name: "Moaaz" });
await api.delete("/users/1");
await api.head("/health");
await api.options("/users");

// The generic escape hatch:
await api.request("GET", "/users", { params: { page: 2 } });

Every method returns a CancellablePromise<ApiResponse<T>> — a normal Promise augmented with a .cancel() method.

Request options ​

OptionTypeDescription
baseURLstringOverride the client base URL for this request
headersRecord<string,string>Merge on top of client headers
paramsRecord<string, ParamValue | ParamValue[]>Serialized into the query string
bodyunknownJSON-serialized unless it's already a BodyInit
signalAbortSignalExternal cancellation
timeoutnumberPer-request timeout override
cacheboolean | CacheOptionsOverride caching for this request
retryboolean | RetryOptionsOverride retrying for this request
tagsstring[]Mark the response for tag-based invalidation

Response shape ​

ts
interface ApiResponse<T> {
  data: T;              // parsed body (JSON by default)
  status: number;       // 200, 201…
  statusText: string;
  headers: Headers;     // native Headers
}

Success is a 2xx status. Non-2xx responses throw an HttpError carrying .status, .statusText, .headers, and the original Response-based diagnostics.

Errors ​

ts
import { HttpError, TimeoutError, CancelledError, isAbortError } from "@reqmind/core";

try {
  await api.get("/users");
} catch (err) {
  if (err instanceof HttpError) {
    console.log("HTTP", err.status, err.statusText);
  } else if (err instanceof TimeoutError) {
    console.log("took too long");
  } else if (err instanceof CancelledError) {
    console.log("aborted");
  }
}

Next: request intelligence — dedup, cache & SWR.