URL Value Replacer

Common errors

• TypeError: replaceUrlValues is not a function

  cause The 'replaceUrlValues' function was not correctly imported or does not exist as a named export. This can happen if the package uses a default export, or if the import path is incorrect.
  fix Try importing as a default export: `import replaceUrlValues from 'replace-url-values';` or verify the correct named export from the package's documentation/source code. Ensure the package is installed correctly.

• URIError: URI malformed

  cause This error typically occurs if a string passed to an internal URL encoding/decoding function is not valid. It might indicate that the input URL or a replacement value caused an intermediate malformed URI.
  fix Inspect the input URL and all replacement values for invalid characters or malformed segments that could prevent proper parsing or encoding. Ensure all string inputs are well-formed before passing them to the utility.

Warnings

• gotcha When replacing values, ensure that the new values are correctly URL-encoded, especially if they contain special characters or spaces. While the utility is expected to handle this automatically, improper input can lead to malformed URLs or unexpected behavior.
  Fix: Always pass raw, unencoded string values to the replacement function. The library should handle encoding automatically. If not, manually encode values using `encodeURIComponent()` before passing them.
• gotcha URL objects are often immutable in browsers and Node.js (e.g., `URL` API). This utility is expected to return a *new* string or URL instance after replacement, rather than modifying the input URL object in place. Always assign the return value.
  Fix: Store the result of `replaceUrlValues` in a new variable: `const newUrl = replaceUrlValues(originalUrl, replacements);`
• gotcha Be mindful of ambiguous placeholder patterns (e.g., multiple ':' characters, or similar query parameter keys). The specific replacement logic for complex URL structures might have edge cases not immediately obvious from a simple API.
  Fix: Test complex URL patterns thoroughly. Review the library's source code or documentation (if it becomes available) for exact parsing and replacement rules. Consider using more distinct placeholder names in templates.

Install

• npm install replace-url-values npm
• yarn add replace-url-values yarn
• pnpm add replace-url-values pnpm

Imports

• replaceUrlValues
  wrong:

  const replaceUrlValues = require('replace-url-values');

  correct:

  import { replaceUrlValues } from 'replace-url-values';

  The package is assumed to primarily offer a named export 'replaceUrlValues' for its core functionality, given its TypeScript support and common patterns for modern JavaScript utilities. CommonJS require is likely not supported directly without bundler configuration.
• replaceUrlValues
  wrong:

  import { replaceUrlValues } from 'replace-url-values';

  correct:

  import replaceUrlValues from 'replace-url-values';

  If the package uses a default export, this would be the correct syntax. Verify package.json 'type' field and export style if available, as 'replace-url-values' might use a default export.
• All exports

  import * as UrlReplacer from 'replace-url-values';

  Useful for accessing all exported utilities under a namespace, if multiple functions are exposed. This assumes named exports.

Quickstart

Demonstrates replacing both path placeholders and query parameters in a URL string, including adding new parameters and handling URL encoding of replacement values.

import { replaceUrlValues } from 'replace-url-values';

// Example 1: Replacing placeholders in a URL path like '/products/:productId'
const urlTemplateWithPathParams = '/products/:productId/reviews/:reviewId';
const pathReplacements = {
  productId: '456',
  reviewId: '789'
};
const finalUrl1 = replaceUrlValues(urlTemplateWithPathParams, pathReplacements);
console.log('Replaced path URL:', finalUrl1);
// Expected output: /products/456/reviews/789

// Example 2: Replacing specific query parameter values in an existing URL
const urlWithQueryParams = 'https://example.com/search?q=apple&page=1';
const queryReplacements = {
  q: 'banana and orange', // Replace existing 'q'
  page: '2',              // Replace existing 'page'
  sort: 'desc'            // Add a new parameter 'sort'
};
const finalUrl2 = replaceUrlValues(urlWithQueryParams, queryReplacements);
console.log('Replaced query params URL:', finalUrl2);
// Expected output (order might vary, but parameters should be correct):
// https://example.com/search?q=banana%20and%20orange&page=2&sort=desc

// Example 3: Handling missing placeholders gracefully (assumption: no change for unmatched keys)
const incompleteTemplate = '/users/:userId/profile';
const partialReplacements = { userId: '101' };
const finalUrl3 = replaceUrlValues(incompleteTemplate, partialReplacements);
console.log('Partial replacements:', finalUrl3);
// Expected output: /users/101/profile

// Example 4: When no matches are found, the original URL is returned (assumption)
const noMatchUrl = 'https://example.com/data';
const noMatchReplacements = { unknownKey: 'value' };
const finalUrl4 = replaceUrlValues(noMatchUrl, noMatchReplacements);
console.log('No matches:', finalUrl4);