# url-modify

> Modify URL instances cleanly and safely. Works in any environment that supports the URL API.

Latest version **0.0.5** (published 2021-09-27) · MIT license · 0 weekly downloads

## Install

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

## Health

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

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

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2021-09-27 |
| First published | 2021-09-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 9.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Adam Pancutt |
| Maintainers | apancutt |
| Keywords | extend, manipulate, modify, url, urlsearchparams |

## Links

- npm: https://www.npmjs.com/package/url-modify
- Repository: https://github.com/apancutt/url-modify
- Homepage: https://github.com/apancutt/url-modify#readme
- Issues: https://github.com/apancutt/url-modify/issues
- npm.io page: https://npm.io/package/url-modify

## 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

- 0.0.5 (latest) — 2021-09-27
- 0.0.4 — 2021-09-27
- 0.0.3 — 2021-09-27
- 0.0.2 — 2021-09-27
- 0.0.1 — 2021-09-27

## README

# `url-modify`

Modify URL instances cleanly and safely. Works in any environment that supports the URL API.

## Installation

```bash
yarn add url-modify
# Or if you are using NPM:
# npm install --save url-modify
```

## Usage

```typescript
urlModify(modifications: UrlModifyModifications, base: string | URL, options?: UrlModifyOptions): URL
```

### `UrlModifyModifications`

```typescript
{
  hash?: string;
  host?: string;
  password?: string;
  path?: string;
  port?: string;
  protocol?: string;
  search?: string | string[][] | Record<string, string> | URLSearchParams;
  username?: string;
}
```

### `UrlModifyOptions`

```typescript
{
  pathBehavior?: 'append' | 'prepend' | 'replace';
  searchBehavior?: 'append' | 'clear' | 'replace';
}
```

#### `pathBehavior`

* `append`

  Appends `modifications.path` to the base URL path. Note that the base URL path is not tampered with; it may or may not end in a trailing slash depending how you provided it.

* `prepend`

  Prepend `modifications.path` to the base URL path. Note that the leading slash from the base URL path is removed, so you may need to ensure `modifications.path` ends with a slash.

* `replace` _(default)_

  Replace the base URL path with `modifications.path`.

#### `searchBehavior`

* `append`

  If a search key provided in `modifications.search` already exists in the base URL then retain it and append the values provided in `modifications.search` to the search string.

* `clear`

  Clear all search params provided in the base URL before appending the values provided in `modifications.search` to the search string.

* `replace` _(default)_

    If a search key provided in `modifications.search` already exists in the base URL then remove it before appending the values provided in `modifications.search` to the search string.

## Examples

```typescript
import { urlModify } from 'url-modify';
// Or if you are using CommonJS:
// const { urlModify } = require('url-modify');

const base = new URL('https://foo.example?foo=bar');

console.log(urlModify({ protocol: 'wss' }, base).toString())
// "wss://foo.example/?foo=bar"

console.log(urlModify({ search: { foo: 'bar2' } }, base).toString())
// "https://foo.example/?foo=bar2"

console.log(urlModify({ search: { foo: 'bar2' } }, base, { searchBehavior: 'append' }).toString())
// "https://foo.example/?foo=bar&foo=bar2"

console.log(urlModify({ search: [ [ 'foo', 'bar2' ], [ 'foo', 'bar3' ] ] }, base, { searchBehavior: 'append' }).toString())
// "https://foo.example/?foo=bar&foo=bar2&foo=bar3"

console.log(urlModify({ search: [ [ 'foo', 'bar2' ], [ 'foo', 'bar3' ] ] }, base, { searchBehavior: 'replace' }).toString())
// "https://foo.example/?foo=bar2&foo=bar3"

console.log(urlModify({ search: { abc: '123' } }, base).toString())
// "https://foo.example/?foo=bar&abc=123"

console.log(urlModify({ search: { abc: '123' } }, base, { searchBehavior: 'clear' }).toString())
// "https://foo.example/?abc=123"
```

## Rationale

While the URL API simplifies creating URL strings, it's difficult to cleanly mutate URL instances
without creating excessive variables and/or risk modifying the original URL instance.

Until the spec allows you to do something like...

```typescript
const base = new URL('http://foo.example');
new URL({ protocol: 'https' }, base);
```

...or...

```typescript
const base = new URL('http://foo.example');
new URL({ ...base, protocol: 'https' });
```

...then this package is a helpful workaround.

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