### Install vue-qs using npm, pnpm, or bun

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/getting-started.md

These commands show how to install the `vue-qs` library using different package managers. Ensure you have the peer dependency `vue@^3.3` installed. `vue-router@^4.2` is optional for router integration.

```bash
npm i vue-qs
# or
pnpm add vue-qs
# or
bun add vue-qs
```

--------------------------------

### Manage multiple URL query parameters with queryReactive in Vue

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/getting-started.md

This example showcases the `queryReactive` composable for managing multiple URL query parameters as a reactive object. It allows defining default values, custom parsing, and serialization functions for each parameter.

```vue
<script setup lang="ts">
import { queryReactive } from 'vue-qs';

const queryState = queryReactive({
  search: { defaultValue: '' },
  page: {
    defaultValue: 1,
    parse: (value) => (value ? Number(value) : 1),
    serializeFunction: (value) => String(value),
  },
});
</script>

<template>
  <input v-model="queryState.search" />
  <button @click="queryState.page++">Next</button>
</template>
```

--------------------------------

### Vue-QS: Development Setup Bash Commands

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Provides essential bash commands for setting up the development environment for vue-qs. This includes cloning the repository, installing dependencies, and running development tasks.

```bash
# Clone and install
git clone https://github.com/iamsomraj/vue-qs.git
cd vue-qs
bun install

# Development
bun run dev          # Watch mode
bun run test         # Run tests
bun run typecheck    # Type checking
bun run lint         # Linting
bun run docs:dev     # Documentation dev server
```

--------------------------------

### Create History API and Vue Router adapters for vue-qs

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/getting-started.md

This code illustrates how to create adapters for `vue-qs`. `createHistoryAdapter` uses the browser's History API, while `createVueRouterAdapter` integrates with Vue Router. Both return a `QueryAdapter` object.

```typescript
import { createHistoryAdapter, createVueRouterAdapter } from 'vue-qs';

// All adapters return QueryAdapter directly - no destructuring needed
const historyAdapter = createHistoryAdapter(); // Browser History API (default)
const routerAdapter = createVueRouterAdapter(router); // Vue Router integration
```

--------------------------------

### Configure vue-qs plugin with Vue Router adapter in Vue application

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/getting-started.md

This example shows how to set up the `vue-qs` plugin within a Vue application, specifically integrating it with Vue Router. By passing the `createVueRouterAdapter` to the plugin, navigation events and URL changes are kept in sync.

```typescript
import { createVueQsPlugin, createVueRouterAdapter } from 'vue-qs';
import { router } from './router';

app.use(createVueQsPlugin({ queryAdapter: createVueRouterAdapter(router) }));
```

--------------------------------

### Manage a single URL query parameter with queryRef in Vue

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/getting-started.md

This example demonstrates using the `queryRef` composable from `vue-qs` to bind a single URL query parameter (e.g., `?name=...`) to a Vue ref. It supports a default value if the parameter is missing from the URL.

```vue
<script setup lang="ts">
import { queryRef } from 'vue-qs';

// A ref bound to ?name=... (falls back to default when missing)
const name = queryRef('name', { defaultValue: '' });
</script>

<template>
  <input v-model="name" placeholder="Your name" />
</template>
```

--------------------------------

### Install vue-qs using npm, pnpm, or bun

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/zh/guide/getting-started.md

This snippet shows how to install the vue-qs library using different package managers like npm, pnpm, and bun. It lists the commands for each.

```bash
npm i vue-qs
# 或者
pnpm add vue-qs
# 或者
bun add vue-qs
```

--------------------------------

### Install vue-qs using npm, pnpm, or bun

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Installs the vue-qs package and its peer dependencies. vue-qs requires Vue 3.3.0+ and optionally uses Vue Router 4.2.0+.

```bash
npm install vue-qs
# or
pnpm add vue-qs
# or
bun add vue-qs
```

--------------------------------

### Vue Component with queryRef and queryReactive State Management

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/examples.md

A Vue.js 3 component demonstrating the use of `vue-qs` library to manage URL query parameters. It utilizes `queryRef` for individual reactive query parameters and `queryReactive` for grouping multiple reactive query parameters. This setup synchronizes component state with the URL, allowing for bookmarkable and shareable filter states. Dependencies include Vue.js and `vue-qs`.

