@gravity-ui/data-source

中文文档
0.10.0发布于 2026/07/09MITTypeScriptESM + CJS近 30 天下载 1.4万

A wrapper around data fetching

原始使用文档
文档目录28 节
  1. Installation
  2. Quick Start
  3. 1. Setup DataManager
  4. 2. Define Error Types and Wrappers
  5. 3. Create Custom DataLoader Component
  6. 4. Define Your First Data Source
  7. 5. Use in Components
  8. Core Concepts
  9. Data Source Types
  10. Status Management
  11. Idle Concept
  12. API Reference
  13. Creating Data Sources
  14. React Hooks
  15. React Components
  16. Data Management
  17. Utilities
  18. Advanced Patterns
  19. Conditional Queries with Idle
  20. Data Transformation
  21. Tag-Based Cache Invalidation
  22. Error Handling with Types
  23. Infinite Queries with Complex Pagination
  24. Combining Multiple Data Sources
  25. TypeScript Support
  26. Custom Error Types
  27. Contributing
  28. License

Data Source · npm version ci

Data Source is a simple wrapper around data fetching. It is a kind of "port" in clean architecture. It allows you to make wrappers for stuff around data fetching depending on your use cases. Data Source uses react-query under the hood.

Installation

npm install @gravity-ui/data-source @tanstack/react-query

@tanstack/react-query is a peer dependency.

Quick Start

1. Setup DataManager

First, create and provide a DataManager in your application:

import React from 'react';
import {ClientDataManager, DataManagerContext} from '@gravity-ui/data-source';

const dataManager = new ClientDataManager({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      retry: 3,
    },
    // ... other react-query options
  },
});

function App() {
  return (
    <DataManagerContext.Provider value={dataManager}>
      <YourApplication />
    </DataManagerContext.Provider>
  );
}

2. Define Error Types and Wrappers

Define a type of error and make your constructors for data sources based on default constructors:

import {makePlainQueryDataSource as makePlainQueryDataSourceBase} from '@gravity-ui/data-source';

export interface ApiError {
  code: number;
  title: string;
  description?: string;
}

export const makePlainQueryDataSource = <TParams, TRequest, TResponse, TData, TError = ApiError>(
  config: Omit<PlainQueryDataSource<TParams, TRequest, TResponse, TData, TError>, 'type'>,
): PlainQueryDataSource<TParams, TRequest, TResponse, TData, TError> => {
  return makePlainQueryDataSourceBase(config);
};

3. Create Custom DataLoader Component

Write a DataLoader component based on default to define your display of loading status and errors:

import {
  DataLoader as DataLoaderBase,
  DataLoaderProps as DataLoaderPropsBase,
  ErrorViewProps,
} from '@gravity-ui/data-source';

export interface DataLoaderProps
  extends Omit<DataLoaderPropsBase<ApiError>, 'LoadingView' | 'ErrorView'> {
  LoadingView?: ComponentType;
  ErrorView?: ComponentType<ErrorViewProps<ApiError>>;
}

export const DataLoader: React.FC<DataLoaderProps> = ({
  LoadingView = YourLoader, // You can use your own loader component
  ErrorView = YourError, // You can use your own error component
  ...restProps
}) => {
  return <DataLoaderBase LoadingView={LoadingView} ErrorView={ErrorView} {...restProps} />;
};

4. Define Your First Data Source

import {skipContext} from '@gravity-ui/data-source';

// Your API function
import {fetchUser} from './api';

export const userDataSource = makePlainQueryDataSource({
  // Keys have to be unique. Maybe you should create a helper for making names of data sources
  name: 'user',
  // skipContext is a helper to skip 2 first parameters in the function (context and fetchContext)
  fetch: skipContext(fetchUser),
  // Optional: generate tags for advanced cache invalidation
  tags: (params) => [`user:${params.userId}`, 'users'],
});

5. Use in Components

import {useQueryData} from '@gravity-ui/data-source';

export const UserProfile: React.FC<{userId: number}> = ({userId}) => {
  const {data, status, error, refetch} = useQueryData(userDataSource, {userId});

  return (
    <DataLoader status={status} error={error} errorAction={refetch}>
      {data && <UserCard user={data} />}
    </DataLoader>
  );
};

