v0.3.1 · MIT Licensed

Type-safe URLs
for TypeScript

Build URLs with confidence. Path parameters are inferred from your template strings, and extra params become query strings automatically.

See it in actionnpm
$ npm install @bearstudio/lunalink

Demo

See it in action

simple-params.ts
const path = "/contacts/:id";

// Type is inferred as { id: string }
const url = lunalink(path, {
  id: "4F82CDA2-B869-48A2-A829-F161DB6A94DA",
});
Output/contacts/4F82CDA2-B869-48A2-A829-F161DB6A94DA
query-params.ts
// Extra params are automatically added as query strings
const url = lunalink("/contacts/:id", {
  id: "4F82CDA2",
  search: "FirstName",
  page: "1",
});
Output/contacts/4F82CDA2?page=1&search=FirstName
nested-params.ts
// Multiple path parameters, all type-checked
const url = lunalink("/api/users/:userId/posts/:postId", {
  userId: "42",
  postId: "7",
});
Output/api/users/42/posts/7

Features

Why lunalink?

{T}

Type-safe parameters

Path parameters are extracted from your template string at the type level. Miss a param and TypeScript will tell you.

?=

Auto query strings

Any extra params that don't match a path placeholder are automatically appended as query string parameters.

<1kb

Lightweight

Tiny footprint with zero unnecessary overhead. Ships ESM and CJS so it works everywhere.

://

Base URL support

Pass a baseURL in the config to automatically join your API root with the constructed path.

#!

Custom encoding

Bring your own encodeURIComponent function for full control over how parameters are escaped.

/:

Flexible patterns

Supports params separated by slashes, dots, and optional trailing markers. Covers real-world URL patterns.