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

package/dist/tags.js

@@ -0,0 +1,53 @@
+import { operationToken } from './query-key.js';
+/**
+ * Bundlers statically replace `process.env.NODE_ENV`, so a production build
+ * collapses this to `false` and drops the warning call; the `typeof` guard
+ * keeps it safe to evaluate where no global `process` exists at all.
+ */
+const IS_DEV = typeof process !== 'undefined' && process?.env?.NODE_ENV !== 'production';
+export function createTagRegistry(vocabulary) {
+    const known = vocabulary ? new Set(vocabulary) : undefined;
+    const endpointsByTag = new Map();
+    const warned = new Set();
+    /** Names the vocabulary, for a message that has to report a tag outside it. */
+    const describeVocabulary = (declared) => `Declared tags: ${[...declared].join(', ') || '(none)'}`;
+    // Both checks below read `known` directly rather than through a shared
+    // predicate: with no vocabulary there is no closed set, so no tag is unknown
+    // and neither branch is reachable.
+    const assertKnown = (tag) => {
+        if (known && !known.has(tag)) {
+            throw new Error(`http-client-react: unknown tag "${tag}". ${describeVocabulary(known)}`);
+        }
+    };
+    const acceptOrWarn = (tag) => {
+        if (!known || known.has(tag))
+            return true;
+        if (IS_DEV && !warned.has(tag)) {
+            warned.add(tag);
+            console.warn(`http-client-react: skipping unknown tag "${tag}" produced by an ` +
+                `invalidates callback — nothing was invalidated for it. ` +
+                describeVocabulary(known));
+        }
+        return false;
+    };
+    return {
+        assertKnown,
+        acceptOrWarn,
+        register: (tag, method, path) => {
+            assertKnown(tag);
+            const tokens = endpointsByTag.get(tag) ?? new Set();
+            tokens.add(operationToken(method, path));
+            endpointsByTag.set(tag, tokens);
+        },
+        matches: (tag, queryKey) => {
+            const tokens = endpointsByTag.get(tag);
+            if (!tokens)
+                return false;
+            const [method, path] = queryKey;
+            if (typeof method !== 'string' || typeof path !== 'string')
+                return false;
+            return tokens.has(operationToken(method, path));
+        },
+        endpoints: (tag) => [...(endpointsByTag.get(tag) ?? [])],
+    };
+}

package/dist/zod-response.d.ts