Core Concepts

Data Source Types

The library provides two main types of data sources:

Plain Query Data Source

For simple request/response patterns:

const userDataSource = makePlainQueryDataSource({
  name: 'user',
  fetch: skipContext(async (params: {userId: number}) => {
    const response = await fetch(`/api/users/${params.userId}`);
    return response.json();
  }),
});

Infinite Query Data Source

For pagination and infinite scrolling:

const postsDataSource = makeInfiniteQueryDataSource({
  name: 'posts',
  fetch: skipContext(async (params: {page: number; limit: number}) => {
    const response = await fetch(`/api/posts?page=${params.page}&limit=${params.limit}`);
    return response.json();
  }),
  next: (lastPage, allPages) => {
    if (lastPage.hasNext) {
      return {page: allPages.length + 1, limit: 20};
    }
    return undefined;
  },
});

Status Management

The library normalizes query states into three simple statuses:

  • loading - Actual data loading. The same as isLoading in React Query
  • success - Data available (may be skipped using idle)
  • error - Failed to fetch data

Idle Concept

The library provides a special idle symbol for skipping query execution:

import {idle} from '@gravity-ui/data-source';

const UserProfile: React.FC<{userId?: number}> = ({userId}) => {
  // Query won't execute if userId is not defined
  const {data, status} = useQueryData(userDataSource, userId ? {userId} : idle);

  return (
    <DataLoader status={status} error={null}>
      {data && <UserCard user={data} />}
    </DataLoader>
  );
};

When parameters equal idle:

  • Query doesn't execute
  • Status remains success
  • Data remains undefined
  • Component can safely render without loading

Benefits of idle:

  1. Type Safety - TypeScript correctly infers types for conditional parameters
  2. Performance - Avoids unnecessary server requests
  3. Logic Simplicity - No need to manage additional enabled state
  4. Consistency - Unified approach for all conditional queries

This is especially useful for conditional queries when you want to load data only under certain conditions while maintaining type safety.

API Reference

Creating Data Sources

makePlainQueryDataSource(config)

Creates a plain query data source for simple request/response patterns.

const dataSource = makePlainQueryDataSource({
  name: 'unique-name',
  fetch: skipContext(fetchFunction),
  transformParams: (params) => transformedRequest,
  transformResponse: (response) => transformedData,
  tags: (params) => ['tag1', 'tag2'],
  options: {
    staleTime: 60000,
    retry: 3,
    // ... other react-query options
  },
});

Parameters:

  • name - Unique identifier for the data source
  • fetch - Function that performs the actual data fetching
  • transformParams (optional) - Transform input parameters before request
  • transformResponse (optional) - Transform response data
  • tags (optional) - Generate cache tags for invalidation
  • options (optional) - React Query options

makeInfiniteQueryDataSource(config)

Creates an infinite query data source for pagination and infinite scrolling patterns.

const infiniteDataSource = makeInfiniteQueryDataSource({
  name: 'infinite-data',
  fetch: skipContext(fetchFunction),
  next: (lastPage, allPages) => nextPageParam || undefined,
  prev: (firstPage, allPages) => prevPageParam || undefined,
  // ... other options same as plain
});

Additional Parameters:

  • next - Function to determine next page parameters
  • prev (optional) - Function to determine previous page parameters

React Hooks

useQueryData(dataSource, params, options?)

Main hook for fetching data with a data source.

const {data, status, error, refetch, ...rest} = useQueryData(
  userDataSource,
  {userId: 123},
  {
    enabled: true,
    refetchInterval: 30000,
  },
);

Returns:

  • data - The fetched data
  • status - Current status ('loading' | 'success' | 'error')
  • error - Error object if request failed
  • refetch - Function to manually refetch data
  • Other React Query properties

useQueryResponses(responses)

Combines multiple query responses into a single state.

const user = useQueryData(userDataSource, {userId});
const posts = useQueryData(postsDataSource, {userId});

const {status, error, refetch, refetchErrored} = useQueryResponses([user, posts]);

Returns:

  • status - Combined status of all queries
  • error - First error encountered
  • refetch - Function to refetch all queries
  • refetchErrored - Function to refetch only failed queries

