Skip to main content

​
Overview

QueryState provides TypeScript types and helper functions for managing async request state with QueryClient. It defines request statuses, state interfaces, and factory functions for creating state objects.

​
Import

import {
  RequestState,
  RequestStatus,
  RequestContext,
  createInitialState,
  createLoadingState,
  createSuccessState,
  createErrorState
} from "bytekit";
// or
import { RequestState } from "bytekit/query-state";

​
Types

​
RequestStatus

Request lifecycle status. 
type RequestStatus = "idle" | "loading" | "success" | "error";

​
RequestState

Complete state of a request.
​
RequestState<T>
object

​
RequestContext

Context information for a request. 
interface RequestContext {
  queryKey?: string[];
  url: string;
  method: string;
  timestamp: number;
  requestId: string;
}

​
RequestLifecycleCallbacks

Callbacks for request lifecycle events. 
interface RequestLifecycleCallbacks<T = unknown> {
  onStart?: (context: RequestContext) => void | Promise<void>;
  onSuccess?: (data: T, context: RequestContext) => void | Promise<void>;
  onError?: (error: ApiError, context: RequestContext) => void | Promise<void>;
  onSettled?: (
    data: T | undefined,
    error: ApiError | undefined,
    context: RequestContext
  ) => void | Promise<void>;
}

​
State Helpers

​
createInitialState

Create initial idle state. 
function createInitialState<T = unknown>(): RequestState<T>
Usage: 
import { createInitialState } from "bytekit";

const state = createInitialState<User>();
// {
//   status: "idle",
//   isLoading: false,
//   isSuccess: false,
//   isError: false,
//   isIdle: true,
//   isFetching: false,
//   dataUpdatedAt: 0,
//   errorUpdatedAt: 0
// }

​
createLoadingState

Create loading state. 
function createLoadingState<T = unknown>(previousData?: T): RequestState<T>
Usage: 
import { createLoadingState } from "bytekit";

const state = createLoadingState(previousData);
// {
//   status: "loading",
//   data: previousData,
//   isLoading: true,
//   isFetching: true,
//   ...
// }

​
createSuccessState

Create success state with data. 
function createSuccessState<T = unknown>(data: T): RequestState<T>
Usage: 
import { createSuccessState } from "bytekit";

const state = createSuccessState({ id: 1, name: "John" });
// {
//   status: "success",
//   data: { id: 1, name: "John" },
//   isSuccess: true,
//   dataUpdatedAt: Date.now(),
//   ...
// }

​
createErrorState

Create error state. 
function createErrorState<T = unknown>(
  error: ApiError,
  previousData?: T
): RequestState<T>
Usage: 
import { createErrorState } from "bytekit";

const state = createErrorState(error, previousData);
// {
//   status: "error",
//   error,
//   data: previousData,
//   isError: true,
//   errorUpdatedAt: Date.now(),
//   ...
// }

​
Usage with QueryClient

import { 
  QueryClient, 
  RequestState, 
  createInitialState,
  createLoadingState,
  createSuccessState,
  createErrorState 
} from "bytekit";

class MyQueryManager {
  private state: RequestState<User> = createInitialState();
  private queryClient = new QueryClient();

  async fetchUser(id: string) {
    // Set loading state
    this.state = createLoadingState(this.state.data);
    this.notifySubscribers();

    try {
      const data = await this.queryClient.query(
        ["user", id],
        () => api.get(`/users/${id}`)
      );

      // Set success state
      this.state = createSuccessState(data);
      this.notifySubscribers();
      return data;
    } catch (error) {
      // Set error state
      this.state = createErrorState(error as ApiError, this.state.data);
      this.notifySubscribers();
      throw error;
    }
  }

  private notifySubscribers() {
    // Notify UI of state change
  }
}

​
QueryClientEvents

Event types emitted by QueryClient. 
interface QueryClientEvents<T = unknown> {
  "query:start": { context: RequestContext };
  "query:success": { data: T; context: RequestContext };
  "query:error": { error: ApiError; context: RequestContext };
  "query:settled": {
    data?: T;
    error?: ApiError;
    context: RequestContext;
  };
  "state:change": { state: RequestState<T>; context: RequestContext };
  "cache:invalidate": { queryKey: string[] };
  "cache:update": { queryKey: string[]; data: T };
}

​
See Also