```vue
<script setup lang="ts">
import { computed } from 'vue';
import { serializers, queryRef, queryReactive } from 'vue-qs';

// Individual queryRef for category selection
const category = queryRef<'books' | 'music' | 'games'>('category', {
  defaultValue: 'books',
  codec: serializers.createEnumCodec(['books', 'music', 'games'] as const),
});

// queryReactive for grouped filter state
const filters = queryReactive({
  search: { defaultValue: '' },
  page: { defaultValue: 1, codec: serializers.numberCodec },
  minPrice: { defaultValue: 0, codec: serializers.numberCodec },
  maxPrice: { defaultValue: 1000, codec: serializers.numberCodec },
  inStock: { defaultValue: false, codec: serializers.booleanCodec },
});

// Computed property that combines both states
const searchSummary = computed(() => ({
  category: category.value,
  totalFilters: Object.values(filters).filter(Boolean).length,
  ...filters,
}));

// Method to reset all filters at once
const resetFilters = () => {
  filters.search = '';
  filters.page = 1;
  filters.minPrice = 0;
  filters.maxPrice = 1000;
  filters.inStock = false;
};

// Method to apply quick filters
const applyQuickFilter = (type: 'cheap' | 'expensive' | 'available') => {
  switch (type) {
    case 'cheap':
      filters.minPrice = 0;
      filters.maxPrice = 50;
      filters.inStock = true;
      break;
    case 'expensive':
      filters.minPrice = 500;
      filters.maxPrice = 1000;
      break;
    case 'available':
      filters.inStock = true;
      filters.page = 1;
      break;
  }
};
</script>

<template>
  <div class="search-container">
    <h2>Product Search</h2>

    <!-- Category selection using queryRef -->
    <div class="section">
      <h3>Category (queryRef)</h3>
      <div class="category-buttons">
        <button
          v-for="cat in ['books', 'music', 'games']"
          :key="cat"
          :class="{ active: category === cat }"
          @click="category = cat"
        >
          {{ cat.charAt(0).toUpperCase() + cat.slice(1) }}
        </button>
      </div>
    </div>

    <!-- Filters using queryReactive -->
    <div class="section">
      <h3>Filters (queryReactive)</h3>

      <div class="field">
        <label>Search:</label>
        <input v-model="filters.search" placeholder="Search products..." />
      </div>

      <div class="field">
        <label>Page:</label>
        <input v-model="filters.page" type="number" min="1" />
      </div>

      <div class="field-group">
        <div class="field">
          <label>Min Price:</label>
          <input v-model="filters.minPrice" type="number" min="0" />
        </div>

        <div class="field">
          <label>Max Price:</label>
          <input v-model="filters.maxPrice" type="number" min="0" />
        </div>
      </div>

      <div class="field">
        <label>
          <input v-model="filters.inStock" type="checkbox" />
          In Stock Only
        </label>
      </div>
    </div>

    <!-- Quick actions -->
    <div class="section">
      <h3>Quick Filters</h3>
      <div class="quick-buttons">
        <button @click="applyQuickFilter('cheap')">Cheap Items</button>
        <button @click="applyQuickFilter('expensive')">Expensive Items</button>
        <button @click="applyQuickFilter('available')">Available Items</button>
        <button @click="resetFilters()" class="reset">Reset All</button>
      </div>
    </div>

    <!-- State display -->
    <div class="output">
      <h3>Current Search State:</h3>
      <pre>{{ JSON.stringify(searchSummary, null, 2) }}</pre>
    </div>
  </div>
</template>

```

--------------------------------

### createVueQsPlugin: Global Vue-QS Plugin Setup

Source: https://context7.com/iamsomraj/vue-qs/llms.txt

This function creates a Vue plugin that globally provides the specified query adapter to all components within the Vue application. It simplifies integration, especially when using adapters like `createVueRouterAdapter`. Requires `vue-qs` and `vue-router` for the example.

```typescript
import { createApp } from 'vue';
import { createRouter } from 'vue-router';
import { createVueQsPlugin, createVueRouterAdapter } from 'vue-qs';
import App from './App.vue';

const app = createApp(App);
const router = createRouter({ /* ... */ });

// Setup plugin with Vue Router
const vueQsPlugin = createVueQsPlugin({
  queryAdapter: createVueRouterAdapter(router)
});

app.use(vueQsPlugin);
app.use(router);
app.mount('#app');

// All components now have access to the adapter
// No need to pass queryAdapter in component options
```

--------------------------------

### Global vue-qs Installation with Vue Router

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/zh/guide/vue-router.md

This snippet demonstrates the recommended global installation of vue-qs by passing the Vue Router instance to `createVueQsPlugin` and configuring the adapter. This ensures query parameters are automatically synchronized with the router.

```typescript
import { createApp } from 'vue';
import { createVueQsPlugin, createVueRouterAdapter } from 'vue-qs';
import { createRouter, createWebHistory } from 'vue-router';
import App from './App.vue';

const router = createRouter({
  history: createWebHistory(),
  routes: [],
});

createApp(App)
  .use(router)
  .use(createVueQsPlugin({ queryAdapter: createVueRouterAdapter(router) }))
  .mount('#app');
```

