JSC Safe URL Utilities

Common errors

• TypeError: isJscSafeUrl is not a function

  cause The utility functions are named exports, but an incorrect import statement (e.g., default import or CommonJS `require` without `.functionName`) was used.
  fix Ensure you are using named imports for ESM: `import { isJscSafeUrl, toJscSafeUrl } from 'jsc-safe-url';` or for CommonJS: `const { isJscSafeUrl } = require('jsc-safe-url');`

• URL unexpectedly contains '//&' in path component

  cause A URL encoded using `toJscSafeUrl()` was consumed by a part of the application or an external system that does not understand this custom encoding and expects a standard URL format.
  fix Before using a `jsc-safe-url` in contexts outside of the specific JSC error stack reporting, always convert it back to a standard URL using `toNormalUrl(jscSafeUrl)`.

Warnings

• gotcha JavaScriptCore (JSC) environments, such as those used in React Native, sanitize source URLs in error stacks by stripping query strings and URL fragments. This behavior means that valuable debugging context (e.g., `?platform=ios`) will be lost unless URLs are explicitly encoded.
  Fix: Use `toJscSafeUrl(url)` to encode URLs before they are processed by JSC-based environments, typically when generating source maps or error reports. Use `toNormalUrl(jscSafeUrl)` to revert them if the original query string is needed elsewhere.
• gotcha The custom `//&` delimiter used to embed query strings into the path is specific to `jsc-safe-url`. Using URLs containing this delimiter directly in systems that expect standard URL formats (e.g., HTTP clients, web servers, other URL parsers) may lead to incorrect routing, file not found errors, or unexpected behavior.
  Fix: Always call `toNormalUrl()` before passing a URL that was previously converted with `toJscSafeUrl()` to any external system or component that expects a standard, RFC-compliant URL format. Only use the JSC-safe format where specifically required by the JSC environment.

Install

• npm install jsc-safe-url npm
• yarn add jsc-safe-url yarn
• pnpm add jsc-safe-url pnpm

Imports

• toJscSafeUrl
  wrong:

  const toJscSafeUrl = require('jsc-safe-url').toJscSafeUrl;

  correct:

  import { toJscSafeUrl } from 'jsc-safe-url';

  Package primarily uses named exports. Supports TypeScript.
• toNormalUrl
  wrong:

  import toNormalUrl from 'jsc-safe-url/toNormalUrl';

  correct:

  import { toNormalUrl } from 'jsc-safe-url';

  All utility functions are named exports from the root package.
• isJscSafeUrl
  wrong:

  import * as jscSafeUrl from 'jsc-safe-url'; jscSafeUrl.isJscSafeUrl(...);

  correct:

  import { isJscSafeUrl } from 'jsc-safe-url';

  While star imports work, direct named imports are preferred for clarity and tree-shaking.

Quickstart

Demonstrates how to convert a standard URL into a JSC-safe format, verify its safety, and then convert it back to its original form, showcasing the package's primary utilities.

import { toJscSafeUrl, toNormalUrl, isJscSafeUrl } from 'jsc-safe-url';

// An example URL that would have its query string stripped by JavaScriptCore
const originalUrl = 'https://my-app.com/bundle.js?platform=ios&dev=true#source-map-id';

console.log(`Original URL: ${originalUrl}`);

// Check if the URL is currently "JSC-safe" (it shouldn't be)
console.log(`Is original URL JSC-safe? ${isJscSafeUrl(originalUrl)}`);
// Expected output: Is original URL JSC-safe? false

// Convert the URL to a JSC-safe format, embedding query params into the path
const jscSafeUrl = toJscSafeUrl(originalUrl);
console.log(`JSC-safe URL: ${jscSafeUrl}`);
// Expected output: JSC-safe URL: https://my-app.com/bundle.js//&platform=ios&dev=true#source-map-id

// Verify the new URL is considered JSC-safe
console.log(`Is JSC-safe URL truly JSC-safe? ${isJscSafeUrl(jscSafeUrl)}`);
// Expected output: Is JSC-safe URL truly JSC-safe? true

// Convert the JSC-safe URL back to its original, normal form
const normalUrl = toNormalUrl(jscSafeUrl);
console.log(`Normal URL after conversion: ${normalUrl}`);
// Expected output: Normal URL after conversion: https://my-app.com/bundle.js?platform=ios&dev=true#source-map-id

// Verify that the restored URL is identical to the original
console.log(`URLs match after round-trip: ${originalUrl === normalUrl}`);
// Expected output: URLs match after round-trip: true

// Example with a URL that has no query string initially
const urlWithoutQuery = 'https://my-app.com/no-query.js';
console.log(`\nIs URL without query JSC-safe? ${isJscSafeUrl(urlWithoutQuery)}`);
// Expected output: Is URL without query JSC-safe? true
console.log(`toJscSafeUrl on no query: ${toJscSafeUrl(urlWithoutQuery)}`);
// Expected output: toJscSafeUrl on no query: https://my-app.com/no-query.js