@geekmidas/client

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS构建来源已验证近 30 天下载 1.3万

Type-safe client library for consuming HTTP APIs with full TypeScript support, React Query integration, and automatic code generation from OpenAPI specifications.

原始使用文档
文档目录26 节
  1. Features
  2. Installation
  3. Package Exports
  4. Quick Start
  5. Type-Safe Fetcher
  6. React Query Integration
  7. Query Parameters
  8. Infinite Queries
  9. Generated API Client (Recommended)
  10. Type-Safe Config Requirements
  11. Authentication Strategies
  12. Auth-Aware Fetcher
  13. OpenAPI Code Generation
  14. Advanced Features
  15. Query Invalidation
  16. Optimistic Updates
  17. Custom Headers
  18. Error Handling
  19. Request/Response Interceptors
  20. Prefetching
  21. Type Utilities
  22. Infer API Types
  23. Method Restrictions
  24. Testing
  25. Related Packages
  26. License

@geekmidas/client

Type-safe client library for consuming HTTP APIs with full TypeScript support, React Query integration, and automatic code generation from OpenAPI specifications.

Features

  • Type-Safe Fetcher: Fully typed HTTP client with automatic type inference
  • React Query Integration: Pre-built hooks with TypeScript support
  • OpenAPI Code Generation: Generate React Query hooks from OpenAPI specs
  • Infinite Queries: Built-in support for pagination and infinite scroll
  • Automatic Validation: Request/response validation with StandardSchema
  • Error Handling: Type-safe error handling with HTTP status codes
  • Query Invalidation: Type-safe cache invalidation
  • Method Restrictions: Type-level enforcement of HTTP methods per endpoint

Installation

pnpm add @geekmidas/client

For React Query integration:

pnpm add @geekmidas/client @tanstack/react-query

Package Exports

// Type-safe fetcher
import { createTypedFetcher } from '@geekmidas/client';

// Auth-aware fetcher with security schemes
import { createAuthAwareFetcher } from '@geekmidas/client/auth-fetcher';

// React Query hooks (endpoint-string based)
import { createEndpointHooks } from '@geekmidas/client/endpoint-hooks';

// React Query client (class-based)
import { createTypedQueryClient } from '@geekmidas/client/react-query';

// OpenAPI hooks generation
import { generateReactQueryHooks } from '@geekmidas/client/openapi';

// Type utilities
import type { TypedApiFunction, FilteredRequestConfig } from '@geekmidas/client/types';

Quick Start

Type-Safe Fetcher

Create a typed fetcher for your API:

import { createTypedFetcher } from '@geekmidas/client';

// Define your API types
interface API {
  'GET /users': {
    response: {
      id: string;
      name: string;
      email: string;
    }[];
  };
  'POST /users': {
    body: {
      name: string;
      email: string;
    };
    response: {
      id: string;
      name: string;
      email: string;
    };
  };
  'GET /users/:id': {
    params: {
      id: string;
    };
    response: {
      id: string;
      name: string;
      email: string;
    };
  };
}

// Create typed fetcher
const api = createTypedFetcher<API>({
  baseUrl: 'https://api.example.com'
});

// Use with full type safety
const users = await api('GET /users');
// users is typed as Array<{ id: string; name: string; email: string }>

const user = await api('POST /users', {
  body: { name: 'John Doe', email: '[email protected]' }
});
// user is typed as { id: string; name: string; email: string }

const singleUser = await api('GET /users/:id', {
  params: { id: '123' }
});
// singleUser is typed as { id: string; name: string; email: string }

React Query Integration

Use with React Query for automatic caching and state management:

import { createTypedQueryClient } from '@geekmidas/client/react-query';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Create query client
const queryClient = new QueryClient();
const api = createTypedQueryClient<API>({
  baseUrl: 'https://api.example.com'
});