--------------------------------

### Vue Router Integration: Global plugin setup

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Configures vue-qs as a global plugin using `createVueQsPlugin` and integrates it with Vue Router via `createVueRouterAdapter`. This is the recommended approach for seamless router integration across the application.

```typescript
// main.ts
import { createApp } from 'vue';
import { createVueQsPlugin, createVueRouterAdapter } from 'vue-qs';
import { router } from './router';
import App from './App.vue';

const app = createApp(App);

app.use(
  createVueQsPlugin({
    queryAdapter: createVueRouterAdapter(router),
  })
);
app.use(router);
app.mount('#app');
```

--------------------------------

### QueryAdapter Interface Implementation Example - TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/QueryAdapter.md

This code demonstrates how to implement the QueryAdapter interface. It provides functions for getting current query parameters, updating them in the URL, and checking if an update is in progress. This interface is crucial for integrating vue-qs with different routing strategies.

```TypeScript
const adapter: QueryAdapter = {
  getCurrentQuery: () => ({ page: '1', search: 'test' }),
  updateQuery: (updates) => {
    // Update URL with new query parameters
  },
  isUpdating: () => false
};
```

--------------------------------

### Multiple Parameters: Use queryReactive for multiple query states

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Shows how to manage multiple query parameters simultaneously using `queryReactive`. Each parameter can be configured with a `defaultValue` and a custom `codec` for type conversion. This example manages search query, page number, and a boolean flag.

```vue
<script setup lang="ts">
import { queryReactive } from 'vue-qs';

// Each field config controls parsing, defaults, and omission rules
const queryState = queryReactive({
  q: { defaultValue: '' },
  page: { defaultValue: 1, codec: numberCodec },
  showDetails: { defaultValue: false, codec: booleanCodec },
});
</script>

<template>
  <input v-model="queryState.q" placeholder="Search..." />
  <button @click="queryState.page++">Next Page</button>
  <button @click="queryState.showDetails = !queryState.showDetails">Toggle Details</button>
</template>
```

--------------------------------

### Vue-QS Number Codec Example (TypeScript)

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/serializers.md

Demonstrates using the built-in `numberCodec` for query parameters in Vue-QS. It shows both explicit parse function and shorthand codec assignment. Assumes `queryRef` and `serializers` are imported.

```typescript
import { queryRef, serializers } from 'vue-qs';

queryRef('count', { defaultValue: 0, parse: serializers.numberCodec.parse });
// or shorter
queryRef('count', { defaultValue: 0, codec: serializers.numberCodec });
```

--------------------------------

### Vue Basic Form Component with Query Parameters

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/examples.md

A Vue 3 component using `vue-qs`'s `queryRef` to manage string, number, boolean, and array query parameters. It includes input fields bound to these refs and displays the current state. Dependencies include Vue 3 and `vue-qs`.

```vue
<script setup lang="ts">
import { serializers, queryRef } from 'vue-qs';

const name = queryRef('name', { defaultValue: '', parse: String });

const itemCount = queryRef('itemCount', { defaultValue: 0, codec: serializers.numberCodec });

const isPublished = queryRef('isPublished', {
  defaultValue: false,
  codec: serializers.booleanCodec,
});

const tags = queryRef<string[]>('tags', {
  defaultValue: [],
  codec: serializers.createArrayCodec(serializers.stringCodec),
});
</script>

<template>
  <div class="form-container">
    <h2>Basic Form Example</h2>

    <div class="field">
      <label>Name:</label>
      <input v-model="name" placeholder="Your name" />
    </div>

    <div class="field">
      <label>Item Count:</label>
      <input v-model="itemCount" type="number" placeholder="Item count" />
    </div>

    <div class="field">
      <label>
        <input v-model="isPublished" type="checkbox" />
        Is Published
      </label>
    </div>

    <div class="field">
      <label>Tags:</label>
      <select v-model="tags" multiple>
        <option v-for="tag in ['vue', 'javascript', 'frontend', 'backend']" :key="tag" :value="tag">
          {{ tag }}
        </option>
      </select>
    </div>

    <div class="output">
      <h3>Current State:</h3>
      <pre>{{ JSON.stringify({ name, itemCount, isPublished, tags }, null, 2) }}</pre>
    </div>
  </div>
</template>
```

--------------------------------

### QueryParameterSchema Example in TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/QueryParameterSchema.md

This example demonstrates how to define a QueryParameterSchema in TypeScript. It shows the structure for setting default values and custom codecs for query parameters like 'search', 'page', and 'filters'.

```typescript
const schema: QueryParameterSchema = {
  search: { defaultValue: '' },
  page: { defaultValue: 1, codec: numberCodec },
  filters: { defaultValue: {}, codec: jsonCodec }
};
```

