Merge pull request #17 from developerEhsan/feat/api-client-overhaul

feat: major overhaul — DX, type-safety, modules-beyond-HTTP, roadmap features

Author: developerEhsan

.changeset/api-client-overhaul.md

@@ -0,0 +1,46 @@
+---
+"@developerehsan/api-client": major
+"@developerehsan/api-client-cli": major
+"@developerehsan/api-client-vite": major
+---
+
+Major overhaul: developer experience, type-safety, modular logic, and roadmap features.
+
+**Breaking / behavioral**
+
+- `ctx.request` is now generic over the literal `path` (`request<T, const P>`): a path
+  with `{placeholders}` requires exactly those `pathParams` at compile time (missing/typo
+  is now a type error). Explicit `request<T>(...)` still works.
+- Lifecycle hooks now COMPOSE across global → module → per-call (all fire; transforming
+  hooks chain). Transforming-hook return types widened to allow a `void` pass-through.
+- `createClient` fail-fasts on nonsensical config (negative ttl/attempts, bad queue
+  concurrency, SWR with cache disabled, oauth2 without a refresh endpoint).
+- The dead parallel `http/pipeline.ts` implementation was removed.
+
+**New capabilities**
+
+- Config & hooks parity: `hooks` on module + per-call config; new `onSuccess`/`onSettled`;
+  `onRetry` is now actually fired; per-call `queue` opt-out; `client.config.resolve()`
+  returns a redacted resolved-config snapshot.
+- Type-safety: template-literal path-param inference, a typed `ClientEventMap` for
+  `on`/`off`, and a `*.test-d.ts` regression suite.
+- Config-driven codegen: `api-client.config.*` files, real per-operation `diff`,
+  `watchAndGenerate` (local + remote-URL polling with ETag/hash), `generate --check`
+  for CI, and secret-safe remote spec fetching.
+- Modules beyond HTTP: `ctx.run` (opt-in queue/dedup/retry/timeout for any async work),
+  `ctx.stream` (NDJSON/SSE/raw async iterables), `ctx.emit`/`ctx.logger`/`ctx.config`,
+  and `extends: 'auto'` from the runtime schema. New `OperationError`.
+- RPC bridge: request batching (`{ __rpcBatch }`, per-sub-call validation, `maxBatchSize`),
+  a built-in rate limiter (`createRateLimiter`), and TanStack Start / Remix route adapters.
+- Pluggable persistent cache stores (`@developerehsan/api-client/cache-stores`:
+  memory / IndexedDB / Redis) layered behind the sync in-memory LRU.
+- React Query hooks emission (`emitReactQueryHooks`).
+- Framework glue: `withApiClientCodegen` for Next.js and the new
+  `@developerehsan/api-client-vite` plugin (also covers TanStack Start).
+
+Security-reviewed: the RPC trust boundary, batching, prototype-pollution guards,
+`sanitizePerCall` closed-set, rate-limiter key handling, and codegen fetch hygiene were
+adversarially reviewed with numbered threat-case tests.
+
+> Note: loading a **TypeScript** `api-client.config.ts` requires the optional `jiti`
+> dependency (`pnpm add -D jiti`); `.mjs`/`.js`/`.json` config files work with no extra deps.

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "cSpell.words": ["Codegen"]
+}

README.md

@@ -85,6 +85,13 @@ code stays clean.
 | **Validation** | Runtime response validation + schema drift detection |
 | **TanStack Query** | Typed `queryOptions` / `mutationOptions` / `infiniteQueryOptions` for React, Vue, Solid |
 | **SSR RPC bridge** | Call `api.module.method()` from client components in Next.js / TanStack Start **without** exposing the backend URL, paths, or OpenAPI to the browser |
+| **RPC batching** | Coalesce same-tick bridge calls into one round-trip; each sub-call validated + authorized individually |
+| **RPC rate limiter** | Built-in `createRateLimiter` for the handler `onRequest` (per-IP / per-session, pluggable store) |
+| **Streaming** | `ctx.stream()` → `AsyncIterable` for NDJSON / SSE / raw byte streams (client-side) |
+| **Modules beyond HTTP** | `ctx.run()` runs any async logic with opt-in queue/dedup/retry/timeout; `ctx.emit` / `ctx.logger` / `ctx.config` |
+| **Cache persistence** | Pluggable L2 stores (IndexedDB / Redis) behind the in-memory LRU |
+| **Auto codegen** | Config-file-driven `generate` / watch / `--check`; Vite plugin + Next.js integration |
+| **Hooks** | `onRequest`/`onResponse`/`onError`/`onRetry`/`onSuccess`/`onSettled` composed across global → module → per-call |
 | **Testing** | `createMockClient` + `MockAdapter` |
 
 ### Packages
