gen-query

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]

A powerful Nuxt module for type-safe API queries using TanStack Query (Vue Query) with full TypeScript support and automatic cache management.

- ✨ Release Notes
- 📖 Backend API Specification

Features

- 🔥 Type-safe - Full TypeScript support with generics
- 🚀 TanStack Query - Built on TanStack Query for powerful data fetching and caching
- 🎯 Composables-first - Easy-to-use Vue composables for all operations
- 📄 Pagination - Built-in infinite scroll and pagination support
- 🔄 Smart Caching - Automatic cache invalidation with configurable update strategies
- 🔐 Authentication - Optional token-based authentication
- 🎨 Flexible Filtering - Advanced filtering with multiple match modes
- 📦 Lightweight - Minimal dependencies

Quick Setup

Install the module:

``bash
npx nuxi module add gen-query
`

Configuration

Configure in nuxt.config.ts:

`typescript
export default defineNuxtConfig({
modules: ['gen-query'],

genQuery: {
baseURL: 'https://api.example.com', // API base URL
cachedPages: 4, // Max cached pages for infinite queries
update: UpdateStrategy.Invalidate, // Cache update strategy
},
})
`

$3

| Option | Type | Default | Description |
| ------------- | ---------------- | ------------ | ------------------------------------------------------------------------------------------ |
| baseURL | string | '' | Base URL for all API requests. Can also be set via NUXT_PUBLIC_API_BASE_URL env variable |
| cachedPages | number | 4 | Maximum number of pages to cache in infinite queries |
| update | UpdateStrategy | Invalidate | Strategy for updating cache after mutations |

$3

The module supports three cache update strategies:

- UpdateStrategy.None - No automatic cache updates. You manage cache manually.
- UpdateStrategy.Invalidate - Invalidates and refetches affected queries after mutations (recommended).
- UpdateStrategy.Optimistic - Immediately updates cache optimistically before server confirms.

`typescript
import { UpdateStrategy } from 'gen-query'

export default defineNuxtConfig({
genQuery: {
update: UpdateStrategy.Optimistic, // Use optimistic updates
},
})
`

Quick Start

`vue



`

Core Concepts

$3

gen-query provides four main composables:

1. useLoginService - Handle user authentication
2. useSingleQuery - CRUD operations for a single entity by ID
3. useMultipleQuery - CRUD operations for collections
4. usePaginatedQuery - Paginated data with filtering and sorting

All composables return TanStack Query objects with reactive properties for data, loading states, errors, and mutation functions.

$3

- Queries (read, list, page) - Fetch data with automatic caching and background refetching
- Mutations (create, update, del) - Modify data with automatic cache updates based on your strategy

Usage Guide

$3

Use useLoginService for user authentication:

`vue



`

$3

Use useSingleQuery to work with a single entity by ID:

`vue



`

$3

Use useMultipleQuery for CRUD operations on collections:

`vue



`

$3

Use usePaginatedQuery for paginated data with advanced filtering and sorting:

`vue



`

$3

For infinite scroll, use all loaded pages:

`vue



`

API Reference

$3

#### useLoginService(resource?: string)

Creates a login service for authentication.

Parameters:

- resource (optional): API endpoint for login. Default: 'auth'

Returns:

`typescript
{
login: {
mutate: (credentials: Login, options?) => void
isPending: Ref
isError: Ref
isSuccess: Ref
error: Ref
data: Ref
}
}
`

---

#### useSingleQuery(resource: string, id: Ref, token?: MaybeRefOrGetter)

Fetches and manages a single entity by ID.

Type Parameters:

- T: Entity type extending Entity
- K: ID type (e.g., number, string)

Parameters:

- resource: API endpoint (e.g., 'products')
- id: Reactive reference to entity ID
- token (optional): Authentication token (reactive or getter)

Returns:

`typescript
{
read: {
data: Ref
error: Ref
isLoading: Ref
isError: Ref
isSuccess: Ref
isFetching: Ref
status: Ref<'loading' | 'error' | 'success'>
refetch: () => Promise
},
create: {
mutate: (entity: T, options?) => void
isPending: Ref
isError: Ref
isSuccess: Ref
error: Ref
},
update: { / same as create / },
del: { / same as create / }
}
`

---

#### useMultipleQuery(resource: string, token?: MaybeRefOrGetter)

Provides CRUD operations for a collection of entities.

Type Parameters:

- T: Entity type extending Entity
- K: ID type

Parameters:

- resource: API endpoint
- token (optional): Authentication token

Returns:

`typescript
{
read: {
data: Ref
error: Ref
isLoading: Ref
isError: Ref
isSuccess: Ref
isFetching: Ref
refetch: () => Promise
},
create: { / mutation object / },
update: { / mutation object / },
del: { / mutation object / }
}
`

---

#### usePaginatedQuery(resource: string, pageable: Pageable, filters: Ref, token?: MaybeRefOrGetter)

Fetches paginated entities with filtering and sorting.

Type Parameters:

- T: Entity type extending Entity
- K: ID type

Parameters:

- resource: API endpoint
- pageable: Pagination configuration
- filters: Reactive filters
- token (optional): Authentication token

Returns:

`typescript
{
read: {
data: Ref> | undefined>
error: Ref
isLoading: Ref
isError: Ref
isSuccess: Ref
isFetching: Ref
isFetchingNextPage: Ref
isFetchingPreviousPage: Ref
hasNextPage: Ref
hasPreviousPage: Ref
fetchNextPage: () => Promise
fetchPreviousPage: () => Promise
refetch: () => Promise
},
create: { / mutation object / },
update: { / mutation object / },
del: { / mutation object / }
}
`

---

$3

#### Entity

Base interface for entities with an ID.

`typescript
interface Entity {
id: K
}
`

Example:

`typescript
interface Product extends Entity {
name: string
price: number
}
`

---

#### Login

Login credentials.

`typescript
type Login = {
username: string
password: string
}
`

---

#### User

User information returned after login.

`typescript
type User = {
username: string
password: string
fullName: string
email: string
token: string
}
`

---

#### Page

Paginated response structure.

`typescript
type Page = {
page: {
number: number // Current page (0-indexed)
size: number // Items per page
totalElements: number // Total items across all pages
totalPages: number // Total number of pages
}
content: T[] // Items in current page
}
`

---

#### Sort

Sorting configuration.

`typescript
type Sort = {
property: string // Field to sort by
direction: 'asc' | 'desc' // Sort direction
}
`

---

#### FilterItem

Filter configuration.

`typescript
type FilterItem = {
operator: string // 'and' or 'or'
constraints: Constraint[]
}
`

---

#### Constraint

Filter constraint.

`typescript
type Constraint = {
matchMode: string // eq, ne, lt, lte, gt, gte, contains, startsWith, endsWith, in
value: unknown // Filter value
}
`

---

$3

#### Pageable

Pagination configuration class.

`typescript
class Pageable {
constructor(page: number = 0, size: number = 30, sort: Sort[] = [])

toQueryParams(): string
}
`

Example:

`typescript
const pageable = new Pageable(
0, // first page
20, // 20 items per page
[
{ property: 'name', direction: 'asc' },
{ property: 'price', direction: 'desc' },
]
)
`

---

#### Filters

Filter configuration class.

`typescript
class Filters {
[key: string]: FilterItem

toQueryParams(): string
}
`

Example:

`typescript
const filters = new Filters()