--------------------------------

### QueryRefOptions Example - TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/QueryRefOptions.md

An example demonstrating how to define and use the QueryRefOptions type in TypeScript. This shows the structure for providing default values, codecs, history strategies, and omission conditions for query parameters.

```typescript
const options: QueryRefOptions<number> = {
  defaultValue: 1,
  codec: numberCodec,
  historyStrategy: 'replace',
  shouldOmitDefault: true
};
```

--------------------------------

### Vue-QS QueryParameterOptions Example

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/QueryParameterOptions.md

This example demonstrates how to define a QueryParameterOptions object for a number type. It showcases setting a defaultValue, a custom codec, and a custom equality function. This configuration helps in managing how a specific query parameter is parsed, serialized, and compared.

```typescript
const pageOptions: QueryParameterOptions<number> = {
  defaultValue: 1,
  codec: numberCodec,
  shouldOmitDefault: true,
  isEqual: (a, b) => a === b
};
```

--------------------------------

### Vue-QS: Custom Equality Example with queryRef

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Demonstrates how to use a custom equality function with `queryRef` to control when a reactive query parameter should be updated. This is useful for complex objects where default equality checks might not be sufficient.

```typescript
const filters = queryRef('filters', {
  defaultValue: { category: 'all', sort: 'name' },
  codec: createJsonCodec<{ category: string; sort: string }>(),
  isEqual: (a, b) => a.category === b.category && a.sort === b.sort,
});
```

--------------------------------

### createVueRouterAdapter: Integrate Vue Router with Vue-QS

Source: https://context7.com/iamsomraj/vue-qs/llms.txt

This function facilitates the integration of `vue-qs` with Vue Router, enabling query parameter management directly through the router. It allows configuration options like warning about array parameters. The adapter can be installed globally via `createVueQsPlugin`. Requires `vue-router` and `vue-qs`.

```typescript
import { createRouter, createWebHistory } from 'vue-router';
import { createVueRouterAdapter, createVueQsPlugin } from 'vue-qs';
import { createApp } from 'vue';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home },
    { path: '/products', component: Products }
  ]
});

// Create adapter with options
const routerAdapter = createVueRouterAdapter(router, {
  warnOnArrayParams: true // Warn when multiple values detected
});

// Install plugin globally
const app = createApp(App);
app.use(createVueQsPlugin({ queryAdapter: routerAdapter }));
app.use(router);
app.mount('#app');

// Component usage - adapter is automatically injected
// In Products.vue
import { queryRef, numberCodec } from 'vue-qs';

const page = queryRef('page', {
  defaultValue: 1,
  codec: numberCodec
});
// No need to pass queryAdapter - uses injected Vue Router adapter
```

--------------------------------

### Basic Usage: Bind reactive ref to URL query parameter

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Demonstrates how to use `queryRef` to create a reactive ref that is synchronized with a URL query parameter. If the parameter is missing, it falls back to the `defaultValue`. This example shows basic binding without Vue Router.

```vue
<script setup lang="ts">
import { queryRef } from 'vue-qs';

// Create a ref bound to ?name=...
// Falls back to default value if param is missing
const name = queryRef('name', {
  defaultValue: '',
});
</script>

<template>
  <input v-model="name" placeholder="Your name" />
</template>
```

--------------------------------

### Use stringCodec with queryRef in Vue-qs

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/variables/stringCodec.md

This example demonstrates how to use the stringCodec with the queryRef function in vue-qs. It shows the default value and the codec configuration for a query parameter named 'name'.

```typescript
const name = queryRef('name', {
  defaultValue: '',
  codec: stringCodec
});
```

--------------------------------

### Example Usage of ReactiveQueryState - TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/ReactiveQueryState.md

This TypeScript example demonstrates how to use the ReactiveQueryState type alias. It defines a sample schema with default values for 'search' and 'page' parameters and then infers the State type using ReactiveQueryState. The resulting State type accurately reflects the expected types for each query parameter (string for search, number for page).

```typescript
const schema = {
  search: { defaultValue: '' },
  page: { defaultValue: 1 }
} as const;

type State = ReactiveQueryState<typeof schema>;
// State = { search: string; page: number }
```

--------------------------------

### createHistoryAdapter: Use Browser History API for Vue-QS Parameters

Source: https://context7.com/iamsomraj/vue-qs/llms.txt

This function creates an adapter that utilizes the browser's History API for managing URL query parameters. It can be used individually with `queryRef` or globally through the `createVueQsPlugin`. The `vue-qs` library and `numberCodec` are required for examples shown.

