simple-url-stringify

A lightweight utility for building URLs with path params and query strings.

Install

npm i simple-url-stringify

Usage

import { urlStringify } from 'simple-url-stringify';

Query String

Basic query string serialization. undefined values are automatically omitted.

urlStringify({
  url: '/api/users',
  query: { page: 1, size: 10 }
});
// '/api/users?page=1&size=10'

urlStringify({
  url: '/api/users',
  query: { page: undefined, size: 10 }
});
// '/api/users?size=10'

Nested objects are serialized using dot notation by default (allowDots: true).

urlStringify({
  url: '/api/users',
  query: { filter: { name: 'foo', age: 20 } }
});
// '/api/users?filter.name=foo&filter.age=20'

Disable dot notation to get bracket encoding instead:

urlStringify({
  url: '/api/users',
  query: { filter: { name: 'foo', age: 20 } }
}, { allowDots: false });
// '/api/users?filter%5Bname%5D=foo&filter%5Bage%5D=20'

Path Params

Replace path placeholders with values. Default delimiters are { and }.

urlStringify({
  url: '/api/users/{id}/posts/{postId}',
  params: { id: 1, postId: 42 }
});
// '/api/users/1/posts/42'

Customize delimiters via options:

urlStringify({
  url: '/api/users/[id]/posts/[postId]',
  params: { id: 1, postId: 42 }
}, {
  paramsTemplatePrefix: '\\[',
  paramsTemplateSuffix: '\\]'
});
// '/api/users/1/posts/42'

Combined

urlStringify({
  url: '/api/users/{id}/posts',
  params: { id: 1 },
  query: { page: 1, size: 10 }
});
// '/api/users/1/posts?page=1&size=10'

API

urlStringify(args, options?)

Args:

| Property | Type | Description | |----------|------|-------------| | url | string | Base URL path | | query | Record<string, any> | Query parameters (undefined values are omitted) | | params | Record<string, any> | Path parameters to interpolate into the URL |

Options:

| Property | Type | Default | Description | |----------|------|---------|-------------| | allowDots | boolean | true | Use dot notation for nested objects in query strings | | paramsTemplatePrefix | string | '{' | Left delimiter for path parameter placeholders | | paramsTemplateSuffix | string | '}' | Right delimiter for path parameter placeholders |

License

MIT