// In your component
function UsersList() {
  const { data, isLoading, error } = api.useQuery('GET /users');

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {data.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

// Mutations
function CreateUser() {
  const createUser = api.useMutation('POST /users');

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    await createUser.mutateAsync({
      body: { name: 'Jane Doe', email: '[email protected]' }
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button disabled={createUser.isPending}>
        Create User
      </button>
    </form>
  );
}

Query Parameters

Handle query parameters with full type safety:

interface API {
  'GET /users/search': {
    query: {
      q: string;
      limit?: number;
      offset?: number;
    };
    response: {
      users: Array<{ id: string; name: string }>;
      total: number;
    };
  };
}

// Usage
const result = await api('GET /users/search', {
  query: { q: 'john', limit: 10 }
});

Infinite Queries

Implement infinite scroll pagination:

function InfiniteUsersList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage
  } = api.useInfiniteQuery(
    'GET /users',
    {
      query: { limit: 20 }
    },
    {
      getNextPageParam: (lastPage, pages) => {
        if (pages.length * 20 < lastPage.total) {
          return { offset: pages.length * 20 };
        }
        return undefined;
      }
    }
  );

  return (
    <div>
      {data?.pages.map((page, i) => (
        <div key={i}>
          {page.users.map(user => (
            <div key={user.id}>{user.name}</div>
          ))}
        </div>
      ))}
      {hasNextPage && (
        <button
          onClick={() => fetchNextPage()}
          disabled={isFetchingNextPage}
        >
          Load More
        </button>
      )}
    </div>
  );
}

When using @geekmidas/cli to generate OpenAPI types, you get a fully configured createApi factory:

// Generated by: gkm openapi --output ./src/api.ts
import { createApi } from './api';

// Create API client with authentication
const api = createApi({
  baseURL: 'https://api.example.com',
  authStrategies: {
    // Only strategies for schemes actually used in your API are required
    jwt: {
      type: 'bearer',
      tokenProvider: async () => localStorage.getItem('token'),
    },
  },
});

// Imperative fetching - callable directly
const user = await api('GET /users/{id}', { params: { id: '123' } });

// React Query hooks - available as properties
function UserProfile({ id }: { id: string }) {
  // Config is required when endpoint has path params
  const { data, isLoading } = api.useQuery('GET /users/{id}', {
    params: { id }
  });

  if (isLoading) return <div>Loading...</div>;
  return <div>{data.name}</div>;
}

// Mutations
function CreateUser() {
  const mutation = api.useMutation('POST /users');

  return (
    <button onClick={() => mutation.mutate({
      body: { name: 'John', email: '[email protected]' }
    })}>
      Create User
    </button>
  );
}

Type-Safe Config Requirements

The generated client enforces config requirements at the type level:

// ✅ GET /health - no params, no body → config optional
await api('GET /health');

// ❌ GET /users/{id} - has params → config required
await api('GET /users/{id}'); // Type error!

// ✅ GET /users/{id} - with required params
await api('GET /users/{id}', { params: { id: '123' } });

// ❌ POST /users - has body → config required
await api('POST /users'); // Type error!

// ✅ POST /users - with required body
await api('POST /users', { body: { name: 'John', email: '[email protected]' } });

Authentication Strategies

The authStrategies option maps security scheme IDs to authentication handlers:

const api = createApi({
  baseURL: 'https://api.example.com',
  authStrategies: {
    // Bearer token (JWT)
    jwt: {
      type: 'bearer',
      tokenProvider: async () => getAccessToken(),
    },

    // API Key in header
    apiKey: {
      type: 'apiKey',
      tokenProvider: async () => process.env.API_KEY,
    },

    // Custom authentication
    custom: {
      type: 'custom',
      applyAuth: async (headers) => {
        headers.set('X-Custom-Auth', await getCustomToken());
      },
    },
  },
});

Auth-Aware Fetcher

For manual setup without code generation, use createAuthAwareFetcher:

import { createAuthAwareFetcher } from '@geekmidas/client/auth-fetcher';
import { createEndpointHooks } from '@geekmidas/client/endpoint-hooks';
import type { paths } from './openapi-types';

// Define which endpoints use which auth
const endpointAuth = {
  'GET /users': 'jwt',
  'POST /users': 'jwt',
  'GET /health': null, // Public endpoint
} as const;

// Define security schemes
const securitySchemes = {
  jwt: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
} as const;

// Create auth-aware fetcher
const fetcher = createAuthAwareFetcher<
  paths,
  typeof endpointAuth,
  typeof securitySchemes
>({
  baseURL: 'https://api.example.com',
  endpointAuth,
  securitySchemes,
  authStrategies: {
    jwt: {
      type: 'bearer',
      tokenProvider: async () => localStorage.getItem('token'),
    },
  },
});

// Add React Query hooks
const hooks = createEndpointHooks<paths>(fetcher);

// Combine into single API object
const api = Object.assign(fetcher, hooks);

OpenAPI Code Generation

Generate React Query hooks from OpenAPI specifications:

# Using CLI
pnpm gkm generate:react-query --input api-docs.json --output ./src/api

# Programmatic usage
import { generateReactQueryHooks } from '@geekmidas/client/openapi';
import fs from 'fs/promises';

const spec = JSON.parse(await fs.readFile('api-docs.json', 'utf-8'));
const code = await generateReactQueryHooks(spec);
await fs.writeFile('./src/api/generated.ts', code);

Generated hooks example:

// Generated from OpenAPI spec
export const api = createTypedQueryClient<{
  'GET /users': {
    response: User[];
  };
  'POST /users': {
    body: CreateUserRequest;
    response: User;
  };
  // ... all your endpoints
}>({
  baseUrl: process.env.REACT_APP_API_URL
});

// Use generated hooks
function MyComponent() {
  const { data: users } = api.useQuery('GET /users');
  const createUser = api.useMutation('POST /users');

  return (
    // Your component
  );
}

Advanced Features

Query Invalidation

Type-safe cache invalidation:

// Invalidate specific query
await api.invalidateQueries('GET /users');

// Invalidate with params
await api.invalidateQueries('GET /users/:id', {
  params: { id: '123' }
});

// Invalidate multiple queries
await Promise.all([
  api.invalidateQueries('GET /users'),
  api.invalidateQueries('GET /users/:id')
]);

Optimistic Updates

Implement optimistic UI updates:

const updateUser = api.useMutation('PUT /users/:id', {
  onMutate: async (variables) => {
    // Cancel outgoing refetches
    await api.cancelQueries('GET /users/:id', {
      params: { id: variables.params.id }
    });

    // Snapshot previous value
    const previousUser = api.getQueryData('GET /users/:id', {
      params: { id: variables.params.id }
    });

    // Optimistically update
    api.setQueryData('GET /users/:id', {
      params: { id: variables.params.id }
    }, variables.body);

    return { previousUser };
  },
  onError: (err, variables, context) => {
    // Rollback on error
    if (context?.previousUser) {
      api.setQueryData('GET /users/:id', {
        params: { id: variables.params.id }
      }, context.previousUser);
    }
  },
  onSettled: (data, error, variables) => {
    // Refetch after mutation
    api.invalidateQueries('GET /users/:id', {
      params: { id: variables.params.id }
    });
  }
});

Custom Headers

Add custom headers to requests:

const api = createTypedFetcher<API>({
  baseUrl: 'https://api.example.com',
  headers: {
    'Authorization': `Bearer ${token}`,
    'X-Api-Key': apiKey
  }
});

// Per-request headers
const user = await api('GET /users/:id', {
  params: { id: '123' },
  headers: {
    'X-Request-ID': requestId
  }
});

Error Handling

Handle errors with full type safety:

import { HttpError } from '@geekmidas/errors';

try {
  const user = await api('GET /users/:id', {
    params: { id: '123' }
  });
} catch (error) {
  if (error instanceof HttpError) {
    if (error.statusCode === 404) {
      console.log('User not found');
    } else if (error.statusCode === 403) {
      console.log('Access denied');
    } else {
      console.error('API error:', error.message);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Request/Response Interceptors

Add interceptors for logging, auth, etc:

const api = createTypedFetcher<API>({
  baseUrl: 'https://api.example.com',
  beforeRequest: async (url, options) => {
    // Add auth token
    const token = await getAuthToken();
    options.headers = {
      ...options.headers,
      'Authorization': `Bearer ${token}`
    };
    return { url, options };
  },
  afterResponse: async (response) => {
    // Log response
    console.log(`${response.status} ${response.url}`);
    return response;
  },
  onError: async (error) => {
    // Handle auth errors
    if (error instanceof HttpError && error.statusCode === 401) {
      await refreshAuthToken();
      // Retry request
    }
    throw error;
  }
});

Prefetching

Prefetch queries for better UX:

function UsersList() {
  const { data: users } = api.useQuery('GET /users');

  const handleUserHover = (userId: string) => {
    // Prefetch user details on hover
    api.prefetchQuery('GET /users/:id', {
      params: { id: userId }
    });
  };

  return (
    <ul>
      {users?.map(user => (
        <li
          key={user.id}
          onMouseEnter={() => handleUserHover(user.id)}
        >
          {user.name}
        </li>
      ))}
    </ul>
  );
}

Type Utilities

Infer API Types

import type { InferAPIResponse, InferAPIRequest } from '@geekmidas/client/types';

type UsersResponse = InferAPIResponse<API, 'GET /users'>;
// type UsersResponse = Array<{ id: string; name: string; email: string }>

type CreateUserRequest = InferAPIRequest<API, 'POST /users'>;
// type CreateUserRequest = { body: { name: string; email: string } }

Method Restrictions

Enforce correct HTTP methods at type level:

// ✅ Correct - POST endpoint with body
await api('POST /users', {
  body: { name: 'John' }
});

// ❌ Type error - GET endpoint can't have body
await api('GET /users', {
  body: { name: 'John' } // Type error!
});

// ❌ Type error - Wrong method
await api('DELETE /users', {}); // Type error if endpoint not defined!

Testing

Mock API calls in tests:

import { createTypedFetcher } from '@geekmidas/client';
import { vi } from 'vitest';

const mockFetch = vi.fn();
global.fetch = mockFetch;

const api = createTypedFetcher<API>({
  baseUrl: 'https://api.example.com'
});

// Mock response
mockFetch.mockResolvedValueOnce({
  ok: true,
  json: async () => [{ id: '1', name: 'John', email: '[email protected]' }]
});

const users = await api('GET /users');
expect(users).toHaveLength(1);
expect(mockFetch).toHaveBeenCalledWith(
  'https://api.example.com/users',
  expect.objectContaining({ method: 'GET' })
);

License

MIT

版本与发布记录

@geekmidas/client 共发布 216 个版本,首次发布于 2025/10/20;过去 12 个月发布了 215 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/client 的常见问题

@geekmidas/client 是什么?

Type-safe client library for consuming HTTP APIs with full TypeScript support, React Query integration, and automatic code generation from OpenAPI specifications.

如何安装 @geekmidas/client?

在项目目录运行 npm install @geekmidas/client,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^4.1.13)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geekmidas/client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geekmidas/client 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@geekmidas/client 可以商用吗?

@geekmidas/client 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@geekmidas/client 的下载量有多少?

根据 npm 官方下载统计,@geekmidas/client 在 2026/10/16 – 2026/11/14 这 30 天内被下载 13,155 次,日均约 439 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geekmidas/client 还在维护吗?

最新版本 9.6.1 发布于 2026/11/16(今天);至今共发布 216 个版本,其中过去 12 个月发布了 215 个;首次发布于 2025/10/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。