```typescript
import { createHistoryAdapter, queryRef, numberCodec } from 'vue-qs';

// Create adapter instance
const historyAdapter = createHistoryAdapter();

// Use with individual queryRef
const page = queryRef('page', {
  defaultValue: 1,
  codec: numberCodec,
  queryAdapter: historyAdapter
});

// Or provide globally via plugin
import { createApp } from 'vue';
import { createVueQsPlugin } from 'vue-qs';

const app = createApp(App);
app.use(createVueQsPlugin({
  queryAdapter: historyAdapter
}));
```

--------------------------------

### Creating Enum Codec in Vue-QS

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/zh/guide/serializers.md

Demonstrates the creation and usage of an enum codec for query parameters in Vue-QS. This example uses `createEnumCodec` to restrict query parameter values to a specific set of predefined strings.

```typescript
const sort = queryRef<'asc' | 'desc'>('sort', {
  defaultValue: 'asc',
  codec: serializers.createEnumCodec(['asc', 'desc'] as const),
});
```

--------------------------------

### Creating Array Codec in Vue-QS

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/zh/guide/serializers.md

Shows how to create and use a custom array codec for query parameters in Vue-QS. This example uses `createArrayCodec` with `stringCodec` to handle an array of strings.

```typescript
const tags = queryRef<string[]>('tags', {
  defaultValue: [],
  codec: serializers.createArrayCodec(serializers.stringCodec),
});
```

--------------------------------

### Vue-QS Array and Enum Codec Examples (TypeScript)

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/serializers.md

Illustrates how to use `createArrayCodec` and `createEnumCodec` for query parameters in Vue-QS. The array codec takes an inner codec and an optional separator, while the enum codec uses a defined list of values. Assumes `queryRef` and `serializers` are imported.

```typescript
import { queryRef, serializers } from 'vue-qs';

const tags = queryRef<string[]>('tags', {
  defaultValue: [],
  codec: serializers.createArrayCodec(serializers.stringCodec),
});

const sort = queryRef<'asc' | 'desc'>('sort', {
  defaultValue: 'asc',
  codec: serializers.createEnumCodec(['asc', 'desc'] as const),
});
```

--------------------------------

### Create Enum Codec with TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/functions/createEnumCodec.md

This example demonstrates how to use createEnumCodec to define a query parameter with a specific string enum type. It shows setting a default value and how invalid inputs are handled by falling back to the default.

```typescript
type SortOrder = 'asc' | 'desc';

const sort = queryRef('sort', {
  defaultValue: 'asc',
  codec: createEnumCodec<SortOrder>(['asc', 'desc'])
});

// URL: ?sort=desc
// Invalid values fall back to 'asc'
```

--------------------------------

### RuntimeEnvironment Example - TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/RuntimeEnvironment.md

Demonstrates how to define and use the RuntimeEnvironment type alias to specify the current execution environment. This is useful for conditional logic based on whether the code is running in a browser or a server-side environment.

```typescript
const env: RuntimeEnvironment = {
  isBrowser: true,
  windowObject: window
};
```

--------------------------------

### Vue-qs: Use numberCodec for Numeric Query Params (TypeScript)

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/variables/numberCodec.md

This example demonstrates how to use the numberCodec to specify that a query parameter should be treated as a number. It sets a default value and applies the numberCodec, ensuring that only valid numbers are processed. Invalid inputs will result in NaN.

```typescript
const page = queryRef('page', {
  defaultValue: 1,
  codec: numberCodec
});
```

--------------------------------

### Convert Query Object to URL Search String (TypeScript)

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/functions/buildSearchString.md

Safely converts a query object with key-value pairs into a URL search string. It handles undefined values by excluding them. The function returns a string starting with '?' or an empty string if the object is empty or all values are undefined.

```typescript
function buildSearchString(queryObject: Record<string, string | undefined>): string {
  const params = Object.entries(queryObject)
    .filter(([, value]) => value !== undefined)
    .map(([key, value]) => `${key}=${value}`)
    .join('&');

  return params ? `?${params}` : '';
}

// Example Usage:
console.log(buildSearchString({ page: '1', search: 'test' }));
// Expected output: "?page=1&search=test"

console.log(buildSearchString({ page: undefined, search: 'test' }));
// Expected output: "?search=test"

console.log(buildSearchString({}));
// Expected output: ""

console.log(buildSearchString({ page: undefined }));
// Expected output: ""

```

--------------------------------

### Define Number QueryCodec in TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/QueryCodec.md

This example demonstrates how to create a QueryCodec for the 'number' type. It includes a 'parse' function to convert string representations to numbers and a 'serialize' function to convert numbers back to strings for URL storage. The 'parse' function defaults to 0 if the input is falsy, and the 'serialize' function returns null for a value of 0.

```typescript
const numberCodec: QueryCodec<number> = {
  parse: (raw) => raw ? Number(raw) : 0,
  serialize: (value) => value === 0 ? null : String(value)
};
```

