467 lines
10 KiB
Markdown
467 lines
10 KiB
Markdown
# ufo
|
|
|
|
[![npm version][npm-version-src]][npm-version-href]
|
|
[![npm downloads][npm-downloads-src]][npm-downloads-href]
|
|
[![bundle][bundle-src]][bundle-href]
|
|
[![Codecov][codecov-src]][codecov-href]
|
|
|
|
URL utils for humans.
|
|
|
|
## Install
|
|
|
|
Install using npm or your favourite package manager:
|
|
|
|
Install package:
|
|
|
|
```sh
|
|
# npm
|
|
npm install ufo
|
|
|
|
# yarn
|
|
yarn add ufo
|
|
|
|
# pnpm
|
|
pnpm install ufo
|
|
|
|
# bun
|
|
bun install ufo
|
|
```
|
|
|
|
Import utils:
|
|
|
|
```js
|
|
// ESM
|
|
import { normalizeURL, joinURL } from "ufo";
|
|
|
|
// CommonJS
|
|
const { normalizeURL, joinURL } = require("ufo");
|
|
|
|
// Deno
|
|
import { parseURL } from "https://unpkg.com/ufo/dist/index.mjs";
|
|
```
|
|
|
|
<!-- automd:jsdocs src=./src defaultGroup=utils -->
|
|
|
|
## Encoding Utils
|
|
|
|
### `decode(text)`
|
|
|
|
Decodes text using `decodeURIComponent`. Returns the original text if it fails.
|
|
|
|
### `decodePath(text)`
|
|
|
|
Decodes path section of URL (consistent with encodePath for slash encoding).
|
|
|
|
### `decodeQueryKey(text)`
|
|
|
|
Decodes query key (consistent with `encodeQueryKey` for plus encoding).
|
|
|
|
### `decodeQueryValue(text)`
|
|
|
|
Decodes query value (consistent with `encodeQueryValue` for plus encoding).
|
|
|
|
### `encode(text)`
|
|
|
|
Encodes characters that need to be encoded in the path, search and hash sections of the URL.
|
|
|
|
### `encodeHash(text)`
|
|
|
|
Encodes characters that need to be encoded in the hash section of the URL.
|
|
|
|
### `encodeHost(name)`
|
|
|
|
Encodes hostname with punycode encoding.
|
|
|
|
### `encodeParam(text)`
|
|
|
|
Encodes characters that need to be encoded in the path section of the URL as a param. This function encodes everything `encodePath` does plus the slash (`/`) character.
|
|
|
|
### `encodePath(text)`
|
|
|
|
Encodes characters that need to be encoded in the path section of the URL.
|
|
|
|
### `encodeQueryKey(text)`
|
|
|
|
Encodes characters that need to be encoded for query values in the query section of the URL and also encodes the `=` character.
|
|
|
|
### `encodeQueryValue(input)`
|
|
|
|
Encodes characters that need to be encoded for query values in the query section of the URL.
|
|
|
|
## Parsing Utils
|
|
|
|
### `parseAuth(input)`
|
|
|
|
Takes a string of the form `username:password` and returns an object with the username and password decoded.
|
|
|
|
### `parseFilename(input, opts?: { strict? })`
|
|
|
|
Parses a URL and returns last segment in path as filename.
|
|
|
|
If `{ strict: true }` is passed as the second argument, it will only return the last segment only if ending with an extension.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
// Result: filename.ext
|
|
parseFilename("http://example.com/path/to/filename.ext");
|
|
|
|
// Result: undefined
|
|
parseFilename("/path/to/.hidden-file", { strict: true });
|
|
```
|
|
|
|
### `parseHost(input)`
|
|
|
|
Takes a string, and returns an object with two properties: `hostname` and `port`.
|
|
|
|
### `parsePath(input)`
|
|
|
|
Splits the input string into three parts, and returns an object with those three parts.
|
|
|
|
### `parseURL(input, defaultProto?)`
|
|
|
|
Takes a URL string and returns an object with the URL's `protocol`, `auth`, `host`, `pathname`, `search`, and `hash`.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
parseURL("http://foo.com/foo?test=123#token");
|
|
// { protocol: 'http:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }
|
|
|
|
parseURL("foo.com/foo?test=123#token");
|
|
// { pathname: 'foo.com/foo', search: '?test=123', hash: '#token' }
|
|
|
|
parseURL("foo.com/foo?test=123#token", "https://");
|
|
// { protocol: 'https:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }
|
|
```
|
|
|
|
### `stringifyParsedURL(parsed)`
|
|
|
|
Takes a `ParsedURL` object and returns the stringified URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
const obj = parseURL("http://foo.com/foo?test=123#token");
|
|
obj.host = "bar.com";
|
|
|
|
stringifyParsedURL(obj); // "http://bar.com/foo?test=123#token"
|
|
```
|
|
|
|
## Query Utils
|
|
|
|
### `encodeQueryItem(key, value)`
|
|
|
|
Encodes a pair of key and value into a url query string value.
|
|
|
|
If the value is an array, it will be encoded as multiple key-value pairs with the same key.
|
|
|
|
### `parseQuery(parametersString)`
|
|
|
|
Parses and decodes a query string into an object.
|
|
|
|
The input can be a query string with or without the leading `?`.
|
|
|
|
### `stringifyQuery(query)`
|
|
|
|
Stringfies and encodes a query object into a query string.
|
|
|
|
## Utils
|
|
|
|
### `$URL()`
|
|
|
|
### `cleanDoubleSlashes(input)`
|
|
|
|
Removes double slashes from the URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
cleanDoubleSlashes("//foo//bar//"); // "/foo/bar/"
|
|
|
|
cleanDoubleSlashes("http://example.com/analyze//http://localhost:3000//");
|
|
// Returns "http://example.com/analyze/http://localhost:3000/"
|
|
```
|
|
|
|
### `filterQuery(input, predicate)`
|
|
|
|
Removes the query section of the URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
filterQuery("/foo?bar=1&baz=2", (key) => key !== "bar"); // "/foo?baz=2"
|
|
```
|
|
|
|
### `getQuery(input)`
|
|
|
|
Parses and decodes the query object of an input URL into an object.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
getQuery("http://foo.com/foo?test=123&unicode=%E5%A5%BD");
|
|
// { test: "123", unicode: "好" }
|
|
```
|
|
|
|
### `hasLeadingSlash(input)`
|
|
|
|
Checks if the input has a leading slash (e.g. `/foo`).
|
|
|
|
### `hasProtocol(inputString, opts)`
|
|
|
|
### `hasTrailingSlash(input, respectQueryAndFragment?)`
|
|
|
|
Checks if the input has a trailing slash.
|
|
|
|
### `isEmptyURL(url)`
|
|
|
|
Checks if the input URL is empty or `/`.
|
|
|
|
### `isEqual(a, b, options)`
|
|
|
|
Checks if two paths are equal regardless of encoding, trailing slash, and leading slash differences.
|
|
|
|
You can make slash check strict by setting `{ trailingSlash: true, leadingSlash: true }` as options.
|
|
|
|
You can make encoding check strict by setting `{ encoding: true }` as options.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
isEqual("/foo", "foo"); // true
|
|
isEqual("foo/", "foo"); // true
|
|
isEqual("/foo bar", "/foo%20bar"); // true
|
|
|
|
// Strict compare
|
|
isEqual("/foo", "foo", { leadingSlash: true }); // false
|
|
isEqual("foo/", "foo", { trailingSlash: true }); // false
|
|
isEqual("/foo bar", "/foo%20bar", { encoding: true }); // false
|
|
```
|
|
|
|
### `isNonEmptyURL(url)`
|
|
|
|
Checks if the input URL is neither empty nor `/`.
|
|
|
|
### `isRelative(inputString)`
|
|
|
|
Check if a path starts with `./` or `../`.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
isRelative("./foo"); // true
|
|
```
|
|
|
|
### `isSamePath(p1, p2)`
|
|
|
|
Check if two paths are equal or not. Trailing slash and encoding are normalized before comparison.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
isSamePath("/foo", "/foo/"); // true
|
|
```
|
|
|
|
### `isScriptProtocol(protocol?)`
|
|
|
|
Checks if the input protocol is any of the dangerous `blob:`, `data:`, `javascript`: or `vbscript:` protocols.
|
|
|
|
### `joinRelativeURL()`
|
|
|
|
Joins multiple URL segments into a single URL and also handles relative paths with `./` and `../`.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
joinRelativeURL("/a", "../b", "./c"); // "/b/c"
|
|
```
|
|
|
|
### `joinURL(base)`
|
|
|
|
Joins multiple URL segments into a single URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
joinURL("a", "/b", "/c"); // "a/b/c"
|
|
```
|
|
|
|
### `normalizeURL(input)`
|
|
|
|
Normalizes the input URL:
|
|
|
|
- Ensures the URL is properly encoded - Ensures pathname starts with a slash - Preserves protocol/host if provided
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
normalizeURL("test?query=123 123#hash, test");
|
|
// Returns "test?query=123%20123#hash,%20test"
|
|
|
|
normalizeURL("http://localhost:3000");
|
|
// Returns "http://localhost:3000"
|
|
```
|
|
|
|
### `resolveURL(base)`
|
|
|
|
Resolves multiple URL segments into a single URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
resolveURL("http://foo.com/foo?test=123#token", "bar", "baz");
|
|
// Returns "http://foo.com/foo/bar/baz?test=123#token"
|
|
```
|
|
|
|
### `withBase(input, base)`
|
|
|
|
Ensures the URL or pathname starts with base.
|
|
|
|
If input already starts with base, it will not be added again.
|
|
|
|
### `withFragment(input, hash)`
|
|
|
|
Adds or replaces the fragment section of the URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withFragment("/foo", "bar"); // "/foo#bar"
|
|
withFragment("/foo#bar", "baz"); // "/foo#baz"
|
|
withFragment("/foo#bar", ""); // "/foo"
|
|
```
|
|
|
|
### `withHttp(input)`
|
|
|
|
Adds or replaces the URL protocol to `http://`.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withHttp("https://example.com"); // http://example.com
|
|
```
|
|
|
|
### `withHttps(input)`
|
|
|
|
Adds or replaces the URL protocol to `https://`.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withHttps("http://example.com"); // https://example.com
|
|
```
|
|
|
|
### `withLeadingSlash(input)`
|
|
|
|
Ensures the URL or pathname has a leading slash.
|
|
|
|
### `withoutBase(input, base)`
|
|
|
|
Removes the base from the URL or pathname.
|
|
|
|
If input does not start with base, it will not be removed.
|
|
|
|
### `withoutFragment(input)`
|
|
|
|
Removes the fragment section from the URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withoutFragment("http://example.com/foo?q=123#bar")
|
|
// Returns "http://example.com/foo?q=123"
|
|
```
|
|
|
|
### `withoutHost(input)`
|
|
|
|
Removes the host from the URL while preserving everything else.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withoutHost("http://example.com/foo?q=123#bar")
|
|
// Returns "/foo?q=123#bar"
|
|
```
|
|
|
|
### `withoutLeadingSlash(input)`
|
|
|
|
Removes leading slash from the URL or pathname.
|
|
|
|
### `withoutProtocol(input)`
|
|
|
|
Removes the protocol from the input.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withoutProtocol("http://example.com"); // "example.com"
|
|
```
|
|
|
|
### `withoutTrailingSlash(input, respectQueryAndFragment?)`
|
|
|
|
Removes the trailing slash from the URL or pathname.
|
|
|
|
If second argument is `true`, it will only remove the trailing slash if it's not part of the query or fragment with cost of more expensive operations.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withoutTrailingSlash("/foo/"); // "/foo"
|
|
|
|
withoutTrailingSlash("/path/?query=true", true); // "/path?query=true"
|
|
```
|
|
|
|
### `withProtocol(input, protocol)`
|
|
|
|
Adds or replaces protocol of the input URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withProtocol("http://example.com", "ftp://"); // "ftp://example.com"
|
|
```
|
|
|
|
### `withQuery(input, query)`
|
|
|
|
Add/Replace the query section of the URL.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withQuery("/foo?page=a", { token: "secret" }); // "/foo?page=a&token=secret"
|
|
```
|
|
|
|
### `withTrailingSlash(input, respectQueryAndFragment?)`
|
|
|
|
Ensures the URL ends with a trailing slash.
|
|
|
|
If second argument is `true`, it will only add the trailing slash if it's not part of the query or fragment with cost of more expensive operation.
|
|
|
|
**Example:**
|
|
|
|
```js
|
|
withTrailingSlash("/foo"); // "/foo/"
|
|
|
|
withTrailingSlash("/path?query=true", true); // "/path/?query=true"
|
|
```
|
|
|
|
<!-- /automd -->
|
|
|
|
## License
|
|
|
|
[MIT](./LICENSE)
|
|
|
|
Special thanks to Eduardo San Martin Morote ([posva](https://github.com/posva)) for [encoding utilities](https://github.com/vuejs/vue-router-next/blob/v4.0.1/src/encoding.ts)
|
|
|
|
<!-- Badges -->
|
|
|
|
[npm-version-src]: https://img.shields.io/npm/v/ufo?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[npm-version-href]: https://npmjs.com/package/ufo
|
|
[npm-downloads-src]: https://img.shields.io/npm/dm/ufo?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[npm-downloads-href]: https://npmjs.com/package/ufo
|
|
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/ufo/main?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[codecov-href]: https://codecov.io/gh/unjs/ufo
|
|
[bundle-src]: https://img.shields.io/bundlephobia/minzip/ufo?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[bundle-href]: https://bundlephobia.com/result?p=ufo
|