@@ -1058,7 +1065,7 @@ ergonomics.
 ```text
  Browser (client component)                Server (Node / edge)
  ───────────────────────────               ─────────────────────────────
- api.pet.getPetById({ petId })             createRpcHandler(realApi, { expose })
+ api.products.getProductById({ id })       createRpcHandler(realApi, { expose })
    │  proxy, typed via `typeof serverApi`     │  allowlist → authorize → dispatch
    │  (type-only, erased at build)            ▼  runs the REAL client (holds secrets)
    ▼  POST same-origin { module,method,args }
@@ -1150,7 +1157,7 @@ import { ApiError } from '@developerehsan/api-client/browser'
 
 async function load() {
   try {
-    const pet = await api.pet.getPetById({ petId: 1 }) // → Pet, fully typed
+    const product = await api.products.getProductById({ id: 1 }) // → Product, typed
   } catch (e) {
     if (e instanceof ApiError) console.log(e.status, e.message) // rehydrated!
   }
@@ -1170,7 +1177,7 @@ export const q = createQueryIntegration(api, { modules: rpcModules })
 
 ### Cancellation
 
-Pass an `AbortSignal` as usual — `api.pet.getPetById({ petId }, { signal })`. The
+Pass an `AbortSignal` as usual — `api.products.getProductById({ id }, { signal })`. The
 signal is **not** sent over the wire (it isn't serializable); it's honored
 locally and rejects the promise with an `AbortError` on abort.
 
@@ -1189,7 +1196,7 @@ The handler enforces all of the following before dispatch:
 | Error leakage | Only `{ name, status, code, message }` cross the wire; stacks, request URLs, and headers never do (`details` only when `dev: true`) |
 
 > **Note:** the bridge client *type* mirrors your whole API surface, so
-> `api.pet.deletePet(...)` still type-checks even if it isn't exposed — the
+> `api.products.deleteProduct(...)` still type-checks even if it isn't exposed — the
 > `expose` allowlist is the runtime gate, and an un-exposed call is denied.
 
 A complete, runnable example lives in [`examples/nextjs`](./examples/nextjs).
@@ -1423,28 +1430,41 @@ Monorepo layout: `packages/core` (runtime), `packages/cli` (codegen),
 
 ---
 
-## 28. Roadmap (planned features)
-
-These are planned or under consideration — not yet shipped. Contributions and
-feedback welcome.
-
-- **`extends: 'auto'` auto-modules from the runtime schema** — build module
-  methods directly from a runtime-fetched OpenAPI document (today auto-modules
-  come from the build-time codegen descriptor; the runtime path is stubbed).
-- **Batching over the RPC bridge** — coalesce multiple `api.*.*()` calls made in
-  the same tick into a single round-trip, with per-sub-call allowlist/authorize.
-- **Streaming / async-iterable responses** — first-class support for
-  `text/event-stream` and chunked responses through the pipeline and the bridge.
-- **Built-in rate limiter** — a ready-to-use limiter for `onRequest` (per-IP /
-  per-session), instead of only the hook point.
-- **Richer per-module method-name autocomplete in `config.modules`** — close the
-  one remaining inference gap so the plain-object form matches the definer form.
-- **First-party TanStack Start & Remix adapters** — thin glue on top of the
-  generic HTTP transport, mirroring the Next.js Server Action helper.
+## 28. Roadmap
+
+### Shipped (major overhaul)
+
+- **`extends: 'auto'` auto-modules from the runtime schema** — module methods
+  are now derived at runtime from a fetched OpenAPI document (resolved lazily as
+  the schema loads).
+- **Batching over the RPC bridge** — `createRpcClient(transport, { batch: true })`
+  coalesces same-tick calls into one round-trip; each sub-call is validated and
+  authorized individually server-side (`maxBatchSize`, nested-batch rejection).
+- **Client-side streaming / async-iterable responses** — `ctx.stream(spec, { mode:
+  'ndjson' | 'sse' | 'raw' })` returns an `AsyncIterable`, plus `parseSse` /
+  `parseNdjson` helpers. (Streaming *through the RPC bridge* remains a follow-up.)
+- **Built-in rate limiter** — `createRateLimiter({ windowMs, max })` wires into the
+  handler `onRequest` (per-IP with `trustProxy`, or a custom `keyFor`; pluggable store).
+- **Pluggable cache persistence** — `@developerehsan/api-client/cache-stores`
+  (memory / IndexedDB / Redis) layered behind the in-memory LRU via
+  `cache.persistentStore`.
+- **First-party TanStack Start & Remix adapters** — `createStartRpcRoute` /
+  `createRemixRpcAction` over the framework-agnostic route handler.
+- **Config-driven codegen + framework glue** — `api-client.config.*`, watch with
+  remote-URL polling, `generate --check` for CI, plus `withApiClientCodegen`
+  (Next.js) and `@developerehsan/api-client-vite` (Vite / TanStack Start).
+- **Codegen: React Query hooks emission** — `emitReactQueryHooks` emits typed
+  `useXxx` hooks alongside the option factories.
+- **Modules beyond HTTP** — `ctx.run` gives any async module logic opt-in
+  queue / dedup / retry / timeout; `ctx.emit` / `ctx.logger` / `ctx.config` round
+  out the module context.
+
+### Still planned
+
+- **Richer per-module method-name autocomplete in the plain-object `config.modules`**
+  form — use `createModuleDefiner` today for full operation-aware autocomplete.
+- **Streaming through the RPC bridge** — route-only, with duration/idle/backpressure
+  hardening (Server Actions can't stream).
 - **OpenAPI 3.1 & webhooks** — expand the parser beyond 3.0.x.
-- **GraphQL transport** — an alternative adapter for GraphQL backends behind the
-  same module/method surface.
-- **Response caching persistence** — pluggable stores (IndexedDB, Redis) beyond
-  the in-memory LRU.
-- **Codegen: React Query hooks emission** — optionally emit `useXxx` hooks in
-  addition to the option factories.
+- **GraphQL transport** — an alternative adapter behind the same module/method
+  surface (largely a `ctx.run`-based module on top of the new runner).