useRefetchAll(states)

Creates a callback to refetch multiple queries.

const refetchAll = useRefetchAll([user, posts, comments]);
// refetchAll() will trigger refetch for all queries

useRefetchErrored(states)

Creates a callback to refetch only failed queries.

const refetchErrored = useRefetchErrored([user, posts, comments]);
// refetchErrored() will only refetch queries with errors

useDataManager()

Returns the DataManager from context.

const dataManager = useDataManager();
await dataManager.invalidateTag('users');

useQueryContext()

Returns the query context (for building custom data hooks base on react-query).

React Components

<DataLoader />

Component for handling loading states and errors.

<DataLoader
  status={status}
  error={error}
  errorAction={refetch}
  LoadingView={SpinnerComponent}
  ErrorView={ErrorComponent}
  loadingViewProps={{size: 'large'}}
  errorViewProps={{showDetails: true}}
>
  {data && <YourContent data={data} />}
</DataLoader>

Props:

  • status - Current loading status
  • error - Error object
  • errorAction - Function or action config for error retry
  • LoadingView - Component to show during loading
  • ErrorView - Component to show on error
  • loadingViewProps - Props passed to LoadingView
  • errorViewProps - Props passed to ErrorView

<DataInfiniteLoader />

Specialized component for infinite queries.

<DataInfiniteLoader
  status={status}
  error={error}
  hasNextPage={hasNextPage}
  fetchNextPage={fetchNextPage}
  isFetchingNextPage={isFetchingNextPage}
  LoadingView={SpinnerComponent}
  ErrorView={ErrorComponent}
  MoreView={LoadMoreButton}
>
  {data.map((item) => (
    <Item key={item.id} data={item} />
  ))}
</DataInfiniteLoader>

Additional Props:

  • hasNextPage - Whether more pages are available
  • fetchNextPage - Function to fetch next page
  • isFetchingNextPage - Whether next page is being fetched
  • MoreView - Component for "load more" button

withDataManager(Component)

HOC that injects DataManager as a prop.

const MyComponent = withDataManager<Props>(({dataManager, ...props}) => {
  // Component has access to dataManager
  return <div>...</div>;
});

Data Management

ClientDataManager

Main class for data management.

const dataManager = new ClientDataManager({
  defaultOptions: {
    queries: {
      staleTime: 300000, // 5 minutes
      retry: 3,
      refetchOnWindowFocus: false,
    },
  },
});

Methods:

invalidateTag(tag, options?)

Invalidate all queries with a specific tag.

await dataManager.invalidateTag('users');
await dataManager.invalidateTag('posts', {
  repeat: {count: 3, interval: 1000}, // Retry invalidation
});
invalidateTags(tags, options?)

Invalidate queries that have all specified tags.

await dataManager.invalidateTags(['user', 'profile']);
invalidateSource(dataSource, options?)

Invalidate all queries for a data source.

await dataManager.invalidateSource(userDataSource);
invalidateParams(dataSource, params, options?)

Invalidate a specific query with exact parameters.

await dataManager.invalidateParams(userDataSource, {userId: 123});
resetSource(dataSource)

Reset (clear) all cached data for a data source.

await dataManager.resetSource(userDataSource);
resetParams(dataSource, params)

Reset cached data for specific parameters.

await dataManager.resetParams(userDataSource, {userId: 123});
invalidateSourceTags(dataSource, params, options?)

Invalidate queries based on tags generated by a data source.

await dataManager.invalidateSourceTags(userDataSource, {userId: 123});

Utilities

skipContext(fetchFunction)

Utility to adapt existing fetch functions to data source interface.

// Existing function
async function fetchUser(params: {userId: number}) {
  // ...
}

// Adapted for data source
const dataSource = makePlainQueryDataSource({
  name: 'user',
  fetch: skipContext(fetchUser), // Skips context and fetchContext params
});

withCatch(fetchFunction, errorHandler)

Adds standardized error handling to fetch functions.

const safeFetch = withCatch(fetchUser, (error) => ({error: true, message: error.message}));

withCancellation(fetchFunction)

Adds cancellation support to fetch functions.

const cancellableFetch = withCancellation(fetchFunction);
// Automatically handles AbortSignal from React Query

