tessl/npm-refinedev--core

React meta-framework for building enterprise CRUD applications with authentication, data management, and headless UI integration

—

Pending

Overview

Eval results

Files

Data Operations & CRUD Hooks

Name: tessl/npm-refinedev--core
Author: tessl

Comprehensive data management hooks for CRUD operations, custom queries, and real-time data synchronization.

Capabilities

Query Hooks

useList Hook

Fetches multiple records from a resource with support for pagination, filtering, sorting, and real-time updates.

/**
 * Fetches multiple records from a resource with comprehensive query options
 * @param params - Configuration for the list query
 * @returns Query result with data and pagination information
 */
function useList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
  params?: UseListConfig<TQueryFnData, TError, TData>
): UseListReturnType<TData, TError>;

interface UseListConfig<TQueryFnData, TError, TData> {
  /** Resource name - inferred from route if not provided */
  resource?: string;
  /** Pagination configuration */
  pagination?: Pagination;
  /** Sorting configuration */
  sorters?: CrudSorting;
  /** Filtering configuration */
  filters?: CrudFilters;
  /** Additional metadata for the query */
  meta?: MetaQuery;
  /** Specific data provider to use */
  dataProviderName?: string;
  /** React Query options */
  queryOptions?: UseQueryOptions<GetListResponse<TQueryFnData>, TError>;
  /** Success notification configuration */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification configuration */
  errorNotification?: SuccessErrorNotification | false;
  /** Live mode configuration */
  liveMode?: LiveModeProps;
  /** Callback when live event received */
  onLiveEvent?: (event: LiveEvent) => void;
  /** Auto-invalidation configuration */
  invalidates?: Array<string>;
  /** Override mutation mode */
  mutationMode?: MutationMode;
}

interface UseListReturnType<TData, TError> {
  /** React Query result object */
  query: UseQueryResult<GetListResponse<TData>, TError>;
  /** Processed result with data and total */
  result: {
    data: TData[];
    total: number | undefined;
  };
}

Usage Example:

import { useList } from "@refinedev/core";

function PostsList() {
  const { data: posts, isLoading, error } = useList({
    resource: "posts",
    pagination: {
      current: 1,
      pageSize: 10,
      mode: "server"
    },
    sorters: [{
      field: "createdAt",
      order: "desc"
    }],
    filters: [{
      field: "status",
      operator: "eq",
      value: "published"
    }],
    meta: {
      populate: ["author", "category"]
    }
  });
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      {posts?.data.map(post => (
        <article key={post.id}>
          <h3>{post.title}</h3>
          <p>{post.content}</p>
        </article>
      ))}
    </div>
  );
}

useOne Hook

Fetches a single record by its identifier with support for real-time updates and caching.

/**
 * Fetches a single record by ID
 * @param params - Configuration for the single record query
 * @returns Query result with the fetched record
 */
function useOne<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
  params: UseOneConfig<TQueryFnData, TError, TData>
): UseOneReturnType<TData, TError>;

interface UseOneConfig<TQueryFnData, TError, TData> {
  /** Resource name - inferred from route if not provided */
  resource?: string;
  /** Record identifier to fetch */
  id: BaseKey;
  /** Additional metadata for the query */
  meta?: MetaQuery;
  /** Specific data provider to use */
  dataProviderName?: string;
  /** React Query options */
  queryOptions?: UseQueryOptions<GetOneResponse<TQueryFnData>, TError>;
  /** Success notification configuration */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification configuration */
  errorNotification?: SuccessErrorNotification | false;
  /** Live mode configuration */
  liveMode?: LiveModeProps;
  /** Callback when live event received */
  onLiveEvent?: (event: LiveEvent) => void;
}

interface UseOneReturnType<TData, TError> {
  /** React Query result object */
  query: UseQueryResult<GetOneResponse<TData>, TError>;
}

useMany Hook

Fetches multiple records by their identifiers in a single request.

/**
 * Fetches multiple records by their IDs
 * @param params - Configuration for the multiple records query
 * @returns Query result with the fetched records
 */
function useMany<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
  params: UseManyConfig<TQueryFnData, TError, TData>
): UseManyReturnType<TData, TError>;

