Types

Shared contracts are available from @querry-kit/nuxt/types and re-exported by @querry-kit/nuxt.

Resource API

EndpointDefinition

interface EndpointDefinition<TItem = unknown, TCreate = Partial<TItem>, TUpdate = Partial<TItem>> {
  item: TItem;
  create: TCreate;
  update: TUpdate;
}

Associates one endpoint with its returned resource and mutation payloads. useModuleApi infers its method arguments and response data from this contract.

type BookEndpoint = EndpointDefinition<Book, CreateBook, UpdateBook>;

EndpointMap

type EndpointMap = Record<string, EndpointDefinition>;

Maps endpoint names to contracts and is the first generic of useModuleApi.

type Endpoints = {
  books: EndpointDefinition<Book, CreateBook, UpdateBook>;
  authors: EndpointDefinition<Author>;
};

PaginatedResponse

interface PaginatedResponse<T> {
  items: T[];
  meta: PaginationMeta;
}

The required response shape for a Query Kit list endpoint. Both useTable and useAutocomplete read items; the table also reads the pagination metadata.

PaginationMeta

interface PaginationMeta {
  itemCount: number;
  pageCount: number;
  [key: string]: unknown;
}

Extra backend-specific keys are permitted, but itemCount and pageCount are required by useTable.

QueryParameters

type QueryParameters = Record<string, unknown>;

The open query-payload contract used by API methods and autocomplete. Values are serialized in Query Kit's bracket notation by serializeQuery.

const query: QueryParameters = {
  page: 1,
  perPage: 25,
  where: { status: 'active' },
};

Table state

FilterFieldDefinition

type FilterFieldDefinition<TType extends string = string, TMeta extends object = object> = TMeta & {
  value: string;
  label: string;
  type: TType;
};

A renderer-neutral description of a selectable filtering field. Use TMeta for application-specific details such as an options source or a custom control; the package does not depend on a UI library.

FilteringFieldOperator

type FilteringFieldOperator = 'in' | 'notIn' | 'equals' | 'not' | 'lt' | 'lte' | 'gt' | 'gte';

The operators supported by Query Kit's where convention. Consumers may use a narrower subset for a particular field editor.

FilteringField

interface FilteringField<TType extends string = string, TOperator extends string = string, TValue = unknown> {
  id: string;
  field: string;
  type?: TType;
  operator?: TOperator;
  value?: TValue;
}

Describes one UI filter before it is converted to a Query Kit where payload. field supports dotted paths such as author.name; operator becomes the nested Query Kit operator when supplied.

FilteringState

interface FilteringState<TField extends FilteringField = FilteringField> {
  operator: FilteringMode;
  filters: TField[];
}

The table's complete UI filtering state. filteringToWhere ignores filters without a value and combines the remaining conditions using operator.

FilteringMode

type FilteringMode = 'AND' | 'OR';

The boolean operator used to combine the filtering state entries.

RoutePageRef

type RoutePageRef = Ref<number | string | null | undefined>;

A consumer-owned reactive page value. Pass it to UseTableOptions.routePage to synchronize table pagination without coupling the package to Vue Router.

const routePage = computed({
  get: () => route.query.page,
  set: (page) => router.replace({ query: { ...route.query, page } }),
});

SortingRule

interface SortingRule {
  id: string;
  desc: boolean;
}

A TanStack-compatible sorting entry. The id may be a dotted field path; desc: true becomes desc, otherwise sortingToOrderBy emits asc.

SortingField

type SortingField<TMeta extends object = object> = TMeta & {
  value: string;
  label: string;
};

A renderer-neutral description of a selectable sorting field. Add UI-specific metadata with TMeta.

StorageLike

interface StorageLike {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
}

The minimal persistence adapter accepted by UseTableOptions.storage. It is compatible with localStorage, but lets SSR or embedded applications provide a safer implementation.

TableColumnInput

type TableColumnInput<TItem, TMeta extends object = Record<string, unknown>> = TMeta & {
  id?: string;
  fields?: string[];
};

A renderer-agnostic input column for useTable. Supply application-specific metadata through TMeta; the package keeps it intact without depending on a UI library. Omit id to exclude a conditional column from table selection and persistence.

type AppColumn = TableColumnInput<Book, { label: string; sortable?: boolean }>;

TableColumn

type TableColumn<TItem, TMeta extends object = Record<string, unknown>> = TableColumnInput<TItem, TMeta> & {
  id: string;
};

A visible table column with a resolved identifier. fields lists nested properties required for rendering; useTable turns them into the Query Kit fields grammar.

const columns: Ref<readonly TableColumn<Book, { label: string }>[]> = ref([
  { id: 'title', label: 'Title' },
  { id: 'author', fields: ['name'], label: 'Author' },
]);