@typokit/client-react-query 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import type { RouteContract } from "@typokit/types";
+import type { RouteMap, TypeSafeClient } from "@typokit/client";
+import type { UseQueryResult, UseMutationOptions, UseMutationResult } from "@tanstack/react-query";
+/** Build a React Query cache key from route path, params, and query */
+export declare function buildQueryKey(path: string, params?: Record<string, string>, query?: Record<string, unknown>): readonly unknown[];
+/** Extract GET route paths from a RouteMap */
+type GetPaths<TRoutes extends RouteMap> = {
+    [P in keyof TRoutes]: "GET" extends keyof TRoutes[P] ? P : never;
+}[keyof TRoutes] & string;
+type MutationMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+/** Extract paths that have a given mutation method */
+type MutationPaths<TRoutes extends RouteMap, M extends MutationMethod> = {
+    [P in keyof TRoutes]: M extends keyof TRoutes[P] ? P : never;
+}[keyof TRoutes] & string;
+/** Resolve the RouteContract for a given path and method */
+type ContractFor<TRoutes extends RouteMap, P extends string, M extends string> = P extends keyof TRoutes ? M extends keyof TRoutes[P] ? TRoutes[P][M] extends RouteContract ? TRoutes[P][M] : RouteContract : RouteContract : RouteContract;
+/** Options for useGet: route-specific params/query + React Query config */
+export interface UseGetOptions<C extends RouteContract> {
+    params?: C["params"] extends void ? undefined : C["params"] & Record<string, string>;
+    query?: C["query"] extends void ? undefined : C["query"];
+    enabled?: boolean;
+    staleTime?: number;
+    refetchInterval?: number | false;
+}
+/** Variables passed to mutation hooks */
+export interface MutationVariables<C extends RouteContract> {
+    params?: C["params"] extends void ? undefined : C["params"] & Record<string, string>;
+    body?: C["body"] extends void ? undefined : C["body"];
+}
+/** Mutation lifecycle callbacks */
+type MutationCallbacks<TData, TVars> = Pick<UseMutationOptions<TData, Error, TVars, unknown>, "onSuccess" | "onError" | "onSettled" | "onMutate">;
+/** Type-safe React Query hooks generated from a RouteMap */
+export interface QueryHooks<TRoutes extends RouteMap> {
+    /** useQuery wrapper for GET routes */
+    useGet<P extends GetPaths<TRoutes>>(path: P, options?: UseGetOptions<ContractFor<TRoutes, P, "GET">>): UseQueryResult<ContractFor<TRoutes, P, "GET">["response"], Error>;
+    /** useMutation wrapper for POST routes */
+    usePost<P extends MutationPaths<TRoutes, "POST">>(path: P, options?: MutationCallbacks<ContractFor<TRoutes, P, "POST">["response"], MutationVariables<ContractFor<TRoutes, P, "POST">>>): UseMutationResult<ContractFor<TRoutes, P, "POST">["response"], Error, MutationVariables<ContractFor<TRoutes, P, "POST">>>;
+    /** useMutation wrapper for PUT routes */
+    usePut<P extends MutationPaths<TRoutes, "PUT">>(path: P, options?: MutationCallbacks<ContractFor<TRoutes, P, "PUT">["response"], MutationVariables<ContractFor<TRoutes, P, "PUT">>>): UseMutationResult<ContractFor<TRoutes, P, "PUT">["response"], Error, MutationVariables<ContractFor<TRoutes, P, "PUT">>>;
+    /** useMutation wrapper for PATCH routes */
+    usePatch<P extends MutationPaths<TRoutes, "PATCH">>(path: P, options?: MutationCallbacks<ContractFor<TRoutes, P, "PATCH">["response"], MutationVariables<ContractFor<TRoutes, P, "PATCH">>>): UseMutationResult<ContractFor<TRoutes, P, "PATCH">["response"], Error, MutationVariables<ContractFor<TRoutes, P, "PATCH">>>;
+    /** useMutation wrapper for DELETE routes */
+    useDelete<P extends MutationPaths<TRoutes, "DELETE">>(path: P, options?: MutationCallbacks<ContractFor<TRoutes, P, "DELETE">["response"], MutationVariables<ContractFor<TRoutes, P, "DELETE">>>): UseMutationResult<ContractFor<TRoutes, P, "DELETE">["response"], Error, MutationVariables<ContractFor<TRoutes, P, "DELETE">>>;
+}
+/**
+ * Create type-safe React Query hooks from a TypoKit client.
+ *
+ * @example
+ * ```ts
+ * const hooks = createQueryHooks<MyRoutes>(client);
+ * // In a React component:
+ * const { data, isLoading } = hooks.useGet("/users", { query: { page: 1 } });
+ * const createUser = hooks.usePost("/users");
+ * createUser.mutate({ body: { name: "Alice" } });
+ * ```
+ */
+export declare function createQueryHooks<TRoutes extends RouteMap>(client: TypeSafeClient<TRoutes>): QueryHooks<TRoutes>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,58 @@
+// @typokit/client-react-query — React Query Hooks
+import { useQuery, useMutation } from "@tanstack/react-query";
+// ─── Query Key Builder ──────────────────────────────────────
+/** Build a React Query cache key from route path, params, and query */
+export function buildQueryKey(path, params, query) {
+    const key = [path];
+    if (params && Object.keys(params).length > 0) {
+        key.push(params);
+    }
+    if (query && Object.keys(query).length > 0) {
+        key.push(query);
+    }
+    return key;
+}
+// ─── Factory ────────────────────────────────────────────────
+/**
+ * Create type-safe React Query hooks from a TypoKit client.
+ *
+ * @example
+ * ```ts
+ * const hooks = createQueryHooks<MyRoutes>(client);
+ * // In a React component:
+ * const { data, isLoading } = hooks.useGet("/users", { query: { page: 1 } });
+ * const createUser = hooks.usePost("/users");
+ * createUser.mutate({ body: { name: "Alice" } });
+ * ```
+ */
+export function createQueryHooks(client) {
+    const c = client;
+    function makeGetHook(path, options) {
+        const queryKey = buildQueryKey(path, options?.params, options?.query);
+        return useQuery({
+            queryKey,
+            queryFn: () => c.get(path, { params: options?.params, query: options?.query }),
+            enabled: options?.enabled,
+            staleTime: options?.staleTime,
+        });
+    }
+    function makeMutationHook(method, path, options) {
+        const { onSuccess, onError, onSettled, onMutate, ...rest } = options ?? {};
+        return useMutation({
+            mutationFn: (variables) => c[method](path, { params: variables.params, body: variables.body }),
+            onSuccess: onSuccess,
+            onError: onError,
+            onSettled: onSettled,
+            onMutate: onMutate,
+            ...rest,
+        });
+    }
+    return {
+        useGet: (path, options) => makeGetHook(path, options),
+        usePost: (path, options) => makeMutationHook("post", path, options),
+        usePut: (path, options) => makeMutationHook("put", path, options),
+        usePatch: (path, options) => makeMutationHook("patch", path, options),
+        useDelete: (path, options) => makeMutationHook("delete", path, options),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kDAAkD;AASlD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D,+DAA+D;AAE/D,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,MAA+B,EAC/B,KAA+B;IAE/B,MAAM,GAAG,GAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAmID,+DAA+D;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA+B;IAE/B,MAAM,CAAC,GAAG,MAAkC,CAAC;IAE7C,SAAS,WAAW,CAClB,IAAY,EACZ,OAMC;QAED,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QACtE,OAAO,QAAQ,CAAC;YACd,QAAQ;YACR,OAAO,EAAE,GAAG,EAAE,CACZ,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YACjE,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,SAAS,EAAE,OAAO,EAAE,SAAS;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,SAAS,gBAAgB,CACvB,MAA2C,EAC3C,IAAY,EACZ,OAAiC;QAMjC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC3E,OAAO,WAAW,CAAC;YACjB,UAAU,EAAE,CAAC,SAGZ,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;YACzE,SAAS,EAAE,SAAsB;YACjC,OAAO,EAAE,OAAoB;YAC7B,SAAS,EAAE,SAAsB;YACjC,QAAQ,EAAE,QAAqB;YAC/B,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,MAAM,EAAE,CAAC,IAAY,EAAE,OAAiC,EAAE,EAAE,CAC1D,WAAW,CAAC,IAAI,EAAE,OAAkC,CAAC;QACvD,OAAO,EAAE,CAAC,IAAY,EAAE,OAAiC,EAAE,EAAE,CAC3D,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;QACzC,MAAM,EAAE,CAAC,IAAY,EAAE,OAAiC,EAAE,EAAE,CAC1D,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC;QACxC,QAAQ,EAAE,CAAC,IAAY,EAAE,OAAiC,EAAE,EAAE,CAC5D,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC;QAC1C,SAAS,EAAE,CAAC,IAAY,EAAE,OAAiC,EAAE,EAAE,CAC7D,gBAAgB,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC;KACrB,CAAC;AAC3B,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@typokit/client-react-query",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "version": "0.1.4",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@typokit/client": "0.1.4",
+    "@typokit/types": "0.1.4"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KyleBastien/typokit",
+    "directory": "packages/client-react-query"
+  },
+  "scripts": {
+    "test": "rstest run --passWithNoTests"
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,95 @@
+// Ambient type declarations for @tanstack/react-query (peer dependency)
+// Consumers must install @tanstack/react-query >= 5.0.0
+
+declare module "@tanstack/react-query" {
+  export type QueryKey = readonly unknown[];
+
+  export interface UseQueryOptions<
+    TQueryFnData = unknown,
+    _TError = Error,
+    TData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+  > {
+    queryKey: TQueryKey;
+    queryFn: (context: { queryKey: TQueryKey }) => Promise<TQueryFnData>;
+    enabled?: boolean;
+    staleTime?: number;
+    refetchInterval?: number | false;
+    select?: (data: TQueryFnData) => TData;
+  }
+
+  export interface UseQueryResult<TData = unknown, TError = Error> {
+    data: TData | undefined;
+    error: TError | null;
+    isLoading: boolean;
+    isPending: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    isFetching: boolean;
+    refetch: () => Promise<UseQueryResult<TData, TError>>;
+    status: "pending" | "error" | "success";
+  }
+
+  export interface UseMutationOptions<
+    TData = unknown,
+    TError = Error,
+    TVariables = void,
+    TContext = unknown,
+  > {
+    mutationFn: (variables: TVariables) => Promise<TData>;
+    onSuccess?: (
+      data: TData,
+      variables: TVariables,
+      context: TContext | undefined,
+    ) => void;
+    onError?: (
+      error: TError,
+      variables: TVariables,
+      context: TContext | undefined,
+    ) => void;
+    onSettled?: (
+      data: TData | undefined,
+      error: TError | null,
+      variables: TVariables,
+      context: TContext | undefined,
+    ) => void;
+    onMutate?: (
+      variables: TVariables,
+    ) => TContext | Promise<TContext | undefined>;
+  }
+
+  export interface UseMutationResult<
+    TData = unknown,
+    TError = Error,
+    TVariables = void,
+  > {
+    mutate: (variables: TVariables) => void;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    data: TData | undefined;
+    error: TError | null;
+    isIdle: boolean;
+    isPending: boolean;
+    isError: boolean;
+    isSuccess: boolean;
+    reset: () => void;
+    status: "idle" | "pending" | "error" | "success";
+  }
+
+  export function useQuery<
+    TQueryFnData = unknown,
+    TError = Error,
+    TData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+  >(
+    options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+  ): UseQueryResult<TData, TError>;
+
+  export function useMutation<
+    TData = unknown,
+    TError = Error,
+    TVariables = void,
+    TContext = unknown,
+  >(
+    options: UseMutationOptions<TData, TError, TVariables, TContext>,
+  ): UseMutationResult<TData, TError, TVariables>;
+}

package/src/index.test.ts

@@ -0,0 +1,60 @@
+// @typokit/client-react-query — Tests
+
+import { describe, it, expect } from "@rstest/core";
+import { buildQueryKey } from "./index.js";
+
+// ─── buildQueryKey Tests ────────────────────────────────────
+
+describe("buildQueryKey", () => {
+  it("returns path-only key when no params or query", () => {
+    const key = buildQueryKey("/users");
+    expect(key).toEqual(["/users"]);
+  });
+
+  it("includes params in key when provided", () => {
+    const key = buildQueryKey("/users/:id", { id: "123" });
+    expect(key).toEqual(["/users/:id", { id: "123" }]);
+  });
+
+  it("includes query in key when provided", () => {
+    const key = buildQueryKey("/users", undefined, { page: 1, limit: 10 });
+    expect(key).toEqual(["/users", { page: 1, limit: 10 }]);
+  });
+
+  it("includes both params and query when provided", () => {
+    const key = buildQueryKey(
+      "/users/:id/posts",
+      { id: "42" },
+      { sort: "date" },
+    );
+    expect(key).toEqual(["/users/:id/posts", { id: "42" }, { sort: "date" }]);
+  });
+
+  it("omits empty params object", () => {
+    const key = buildQueryKey("/users", {});
+    expect(key).toEqual(["/users"]);
+  });
+
+  it("omits empty query object", () => {
+    const key = buildQueryKey("/users", undefined, {});
+    expect(key).toEqual(["/users"]);
+  });
+
+  it("produces different keys for different params", () => {
+    const key1 = buildQueryKey("/users/:id", { id: "1" });
+    const key2 = buildQueryKey("/users/:id", { id: "2" });
+    expect(key1).not.toEqual(key2);
+  });
+
+  it("produces different keys for different queries", () => {
+    const key1 = buildQueryKey("/users", undefined, { page: 1 });
+    const key2 = buildQueryKey("/users", undefined, { page: 2 });
+    expect(key1).not.toEqual(key2);
+  });
+
+  it("produces different keys for different paths", () => {
+    const key1 = buildQueryKey("/users");
+    const key2 = buildQueryKey("/posts");
+    expect(key1).not.toEqual(key2);
+  });
+});

package/src/index.ts

@@ -0,0 +1,233 @@
+// @typokit/client-react-query — React Query Hooks
+
+import type { RouteContract } from "@typokit/types";
+import type { RouteMap, TypeSafeClient } from "@typokit/client";
+import type {
+  UseQueryResult,
+  UseMutationOptions,
+  UseMutationResult,
+} from "@tanstack/react-query";
+import { useQuery, useMutation } from "@tanstack/react-query";
+
+// ─── Query Key Builder ──────────────────────────────────────
+
+/** Build a React Query cache key from route path, params, and query */
+export function buildQueryKey(
+  path: string,
+  params?: Record<string, string>,
+  query?: Record<string, unknown>,
+): readonly unknown[] {
+  const key: unknown[] = [path];
+  if (params && Object.keys(params).length > 0) {
+    key.push(params);
+  }
+  if (query && Object.keys(query).length > 0) {
+    key.push(query);
+  }
+  return key;
+}
+
+// ─── Type-Level Utilities ───────────────────────────────────
+
+/** Extract GET route paths from a RouteMap */
+type GetPaths<TRoutes extends RouteMap> = {
+  [P in keyof TRoutes]: "GET" extends keyof TRoutes[P] ? P : never;
+}[keyof TRoutes] &
+  string;
+
+type MutationMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** Extract paths that have a given mutation method */
+type MutationPaths<TRoutes extends RouteMap, M extends MutationMethod> = {
+  [P in keyof TRoutes]: M extends keyof TRoutes[P] ? P : never;
+}[keyof TRoutes] &
+  string;
+
+/** Resolve the RouteContract for a given path and method */
+type ContractFor<
+  TRoutes extends RouteMap,
+  P extends string,
+  M extends string,
+> = P extends keyof TRoutes
+  ? M extends keyof TRoutes[P]
+    ? TRoutes[P][M] extends RouteContract
+      ? TRoutes[P][M]
+      : RouteContract
+    : RouteContract
+  : RouteContract;
+
+// ─── Hook Option / Variable Types ───────────────────────────
+
+/** Options for useGet: route-specific params/query + React Query config */
+export interface UseGetOptions<C extends RouteContract> {
+  params?: C["params"] extends void
+    ? undefined
+    : C["params"] & Record<string, string>;
+  query?: C["query"] extends void ? undefined : C["query"];
+  enabled?: boolean;
+  staleTime?: number;
+  refetchInterval?: number | false;
+}
+
+/** Variables passed to mutation hooks */
+export interface MutationVariables<C extends RouteContract> {
+  params?: C["params"] extends void
+    ? undefined
+    : C["params"] & Record<string, string>;
+  body?: C["body"] extends void ? undefined : C["body"];
+}
+
+/** Mutation lifecycle callbacks */
+type MutationCallbacks<TData, TVars> = Pick<
+  UseMutationOptions<TData, Error, TVars, unknown>,
+  "onSuccess" | "onError" | "onSettled" | "onMutate"
+>;
+
+// ─── QueryHooks Interface ───────────────────────────────────
+
+/** Type-safe React Query hooks generated from a RouteMap */
+export interface QueryHooks<TRoutes extends RouteMap> {
+  /** useQuery wrapper for GET routes */
+  useGet<P extends GetPaths<TRoutes>>(
+    path: P,
+    options?: UseGetOptions<ContractFor<TRoutes, P, "GET">>,
+  ): UseQueryResult<ContractFor<TRoutes, P, "GET">["response"], Error>;
+
+  /** useMutation wrapper for POST routes */
+  usePost<P extends MutationPaths<TRoutes, "POST">>(
+    path: P,
+    options?: MutationCallbacks<
+      ContractFor<TRoutes, P, "POST">["response"],
+      MutationVariables<ContractFor<TRoutes, P, "POST">>
+    >,
+  ): UseMutationResult<
+    ContractFor<TRoutes, P, "POST">["response"],
+    Error,
+    MutationVariables<ContractFor<TRoutes, P, "POST">>
+  >;
+
+  /** useMutation wrapper for PUT routes */
+  usePut<P extends MutationPaths<TRoutes, "PUT">>(
+    path: P,
+    options?: MutationCallbacks<
+      ContractFor<TRoutes, P, "PUT">["response"],
+      MutationVariables<ContractFor<TRoutes, P, "PUT">>
+    >,
+  ): UseMutationResult<
+    ContractFor<TRoutes, P, "PUT">["response"],
+    Error,
+    MutationVariables<ContractFor<TRoutes, P, "PUT">>
+  >;
+
+  /** useMutation wrapper for PATCH routes */
+  usePatch<P extends MutationPaths<TRoutes, "PATCH">>(
+    path: P,
+    options?: MutationCallbacks<
+      ContractFor<TRoutes, P, "PATCH">["response"],
+      MutationVariables<ContractFor<TRoutes, P, "PATCH">>
+    >,
+  ): UseMutationResult<
+    ContractFor<TRoutes, P, "PATCH">["response"],
+    Error,
+    MutationVariables<ContractFor<TRoutes, P, "PATCH">>
+  >;
+
+  /** useMutation wrapper for DELETE routes */
+  useDelete<P extends MutationPaths<TRoutes, "DELETE">>(
+    path: P,
+    options?: MutationCallbacks<
+      ContractFor<TRoutes, P, "DELETE">["response"],
+      MutationVariables<ContractFor<TRoutes, P, "DELETE">>
+    >,
+  ): UseMutationResult<
+    ContractFor<TRoutes, P, "DELETE">["response"],
+    Error,
+    MutationVariables<ContractFor<TRoutes, P, "DELETE">>
+  >;
+}
+
+// ─── Untyped client for internal use ────────────────────────
+
+interface UntypedClient {
+  get(path: string, options?: unknown): Promise<unknown>;
+  post(path: string, options?: unknown): Promise<unknown>;
+  put(path: string, options?: unknown): Promise<unknown>;
+  patch(path: string, options?: unknown): Promise<unknown>;
+  delete(path: string, options?: unknown): Promise<unknown>;
+}
+
+// ─── Factory ────────────────────────────────────────────────
+
+/**
+ * Create type-safe React Query hooks from a TypoKit client.
+ *
+ * @example
+ * ```ts
+ * const hooks = createQueryHooks<MyRoutes>(client);
+ * // In a React component:
+ * const { data, isLoading } = hooks.useGet("/users", { query: { page: 1 } });
+ * const createUser = hooks.usePost("/users");
+ * createUser.mutate({ body: { name: "Alice" } });
+ * ```
+ */
+export function createQueryHooks<TRoutes extends RouteMap>(
+  client: TypeSafeClient<TRoutes>,
+): QueryHooks<TRoutes> {
+  const c = client as unknown as UntypedClient;
+
+  function makeGetHook(
+    path: string,
+    options?: {
+      params?: Record<string, string>;
+      query?: Record<string, unknown>;
+      enabled?: boolean;
+      staleTime?: number;
+      refetchInterval?: number | false;
+    },
+  ): UseQueryResult<unknown, Error> {
+    const queryKey = buildQueryKey(path, options?.params, options?.query);
+    return useQuery({
+      queryKey,
+      queryFn: () =>
+        c.get(path, { params: options?.params, query: options?.query }),
+      enabled: options?.enabled,
+      staleTime: options?.staleTime,
+    });
+  }
+
+  function makeMutationHook(
+    method: "post" | "put" | "patch" | "delete",
+    path: string,
+    options?: Record<string, unknown>,
+  ): UseMutationResult<
+    unknown,
+    Error,
+    { params?: Record<string, string>; body?: unknown }
+  > {
+    const { onSuccess, onError, onSettled, onMutate, ...rest } = options ?? {};
+    return useMutation({
+      mutationFn: (variables: {
+        params?: Record<string, string>;
+        body?: unknown;
+      }) => c[method](path, { params: variables.params, body: variables.body }),
+      onSuccess: onSuccess as undefined,
+      onError: onError as undefined,
+      onSettled: onSettled as undefined,
+      onMutate: onMutate as undefined,
+      ...rest,
+    });
+  }
+
+  return {
+    useGet: (path: string, options?: Record<string, unknown>) =>
+      makeGetHook(path, options as Record<string, unknown>),
+    usePost: (path: string, options?: Record<string, unknown>) =>
+      makeMutationHook("post", path, options),
+    usePut: (path: string, options?: Record<string, unknown>) =>
+      makeMutationHook("put", path, options),
+    usePatch: (path: string, options?: Record<string, unknown>) =>
+      makeMutationHook("patch", path, options),
+    useDelete: (path: string, options?: Record<string, unknown>) =>
+      makeMutationHook("delete", path, options),
+  } as QueryHooks<TRoutes>;
+}