api.md

API

ParamMap: an object with string keys

type ParamMap = Record<string, any>;

For example, { firstParam: 1, 'second-param': 2 } is a valid ParamMap.

urlcat: build full URLs

function urlcat(baseUrl: string, pathTemplate: string, params: ParamMap): string
function urlcat(baseUrl: string, pathTemplate: string): string
function urlcat(baseTemplate: string, params: ParamMap): string

Examples

• 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'

NOTE about empty path segments: RFC 3986 allows empty path segments in URLs (for example, https://example.com//users////2). urlcat keeps any empty path segments that aren't at the concatenation boundary between baseUrl and pathTemplate. If you need to include an empty path segment there, you have two options:

• use a double slash: urlcat('https://example.com/', '//users', { q: 1 }) → https://example.com//users?q=1
• use the baseTemplate overload: urlcat('https://example.com//users', { q: 1 }) → https://example.com//users?q=1

query: build query strings

function query(params: ParamMap): string

Builds a query string using the key-value pairs specified. Keys and values are escaped, then joined by the '&' character.

Examples

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: substitute path parameters

function subst(template: string, params: ParamMap): string

Substitutes parameters with values in a template string. template may contain 0 or more parameter placeholders. Placeholders start with a colon (:), followed by a parameter name that can only contain uppercase or lowercase letters. Any placeholders found in the template are replaced with the value under the corresponding key in params.

Examples

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: join two strings using exactly one separator

function join(part1: string, separator: string, part2: string): string

Joins the two parts using exactly one separator. If a separator is present at the end of part1 or the beginning of part2, it is removed, then the two parts are joined using separator.

Examples

part1	separator	part2	result
'first'	','	'second'	'first,second'
'first,'	','	'second'
'first'	','	',second'
'first,'	','	',second'