rainxh11 / vue-useurl

Vue.js Reactive URL Composable

🔗 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.

vue-useurl's Issues

undefined value in queryParams and disableCSV is not working.

#3 is not fixed.
And disableCSV is not working. Always returns ?query=value1,value2,value3.

There is `Unhandled error during execution of setup function` if one of some fields in `options` argument was not provided

Version:

• "@vueuse/core": "9.1.0",
• "@vueuse/nuxt": "9.1.0",
• "vue-useurl": "1.0.32"
• "nuxt": "3.0.0-rc.6"

What happened:

When calling the useUrl() without providing one of following fields in options argument like below, there is the error Unhandled error during execution of setup function like attached image.

List of field cause problem:

1. path
2. pathVariables
3. queryParams
4. hash

const {url} = useUrl({
  path: '/api/v1/users/:id/search',
  // Bellow comment raise the error
  // pathVariables: {
  //   id: 451,
  // },
  queryParams: {
    search: 'ahmed',
    limit: 50,
    page: 12,
    sort: 'CreatedOn',
    types: ['Cancelled', 'OnGoing'],
  },
  hash: 'hashtag',
  disableCSV: false,
});

Expected:

Above fields are optional so it should not raise the error when we did not provide any of these fields in options argument.

queryParams bug with undefined value

console.log(
  (useUrl({
    queryParams: {
      someKey: undefined,
    },
  }, `https://example.com`)).url.value
)

This will result in https://example.com/?someKey=undefined
Which is a param with the string value 'undefined' and is truthy, which causes unwanted behavior in many ways.

Could be fixed with a small modification to filter at line 87

I don't currently have time to make a PR sorry.
Thanks a lot.