🔗 Vue-useUrl

Reactive Url Builder Vue Composable for Vue 2 & Vue 3

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

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:

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

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

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

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():

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.

rainxh11/vue-useurl