interface UseManyConfig<TQueryFnData, TError, TData> {
  /** Resource name - inferred from route if not provided */
  resource?: string;
  /** Array of record identifiers to fetch */
  ids: BaseKey[];
  /** Additional metadata for the query */
  meta?: MetaQuery;
  /** Specific data provider to use */
  dataProviderName?: string;
  /** React Query options */
  queryOptions?: UseQueryOptions<GetManyResponse<TQueryFnData>, TError>;
  /** Success notification configuration */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification configuration */
  errorNotification?: SuccessErrorNotification | false;
  /** Live mode configuration */
  liveMode?: LiveModeProps;
  /** Callback when live event received */
  onLiveEvent?: (event: LiveEvent) => void;
}

interface UseManyReturnType<TData, TError> {
  /** React Query result object */
  query: UseQueryResult<GetManyResponse<TData>, TError>;
}

useInfiniteList Hook

Provides infinite scrolling functionality for large datasets with incremental loading.

/**
 * Provides infinite scrolling/pagination functionality
 * @param params - Configuration for infinite list query
 * @returns Infinite query result with pagination controls
 */
function useInfiniteList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
  params?: UseInfiniteListConfig<TQueryFnData, TError, TData>
): UseInfiniteListReturnType<TData, TError>;

interface UseInfiniteListConfig<TQueryFnData, TError, TData> {
  /** Resource name */
  resource?: string;
  /** Pagination configuration */
  pagination?: Pagination;
  /** Sorting configuration */
  sorters?: CrudSorting;
  /** Filtering configuration */
  filters?: CrudFilters;
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** React Query infinite options */
  queryOptions?: UseInfiniteQueryOptions<GetListResponse<TQueryFnData>, TError>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
}

interface UseInfiniteListReturnType<TData, TError> {
  /** React Query infinite result */
  query: UseInfiniteQueryResult<InfiniteData<GetListResponse<TData>>, TError>;
  /** Flattened data from all pages */
  data: TData[] | undefined;
  /** Total count across all pages */
  total: number | undefined;
  /** Whether more data can be fetched */
  hasNextPage: boolean | undefined;
  /** Function to fetch next page */
  fetchNextPage: () => void;
  /** Whether next page is being fetched */
  isFetchingNextPage: boolean;
}

Mutation Hooks

useCreate Hook

Creates new records with support for optimistic updates, notifications, and cache invalidation.

/**
 * Creates a new record with mutation handling
 * @param params - Configuration for the create mutation
 * @returns Mutation function and state
 */
function useCreate<TData = BaseRecord, TError = HttpError, TVariables = {}>(
  params?: UseCreateConfig<TData, TError, TVariables>
): UseCreateReturnType<TData, TError, TVariables>;

interface UseCreateConfig<TData, TError, TVariables> {
  /** React Query mutation options */
  mutationOptions?: UseMutationOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>;
}

interface UseCreateReturnType<TData, TError, TVariables> {
  /** Mutation function to execute create */
  mutate: (params: UseCreateParams<TVariables>, options?: MutationObserverOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>) => void;
  /** Async mutation function */
  mutateAsync: (params: UseCreateParams<TVariables>, options?: MutationObserverOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>) => Promise<CreateResponse<TData>>;
  /** React Query mutation result */
  mutation: UseMutationResult<CreateResponse<TData>, TError, UseCreateParams<TVariables>>;
}

interface UseCreateParams<TVariables> {
  /** Resource name */
  resource: string;
  /** Data to create */
  values: TVariables;
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Cache invalidation configuration */
  invalidates?: Array<string>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
  /** Override mutation mode */
  mutationMode?: MutationMode;
  /** Timeout for undoable mutations */
  undoableTimeout?: number;
}

Usage Example:

import { useCreate } from "@refinedev/core";

function CreatePostForm() {
  const { mutate: createPost, isLoading } = useCreate();
  
  const handleSubmit = (values: { title: string; content: string }) => {
    createPost({
      resource: "posts",
      values,
      successNotification: {
        message: "Post created successfully!",
        description: "Your new post has been published.",
        type: "success"
      },
      meta: {
        populate: ["author"]
      }
    });
  };
  
  return (
    <form onSubmit={handleSubmit}>
      {/* Form fields */}
      <button type="submit" disabled={isLoading}>
        {isLoading ? "Creating..." : "Create Post"}
      </button>
    </form>
  );
}

useUpdate Hook

Updates existing records with optimistic updates and undoable operations.

/**
 * Updates an existing record with mutation handling
 * @param params - Configuration for the update mutation
 * @returns Mutation function and state
 */
function useUpdate<TData = BaseRecord, TError = HttpError, TVariables = {}>(
  params?: UseUpdateConfig<TData, TError, TVariables>
): UseUpdateReturnType<TData, TError, TVariables>;

