@nullzero/urlcat

Tiny URL builder. Two call shapes:

cat(base, params)                       // append query string
cat(base, pathTemplate, params)         // substitute path tokens, then append leftover as query

Path tokens and query keys/values are URL-encoded. Empty / null / undefined values are skipped from the query.

Install

npm i @nullzero/urlcat

Usage

Query string

import cat from '@nullzero/urlcat';

cat('https://api.example.com/v1/users', {
  page: 1,
  perPage: 25,
  q: 'hello world',
});
// → "https://api.example.com/v1/users?page=1&perPage=25&q=hello%20world"

Path tokens

cat('https://api.example.com', '/users/:userId/posts', {
  userId: 'u_42',
  filter: 'published',
});
// → "https://api.example.com/users/u_42/posts?filter=published"

Tokens look like :name and consume the matching key from params. Any leftover keys become the query string.

Etherscan-style endpoint

cat(process.env.EXPLORER_API_BASE, {
  module: 'account',
  action: 'txlistinternal',
  address,
  apikey: process.env.EXPLORER_API_KEY,
});

Repeated query values

cat('/search', { tag: ['eth', 'l2', 'mev'] });
// → "/search?tag=eth&tag=l2&tag=mev"

API

cat(base: string, params: Params): string
cat(base: string, pathTemplate: string, params?: Params): string

cat.query(params): string     // build a query string only
cat.encode(value): string     // URL-encode a path segment
cat.append(url, query): string
cat.join(base, path): string

Behavior notes

• Existing ? in base is honored — extra params are appended with &.
• Absolute path (https://…) overrides base.
• Trailing / on base and leading / on path are normalized.
• null / undefined / '' values are dropped from the query.

License

MIT.