urlcat 是一个小型的 JavaScript 库,它使构建 URL 十分不便并避免常见谬误。
个性:
- 敌对的 API
- 无依赖
- 压缩后 0.8KB 大小
- 提供 TypeScript 类型
为什么用?
在调用 HTTP API 时,通常须要在 URL 中增加动静参数:
const API_URL = 'https://api.example.com/';
function getUserPosts(id, blogId, limit, offset) {const requestUrl = `${API_URL}/users/${id}/blogs/${blogId}/posts?limit=${limit}&offset=${offset}`;
// send HTTP request
}
正如你所看到的,这个最小的例子曾经很难浏览了。这也是不正确的:
- 我遗记了
API_URL
常量开端有一个斜杠,所以这导致了一个蕴含反复斜杠的 URL(https://api.example.com//users
) - 嵌入的值须要应用
encodeURIComponent
进行本义
我能够应用内置的 URL
类来避免反复的斜杠和 URLSearchParams
来本义查问字符串。但我依然须要手动本义所有门路参数。
const API_URL = 'https://api.example.com/';
function getUserPosts(id, blogId, limit, offset) {const escapedId = encodeURIComponent(id);
const escapedBlogId = encodeURIComponent(blogId);
const path = `/users/${escapedId}/blogs/${escapedBlogId}`;
const url = new URL(path, API_URL);
url.search = new URLSearchParams({limit, offset});
const requestUrl = url.href;
// send HTTP request
}
如此简略的工作,却又很难读,写也很乏味!这是这个小型库能够帮忙您的中央:
const API_URL = 'https://api.example.com/';
function getUserPosts(id, limit, offset) {const requestUrl = urlcat(API_URL, '/users/:id/posts', { id, limit, offset});
// send HTTP request
}
这个库会这样解决:
- 本义所有参数
- 将所有局部连接起来(它们之间总是正好有一个
/
和?
)
如何应用?
目前,该软件包通过 npm 散发。(Zip 下载和 CDN 行将推出)。
npm install --save urlcat
在 Node.js 中应用
官网反对 Node 10 及更高版本。因为代码在外部应用 URL 和 URLSearchParams 类,它们在 v10 以下不可用,因而咱们无奈反对这些版本。
要构建残缺的 URL(最常见的用例):
const urlcat = require('urlcat').default;
要应用任何一个实用函数:
const {query, subst, join} = require('urlcat');
要应用所有导出的函数:
const {default: urlcat, query, subst, join} = require('urlcat');
在 Typescript 中应用
官网反对 TypeScript 2.1 及更高版本。
要构建残缺的 URL(最常见的用例):
import urlcat from 'urlcat';
要应用任何一个实用函数:
import {query, subst, join} from 'urlcat';
要应用所有导出的函数:
import urlcat, {query, subst, join} from 'urlcat';
在 Deno 中应用
import urlcat from 'https://deno.land/x/urlcat/src/index.ts';
console.log(urlcat('https://api.foo.com', ':name', { id: 25, name: 'knpwrs'}));
API
ParamMap:具备字符串键的对象
例如,{firstParam: 1, 'second-param': 2}
是一个无效的 ParamMap。
urlcat:构建残缺的 URL
function urlcat(baseUrl: string, pathTemplate: string, params: ParamMap): string
function urlcat(baseUrl: string, pathTemplate: string): string
function urlcat(baseTemplate: string, params: ParamMap): string
例如:
urlcat('https://api.example.com', '/users/:id/posts', { id: 123, limit: 10, offset: 120})
→'https://api.example.com/users/123/posts?limit=10&offset=120'
urlcat('http://example.com/', '/posts/:title', { title: 'Letters &"Special"Characters'})
→'http://example.com/posts/Letters%20%26%20%22Special%22%20Characters'
urlcat('https://api.example.com', '/users')
→'https://api.example.com/users'
urlcat('https://api.example.com/', '/users')
→'https://api.example.com/users'
urlcat('http://example.com/', '/users/:userId/posts/:postId/comments', { userId: 123, postId: 987, authorId: 456, limit: 10, offset: 120})
→'http://example.com/users/123/posts/987/comments?authorId=456&limit=10&offset=120'
query:构建查问字符串
应用指定的键值对构建查问字符串。键和值被本义,而后由 '&'
字符连贯。
例如:
params |
result |
---|---|
{} |
'' |
{query: 'some text'} |
'query=some%20text' |
{id: 42, 'comment-id': 86} |
'id=42&comment-id=86' |
{id: 42, 'a name': 'a value'} |
'id=42&a%20name=a%20value' |
subst:替换门路参数
用模板字符串中的值替换参数。模板可能蕴含 0 个或多个参数占位符。占位符以冒号 (:
) 结尾,后跟只能蕴含大写或小写字母的参数名称。在模板中找到的任何占位符都将替换为 params
中相应键下的值。
例如
template |
params |
result |
---|---|---|
':id' |
{id: 42} |
'42' |
'/users/:id' |
{id: 42} |
'/users/42' |
'/users/:id/comments/:commentId' |
{id: 42, commentId: 86} |
'/users/42/comments/86' |
'/users/:id' |
{id: 42, foo: 'bar'} |
'/users/42' |
join:应用一个分隔符连贯两个字符串
仅应用一个分隔符连贯两个局部。如果分隔符呈现在 part1
的开端或 part2
的结尾,则将其删除,而后应用分隔符连贯两个局部。
例如:
part1 |
separator |
part2 |
result |
---|---|---|---|
'first' |
',' |
'second' |
'first,second' |
'first,' |
',' |
'second' |
|
'first' |
',' |
',second' |
|
'first,' |
',' |
',second' |
Github 库地址:https://github.com/balazsboto…