interface UseUpdateConfig<TData, TError, TVariables> {
  /** React Query mutation options */
  mutationOptions?: UseMutationOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>;
}

interface UseUpdateReturnType<TData, TError, TVariables> {
  /** Mutation function to execute update */
  mutate: (params: UseUpdateParams<TVariables>, options?: MutationObserverOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>) => void;
  /** Async mutation function */
  mutateAsync: (params: UseUpdateParams<TVariables>, options?: MutationObserverOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>) => Promise<UpdateResponse<TData>>;
  /** React Query mutation result */
  mutation: UseMutationResult<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>;
}

interface UseUpdateParams<TVariables> {
  /** Resource name */
  resource: string;
  /** Record identifier to update */
  id: BaseKey;
  /** Data to update */
  values: TVariables;
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Cache invalidation configuration */
  invalidates?: Array<string>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
  /** Override mutation mode */
  mutationMode?: MutationMode;
  /** Timeout for undoable mutations */
  undoableTimeout?: number;
}

useDelete Hook

Deletes records with support for soft delete, confirmations, and undo functionality.

/**
 * Deletes a record with mutation handling
 * @param params - Configuration for the delete mutation
 * @returns Mutation function and state
 */
function useDelete<TData = BaseRecord, TError = HttpError>(
  params?: UseDeleteConfig<TData, TError>
): UseDeleteReturnType<TData, TError>;

interface UseDeleteConfig<TData, TError> {
  /** React Query mutation options */
  mutationOptions?: UseMutationOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>;
}

interface UseDeleteReturnType<TData, TError> {
  /** Mutation function to execute delete */
  mutate: (params: UseDeleteParams, options?: MutationObserverOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>) => void;
  /** Async mutation function */
  mutateAsync: (params: UseDeleteParams, options?: MutationObserverOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>) => Promise<DeleteOneResponse<TData>>;
  /** React Query mutation result */
  mutation: UseMutationResult<DeleteOneResponse<TData>, TError, UseDeleteParams>;
}

interface UseDeleteParams {
  /** Resource name */
  resource: string;
  /** Record identifier to delete */
  id: BaseKey;
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Cache invalidation configuration */
  invalidates?: Array<string>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
  /** Override mutation mode */
  mutationMode?: MutationMode;
  /** Timeout for undoable mutations */
  undoableTimeout?: number;
}

Bulk Operations

useCreateMany Hook

Creates multiple records in a single operation for batch processing.

/**
 * Creates multiple records in batch
 * @param params - Configuration for the bulk create mutation
 * @returns Mutation function and state for bulk creation
 */
function useCreateMany<TData = BaseRecord, TError = HttpError, TVariables = {}>(
  params?: UseCreateManyConfig<TData, TError, TVariables>
): UseCreateManyReturnType<TData, TError, TVariables>;

interface UseCreateManyParams<TVariables> {
  /** Resource name */
  resource: string;
  /** Array of data to create */
  values: TVariables[];
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Cache invalidation configuration */
  invalidates?: Array<string>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
}

useUpdateMany Hook

Updates multiple records by their identifiers in a single operation.

/**
 * Updates multiple records in batch
 * @param params - Configuration for the bulk update mutation
 * @returns Mutation function and state for bulk updates
 */
function useUpdateMany<TData = BaseRecord, TError = HttpError, TVariables = {}>(
  params?: UseUpdateManyConfig<TData, TError, TVariables>
): UseUpdateManyReturnType<TData, TError, TVariables>;

interface UseUpdateManyParams<TVariables> {
  /** Resource name */
  resource: string;
  /** Array of record identifiers to update */
  ids: BaseKey[];
  /** Data to update */
  values: TVariables;
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Cache invalidation configuration */
  invalidates?: Array<string>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
}

useDeleteMany Hook

Deletes multiple records by their identifiers in a single operation.

/**
 * Deletes multiple records in batch
 * @param params - Configuration for the bulk delete mutation
 * @returns Mutation function and state for bulk deletion
 */
function useDeleteMany<TData = BaseRecord, TError = HttpError>(
  params?: UseDeleteManyConfig<TData, TError>
): UseDeleteManyReturnType<TData, TError>;

interface UseDeleteManyParams {
  /** Resource name */
  resource: string;
  /** Array of record identifiers to delete */
  ids: BaseKey[];
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Cache invalidation configuration */
  invalidates?: Array<string>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
}

Custom Data Operations

useCustom Hook

Executes custom API queries that don't fit standard CRUD patterns.

/**
 * Executes custom API queries
 * @param params - Configuration for custom query
 * @returns Query result with custom data
 */
