URL to HTTP Options Converter

Common errors

• TypeError: Invalid URL object provided

  cause 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

  cause 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.

Warnings

• gotcha The 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');`.
• gotcha The `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);`.
• gotcha The 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.

Install

• npm install url-to-options npm
• yarn add url-to-options yarn
• pnpm add url-to-options pnpm

Imports

• urlToOptions
  wrong:

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

  correct:

  import urlToOptions from '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)
  wrong:

  import urlToOptions from 'url-to-options';

  correct:

  const urlToOptions = require('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)
  wrong:

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

  correct:

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

  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.

Quickstart

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();