vuerl 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Marius Oseth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# vuerl
+
+[![npm version](https://img.shields.io/npm/v/vuerl.svg)](https://www.npmjs.com/package/vuerl)
+[![CI](https://github.com/mariusoseth/vuerls/actions/workflows/ci.yml/badge.svg)](https://github.com/mariusoseth/vuerls/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Type-safe URL query state management for Vue 3 + Vue Router.
+
+This package gives you typed composables that keep Vue state and the URL query string in sync. You get the same ergonomics as `const [value, setValue] = useQueryState(...)` in React/nuqs, including parser-based type safety, automatic batching, and browser-aware rate limiting.
+
+## Installation
+
+```bash
+pnpm add vuerl
+# or
+npm install vuerl
+# or
+yarn add vuerl
+```
+
+Peer dependencies:
+
+```bash
+pnpm add vue@^3.3 vue-router@^4.0
+```
+
+## Quick Start
+
+```ts
+<script setup lang="ts">
+import { useQueryState, parseAsString, parseAsInteger } from 'vuerl'
+
+const [search, setSearch] = useQueryState('q', parseAsString.withDefault(''))
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1), {
+  debounce: 200,
+  history: 'replace'
+})
+</script>
+
+<template>
+  <input v-model="search" placeholder="Search" />
+  <button @click="setPage(page.value + 1)">Next Page</button>
+</template>
+```
+
+- State updates immediately when you type.
+- URL updates are debounced to keep browsers happy.
+- Defaults never show up in the URL (unless you turn off `clearOnDefault`).
+- TypeScript knows `search.value` is `string` and `page.value` is `number`.
+
+## Multi-parameter State
+
+Use `useQueryStates` when several params should update together.
+
+```ts
+import {
+  useQueryStates,
+  parseAsString,
+  parseAsInteger,
+  parseAsStringLiteral
+} from 'vuerl'
+
+const [filters, setFilters] = useQueryStates({
+  search: parseAsString.withDefault(''),
+  status: parseAsStringLiteral(['active', 'inactive']).withDefault('active'),
+  limit: parseAsInteger.withDefault(20)
+}, {
+  debounce: 120,
+  history: 'push'
+})
+
+setFilters({ search: 'vue' })             // single field
+setFilters({ status: 'inactive', limit: 50 }) // batched update → one router push
+setFilters({ status: null })               // drop from URL + reset to parser default
+setFilters(null)                           // reset every field to defaults
+```
+
+Updates inside the same tick (`setFilters({...}); setFilters({...})`) merge before touching the router, so you only pay for one navigation.
+
+## Parser Cheatsheet
+
+Parsers define how a query string turns into a typed value (and back). Every parser supports `.withDefault(value)` and `.withOptions({ ...queryStateOptions })`.
+
+| Parser | Example | URL → Value |
+| --- | --- | --- |
+| `parseAsString` | `"hello"` | `'hello'`
+| `parseAsInteger` | `"42"` | `42`
+| `parseAsFloat` | `"3.14"` | `3.14`
+| `parseAsBoolean` | `"true"` | `true`
+| `parseAsStringLiteral(['asc','desc'])` | `"asc"` | `'asc'`
+| `parseAsStringEnum(MyEnum)` | `"VALUE"` | `MyEnum.VALUE`
+| `parseAsArrayOf(parseAsInteger)` | `"1,2,3"` | `[1,2,3]`
+| `parseAsNativeArrayOf(parseAsString)` | `?tag=a&tag=b` | `['a','b']`
+| `parseAsIsoDate` | `"2025-11-22"` | `Date`
+| `parseAsIsoDateTime` | `"2025-11-22T10:30:00Z"` | `Date`
+| `parseAsJson()` | `"%7B%5C"id%5C":1%7D"` | `{ id: 1 }`
+| `parseAsHex` | `"ff00ff"` | `'ff00ff'`
+| `withDefault(customParser, defaultValue)` | – | Keeps custom parser logic but adds defaults |
+
+Need something custom? Implement the `Parser<T>` interface or wrap an existing parser with `.withDefault`/`.withOptions`.
+
+```ts
+const parseAsSlug = withDefault({
+  parse: (value) => (value && /[a-z0-9-]+/.test(value) ? value : null),
+  serialize: (value) => value ?? null
+}, 'home')
+```
+
+## Options Reference
+
+Both hooks accept the same `QueryStateOptions` either directly or via parser `.withOptions`.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `history` | `'replace'` | `'push'` to record every change in browser history. |
+| `debounce` | browser-safe (50ms / 120ms Safari) | Delay before writing to the URL. |
+| `throttle` | `null` | Alternate rate limiter if you prefer throttling. |
+| `clearOnDefault` | `true` | Drop params from the URL when they match parser default. |
+| `shallow` | `true` | Skip full router navigation (like `router.replace({ query })`). Set `false` when SSR needs to know about query changes. |
+| `scroll` | `false` | Force scroll to top on navigation. |
+
+Parser-level options merge with hook options, so you can keep most defaults global and override only the odd field:
+
+```ts
+const parser = parseAsInteger
+  .withDefault(20)
+  .withOptions({ clearOnDefault: false })
+
+const [, setLimit] = useQueryState('limit', parser)
+```
+
+## Watching External Changes
+
+Both hooks watch `route.query` so back/forward navigation, shared URLs, or manual `router.push` calls stay in sync automatically. Pending debounced updates are cancelled when the user navigates elsewhere.
+
+## Working With Arrays
+
+`parseAsArrayOf` (comma separated) and `parseAsNativeArrayOf` (repeated params) always return concrete arrays:
+
+```ts
+const [tags] = useQueryState('tags', parseAsArrayOf(parseAsString))
+tags.value // always string[]
+
+const [, setIds] = useQueryState('id', parseAsNativeArrayOf(parseAsInteger))
+setIds([1, 2, 3]) // → ?id=1&id=2&id=3
+```
+
+## Custom Equality
+
+If your parser returns objects/arrays that shouldn't trigger updates when reference changes, provide `eq(a, b)`:
+
+```ts
+const parseAsJsonFilters = withDefault({
+  parse: (value) => value ? JSON.parse(value) : null,
+  serialize: (value) => value ? JSON.stringify(value) : null,
+  eq: (a, b) => JSON.stringify(a) === JSON.stringify(b)
+}, {})
+```
+
+## Testing Helpers
+
+The test suite uses Vue Test Utils + Vue Router in memory. If you need to write your own tests, copy the helper from `tests/helpers.ts` to mount a composable inside a dummy component.
+
+## FAQ
+
+**Does this work with SSR?**
+
+Yes. Hooks guard against `window` access and fall back to safe defaults in SSR environments. Set `{ shallow: false }` if your framework needs full navigations for query changes.
+
+**What about browser rate limits?**
+
+We auto-detect Safari vs other browsers and ensure the debounce/throttle never drops below 120ms/50ms respectively. You can still pass your own values—they're clamped to the safe floor.
+
+**Can I mix `useQueryState` and `useQueryStates`?**
+
+Absolutely. They both watch the same router instance and will stay in sync. When both write the same key the last writer wins, so prefer one hook per param to avoid confusion.
+
+## Contributing
+
+PRs welcome! If you add new parsers, remember to extend `src/parsers.ts`, export from `src/index.ts`, and cover them in `tests/parsers.test.ts`.
+
+## License
+
+MIT