function useCustom<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(
  params: UseCustomConfig<TQueryFnData, TError, TData>
): UseCustomReturnType<TData, TError>;

interface UseCustomConfig<TQueryFnData, TError, TData> {
  /** Custom URL endpoint */
  url: string;
  /** HTTP method */
  method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
  /** Additional configuration */
  config?: {
    /** Request headers */
    headers?: Record<string, string>;
    /** URL query parameters */
    query?: Record<string, any>;
    /** Request payload */
    payload?: Record<string, any>;
    /** Request filters */
    filters?: CrudFilters;
    /** Request sorters */
    sorters?: CrudSorting;
    /** Pagination */
    pagination?: Pagination;
  };
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** React Query options */
  queryOptions?: UseQueryOptions<CustomResponse<TQueryFnData>, TError>;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
}

interface UseCustomReturnType<TData, TError> {
  /** React Query result */
  query: UseQueryResult<CustomResponse<TData>, TError>;
}

interface CustomResponse<TData> {
  data: TData;
}

useCustomMutation Hook

Executes custom API mutations for non-standard operations.

/**
 * Executes custom API mutations
 * @param params - Configuration for custom mutation
 * @returns Mutation function and state
 */
function useCustomMutation<TData = BaseRecord, TError = HttpError, TVariables = {}>(
  params?: UseCustomMutationConfig<TData, TError, TVariables>
): UseCustomMutationReturnType<TData, TError, TVariables>;

interface UseCustomMutationConfig<TData, TError, TVariables> {
  /** React Query mutation options */
  mutationOptions?: UseMutationOptions<CustomResponse<TData>, TError, UseCustomMutationParams<TVariables>>;
}

interface UseCustomMutationParams<TVariables> {
  /** Custom URL endpoint */
  url: string;
  /** HTTP method */
  method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
  /** Request configuration */
  config?: {
    /** Request headers */
    headers?: Record<string, string>;
    /** Request payload */
    payload?: TVariables;
  };
  /** Additional metadata */
  meta?: MetaQuery;
  /** Data provider name */
  dataProviderName?: string;
  /** Success notification */
  successNotification?: SuccessErrorNotification | false;
  /** Error notification */
  errorNotification?: SuccessErrorNotification | false;
}

Data Provider Utilities

useDataProvider Hook

Provides direct access to the data provider instance for advanced operations.

/**
 * Gets access to the data provider instance
 * @returns Data provider instance or provider map
 */
function useDataProvider(): DataProviderResult;

type DataProviderResult = DataProvider | Record<string, DataProvider>;

useApiUrl Hook

Generates the base API URL for a specific resource using the data provider.

/**
 * Gets the API URL for a resource
 * @param params - Configuration for API URL generation
 * @returns Query result with the API URL
 */
function useApiUrl(params?: UseApiUrlConfig): UseApiUrlReturnType;

interface UseApiUrlConfig {
  /** Data provider name */
  dataProviderName?: string;
}

interface UseApiUrlReturnType {
  /** Query result with API URL */
  query: UseQueryResult<string, Error>;
}

Types

interface MetaQuery {
  [key: string]: any;
}

interface SuccessErrorNotification {
  message: string;
  description?: string;
  type: "success" | "error" | "progress";
}

interface LiveEvent {
  channel: string;
  type: "created" | "updated" | "deleted";
  payload: {
    ids?: BaseKey[];
    [key: string]: any;
  };
  date: Date;
}

interface GetListParams {
  resource: string;
  pagination?: Pagination;
  sorters?: CrudSorting;
  filters?: CrudFilters;
  meta?: MetaQuery;
}

interface GetOneParams {
  resource: string;
  id: BaseKey;
  meta?: MetaQuery;
}

interface GetManyParams {
  resource: string;
  ids: BaseKey[];
  meta?: MetaQuery;
}

interface CreateParams<TVariables> {
  resource: string;
  variables: TVariables;
  meta?: MetaQuery;
}

interface UpdateParams<TVariables> {
  resource: string;
  id: BaseKey;
  variables: TVariables;
  meta?: MetaQuery;
}

interface DeleteOneParams {
  resource: string;
  id: BaseKey;
  meta?: MetaQuery;
}

interface CustomParams {
  url: string;
  method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";
  filters?: CrudFilters;
  sorters?: CrudSorting;
  pagination?: Pagination;
  payload?: Record<string, any>;
  query?: Record<string, any>;
  headers?: Record<string, string>;
  meta?: MetaQuery;
}

Install with Tessl CLI