docs

Documentation

Complete, feature-by-feature documentation for @developerehsan/api-client — a typed, modular, universal API client factory for TypeScript.

Every page here is self-contained: it explains one feature, shows runnable code, and links to the exact example source that demonstrates it live. If you want one long top-to-bottom guide instead, read the project README.

New here? Start with Getting started → Mental model → Modules & methods. Then jump to whatever feature you need.

---

The two runnable examples

Everything in these docs is exercised by two apps you can run locally:

Example	Stack	Shows
examples/react-vite	React + Vite (pure client-side)	Direct typed client, TanStack Query, and an interactive Feature Lab for the pipeline
examples/nextjs	Next.js App Router (SSR)	The SSR RPC bridge — call api.module.method() from the browser without leaking the backend URL, paths, or OpenAPI

Both are backed by the free, CORS-enabled DummyJSON API, so they run with no backend setup.

---

Guides by topic

Foundations

• Getting started — your first client in 5 minutes
• Mental model — the three concepts and the request pipeline
• Modules & methods — defineModule, ctx.request, composed calls
• Configuration reference — global → module → per-call, deep-merged
• Responses & error handling — the ApiResponse<T> envelope, typed errors, safeMode

The request pipeline

• Authentication — Bearer, Cookie, API key, OAuth2 (auto 401 → refresh → retry)
• Caching — LRU + TTL, cache-first / network-first / stale-while-revalidate, glob invalidation
• Deduplication — collapse identical in-flight requests
• Retries & backoff — exponential/linear/fixed, full-jitter, Retry-After
• Timeouts & cancellation — per-request timeouts, AbortSignal, debounce-cancel
• Concurrency queue — cap in-flight requests
• Multi-tenancy — per-call / per-module / global tenant, server context
• Environments — named base URLs, switch at runtime

Beyond HTTP

• Hooks & events — lifecycle hooks + the event emitter
• Streaming — ctx.stream() → NDJSON / SSE / raw byte AsyncIterable
• Modules beyond HTTP — ctx.run, ctx.emit, ctx.logger, ctx.config
• Cache persistence — pluggable L2 stores (memory / IndexedDB / Redis)

Tooling

• Code generation (CLI + Vite + Next.js) — types + descriptors from OpenAPI
• Runtime schema validation & drift detection
• TanStack Query — React / Vue / Solid

SSR & security

• SSR RPC bridge — hide the backend from the browser
• RPC rate limiting — createRateLimiter

Practical

• Testing — createMockClient + MockAdapter
• Framework & runtime guides — React SPA, Next.js, Node, edge
• Full API reference
• Troubleshooting & FAQ

---

Feature → example map

Where to see each feature actually running:

Feature	Doc	Live in
Typed client wiring	modules-and-methods	react-vite/.../api.config.ts
Direct typed calls	getting-started	DirectClientDemo.tsx
Caching / SWR	caching	FeatureLab.tsx
Deduplication	deduplication	FeatureLab.tsx
Retries & backoff	retries	FeatureLab.tsx
Timeout / cancellation	timeouts-and-cancellation	FeatureLab.tsx
Typed errors / safeMode	responses-and-errors	FeatureLab.tsx
Composed multi-call	modules-and-methods	api.config.ts
ctx.run (non-HTTP)	modules-beyond-http	api.config.ts
Hooks & events	hooks-and-events	ui.tsx (useEventLog)
Bearer auth + login	authentication	api.config.ts
TanStack Query	tanstack-query	TanstackDemo.tsx
Codegen wiring	codegen	types/generated/
SSR RPC bridge	ssr-rpc-bridge	nextjs/lib/api/api.config.ts
RPC rate limiter	rpc-rate-limiting	nextjs/lib/api/api.config.ts
RPC batching	ssr-rpc-bridge	nextjs/lib/api/rpc-client.ts

---

Packages

Package	Import	Purpose
@developerehsan/api-client	@developerehsan/api-client	The runtime library
— server entry	.../server	SSR RPC bridge (server half)
— browser entry	.../browser	SSR RPC bridge (browser half)
— codegen entry	.../codegen	Node-only codegen functions
— testing entry	.../testing	Mock client & adapter
— cache-stores entry	.../cache-stores	Pluggable persistent cache stores
@developerehsan/api-client-cli	npx @developerehsan/api-client	Codegen CLI
@developerehsan/api-client-query	.../query/{react,vue,solid}	TanStack Query integration
@developerehsan/api-client-vite	@developerehsan/api-client-vite	Vite / TanStack Start codegen plugin