vue-query-params/README.md

Реактивная работа с query-параметрами (query params) во Vue 3

# vue-query-params
[![npm version](https://img.shields.io/npm/v/vue-query-params.svg)](https://www.npmjs.com/package/vue-query-params)
[![Downloads](https://img.shields.io/npm/dm/vue-query-params.svg)](https://www.npmjs.com/package/vue-query-params)

Удобная работа с query-параметрами во Vue 3 с типизацией и реактивностью. Ссылка на npm-пакет - https://www.npmjs.com/package/vue-query-params

## Описание

`vue-query-params` — это легкая библиотека для синхронизации query-параметров URL с реактивными данными во Vue 3. Позволяет легко читать, изменять, валидировать и сбрасывать параметры запроса, не теряя сторонние параметры и сохраняя типизацию.

## Возможности

- Реактивная синхронизация query-параметров с состоянием компонента
- Гибкая типизация параметров (string, number, boolean, array, object, date)
- Кастомная сериализация/десериализация
- Валидация и нормализация значений
- Debounce обновлений URL
- Сброс и очистка параметров
- Не затирает чужие параметры в URL
- Простое подключение как плагина

## Установка

```bash
npm install vue-query-params
```

или

```bash
yarn add vue-query-params
```

## Быстрый старт

```typescript
import { useQueryParams } from 'vue-query-params'

const config = {
  page: { type: 'number', default: 1 },
  search: { type: 'string', default: '' },
  tags: { type: 'array', default: [] }
}

const { params, update, reset, clear } = useQueryParams(config)
```

Теперь `params.value` всегда содержит актуальные значения из URL, а любые изменения автоматически обновляют адресную строку.

## Пример использования

```vue
<script setup lang="ts">
import { useQueryParams } from 'vue-query-params'

const config = {
  page: { type: 'number', default: 1 },
  search: { type: 'string', default: '' },
  tags: { type: 'array', default: [] }
}

const { params, update, reset, clear } = useQueryParams(config)
</script>

<template>
  <input v-model="params.search" placeholder="Поиск..." />
  <button @click="update({ page: params.page + 1 })">Следующая страница</button>
  <button @click="reset">Сбросить</button>
  <button @click="clear">Очистить параметры</button>
</template>
```

## useQueryParam

Если вам нужно работать только с одним query-параметром, используйте `useQueryParam`:

```typescript
import { useQueryParam } from 'vue-query-params'

const page = useQueryParam('page', { type: 'number', default: 1 })

// page.value — реактивное значение параметра "page"
```

**Параметры:**
- `key` — имя параметра в URL
- `config` — объект конфигурации (аналогичен одному элементу из useQueryParams)

**Возвращает:**  
Реактивное значение параметра (ref).

## Типизация

Конфиг строго типизирован:

```typescript
const config = {
  page: { type: 'number', default: 1, validate: v => v > 0 },
  filter: { type: 'string', default: '' }
} as const

const { params } = useQueryParams(config)
// params.value.page — number
// params.value.filter — string
```

## Опции

`useQueryParams(config, options)`

| Опция      | Описание                                  | По умолчанию |
|------------|-------------------------------------------|--------------|
| debounce   | Задержка обновления URL (мс)              | 0            |
| router     | Кастомный экземпляр vue-router            | auto         |
| route      | Кастомный route (например, для SSR)       | auto         |
| immediate  | Синхронизировать сразу при инициализации  | true         |
| deep       | Глубокий watch параметров                 | true         |

## API

- `params` — реактивный объект с параметрами
- `update(updates)` — обновить параметры
- `reset()` — сбросить к значениям по умолчанию
- `clear()` — удалить параметры из URL
- `destroy()` — остановить синхронизацию

## Конфиг параметра

```typescript
{
  type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date',
  default: any,
  serialize?: (value) => string,
  deserialize?: (value: string) => any,
  validate?: (value) => boolean,
  normalize?: (value) => any,
  required?: boolean
}
```

## Плагин

Можно подключить как плагин для глобальных настроек:

```typescript
import { createApp } from 'vue'
import { QueryParamsPlugin } from 'vue-query-params'

createApp(App)
  .use(QueryParamsPlugin, { defaults: { debounce: 200 } })
  .mount('#app')
```

## Лицензия

MIT