// Single constraint
filters.category = {
operator: 'and',
constraints: [{ matchMode: 'eq', value: 'electronics' }],
}

// Multiple constraints (AND)
filters.price = {
operator: 'and',
constraints: [
{ matchMode: 'gte', value: 100 },
{ matchMode: 'lte', value: 500 },
],
}

// Multiple constraints (OR)
filters.status = {
operator: 'or',
constraints: [
{ matchMode: 'eq', value: 'active' },
{ matchMode: 'eq', value: 'pending' },
],
}

// String matching
filters.name = {
operator: 'and',
constraints: [{ matchMode: 'contains', value: 'laptop' }],
}

// Date filtering
filters.createdAt = {
operator: 'and',
constraints: [{ matchMode: 'gte', value: new Date('2024-01-01') }],
}
`

Available Match Modes:

| Match Mode | Description | Example |
| ------------ | --------------------- | ---------------------------------------------- |
| eq | Equals | { matchMode: 'eq', value: 'active' } |
| ne | Not equals | { matchMode: 'ne', value: 'deleted' } |
| lt | Less than | { matchMode: 'lt', value: 100 } |
| lte | Less than or equal | { matchMode: 'lte', value: 100 } |
| gt | Greater than | { matchMode: 'gt', value: 50 } |
| gte | Greater than or equal | { matchMode: 'gte', value: 50 } |
| contains | Contains substring | { matchMode: 'contains', value: 'laptop' } |
| startsWith | Starts with | { matchMode: 'startsWith', value: 'Pro' } |
| endsWith | Ends with | { matchMode: 'endsWith', value: 'Pro' } |
| in | In list | { matchMode: 'in', value: 'active,pending' } |

---

#### ApiError

Custom error class for API errors.

`typescript
class ApiError extends Error {
timestamp: Date
type: string
statusCode: number
status: string
content?: object
stack?: string
}
`

Example:

`typescript
const { error } = productQuery.read

if (error.value) {
console.error('Error:', error.value.message)
console.error('Status:', error.value.statusCode)
console.error('Details:', error.value.content)
}
`

---

$3

#### UpdateStrategy

Cache update strategy for mutations.

`typescript
enum UpdateStrategy {
None, // No automatic cache updates
Invalidate, // Invalidate and refetch (recommended)
Optimistic, // Optimistic updates
}
`

Usage:

`typescript
import { UpdateStrategy } from 'gen-query'

export default defineNuxtConfig({
genQuery: {
update: UpdateStrategy.Optimistic,
},
})
`

Backend Requirements

Your backend API must follow the REST specification detailed in BACKEND_API.md.

Key requirements:

- RESTful endpoints with JSON request/response
- Standard CRUD operations (GET, POST, PUT, DELETE)
- Pagination endpoint with /page suffix
- Support for filter and sort query parameters
- Consistent error response format
- ISO 8601 date format
- Optional Bearer token authentication

Development

`bash


Install dependencies

npm install

Generate type stubs

npm run dev:prepare

Develop with playground

npm run dev

Build playground

npm run dev:build

Run ESLint

npm run lint

Run type checking

npm run test:types

Run tests

npm run test
npm run test:watch

Release new version

npm run release
``

License

MIT License - see LICENSE for details

Links

- NPM Package
- GitHub Repository
- TanStack Query Documentation

[npm-version-src]: https://img.shields.io/npm/v/gen-query/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/gen-query
[npm-downloads-src]: https://img.shields.io/npm/dm/gen-query.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npm.chart.dev/gen-query
[license-src]: https://img.shields.io/npm/l/gen-query.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: https://npmjs.com/package/gen-query
[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com