--------------------------------

### Vue-QS: Creating a Reactive Ref with queryRef

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Shows the basic usage of `queryRef` to create a reactive reference that syncs with a specific URL query parameter. It includes the parameter name and optional configuration options.

```typescript
function queryRef<T>(parameterName: string, options?: QueryRefOptions<T>): Ref<T>;
```

--------------------------------

### Query Adapters

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Adapters provide integration with browser history and routing solutions.

```APIDOC
## Query Adapters

### `createHistoryAdapter()`

#### Description
Creates an adapter for the browser's History API. This is the default adapter used by `vue-qs`.

#### Method
`createHistoryAdapter(): QueryAdapter`

### `createVueRouterAdapter(router)`

#### Description
Creates an adapter for integration with Vue Router. This allows `vue-qs` to read from and write to Vue Router's navigation.

#### Method
`createVueRouterAdapter(router: Router): QueryAdapter`

### Parameters
#### `router` (Router)
- Required - An instance of the Vue Router.

### Request Example
```ts
import { createRouter, createWebHistory } from 'vue-router';
import { createVueRouterAdapter, queryRef } from 'vue-qs';

const router = createRouter({
  history: createWebHistory(),
  routes: []
});

const queryAdapter = createVueRouterAdapter(router);

// Use the adapter with queryRef or queryReactive
const userId = queryRef<string>('user', {
  queryAdapter
});
```

### Response
#### Success Response (QueryAdapter)
- Returns an object conforming to the `QueryAdapter` interface, suitable for use with `vue-qs` composables.
```

--------------------------------

### provideQueryAdapter: Manual Injection of Vue-QS Adapter

Source: https://context7.com/iamsomraj/vue-qs/llms.txt

This function allows for manual injection of a query adapter into the component tree using Vue's provide/inject mechanism. This is useful for scenarios where the global plugin is not desired or for specific component hierarchies. Requires `vue-qs`.

```typescript
import { provideQueryAdapter, createHistoryAdapter } from 'vue-qs';

// In parent component setup
const adapter = createHistoryAdapter();
provideQueryAdapter(adapter);

// Child components can now use queryRef without passing adapter
```

--------------------------------

### Provide Query Adapter with Vue-QS

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/functions/provideQueryAdapter.md

Demonstrates how to provide a query adapter instance to the Vue component tree using the provideQueryAdapter function from vue-qs. This function utilizes dependency injection to make the adapter available to child components. It requires importing both provideQueryAdapter and a factory function like createHistoryAdapter.

```typescript
import { provideQueryAdapter, createHistoryAdapter } from 'vue-qs';

// In a parent component
const historyAdapter = createHistoryAdapter();
provideQueryAdapter(historyAdapter);
```

--------------------------------

### Create Vue.js Plugin with createVueQsPlugin

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/functions/createVueQsPlugin.md

This code snippet demonstrates how to create a Vue.js plugin using the createVueQsPlugin function from the vue-qs library. It initializes a Vue application, creates a history adapter, and then uses createVueQsPlugin to integrate the adapter into the Vue app via a plugin.

```typescript
import { createApp } from 'vue';
import { createVueQsPlugin, createHistoryAdapter } from 'vue-qs';

const app = createApp();
const historyAdapter = createHistoryAdapter();
const vueQueryPlugin = createVueQsPlugin({ queryAdapter: historyAdapter });

app.use(vueQueryPlugin);
```

--------------------------------

### Vue Router Integration: Per-component adapter

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Demonstrates how to integrate vue-qs with Vue Router on a per-component basis using `createVueRouterAdapter`. This allows for localized control over query parameter synchronization within a specific component.

```vue
<script setup lang="ts">
import { queryRef, createVueRouterAdapter } from 'vue-qs';
import { useRouter } from 'vue-router';

const router = useRouter();
const adapter = createVueRouterAdapter(router);

const page = queryRef('page', {
  defaultValue: 1,
  codec: numberCodec,
  queryAdapter: adapter,
});
</script>
```

--------------------------------

### Vue-QS: Creating a Vue Router Adapter with createVueRouterAdapter

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Shows how to create a query adapter specifically for Vue Router integration. This allows vue-qs to seamlessly work with Vue Router's navigation and history management.

```typescript
function createVueRouterAdapter(router: Router): QueryAdapter;
```

--------------------------------

### Create Vue Router Adapter with vue-qs

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/functions/createVueRouterAdapter.md

Creates a query adapter that integrates with Vue Router. This adapter reads and writes query parameters through Vue Router's API. It requires a Vue Router instance and optionally accepts configuration options.

