# url-fns

> Easily define and manipulate urls with relative paths, query parameters, and path parameters

Latest version **1.2.1** (published 2023-08-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install url-fns
pnpm add url-fns
yarn add url-fns
bun add url-fns
```

## Health

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

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

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.1 |
| Published | 2023-08-16 |
| First published | 2022-01-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 0 |
| Unpacked size | 57.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Author | ehmpathy |
| Maintainers | uladkasach |
| Keywords | url, uri, query, parameter, params, query-params, query-param, queryparams, queryparam, path-params, path-param, path, relative, absolute, update, modify, create |

## Links

- npm: https://www.npmjs.com/package/url-fns
- Repository: https://github.com/ehmpathy/url-fns
- Issues: https://github.com/ehmpathy/url-fns/issues
- npm.io page: https://npm.io/package/url-fns

## 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.1 (latest) — 2023-08-16
- 1.2.0 — 2022-09-14
- 1.1.2 — 2022-09-14
- 1.1.1 — 2022-04-14
- 1.1.0 — 2022-04-12
- 1.0.4 — 2022-02-24
- 1.0.3 — 2022-01-21
- 1.0.2 — 2022-01-13
- 1.0.1 — 2022-01-11
- 1.0.0 — 2022-01-11

## README

# url-fns

![ci_on_commit](https://github.com/uladkasach/url-fns/workflows/ci_on_commit/badge.svg)
![deploy_on_tag](https://github.com/uladkasach/url-fns/workflows/deploy_on_tag/badge.svg)

Easily define and manipulate urls with relative paths, query parameters, and path parameters.

# install

```sh
npm install url-fns
```

# use

### createUrl

`createUrl` enables you to create a new url from a path, pathParams, and queryParams

for example:

```ts
import { createUrl } from 'url-fns';

const url = createUrl({
  path: '/jobs/:jobSlug/get-this-job',
  pathParams: { jobSlug: '123' },
  queryParams: { variant: 'b' },
});
expect(url).toEqual('/jobs/123/get-this-job?variant=b');
```

### updateUrl

`updateUrl` enables you to modify parts of an existing url

for example:
```ts
import { updateUrl } from 'url-fns';

const url = updateUrl({
  from: '/jobs/123/get-this-job?variant=b',
  with: {
    path: '../learn-more', // notice that this is a relative path
    queryParams: {
      focus: 'title',
    },
  },
});
expect(url).toEqual('/jobs/123/learn-more?variant=b&focus=title');
```

note:
- the `with.path` argument, optional, allows you to update the path of the url in two ways:
  - absolute replacement: if the `with.path` starts with `/`, it is assumed that you want to completely replace the path
  - relative replacement: if the `with.path` starts with `./` or `../`, it is assumed that you want a relative path update

### stringifyQueryParams

`stringifyQueryParams` enables you to easily stringify query parameter objects

for example:
```ts
import { stringifyQueryParams } from 'url-fns';

const stringifiedQueryParams = stringifyQueryParams({ variant: 'b', focus: 'title' });
expect(stringifiedQueryParams).toEqual('variant=b&focus=title');
```

### parseQueryParams

`parseQueryParams` enables you to easily parse query parameter strings

for example:
```ts
import { parseQueryParams } from 'url-fns';

const parsedQueryParams = parseQueryParams('variant=b&focus=title');
expect(parsedQueryParams).toEqual({ variant: 'b', focus: 'title' });
```

# notes

### allowed query-string values

This library restricts the allowed type of values of query-params you give it to be `string`s

This places the burden of serializing more complicated data types on _you_, the user of the library. This is for a few reasons:
- it incentivizes you to keep the data you're putting into query-params simpler
  - which will hopefully help prevent unexpected errors from cropping up 🙂
- it protects you from errors that could arise when different query-string libraries act on the same query-strings
  - e.g., if the libraries don't quite serialize/deserialize in the same way 😬
- it keeps the logic in this library simpler

As you can see, it:
- helps prevent us users from shooting ourselves in the foot 🦶🔫
- helps keep the library simple 🕊️

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