Registry / http-networking / url-to-options

url-to-options

library2.0.0jsnpmunverified

The `url-to-options` package is a focused utility designed to convert a WHATWG `URL` object into a plain JavaScript options object compatible with Node.js's native `http.request` and `https.request` methods. It abstracts the process of extracting host, port, protocol, auth, and path information from a standard URL representation. The current stable version is 2.0.0. Given its specific utility nature, the package is expected to have an infrequent release cadence, primarily for maintenance, bug fixes, or compatibility with newer Node.js versions or WHATWG URL specification changes. Its primary differentiator is its directness in bridging the WHATWG URL standard with Node's built-in HTTP client APIs, providing a clean way to construct request options without manual parsing.

http-networking serialization

npm install url-to-options

github ↗package ↗

INSTALL

IMPORT

SIG · URL-TO-OPTIONS

url-to-options

http-networkingjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

urlToOptions

✓ import urlToOptions from 'url-to-options';

✗ const urlToOptions = require('url-to-options');

For ESM projects, this default import is the correct approach. However, as the package currently ships as CommonJS, you might need a bundler or Node.js's `--experimental-modules` flag (or `type: "module"` in package.json with compatible `exports` field) for direct ESM usage in older Node environments. For Node.js 12.17.0+ or 13.2.0+, CommonJS modules can be imported using `import` in ESM.

urlToOptions (CommonJS)

✓ const urlToOptions = require('url-to-options');

✗ import urlToOptions from 'url-to-options';

This is the documented and primary way to import the utility in CommonJS environments (e.g., Node.js scripts without `"type": "module"` in package.json).

URL (WHATWG global)

✓ const url = new URL('http://example.com');

✗ import { URL } from 'url-to-options';

The `URL` constructor is a global object in Node.js (and browsers) and does not need to be imported from `url-to-options` or Node's built-in `url` module for basic usage. `url-to-options` *consumes* a WHATWG `URL` instance.

This quickstart demonstrates how to convert a WHATWG `URL` instance into an options object suitable for Node.js `http.request` or `https.request`, logging the resulting object.

import urlToOptions from 'url-to-options'; const rawUrl = 'https://user:pass@example.com:8443/api/data?query=test#hash'; const url = new URL(rawUrl); // Convert the WHATWG URL object to http(s).request options const requestOptions = urlToOptions(url); console.log('Original URL:', rawUrl); console.log('Generated Request Options:', requestOptions); /* Example Output: { protocol: 'https:', hostname: 'example.com', auth: 'user:pass', port: 8443, pathname: '/api/data', search: '?query=test', hash: '#hash', path: '/api/data?query=test' } */ // To actually make a request (requires Node.js built-in modules): // import https from 'https'; // // const req = https.request(requestOptions, (res) => { // console.log(`Status: ${res.statusCode}`); // res.on('data', (d) => { // process.stdout.write(d); // }); // }); // req.on('error', (e) => { // console.error(e); // }); // req.end();

Debug

Known issues

gotchaThe package currently primarily targets CommonJS environments. While it can be used in ESM projects via `import urlToOptions from 'url-to-options';`, direct ESM compatibility without bundlers or specific Node.js configuration might be limited in older Node versions. Ensure your build pipeline or Node.js runtime handles CJS interop correctly.

fix

For pure ESM Node.js environments, consider using a bundler like Webpack or Rollup, or ensure your Node.js version is recent enough (e.g., 12.17.0+ or 13.2.0+) for improved CJS-ESM interop. If issues persist, dynamic `import()` might be an option: `const urlToOptions = await import('url-to-options');`.

affects: >=2.0.0

gotchaThe `url-to-options` function strictly expects a WHATWG `URL` object as its input. Passing a plain string, a legacy `url.parse()` object, or any other type will result in a runtime error.

fix

Always construct a `URL` instance before passing it to `urlToOptions`. Example: `const url = new URL('http://example.com'); urlToOptions(url);`.

affects: >=1.0.0

gotchaThe package specifies Node.js `>=8` as a requirement, which is a very old Node.js version. While it should work on modern Node.js versions, this might indicate less frequent updates for cutting-edge Node.js features or specific edge cases that arise in much newer runtimes. Users on very new Node.js versions might encounter minor compatibility quirks (though unlikely for such a focused utility).

fix

For most users, no fix is needed as it's forward compatible. If an issue arises specific to a very new Node.js version, consider reporting it to the maintainer or evaluating if an alternative parsing method is more suitable for your environment.

affects: <=2.0.0

Errors

Common errors & fixes

TypeError: Invalid URL object provided

The `url-to-options` function was called with an argument that is not a valid WHATWG `URL` instance (e.g., a string, null, or undefined).

fix

Ensure you create a `URL` object using `new URL('your-url-string')` before passing it to `url-to-options`. For example: `const myUrl = new URL('https://example.com'); const opts = urlToOptions(myUrl);`

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".js" for /path/to/node_modules/url-to-options/index.js

This error can occur in pure ESM Node.js projects when trying to `require()` a CommonJS module, or if Node.js's module resolution for CommonJS modules in an ESM context is misconfigured. `url-to-options` is likely distributed as CommonJS.

fix

In an ESM project, use the ESM import syntax: `import urlToOptions from 'url-to-options';`. If this still causes issues, check your `package.json` for `"type": "module"` and ensure Node.js is handling CJS interop correctly for your version. You might also need a bundler.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stevenvachon/url-to-options ↗

packagehttps://www.npmjs.com/package/url-to-options ↗