```typescript
import { createRouter } from 'vue-router';
import { createVueRouterAdapter } from 'vue-qs';

const router = createRouter({ ... });
const routerAdapter = createVueRouterAdapter(router);

// Use with the plugin
app.use(createVueQsPlugin({ queryAdapter: routerAdapter }));
```

--------------------------------

### Vue.js 基础表单组件使用 queryRef 管理查询参数

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/zh/guide/examples.md

此 Vue.js 组件使用 `vue-qs` 库的 `queryRef` 来展示和管理不同类型的查询参数。它允许用户通过表单输入修改姓名、项目数量、发布状态和标签，并实时更新 URL 查询参数。`queryRef` 配合 `serializers` 提供了类型解析和编码/解码功能。

```vue
<script setup lang="ts">
import { serializers, queryRef } from 'vue-qs';

const name = queryRef('name', { defaultValue: '', parse: String });

const itemCount = queryRef('itemCount', { defaultValue: 0, codec: serializers.numberCodec });

const isPublished = queryRef('isPublished', {
  defaultValue: false,
  codec: serializers.booleanCodec,
});

const tags = queryRef<string[]>('tags', {
  defaultValue: [],
  codec: serializers.createArrayCodec(serializers.stringCodec),
});
</script>

<template>
  <div class="form-container">
    <h2>基础表单示例</h2>

    <div class="field">
      <label>姓名：</label>
      <input v-model="name" placeholder="您的姓名" />
    </div>

    <div class="field">
      <label>项目数量：</label>
      <input v-model="itemCount" type="number" placeholder="项目数量" />
    </div>

    <div class="field">
      <label>
        <input v-model="isPublished" type="checkbox" />
        已发布
      </label>
    </div>

    <div class="field">
      <label>标签：</label>
      <select v-model="tags" multiple>
        <option v-for="tag in ['vue', 'javascript', 'frontend', 'backend']" :key="tag" :value="tag">
          {{ tag }}
        </option>
      </select>
    </div>

    <div class="output">
      <h3>当前状态：</h3>
      <pre>{{ JSON.stringify({ name, itemCount, isPublished, tags }, null, 2) }}</pre>
    </div>
  </div>
</template>

<style scoped>
.form-container {
  max-width: 500px;
  margin: 0 auto;
  padding: 20px;
}

.field {
  margin-bottom: 15px;
}

.field label {
  display: block;
  margin-bottom: 5px;
  font-weight: bold;
}

.field input[type='text'],
.field input[type='number'],
.field select {
  width: 100%;
  padding: 8px;
  border: 1px solid #ccc;
  border-radius: 4px;
}

.field select[multiple] {
  height: 100px;
}

.output {
  margin-top: 20px;
  padding: 15px;
  background-color: #f5f5f5;
  border-radius: 4px;
}

.output pre {
  margin: 0;
  white-space: pre-wrap;
}
</style>
```

--------------------------------

### Define Custom Number QueryParser - TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/type-aliases/QueryParser.md

An example of defining a custom QueryParser function in TypeScript for parsing numbers. It handles null or missing raw values, attempts to convert the string to a number, and returns 0 if the conversion results in NaN.

```typescript
const numberParser: QueryParser<number> = (rawValue) => {
  if (!rawValue) return 0;
  const parsed = Number(rawValue);
  return isNaN(parsed) ? 0 : parsed;
};
```

--------------------------------

### Vue-QS: Creating a Default History Adapter with createHistoryAdapter

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Demonstrates how to create the default query adapter using the browser's History API. This adapter is used for managing browser history updates.

```typescript
function createHistoryAdapter(): QueryAdapter;
```

--------------------------------

### Create History Adapter with Browser History API - TypeScript

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/api/functions/createHistoryAdapter.md

This snippet demonstrates how to create a query adapter using the browser's History API with the createHistoryAdapter function. It then shows how to integrate this adapter with the vue-qs plugin for application-wide use.

```typescript
import { createHistoryAdapter } from 'vue-qs';

const queryAdapter = createHistoryAdapter();

// Use with the plugin
app.use(createVueQsPlugin({ queryAdapter }));
```

--------------------------------

### Vue-QS: Creating a Reactive Object with queryReactive

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Illustrates the use of `queryReactive` to synchronize multiple URL query parameters with a reactive object. This is suitable for managing complex state represented by several query parameters.

```typescript
function queryReactive<TSchema extends QueryParameterSchema>(
  parameterSchema: TSchema,
  options?: QueryReactiveOptions
): ReactiveQueryState<TSchema>;
```

--------------------------------

### Shared Options

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Options that can be applied to `queryRef` and `queryReactive` for customizing behavior.

