@r0hitsharma/http-client-react 0.12.0-rohit-fork-ci.1

package/src/test-fixtures.ts

@@ -0,0 +1,222 @@
+/**
+ * Test-only fixtures. Excluded from `tsconfig.build.json` alongside the specs,
+ * so nothing here ships, but still covered by `type:check` — which matters,
+ * because `TestPaths` mirrors `openapi-typescript` output closely enough
+ * (every HTTP method present, absent ones as `?: never`) to prove the query
+ * layer's inference against a real generated `paths` type.
+ */
+
+export type User = { id: string; name: string };
+export type ApiFault = { message: string };
+export type ValidationFault = { message: string; field: string };
+
+type NoBody = { requestBody?: never };
+type NoParams = {
+  query?: never;
+  header?: never;
+  path?: never;
+  cookie?: never;
+};
+
+export type TestPaths = {
+  '/users': {
+    parameters: NoParams;
+    get: NoBody & {
+      parameters: {
+        query?: { limit?: number; search?: string };
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      responses: {
+        200: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': User[];
+          };
+        };
+        500: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': ApiFault;
+          };
+        };
+      };
+    };
+    post: {
+      parameters: NoParams;
+      requestBody: { content: { 'application/json': { name: string } } };
+      responses: {
+        201: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': User;
+          };
+        };
+        422: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': ValidationFault;
+          };
+        };
+      };
+    };
+    /**
+     * A real HEAD operation, not `head?: never`: `queryOptions` accepts `head`,
+     * so leaving it absent everywhere would let the query method union claim
+     * support nothing type-checks. Its 200 declares no content, which is what
+     * `openapi-typescript` emits for a bodyless response.
+     */
+    head: NoBody & {
+      parameters: {
+        query?: { search?: string };
+        header?: never;
+        path?: never;
+        cookie?: never;
+      };
+      responses: {
+        200: { headers: Record<string, unknown>; content?: never };
+        500: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': ApiFault;
+          };
+        };
+      };
+    };
+    put?: never;
+    delete?: never;
+    options?: never;
+    patch?: never;
+    trace?: never;
+  };
+  '/users/{id}': {
+    parameters: NoParams;
+    get: NoBody & {
+      parameters: {
+        query?: { expand?: string };
+        header?: never;
+        path: { id: string };
+        cookie?: never;
+      };
+      responses: {
+        200: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': User;
+          };
+        };
+        404: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': ApiFault;
+          };
+        };
+      };
+    };
+    delete: NoBody & {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: { id: string };
+        cookie?: never;
+      };
+      responses: {
+        204: { headers: Record<string, unknown>; content?: never };
+        404: {
+          headers: Record<string, unknown>;
+          content: {
+            'application/json': ApiFault;
+          };
+        };
+      };
+    };
+    put?: never;
+    post?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+};
+
+export type TestTag = 'users' | 'user';
+
+export type RecordedRequest = { method: string; url: string; body?: string };
+
+/**
+ * A `fetch` stand-in for `createApiClient`'s client options. Routes are matched
+ * on `${method} ${pathname}` so the specs exercise the real `openapi-fetch`
+ * path and query serialization rather than a hand-faked client object.
+ */
+export function createFetchStub(
+  routes: Record<
+    string,
+    (request: Request, url: URL) => Response | Promise<Response>
+  >,
+): {
+  fetch: (request: Request) => Promise<Response>;
+  requests: RecordedRequest[];
+} {
+  const requests: RecordedRequest[] = [];
+
+  return {
+    requests,
+    fetch: async (request) => {
+      const url = new URL(request.url);
+      requests.push({
+        method: request.method,
+        url: `${url.pathname}${url.search}`,
+        body: request.body ? await request.clone().text() : undefined,
+      });
+
+      const route = routes[`${request.method} ${url.pathname}`];
+      if (!route) {
+        return new Response(JSON.stringify({ message: 'no stub route' }), {
+          status: 501,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      return route(request, url);
+    },
+  };
+}
+
+/** A 2xx JSON response. */
+export function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+/** A no-content response, for the 204 branch of the query function. */
+export function emptyResponse(status = 204): Response {
+  return new Response(null, { status });
+}
+
+/**
+ * A failure with an explicitly empty body. `openapi-fetch` short-circuits on
+ * `Content-Length: 0` and resolves `error: undefined`, which is the case
+ * `HttpRequestError.body`'s `| undefined` exists for. Without the header the
+ * body is parsed as text and comes back as `''`, not `undefined`.
+ */
+export function emptyFaultResponse(status = 500): Response {
+  return new Response(null, { status, headers: { 'Content-Length': '0' } });
+}
+
+/**
+ * A HEAD response: 200, no body, and a `Content-Length` echoing the size of the
+ * entity the matching GET would return. That header is what makes HEAD its own
+ * case — neither the 204 nor the `Content-Length: 0` branch catches it.
+ */
+export function headResponse(contentLength = '42'): Response {
+  return new Response(null, {
+    status: 200,
+    headers: {
+      'Content-Length': contentLength,
+      'Content-Type': 'application/json',
+    },
+  });
+}

package/src/zod-response.ts

@@ -0,0 +1,150 @@
+import { getComponentSchemaFromOpenApi } from '@r0hitsharma/http-client-core';
+
+import type {
+  QueryApiMiddleware,
+  QueryApiRequestContext,
+} from './middleware.js';
+import { operationToken } from './query-key.js';
+
+/** A single schema violation, flattened so consumers never touch zod's types. */
+export type ResponseValidationIssue = {
+  /** Dot-joined path to the offending value, `''` at the root. */
+  path: string;
+  message: string;
+};
+
+/** Thrown when a response body does not match its OpenAPI component schema. */
+export class ZodResponseValidationError extends Error {
+  readonly name = 'ZodResponseValidationError';
+  readonly method: string;
+  readonly path: string;
+  /** The `components.schemas` name the body was validated against. */
+  readonly schemaName: string;
+  readonly issues: readonly ResponseValidationIssue[];
+
+  constructor(init: {
+    method: string;
+    path: string;
+    schemaName: string;
+    issues: readonly ResponseValidationIssue[];
+    cause?: unknown;
+  }) {
+    super(
+      `${init.method.toUpperCase()} ${init.path} response failed ${init.schemaName} validation: ${init.issues
+        .map((issue) => `${issue.path || '<root>'} ${issue.message}`)
+        .join('; ')}`,
+      { cause: init.cause },
+    );
+    this.method = init.method;
+    this.path = init.path;
+    this.schemaName = init.schemaName;
+    this.issues = init.issues;
+  }
+}
+
+/**
+ * Narrows a caught value to {@link ZodResponseValidationError}.
+ *
+ * Matches on `name` rather than `instanceof` for the same reason
+ * `isHttpRequestError` does: a consumer can end up with two copies of this
+ * package in its module graph, and an error thrown by one is not `instanceof`
+ * the class the other closed over.
+ */
+export function isZodResponseValidationError(
+  value: unknown,
+): value is ZodResponseValidationError {
+  return value instanceof Error && value.name === 'ZodResponseValidationError';
+}
+
+/**
+ * How to find the component schema for an operation: either a lookup table
+ * keyed `${method} ${path}` (`'get /users/{id}'`), or a function for specs
+ * whose naming is derivable.
+ */
+export type ResponseSchemaSource =
+  | Readonly<Record<string, string>>
+  | ((ctx: QueryApiRequestContext) => string | undefined);
+
+export type ZodResponseMiddlewareOptions = {
+  /** The parsed OpenAPI document the `TPaths` types were generated from. */
+  document: unknown;
+  schemas: ResponseSchemaSource;
+  /**
+   * Called instead of throwing when a body fails validation. Use it to report
+   * drift without breaking the screen; the unmodified body is passed through.
+   */
+  onInvalid?: (error: ZodResponseValidationError) => void;
+};
+
+function normalizeIssues(error: unknown): readonly ResponseValidationIssue[] {
+  const issues = (error as { issues?: unknown } | undefined)?.issues;
+  if (!Array.isArray(issues)) return [];
+
+  return issues.map((issue: unknown) => {
+    const entry = issue as { path?: unknown; message?: unknown };
+    const path = Array.isArray(entry.path) ? entry.path.join('.') : '';
+    return {
+      path,
+      message: typeof entry.message === 'string' ? entry.message : 'invalid',
+    };
+  });
+}
+
+/**
+ * Validates response bodies against the OpenAPI document at runtime, reusing
+ * `getComponentSchemaFromOpenApi` from http-client-core so the schema and the
+ * `TPaths` types come from the same spec.
+ *
+ * The validated body is passed through **unmodified** — the middleware never
+ * substitutes zod's parse output, so the runtime value always matches the
+ * statically inferred one and no coercion happens behind the caller's back.
+ *
+ * Compiled schemas are memoized per middleware instance;
+ * `z.fromJSONSchema` is far too expensive to run per request.
+ */
+export function createZodResponseMiddleware(
+  options: ZodResponseMiddlewareOptions,
+): QueryApiMiddleware {
+  const { document, schemas, onInvalid } = options;
+  const compiled = new Map<
+    string,
+    ReturnType<typeof getComponentSchemaFromOpenApi>
+  >();
+
+  const resolveSchemaName = (
+    ctx: QueryApiRequestContext,
+  ): string | undefined => {
+    if (typeof schemas === 'function') return schemas(ctx);
+    return schemas[operationToken(ctx.method, ctx.path)];
+  };
+
+  return async (ctx, next) => {
+    const data = await next();
+    const schemaName = resolveSchemaName(ctx);
+    if (!schemaName) return data;
+
+    let schema = compiled.get(schemaName);
+    if (!schema) {
+      schema = getComponentSchemaFromOpenApi(document, schemaName);
+      compiled.set(schemaName, schema);
+    }
+
+    const result = schema.safeParse(data);
+    if (result.success) return data;
+
+    const error = new ZodResponseValidationError({
+      method: ctx.method,
+      path: ctx.path,
+      schemaName,
+      issues: normalizeIssues(result.error),
+      cause: result.error,
+    });
+
+    if (onInvalid) {
+      onInvalid(error);
+      return data;
+    }
+
+    throw error;
+  };
+}

package/tsconfig.build.json

@@ -0,0 +1,21 @@
+{
+  "extends": "@r0hitsharma/tsconfig/react",
+  "compilerOptions": {
+    "allowImportingTsExtensions": false,
+    "noEmit": false,
+    "emitDeclarationOnly": false,
+    "declaration": true,
+    "declarationMap": false,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ],
+  "exclude": [
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "src/test-fixtures.ts"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@r0hitsharma/tsconfig/react",
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ]
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Node environment is sufficient: the query layer is plain logic over
+    // key derivation, a middleware chain, and a QueryClient — the specs drive
+    // it directly with an injected `fetch` rather than rendering a component.
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+});