{"id":30740334,"url":"https://github.com/ignacio-nacho-barbano/loveurl","last_synced_at":"2025-09-04T00:03:34.012Z","repository":{"id":304738405,"uuid":"1019812147","full_name":"ignacio-nacho-barbano/loveUrl","owner":"ignacio-nacho-barbano","description":"A url builder and parser pack for handling url states in an easy way.","archived":false,"fork":false,"pushed_at":"2025-09-02T12:24:11.000Z","size":129,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-04T00:01:55.547Z","etag":null,"topics":["builder","javascript","love","npm","open-source","params","parser","searchparams","string","uri","url","validations","validator"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/loveurl","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ignacio-nacho-barbano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ignacio-nacho-barbano","custom":"https://paypal.me/IgnacioRBarbano?country.x=UY\u0026locale.x=es_XC"}},"created_at":"2025-07-14T23:15:13.000Z","updated_at":"2025-09-02T12:24:14.000Z","dependencies_parsed_at":"2025-07-15T02:51:25.006Z","dependency_job_id":"57935749-5930-404d-bd0c-724c35191596","html_url":"https://github.com/ignacio-nacho-barbano/loveUrl","commit_stats":null,"previous_names":["ignacio-nacho-barbano/loveurl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ignacio-nacho-barbano/loveUrl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignacio-nacho-barbano%2FloveUrl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignacio-nacho-barbano%2FloveUrl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignacio-nacho-barbano%2FloveUrl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignacio-nacho-barbano%2FloveUrl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ignacio-nacho-barbano","download_url":"https://codeload.github.com/ignacio-nacho-barbano/loveUrl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ignacio-nacho-barbano%2FloveUrl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273529550,"owners_count":25121828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["builder","javascript","love","npm","open-source","params","parser","searchparams","string","uri","url","validations","validator"],"created_at":"2025-09-04T00:01:25.810Z","updated_at":"2025-09-04T00:03:33.976Z","avatar_url":"https://github.com/ignacio-nacho-barbano.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ignacio-nacho-barbano","https://paypal.me/IgnacioRBarbano?country.x=UY\u0026locale.x=es_XC"],"categories":[],"sub_categories":[],"readme":"# loveUrl\n\nA URL builder and parser pack for handling URL states the easy way.\n\n---\n\n### 📦 Installation\n\nUsing npm:\n\n```bash\nnpm install love-url\n```\n\nUsing yarn:\n\n```bash\nyarn add love-url\n```\n\nUsing pnpm:\n\n```bash\npnpm add love-url\n```\n\n---\n\n### ⚡ TL;DR — Quick Usage\n\n```ts\ntype MyParams = {\n  showDetails: boolean;\n  page: number;\n  tags: string[];\n  status: \"draft\" | \"published\" | \"archived\";\n};\n\n// Encode to URL\n// existing params PRESERVED\n// currentPath PRESERVED\nconst url = loveUrl\u003cMyParams\u003e({\n  showDetails: true,\n  page: 2,\n  tags: [\"food\", \"travel\"],\n  status: \"published\",\n  // This param will be removed\n  car: undefined,\n});\n\n// Pre-existing params ?name=bob\u0026car=fiat%20multipla\u0026page=1\n/*\n  url = \"/current-path?name=bob\u0026showDetails=true\u0026page=2\u0026tags=_._food_._travel\u0026status=published\"\n*/\n\n// Encode to URL (existing params REMOVED)\nconst url = loveUrl\u003cMyParams\u003e(\n  {\n    showDetails: true,\n    page: 2,\n    tags: [\"food\", \"travel\"],\n    status: \"published\",\n  },\n  {\n    currentParams: null,\n    url: \"/route-somewhere-else\",\n  }\n);\n\n// Pre-existing params ?name=bob\u0026page=1\n/*\n  url = \"/route-somewhere-else?showDetails=true\u0026page=2\u0026tags=_._food_._travel\u0026status=published\"\n*/\n\n// Decode from URL\nconst parsed = parseLoveUrl\u003cMyParams\u003e(\n  \"?showDetails=true\u0026page=2\u0026tags=_._food_._travel\u0026status=published\"\n  // or window.location.search\n);\n\n/*\n  parsed = {\n    showDetails: true,\n    page: 2,\n    tags: [\"food\", \"travel\"],\n    status: \"published\"\n  }\n*/\n```\n\n---\n\n### 🧠 Tip\n\n- Arrays are encoded using a custom separator: `_._`  \n  This ensures:\n  - Consistent decoding even with a single item (`tags=_._design` → `[\"design\"]`)\n  - Reliable parsing when array items contain commas\n- Booleans and numbers are parsed and typed automatically\n- Invalid values (e.g., `status=broken`) will be parsed as `strings` unless custom validation is added\n\n---\n\n### 🚀 Motivation\n\n**loveUrl** aims to simplify the common headaches when building and parsing URLs with parameters in modern JavaScript projects.\n\n---\n\n### 🔧 Key Use Cases\n\n#### 1. **Building dynamic URLs that preserve client-side state**\n\nImagine your user is at `/currentPath/example` and the current URL params are:\n\n`fileType=photo\u0026selectedPeriod=weekly`\n\nInstead of manually constructing links, you can just use:\n\n```tsx\nconst ExampleComponent = () =\u003e (\n  \u003cdiv\u003e\n    {/* Renders: /currentPath/example?fileType=photo\u0026selectedOption=option1\u0026selectedPeriod=weekly */}\n    \u003ca href={loveUrl({ selectedOption: \"option1\" })}\u003eOption 1\u003c/a\u003e\n\n    {/* Renders: /currentPath/example?fileType=photo\u0026selectedOption=option2\u0026selectedPeriod=weekly */}\n    \u003ca href={loveUrl({ selectedOption: \"option2\" })}\u003eOption 2\u003c/a\u003e\n\n    {/* Renders: /currentPath/example?fileType=photo\u0026selectedPeriod=weekly */}\n    \u003ca href={loveUrl({ selectedOption: undefined })}\u003eClear\u003c/a\u003e\n  \u003c/div\u003e\n);\n```\n\n---\n\n#### 2. **Building and fetching dynamic URLs for APIs**\n\nBuilding parameterized API URLs manually can get messy:\n\n```ts\ntype DynamicDataOptions = {\n  startDate?: string;\n  endDate?: string;\n  format?: \"photos\" | \"videos\";\n  limit: number;\n};\n\nconst fetchDynamicData = (params: DynamicDataOptions) =\u003e {\n  let dataUrl = \"https://api.my-project/files/archive\";\n\n  // Prevent undefined values from appearing in the query string\n  for (const key in params) {\n    if (params[key] === undefined) {\n      delete params[key];\n    }\n  }\n\n  const queryString = new URLSearchParams(params).toString();\n  if (queryString) dataUrl += `?${queryString}`;\n\n  const req = await fetch(dataUrl);\n  return await req.json();\n};\n```\n\nOr even worse:\n\n```ts\nconst fetchDynamicData = ({\n  startDate,\n  endDate,\n  format,\n  limit,\n}: DynamicDataOptions) =\u003e {\n  const req = await fetch(\n    `https://api.my-project/files/archive?startDate=${startDate}\u0026endDate=${endDate}\u0026format=${format}\u0026limit=${limit}`\n  );\n\n  return await req.json();\n};\n```\n\n**Imagine doing this with 12+ parameters 😭**\n\n---\n\n#### ✅ With loveUrl:\n\n```ts\nconst fetchDynamicData = (params: DynamicDataOptions) =\u003e {\n  const req = await fetch(\n    loveUrl(params, { url: \"https://api.my-project/files/archive\" })\n  );\n\n  return await req.json();\n};\n```\n\nClean. Type-safe. No string interpolation errors.\n\n---\n\n#### 3. **Parsing URL params without the chaos**\n\nHandling conversions manually can quickly get out of hand:\n\n```tsx\nconst ComponentThatUsesParams = () =\u003e {\n  const params = new URLSearchParams(window.location.search);\n\n  const myBoolean = params.get(\"myBoolean\") === \"true\"; // string 'false' is truthy 😬\n  const limit = parseInt(params.get(\"limit\"));\n  const percentage = parseFloat(params.get(\"percentage\"));\n  let favoriteFoods = params.get(\"favoriteFoods\");\n\n  if (favoriteFoods?.includes(\",\")) {\n    favoriteFoods = favoriteFoods.split(\",\");\n  }\n\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eMy Params as an object:\u003c/h1\u003e\n      \u003ccode\u003e\n        {JSON.stringify({\n          myBoolean,\n          limit,\n          percentage,\n        })}\n      \u003c/code\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\n---\n\n#### ✅ With loveUrl:\n\n```tsx\nconst ComponentThatUsesParams = () =\u003e {\n  const { myBoolean, limit, percentage, favoriteFoods } = parseLoveUrl\u003c{\n    myBoolean: boolean;\n    limit: number;\n    percentage: number;\n    favoriteFoods: string[];\n  }\u003e(window.location.search);\n\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eMy Params as an object:\u003c/h1\u003e\n      \u003ccode\u003e\n        {JSON.stringify({\n          myBoolean,\n          limit,\n          percentage,\n        })}\n      \u003c/code\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\nType-safe, clean, and handles all conversions for you.\n\n---\n\n### ❤️ Why you'll love loveUrl\n\n- Automatically ignores `undefined` values\n- Handles complex param types like arrays, numbers, and booleans\n- Uses a custom array separator (`_._`) for full consistency\n- Prevents messy string interpolation\n- Decodes and encodes with full TypeScript support\n- Deals with duplicate params gracefully\n- Keeps your URLs and logic clean and reliable\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fignacio-nacho-barbano%2Floveurl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fignacio-nacho-barbano%2Floveurl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fignacio-nacho-barbano%2Floveurl/lists"}