getProgressiveRefetch(options)

Creates a progressive refetch interval function.

const progressiveRefetch = getProgressiveRefetch({
  minInterval: 1000, // Start with 1 second
  maxInterval: 30000, // Max 30 seconds
  multiplier: 2, // Double each time
});

const dataSource = makePlainQueryDataSource({
  name: 'data',
  fetch: skipContext(fetchData),
  options: {
    refetchInterval: progressiveRefetch,
  },
});

normalizeStatus(status, fetchStatus)

Converts React Query statuses to DataLoader status.

const status = normalizeStatus('pending', 'fetching'); // 'loading'

Status and Error Utilities

// Get combined status from multiple states
const status = getStatus([user, posts, comments]);

// Get first error from multiple states
const error = getError([user, posts, comments]);

// Merge multiple statuses
const combinedStatus = mergeStatuses(['loading', 'success', 'error']); // 'error'

// Check if query key has a tag
const hasUserTag = hasTag(queryKey, 'users');

Key Composition Utilities

// Compose cache key for a data source
const key = composeKey(userDataSource, {userId: 123});

// Compose full key including tags
const fullKey = composeFullKey(userDataSource, {userId: 123});

Constants

import {idle} from '@gravity-ui/data-source';

// Special symbol for skipping query execution
const params = shouldFetch ? {userId: 123} : idle;

// Type-safe alternative to enabled: false
// Instead of:
const {data} = useQueryData(userDataSource, {userId: userId || ''}, {enabled: Boolean(userId)});

// Use:
const {data} = useQueryData(userDataSource, userId ? {userId} : idle);
// TypeScript correctly infers types for both branches

Query Options Composition

// Compose React Query options for plain queries
const plainOptions = composePlainQueryOptions(context, dataSource, params, options);

// Compose React Query options for infinite queries
const infiniteOptions = composeInfiniteQueryOptions(context, dataSource, params, options);

Note: These functions are primarily for internal use when creating custom data source implementations.

Advanced Patterns

Conditional Queries with Idle

Use idle to create conditional queries:

import {idle} from '@gravity-ui/data-source';

const ConditionalDataComponent: React.FC<{
  userId?: number;
  shouldLoadPosts: boolean;
}> = ({userId, shouldLoadPosts}) => {
  // Load user only if userId is defined
  const user = useQueryData(
    userDataSource,
    userId ? {userId} : idle
  );

  // Load posts only if user is loaded and flag is enabled
  const posts = useQueryData(
    userPostsDataSource,
    user.data && shouldLoadPosts ? {userId: user.data.id} : idle
  );

  const combined = useQueryResponses([user, posts]);

  return (
    <DataLoader status={combined.status} error={combined.error}>
      <div>
        {user.data && <UserInfo user={user.data} />}
        {posts.data && <UserPosts posts={posts.data} />}
      </div>
    </DataLoader>
  );
};

Data Transformation

Transform request parameters and response data:

const apiDataSource = makePlainQueryDataSource({
  name: 'api-data',
  transformParams: (params: {id: number}) => ({
    userId: params.id,
    apiVersion: 'v2',
    format: 'json',
  }),
  transformResponse: (response: ApiResponse) => ({
    user: response.data.user,
    metadata: response.meta,
  }),
  fetch: skipContext(apiFetch),
});

Tag-Based Cache Invalidation

Use tags for sophisticated cache management:

const userDataSource = makePlainQueryDataSource({
  name: 'user',
  tags: (params) => [`user:${params.userId}`, 'users', 'profiles'],
  fetch: skipContext(fetchUser),
});

const userPostsDataSource = makePlainQueryDataSource({
  name: 'user-posts',
  tags: (params) => [`user:${params.userId}`, 'posts'],
  fetch: skipContext(fetchUserPosts),
});

// Invalidate all data for specific user
await dataManager.invalidateTag('user:123');

// Invalidate all user-related data
await dataManager.invalidateTag('users');

Error Handling with Types

Create type-safe error handling:

interface ApiError {
  code: number;
  message: string;
  details?: Record<string, unknown>;
}

