@ternaus/openapi-react-query 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Martin Paucot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @ternaus/openapi-react-query
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fork of [openapi-react-query in openapi-ts/openapi-typescript](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-react-query), maintained by [Vladimir Iglovikov](https://github.com/ternaus). The original authorship, Git history, and MIT license are preserved.
+
+`@ternaus/openapi-react-query` is a typed client for [@tanstack/react-query](https://tanstack.com/query/latest/docs/framework/react/overview) that uses your OpenAPI schema.
+
+TypeScript checks request fields and infers response shapes from the types generated by openapi-typescript. The client sends requests through openapi-fetch.
+
+## Setup
+
+Requires React 19 and TanStack Query 5.
+
+Install this library along with [openapi-fetch](../openapi-fetch) and [openapi-typescript](../openapi-typescript):
+
+```bash
+npm i @ternaus/openapi-react-query @ternaus/openapi-fetch
+npm i -D @ternaus/openapi-typescript typescript
+```
+
+Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
+
+```bash
+npx @ternaus/openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
+```
+
+## Usage
+
+Once your types have been generated from your schema, you can create a [fetch client](../openapi-fetch), a react-query client and start querying your API.
+
+```tsx
+import createFetchClient from "@ternaus/openapi-fetch";
+import createClient from "@ternaus/openapi-react-query";
+import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
+
+const fetchClient = createFetchClient<paths>({
+  baseUrl: "https://myapi.dev/v1/",
+});
+const $api = createClient(fetchClient);
+
+const MyComponent = () => {
+  const { data, error, isPending } = $api.useQuery(
+    "get",
+    "/blogposts/{post_id}",
+    {
+      params: {
+        path: { post_id: 5 },
+      },
+    }
+  );
+
+  if (isPending || !data) return "Loading...";
+
+  if (error) return `An error occurred: ${error.message}`;
+
+  return <div>{data.title}</div>;
+};
+```
+
+> You can find more information about `createFetchClient` in the [openapi-fetch documentation](../openapi-fetch).
+
+Clients share a cache by normalized `baseUrl`. Use `createClient(fetchClient, { cacheKey: "user-123" })` to separate users or middleware on the same server. Normal and infinite queries use different keys. Reuse `queryOptions(...).queryKey` for cache access and invalidation.
+
+HTTP errors reject with their parsed payload. An empty error body produces an `Error` with the status in its message and the original `Response` in `cause`. Empty successful queries return `null`.
+
+## 📓 Docs
+
+[View Docs](https://github.com/ternaus/js-tools/blob/main/docs/openapi-react-query/index.md)

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { type DataTag, type InfiniteData, type QueryClient, type SkipToken, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult, type UseSuspenseQueryOptions, type UseSuspenseQueryResult } from "@tanstack/react-query";
+import type { CheckedInit, Client as FetchClient, FetchResponse, MaybeOptionalInit } from "@ternaus/openapi-fetch";
+import type { HttpMethod, MediaType, PathsWithMethod, RequiredKeysOf } from "@ternaus/openapi-typescript-helpers";
+type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer R ? R : TData;
+type QueryData<T> = [T] extends [never] ? null : T extends undefined ? null : T;
+type QueryInit<Init, Options> = CheckedInit<Init, Options> & {
+    [K in keyof UseQueryOptions]?: never;
+} & {
+    [key: string]: unknown;
+};
+export type QueryKey<Paths extends Record<string, Record<HttpMethod, {}>>, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init = MaybeOptionalInit<Paths[Path], Method>, Mode extends "query" | "infinite" = "query"> = readonly [string, string | null, Mode, Method, Path, Init];
+export type QueryOptionsFunction<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"] | Error, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, path: Path, ...[init, options]: RequiredKeysOf<Init> extends never ? [QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>?, Options?] : [QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>, Options?]) => NoInfer<Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"] | Error, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryFn" | "queryKey"> & {
+    queryKey: DataTag<QueryKey<Paths, Method, Path>, QueryData<Response["data"]>, Response["error"] | Error>;
+    queryFn: Exclude<UseQueryOptions<QueryData<Response["data"]>, Response["error"] | Error, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>["queryFn"], SkipToken | undefined>;
+}>;
+export type UseQueryMethod<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"] | Error, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: RequiredKeysOf<Init> extends never ? [QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>?, Options?, QueryClient?] : [QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>, Options?, QueryClient?]) => UseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, Response["error"] | Error>;
+export type UseInfiniteQueryMethod<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, Options extends Omit<UseInfiniteQueryOptions<QueryData<Response["data"]>, Response["error"] | Error, InferSelectReturnType<InfiniteData<QueryData<Response["data"]>>, Options["select"]>, QueryKey<Paths, Method, Path, Init, "infinite">, unknown>, "queryKey" | "queryFn"> & {
+    pageParamName?: string;
+}>(method: Method, url: Path, init: QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>, options: Options, queryClient?: QueryClient) => UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<QueryData<Response["data"]>>, Options["select"]>, Response["error"] | Error>;
+export type UseSuspenseQueryMethod<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, Options extends Omit<UseSuspenseQueryOptions<QueryData<Response["data"]>, Response["error"] | Error, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: RequiredKeysOf<Init> extends never ? [QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>?, Options?, QueryClient?] : [QueryInit<Init, MaybeOptionalInit<Paths[Path], Method>>, Options?, QueryClient?]) => UseSuspenseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, Response["error"] | Error>;
+export type UseMutationMethod<Paths extends Record<string, Record<HttpMethod, {}>>, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, TOnMutateResult = unknown>(method: Method, url: Path, options?: Omit<UseMutationOptions<Response["data"], Response["error"] | Error, MaybeOptionalInit<Paths[Path], Method>, TOnMutateResult>, "mutationKey" | "mutationFn">, queryClient?: QueryClient) => UseMutationResult<Response["data"], Response["error"] | Error, MaybeOptionalInit<Paths[Path], Method>, TOnMutateResult>;
+export interface OpenapiQueryClient<Paths extends {}, Media extends MediaType = MediaType> {
+    queryOptions: QueryOptionsFunction<Paths, Media>;
+    useQuery: UseQueryMethod<Paths, Media>;
+    useSuspenseQuery: UseSuspenseQueryMethod<Paths, Media>;
+    useInfiniteQuery: UseInfiniteQueryMethod<Paths, Media>;
+    useMutation: UseMutationMethod<Paths, Media>;
+}
+export type MethodResponse<CreatedClient extends OpenapiQueryClient<any, any>, Method extends HttpMethod, Path extends CreatedClient extends OpenapiQueryClient<infer Paths, infer _Media> ? PathsWithMethod<Paths, Method> : never, Options = object> = CreatedClient extends OpenapiQueryClient<infer Paths extends {
+    [key: string]: any;
+}, infer Media extends MediaType> ? NonNullable<FetchResponse<Paths[Path][Method], Options, Media>["data"]> : never;
+export interface ClientOptions {
+    cacheKey?: string;
+}
+export default function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: FetchClient<Paths, Media>, { cacheKey }?: ClientOptions): OpenapiQueryClient<Paths, Media>;
+export {};