@@ -0,0 +1,61 @@
+import type { QueryApiMiddleware, QueryApiRequestContext } from './middleware.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 declare 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;
+    });
+}
+/**
+ * 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 declare function isZodResponseValidationError(value: unknown): value is 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;
+};
+/**
+ * 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 declare function createZodResponseMiddleware(options: ZodResponseMiddlewareOptions): QueryApiMiddleware;

package/dist/zod-response.js

@@ -0,0 +1,91 @@
+import { getComponentSchemaFromOpenApi } from '@r0hitsharma/http-client-core';
+import { operationToken } from './query-key.js';
+/** Thrown when a response body does not match its OpenAPI component schema. */
+export class ZodResponseValidationError extends Error {
+    name = 'ZodResponseValidationError';
+    method;
+    path;
+    /** The `components.schemas` name the body was validated against. */
+    schemaName;
+    issues;
+    constructor(init) {
+        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) {
+    return value instanceof Error && value.name === 'ZodResponseValidationError';
+}
+function normalizeIssues(error) {
+    const issues = error?.issues;
+    if (!Array.isArray(issues))
+        return [];
+    return issues.map((issue) => {
+        const entry = issue;
+        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) {
+    const { document, schemas, onInvalid } = options;
+    const compiled = new Map();
+    const resolveSchemaName = (ctx) => {
+        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/oxfmt.config.ts

@@ -0,0 +1,5 @@
+import formatConfig from '@r0hitsharma/oxfmt-config';
+
+export default {
+  ...formatConfig,
+};

package/oxlint.config.ts

@@ -0,0 +1,5 @@
+import reactConfig from '@r0hitsharma/oxlint-config/react';
+
+export default {
+  ...reactConfig,
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@r0hitsharma/http-client-react",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build",
+    "type:check": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint -c oxlint.config.ts --max-warnings=0 src",
+    "lint:fix": "oxlint -c oxlint.config.ts --fix src",
+    "format": "oxfmt -c oxfmt.config.ts --write src",
+    "format:check": "oxfmt -c oxfmt.config.ts --check src",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@r0hitsharma/http-client-core": "*"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.89.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@r0hitsharma/oxfmt-config": "*",
+    "@r0hitsharma/oxlint-config": "*",
+    "@r0hitsharma/tsconfig": "*",
+    "@tanstack/react-query": "5.102.8",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "oxfmt": "0.67.0",
+    "oxlint": "1.82.0",
+    "vitest": "^4.1.9"
+  },
+  "version": "0.12.0-rohit-fork-ci.1",
+  "repository": {
+    "url": "https://github.com/r0hitsharma/uikit"
+  }
+}

package/src/deprecated.test.ts

@@ -0,0 +1,27 @@
+import { QueryClient } from '@tanstack/react-query';
+import { describe, expect, it } from 'vitest';
+
+import { createQueryClient, createQueryOptions } from './index.js';
+
+describe('createQueryOptions (deprecated shim)', () => {
+  it('still produces options a QueryClient can fetch', async () => {
+    const queryClient = createQueryClient();
+
+    expect(queryClient).toBeInstanceOf(QueryClient);
+    await expect(
+      queryClient.fetchQuery(
+        createQueryOptions(['legacy', 'users'], () =>
+          Promise.resolve([{ id: 'u1' }]),
+        ),
+      ),
+    ).resolves.toEqual([{ id: 'u1' }]);
+  });
+
+  it('keeps the caller-supplied query key verbatim', () => {
+    const options = createQueryOptions(['legacy', 'users', { page: 2 }], () =>
+      Promise.resolve(null),
+    );
+
+    expect(options.queryKey).toEqual(['legacy', 'users', { page: 2 }]);
+  });
+});

package/src/errors.ts

@@ -0,0 +1,74 @@
+/**
+ * `openapi-fetch` resolves both outcomes of a request into `{ data, error }`,
+ * so a 404 is a fulfilled promise. TanStack Query only treats a *rejected*
+ * query function as a failure, so the query layer has to convert one into the
+ * other. This is the carrier for that conversion: it keeps the HTTP status and
+ * the parsed error body instead of flattening the failure to a message string.
+ */
+export class HttpRequestError<TBody = unknown> extends Error {
+  readonly name = 'HttpRequestError';
+  /** Lowercase OpenAPI method (`get`, `post`, …) that failed. */
+  readonly method: string;
+  /** The OpenAPI path template, braces intact (`/users/{id}`). */
+  readonly path: string;
+  readonly status: number;
+  readonly statusText: string;
+  /**
+   * The response body parsed by `openapi-fetch`, typed from the operation's
+   * error responses — and `| undefined`, because a failure need not have one: a
+   * 5xx from a proxy, or any non-2xx with an empty body, leaves nothing to
+   * parse. Declaring it as `TBody` alone would let a consumer read through to a
+   * property of a body that is not there.
+   */
+  readonly body: TBody | undefined;
+  readonly response: Response;
+
+  constructor(init: {
+    method: string;
+    path: string;
+    body: TBody | undefined;
+    response: Response;
+  }) {
+    super(
+      `${init.method.toUpperCase()} ${init.path} failed with status ${init.response.status}`,
+    );
+    this.method = init.method;
+    this.path = init.path;
+    this.status = init.response.status;
+    this.statusText = init.response.statusText;
+    this.body = init.body;
+    this.response = init.response;
+  }
+}
+
+/**
+ * What {@link isHttpRequestError} narrows `TValue` to: the `HttpRequestError`
+ * member `TValue` already declares, so the body type the operation described
+ * survives the guard, and a bare `HttpRequestError` when `TValue` declares none
+ * — a `catch` binding, where no body type is knowable.
+ */
+type NarrowedHttpRequestError<TValue> = [
+  Extract<TValue, HttpRequestError<unknown>>,
+] extends [never]
+  ? HttpRequestError<unknown>
+  : Extract<TValue, HttpRequestError<unknown>>;
+
+/**
+ * Narrows a caught value to {@link HttpRequestError}.
+ *
+ * Matches on `name` rather than `instanceof` so the guard still holds when a
+ * consumer ends up with two copies of this package in its module graph (a
+ * bundled app plus a linked workspace build, for instance).
+ *
+ * The body type is *derived* from the argument rather than taken as a type
+ * parameter. A runtime check on `name` can say nothing about the body's shape,
+ * so a `TBody` parameter would have let a call site name any type it liked and
+ * get it back unchecked; deriving it means narrowing a
+ * `QueryApiError<TErrorBody>` yields that operation's own error body, and
+ * narrowing an `unknown` yields `unknown` — which is the truth in both cases.
+ */
+export function isHttpRequestError<TValue>(
+  value: TValue,
+): value is TValue & NarrowedHttpRequestError<TValue> {
+  return value instanceof Error && value.name === 'HttpRequestError';
+}

package/src/index.tsx

@@ -0,0 +1,100 @@
+import {
+  queryOptions,
+  type QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query';
+import type { PropsWithChildren } from 'react';
+
+import { createQueryClient } from './query-client.js';
+
+export { createApiClient } from '@r0hitsharma/http-client-core';
+export type {
+  ApiClient,
+  ApiClientOptions,
+  JsonSchema,
+} from '@r0hitsharma/http-client-core';
+
+export { createQueryApi } from './query-api.js';
+export type {
+  MutationInvalidation,
+  QueryApi,
+  QueryApiCallOptions,
+  QueryApiError,
+  QueryApiKeyFn,
+  QueryApiMutationCallOptions,
+  QueryApiMutationMethod,
+  QueryApiMutationOptionsFn,
+  QueryApiOptions,
+  QueryApiPaths,
+  QueryApiQueryMethod,
+  QueryApiQueryOptionsFn,
+} from './query-api.js';
+
+export { HttpRequestError, isHttpRequestError } from './errors.js';
+
+export { composeMiddleware } from './middleware.js';
+export type {
+  QueryApiMiddleware,
+  QueryApiNext,
+  QueryApiOperationType,
+  QueryApiRequestContext,
+} from './middleware.js';
+
+export {
+  buildQueryApiKey,
+  canonicalizeQueryKeyValue,
+  operationToken,
+  sanitizeQueryInit,
+} from './query-key.js';
+export type { QueryApiKey, SanitizedQueryInit } from './query-key.js';
+
+export {
+  createQueryClient,
+  isRetryableError,
+  isRetryableHttpStatus,
+  shouldRetryRequest,
+} from './query-client.js';
+
+export {
+  createZodResponseMiddleware,
+  isZodResponseValidationError,
+  ZodResponseValidationError,
+} from './zod-response.js';
+export type {
+  ResponseSchemaSource,
+  ResponseValidationIssue,
+  ZodResponseMiddlewareOptions,
+} from './zod-response.js';
+
+/**
+ * The client `HttpProvider` falls back to when the app does not pass one. A
+ * single module-scoped instance, so every consumer of the fallback shares one
+ * cache — but prefer creating it in the app: the fallback cannot be reset
+ * between tests and cannot be reached for `setQueryData` before render.
+ */
+const defaultQueryClient = createQueryClient();
+
+export type HttpProviderProps = PropsWithChildren<{
+  client?: QueryClient;
+}>;
+
+export function HttpProvider({ client, children }: HttpProviderProps) {
+  return (
+    <QueryClientProvider client={client ?? defaultQueryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+
+/**
+ * @deprecated Use `createQueryApi(client).queryOptions(method, path, init)`
+ * instead: it derives the query key from the operation, types the result from
+ * the OpenAPI response, and rejects with a typed error. This shim keeps working
+ * for the hand-written query keys that predate it.
+ */
+export function createQueryOptions<TData>(
+  queryKey: readonly unknown[],
+  queryFn: () => Promise<TData>,
+) {
+  return queryOptions({ queryKey, queryFn });
+}

package/src/middleware.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  composeMiddleware,
+  type QueryApiRequestContext,
+} from './middleware.js';
+
+const ctx: QueryApiRequestContext = {
+  method: 'get',
+  path: '/users',
+  operationType: 'query',
+  init: undefined,
+};
+
+describe('composeMiddleware', () => {
+  it('returns the terminal handler unchanged for an empty chain', () => {
+    const terminal = vi.fn(async () => 'value');
+    expect(composeMiddleware([], terminal)).toBe(terminal);
+  });
+
+  it('runs the chain outermost first and unwinds innermost first', async () => {
+    const trace: string[] = [];
+    const record =
+      (name: string) =>
+      async (
+        current: QueryApiRequestContext,
+        next: (ctx?: QueryApiRequestContext) => Promise<unknown>,
+      ) => {
+        trace.push(`enter:${name}`);
+        const value = await next(current);
+        trace.push(`exit:${name}`);
+        return value;
+      };
+
+    const chain = composeMiddleware(
+      [record('a'), record('b')],
+      async () => 'value',
+    );
+
+    await expect(chain(ctx)).resolves.toBe('value');
+    expect(trace).toEqual(['enter:a', 'enter:b', 'exit:b', 'exit:a']);
+  });
+
+  it('passes the context through unchanged when next() takes no argument', async () => {
+    const terminal = vi.fn(async () => 'value');
+    const chain = composeMiddleware([(_ctx, next) => next()], terminal);
+
+    await chain(ctx);
+
+    expect(terminal).toHaveBeenCalledWith(ctx);
+  });
+
+  it('hands a rewritten context to the rest of the chain', async () => {
+    const terminal = vi.fn(async () => 'value');
+    const chain = composeMiddleware(
+      [(current, next) => next({ ...current, path: '/rewritten' })],
+      terminal,
+    );
+
+    await chain(ctx);
+
+    expect(terminal).toHaveBeenCalledWith({ ...ctx, path: '/rewritten' });
+  });
+
+  it('rejects when a middleware calls next() twice', async () => {
+    const terminal = vi.fn(async () => 'value');
+    const chain = composeMiddleware(
+      [
+        async (current, next) => {
+          await next(current);
+          return await next(current);
+        },
+      ],
+      terminal,
+    );
+
+    await expect(chain(ctx)).rejects.toThrow(/next\(\) more than once/);
+    expect(terminal).toHaveBeenCalledTimes(1);
+  });
+
+  it('lets a middleware short-circuit without reaching the terminal', async () => {
+    const terminal = vi.fn(async () => 'value');
+    const chain = composeMiddleware([async () => 'cached'], terminal);
+
+    await expect(chain(ctx)).resolves.toBe('cached');
+    expect(terminal).not.toHaveBeenCalled();
+  });
+});

package/src/middleware.ts

@@ -0,0 +1,84 @@
+/** Which half of the API a request came from. */
+export type QueryApiOperationType = 'query' | 'mutation';
+
+/**
+ * What a middleware sees. `init` is the init as it will be handed to
+ * `openapi-fetch` — the caller's init plus the abort `signal` react-query
+ * supplies — not the sanitized cache-key form.
+ */
+export type QueryApiRequestContext = {
+  /** Lowercase OpenAPI method (`get`, `post`, …). */
+  readonly method: string;
+  /** The OpenAPI path template, braces intact (`/users/{id}`). */
+  readonly path: string;
+  readonly operationType: QueryApiOperationType;
+  readonly init: Record<string, unknown> | undefined;
+};
+
+/**
+ * Invokes the rest of the chain. Called with no argument to pass the context
+ * through unchanged, or with a replacement to rewrite the request downstream.
+ */
+export type QueryApiNext = (ctx?: QueryApiRequestContext) => Promise<unknown>;
+
+/**
+ * Onion-style middleware over the *parsed result* of a request, not over
+ * `Request`/`Response`. That is the altitude for response validation, logging
+ * and timing, rewriting the request on the way in (`next(ctx)`), reshaping the
+ * result on the way out, and short-circuiting with a substitute result by never
+ * calling `next` at all.
+ *
+ * **Not retries.** `next` is single-use per invocation — a second call rejects —
+ * so a middleware cannot re-issue the request it is wrapping. Retrying belongs
+ * either to react-query, whose `retry`/`retryDelay` re-invoke the whole chain
+ * from the top, or to the `fetch` implementation handed to `createApiClient`,
+ * which owns the actual HTTP call. `openapi-fetch`'s own `use()` middleware
+ * remains available on the client for anything that needs the raw HTTP objects.
+ */
+export type QueryApiMiddleware = (
+  ctx: QueryApiRequestContext,
+  next: QueryApiNext,
+) => Promise<unknown>;
+
+type TerminalHandler = (ctx: QueryApiRequestContext) => Promise<unknown>;
+
+/**
+ * Folds `middleware` around `terminal`, outermost first: given `[a, b]`, `a`
+ * runs before `b` on the way in and after `b` on the way out.
+ *
+ * Each composed handler is single-use per invocation — calling `next()` twice
+ * from one middleware rejects rather than issuing the request twice.
+ */
+export function composeMiddleware(
+  middleware: readonly QueryApiMiddleware[],
+  terminal: TerminalHandler,
+): TerminalHandler {
+  if (middleware.length === 0) return terminal;
+
+  return (ctx) => {
+    let called = -1;
+
+    const dispatch = (
+      index: number,
+      current: QueryApiRequestContext,
+    ): Promise<unknown> => {
+      if (index <= called) {
+        return Promise.reject(
+          new Error(
+            'http-client-react: middleware called next() more than once',
+          ),
+        );
+      }
+      called = index;
+
+      const handler = middleware[index];
+      if (!handler) return terminal(current);
+
+      return handler(current, (nextCtx) =>
+        dispatch(index + 1, nextCtx ?? current),
+      );
+    };
+
+    return dispatch(0, ctx);
+  };
+}