# vue-useurl

> Reactive Url Builder Vue Composable

Latest version **1.2.0** (published 2024-02-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue-useurl
pnpm add vue-useurl
yarn add vue-useurl
bun add vue-useurl
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2024-02-16 |
| First published | 2022-04-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 11.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Ahmed Chakhoum |
| Maintainers | rainxh11 |
| Keywords | vue, compositionapi, hooks, url, urlbuilder, vueuse, vuehook, vue-compositionapi, vuejs, reactive-url, reactive, buildurl, urlgenerator, query, querybuilder, parameters, routing, build, route, api, path, fetch, usefetch |

## Links

- npm: https://www.npmjs.com/package/vue-useurl
- Repository: https://github.com/rainxh11/vue-useurl
- Homepage: https://github.com/rainxh11/vue-useurl#readme
- Issues: https://github.com/rainxh11/vue-useurl/issues
- npm.io page: https://npm.io/package/vue-useurl

## Dependencies (1)

- [vue-demi](https://npm.io/package/vue-demi.md) ^0.14.7

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 1.2.0 (latest) — 2024-02-16
- 1.1.0 — 2023-03-18
- 1.0.33 — 2022-08-14
- 1.0.32 — 2022-05-04
- 1.0.31 — 2022-05-02
- 1.0.30 — 2022-05-02
- 1.0.29 — 2022-05-01
- 1.0.28 — 2022-05-01
- 1.0.27 — 2022-05-01
- 1.0.26 — 2022-05-01
- 1.0.25 — 2022-05-01
- 1.0.24 — 2022-05-01
- 1.0.23 — 2022-05-01
- 1.0.22 — 2022-04-30
- 1.0.21 — 2022-04-30
- … 21 more at https://npm.io/package/vue-useurl/versions

## README

<img src="https://raw.githubusercontent.com/rainxh11/vue-useurl/master/assets/logo.svg" width="300">

# 🔗 Vue-useUrl

## Reactive Url Builder Vue Composable for Vue 2 & Vue 3

[![NPM version](https://img.shields.io/npm/v/vue-useurl.svg)](https://www.npmjs.com/package/vue-useurl)

A library for building URL using ***(Query Parameters, Path Variables, Hash, Path)*** while being reactive and ready to
use as Vue Composition API Composable

## Installation

To install with npm:

```
npm install vue-useurl --save
```

## Usage

```ts
import { useUrl } from 'vue-useurl'

const params = {
	search: 'ahmed',
	limit: 50,
	page: 12,
	sort: 'CreatedOn',
	types: ['Cancelled', 'OnGoing']
}

const { url, queryParams, pathVariables, hash, path, disableCSV } = useUrl({
		path: '/api/v1/users/:id/search',
		pathVariables: {
			id: 451
		},
		queryParams: {
			...params
		},
		hash: 'someHash',
		arraySerializer: (v) => v.join(',')
	},
	'http://api.com')
```

## Options

The `userUrl` function accepts two arguments. The first is 'options' of type IUrlOptions e.g:

```ts
import { useUrl } from 'vue-useurl'

const { url, queryParams, pathVariables, hash, path, disableCSV } = useUrl(
	{
		path: '/path/path1', // URL Path
		pathVariables:
			{
				id: 451
			}
		, // Path variables e.g: /:id/
		queryParams: {
			limit: 10,
			sortBy:
				'property',
			page:
				1
		}
		, // Query parameters
		hash: 'someHash', // Hash
	})
```

The second is 'baseUrl' that will be appended to Url path

```ts
useUrl({
		path: '/about',
		queryParams: {
			foo: 'bar',
			fizz: 'baz'
		},
		hash: 'contact',
	},
	'http://api.com')

// returns http://api.com/about?foo=bar&bar=baz#contact
```

Variables returned by `useUrl()` are all reactive objects, changing any
of: `path` `queryParams` `pathVariables` `hash` `arraySerializer` will rebuild `url`

```ts
const { url, queryParams, pathVariables, hash, path, disableCSV } = useUrl(/*..*/)
```

## Usage with VueUse 'useFetch()'

This library is compatible with VueUse `useFetch()`, and `url` returned from `useUrl()` can easily be used to trigger
auto-reftech if option `{ refetch: true }` is passed to `useFetch()` which make for intuitive and easy way to work with
url parametes and variables without the need to modify url string directly

```ts
import { useFetch } from "@vueuse/core"
import { useUrl } from 'vue-useurl'

const { url, queryParams, pathVariables, hash, path, disableCSV } = useUrl({
		path: '/api/v1/users/:id/search',
		pathVariables: {
			id: 451
		},
		queryParams: {
			search: 'ahmed',
			limit: 50,
			page: 12,
			sort: 'CreatedOn',
			types: ['Cancelled', 'OnGoing']
		},
		hash: 'hashtag',
	},
	'http://api.com')

const { isFetching, error, data } = useFetch(url, { initialData: { results: [] }, refetch: true })
	.get()
	.json()
```

## How to use debouncing, throttling and other reactive backpressures with useUrl():

```ts
import { useFetch, useDebounce } from "@vueuse/core"
import { useUrl } from 'vue-useurl'
import { ref } from 'vue-demi'

export function useApi()
{
	const search = ref('query') //
	const filters = ref(['filter1', 'filter2', 'filter3']) // declare reactive varibales 

	const { url, queryParams, pathVariables, hash, path, disableCSV } = useUrl({
			path: '/api/v1/users/:id/search',
			pathVariables: {
				id: 451
			},
			queryParams: {
				search: useDebounce(search, 500), // 
				limit: 50,
				page: 12,
				sort: 'CreatedOn',
				types: useDebounce(filters, 3500) // then pass their reactive backpressure objects instead
			},
			hash: 'hashtag',
			disableCSV: false
		},
		'http://api.com')

	const { isFetching, error, data } = useFetch(
		url,
		{ initialData: { results: [] }, refetch: true })
		.get()
		.json()

	return {
		data,
		search, //
		filters,// changing this now will trigger the url re-build
		queryParams,
		pathVariables,
		hash,
		path,
		url
	}
}

```

## License

This is licensed under an MIT License.

---
_Source: https://npm.io/package/vue-useurl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