```APIDOC
## Shared Options

These options can be passed to `queryRef` and `queryReactive` to customize their behavior.

### Options Table

| Option              | Type                      | Default       | Description                                  |
| ------------------- | ------------------------- | ------------- | -------------------------------------------- |
| `defaultValue`      | `T`                       | -             | Initial value if parameter is missing        |
| `codec`             | `QueryCodec<T>`           | `stringCodec` | Parser and serializer for the type           |
| `parse`             | `QueryParser<T>`          | -             | Custom parser function (overrides codec)     |
| `serializeFunction` | `QuerySerializer<T>`      | -             | Custom serializer function (overrides codec) |
| `shouldOmitDefault` | `boolean`                 | `true`        | Remove from URL when equal to default        |
| `isEqual`           | `(a: T, b: T) => boolean` | `Object.is`   | Custom equality function                     |
| `historyStrategy`   | `'replace' | 'push'`     | `'replace'`   | Browser history update strategy              |
| `queryAdapter`      | `QueryAdapter`            | -             | Override default query adapter               |

### Custom Equality Example

```ts
import { queryRef, createJsonCodec } from 'vue-qs';

const filters = queryRef('filters', {
  defaultValue: { category: 'all', sort: 'name' },
  codec: createJsonCodec<{ category: string; sort: string }>(),
  isEqual: (a, b) => a.category === b.category && a.sort === b.sort
});
```
```

--------------------------------

### Create Reactive Query Object for Multiple Parameters - TypeScript

Source: https://context7.com/iamsomraj/vue-qs/llms.txt

Creates a reactive object that synchronizes multiple URL query parameters simultaneously. Allows defining default values and codecs for each parameter. Supports global history management strategy for the entire object.

```typescript
import { queryReactive, numberCodec, booleanCodec } from 'vue-qs';

const queryState = queryReactive({
  search: {
    defaultValue: '',
    shouldOmitDefault: true
  },
  page: {
    defaultValue: 1,
    codec: numberCodec
  },
  showDetails: {
    defaultValue: false,
    codec: booleanCodec
  }
}, {
  historyStrategy: 'replace'
});

// Update multiple parameters
queryState.search = 'vue-qs';
queryState.page = 2;
queryState.showDetails = true;
// URL becomes: ?search=vue-qs&page=2&showDetails=true

// Access values directly
console.log(queryState.page); // 2
```

--------------------------------

### queryRef API

Source: https://github.com/iamsomraj/vue-qs/blob/main/README.md

Creates a reactive ref that syncs with a URL query parameter. This is useful for managing individual query parameters.

```APIDOC
## queryRef(name, options)

### Description
Creates a reactive ref that syncs with a URL query parameter.

### Method
`queryRef<T>(parameterName: string, options?: QueryRefOptions<T>): Ref<T>`

### Parameters
#### Path Parameters
* `parameterName` (string) - Required - The name of the URL query parameter to sync with.

#### Query Parameters
* `options` (QueryRefOptions<T>) - Optional - Configuration options for the query ref.
  * `defaultValue` (T) - Initial value if parameter is missing.
  * `codec` (QueryCodec<T>) - Parser and serializer for the type (defaults to `stringCodec`).
  * `parse` (QueryParser<T>) - Custom parser function (overrides codec).
  * `serializeFunction` (QuerySerializer<T>) - Custom serializer function (overrides codec).
  * `shouldOmitDefault` (boolean) - Remove from URL when equal to default (defaults to `true`).
  * `isEqual` ((a: T, b: T) => boolean) - Custom equality function (defaults to `Object.is`).
  * `historyStrategy` ('replace' | 'push') - Browser history update strategy (defaults to 'replace').
  * `queryAdapter` (QueryAdapter) - Override default query adapter.

### Request Example
```ts
import { queryRef } from 'vue-qs';

const searchParam = queryRef<string>('search');
const pageNumber = queryRef<number>('page', {
  defaultValue: 1,
  codec: numberCodec
});
```

### Response
#### Success Response (Ref<T>)
- Returns a Vue ref that is synchronized with the specified URL query parameter.
```

--------------------------------

### Vue Router: Per-hook Adapter with vue-qs

Source: https://github.com/iamsomraj/vue-qs/blob/main/docs/guide/vue-router.md

Demonstrates how to manually pass a Vue Router adapter to `queryRef` and `queryReactive` for synchronization. Requires `vue-qs` and `vue-router`. Inputs are reactive state and query parameters; outputs are synchronized refs/reactive objects.

```vue
<script setup lang="ts">
import { queryRef, queryReactive, createVueRouterAdapter } from 'vue-qs';
import { useRouter } from 'vue-router';

const adapter = createVueRouterAdapter(useRouter());

const page = queryRef('page', { defaultValue: 1, parse: Number, queryAdapter: adapter });
const queryState = queryReactive({ q: { defaultValue: '' } }, { adapter });
</script>
```