package/dist/index.js

@@ -0,0 +1,52 @@
+import { useInfiniteQuery, useMutation, useQuery, useSuspenseQuery, } from "@tanstack/react-query";
+export default function createClient(client, { cacheKey } = {}) {
+    const scope = [client.baseUrl, cacheKey ?? null];
+    const fetch = async (method, path, init) => {
+        const fn = client[method.toUpperCase()];
+        const { data, error, response } = await fn(path, init);
+        if (!response.ok) {
+            throw error === undefined
+                ? new Error(`HTTP ${response.status} ${response.statusText}`.trim(), { cause: response })
+                : error;
+        }
+        return data;
+    };
+    const queryFn = ({ queryKey: [, , , method, path, init], signal, }) => fetch(method, path, { signal, ...init }).then((data) => data ?? null);
+    const queryOptions = (method, path, ...[init, options]) => ({
+        queryKey: [...scope, "query", method, path, init],
+        queryFn,
+        ...options,
+    });
+    return {
+        queryOptions,
+        useQuery: (method, path, ...[init, options, queryClient]) => useQuery(queryOptions(method, path, init, options), queryClient),
+        useSuspenseQuery: (method, path, ...[init, options, queryClient]) => useSuspenseQuery(queryOptions(method, path, init, options), queryClient),
+        useInfiniteQuery: (method, path, init, options, queryClient) => {
+            const { pageParamName = "cursor", ...restOptions } = options;
+            return useInfiniteQuery({
+                queryKey: [...scope, "infinite", method, path, init],
+                queryFn: ({ queryKey: [, , , method, path, init], pageParam, signal }) => {
+                    const mergedInit = {
+                        ...init,
+                        signal,
+                        params: {
+                            ...init?.params,
+                            query: {
+                                ...init?.params?.query,
+                                ...(pageParam === undefined ? {} : { [pageParamName]: pageParam }),
+                            },
+                        },
+                    };
+                    return fetch(method, path, mergedInit).then((data) => data ?? null);
+                },
+                ...restOptions,
+            }, queryClient);
+        },
+        useMutation: (method, path, options, queryClient) => useMutation({
+            mutationKey: [...scope, "mutation", method, path],
+            mutationFn: (init) => fetch(method, path, init),
+            ...options,
+        }, queryClient),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"./","sources":["index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@ternaus/openapi-react-query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Fast, type-safe @tanstack/react-query client to work with your OpenAPI schema.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Martin Paucot",
+    "email": "contact@martin-paucot.fr"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "homepage": "https://ternaus.github.io/js-tools/openapi-react-query/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ternaus/js-tools.git",
+    "directory": "packages/openapi-react-query"
+  },
+  "bugs": {
+    "url": "https://github.com/ternaus/js-tools/issues"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "rest",
+    "api",
+    "oapi_3",
+    "oapi_3_1",
+    "typescript",
+    "fetch",
+    "react",
+    "react-query",
+    "tanstack"
+  ],
+  "dependencies": {
+    "@ternaus/openapi-typescript-helpers": "^1.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "5.104.0",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "msw": "3.0.1",
+    "@ternaus/openapi-fetch": "^1.0.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "react-error-boundary": "6.1.6",
+    "@ternaus/openapi-typescript": "^8.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.80.0",
+    "@ternaus/openapi-fetch": "^1.0.0",
+    "react": "^19.0.0"
+  },
+  "engines": {
+    "node": "^24.15.0 || ^26.0.0"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "maintainers": [
+    {
+      "name": "Vladimir Iglovikov",
+      "url": "https://github.com/ternaus"
+    }
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "format": "biome format . --write",
+    "lint": "pnpm run lint:js && pnpm run typecheck",
+    "lint:js": "biome lint . --error-on-warnings",
+    "generate-types": "openapi-typescript test/fixtures/api.yaml -o test/fixtures/api.d.ts",
+    "test": "pnpm run generate-types && pnpm run test:js && pnpm run test:exports",
+    "test:js": "vitest run --config ../../vitest.config.ts --project openapi-react-query",
+    "test:exports": "publint --strict",
+    "typecheck": "tsc --noEmit"
+  }
 }