const ErrorView: React.FC<ErrorViewProps<ApiError>> = ({error, action}) => (
  <div className="error">
    <h3>Error {error?.code}</h3>
    <p>{error?.message}</p>
    {action && (
      <button onClick={action.handler}>
        {action.children || 'Retry'}
      </button>
    )}
  </div>
);

Infinite Queries with Complex Pagination

Handle complex pagination scenarios:

interface PaginationParams {
  cursor?: string;
  limit?: number;
  filters?: Record<string, unknown>;
}

interface PaginatedResponse<T> {
  data: T[];
  nextCursor?: string;
  hasMore: boolean;
}

const infiniteDataSource = makeInfiniteQueryDataSource({
  name: 'paginated-data',
  fetch: skipContext(async (params: PaginationParams) => {
    const response = await fetch(`/api/data?${new URLSearchParams(params)}`);
    return response.json() as PaginatedResponse<DataItem>;
  }),
  next: (lastPage) => {
    if (lastPage.hasMore && lastPage.nextCursor) {
      return {cursor: lastPage.nextCursor, limit: 20};
    }
    return undefined;
  },
});

Combining Multiple Data Sources

Combine data from multiple sources:

const UserProfile: React.FC<{userId: number}> = ({userId}) => {
  const user = useQueryData(userDataSource, {userId});
  const posts = useQueryData(userPostsDataSource, {userId});
  const followers = useQueryData(userFollowersDataSource, {userId});

  const combined = useQueryResponses([user, posts, followers]);

  return (
    <DataLoader
      status={combined.status}
      error={combined.error}
      errorAction={combined.refetchErrored} // Only retry failed requests
      LoadingView={ProfileSkeleton}
      ErrorView={ProfileError}
    >
      {user && posts && followers && (
        <div>
          <UserInfo user={user.data} />
          <UserPosts posts={posts.data} />
          <UserFollowers followers={followers.data} />
        </div>
      )}
    </DataLoader>
  );
};

TypeScript Support

The library is built with TypeScript-first approach and provides full type inference:

// Types are automatically inferred
const userDataSource = makePlainQueryDataSource({
  name: 'user',
  fetch: skipContext(async (params: {userId: number}): Promise<User> => {
    // Return type is inferred as User
  }),
});

// Hook return type is automatically typed
const {data} = useQueryData(userDataSource, {userId: 123});
// data is typed as User | undefined

Custom Error Types

Define and use custom error types:

interface ValidationError {
  field: string;
  message: string;
}

interface ApiError {
  type: 'network' | 'validation' | 'server';
  message: string;
  validation?: ValidationError[];
}

const typedDataSource = makePlainQueryDataSource<
  {id: number}, // Params type
  {id: number}, // Request type
  ApiResponse, // Response type
  User, // Data type
  ApiError // Error type
>({
  name: 'typed-user',
  fetch: skipContext(fetchUser),
});

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

MIT License. See LICENSE file for details.

版本与发布记录

@gravity-ui/data-source 共发布 39 个版本,首次发布于 2024/07/29;过去 12 个月发布了 21 个版本。

版本发布日期距今
0.10.0latest2026/07/094 个月前
0.10.0-alpha.14alpha2026/05/215 个月前
0.10.0-alpha.132026/05/215 个月前
0.10.0-alpha.122026/05/215 个月前
0.10.0-alpha.112026/05/186 个月前
0.10.0-alpha.102026/05/186 个月前

关于 @gravity-ui/data-source 的常见问题

@gravity-ui/data-source 是什么?

A wrapper around data fetching

如何安装 @gravity-ui/data-source?

在项目目录运行 npm install @gravity-ui/data-source,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@tanstack/react-query(^5.0.0)、react(^18.0.0 || ^19.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ui/data-source 支持 TypeScript 吗?

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

@gravity-ui/data-source 支持 ESM 还是 CommonJS?

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

@gravity-ui/data-source 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >= 24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gravity-ui/data-source 可以商用吗?

@gravity-ui/data-source 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ui/data-source 的下载量有多少?

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

@gravity-ui/data-source 还在维护吗?

最新版本 0.10.0 发布于 2026/07/09(4 个月前);至今共发布 39 个版本,其中过去 12 个月发布了 21 个;首次发布于 2024/07/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。