Installation

# Preserve existing imports with an npm alias
npm install url@npm:@stackline/url@1.0.0
# Or use the scoped package name in your imports
npm install @stackline/url@1.0.0

Node.js: >= 0.4. Read the compatibility and maintenance notes before migrating.

Usage and API

The reference below may retain upstream package names. Use the alias installation above to run those imports with this Stackline release.

@stackline/url

Independent maintenance fork of url@0.11.4, preserving its API and published type declarations.

npm install @stackline/url
# Keep existing imports:
npm install url@npm:@stackline/url@1.0.0

Stackline · Issues · Community

See UPSTREAM.md for source identity and issue review, and CHANGELOG.md for maintenance changes. Functional tests also run against the final npm tarball; releases are published from GitHub Actions with provenance.

Upstream documentation

node-url

This module has utilities for URL resolution and parsing meant to have feature parity with node.js core url module.

var url = require('url');

api

Parsed URL objects have some or all of the following fields, depending on whether or not they exist in the URL string. Any parts that are not in the URL string will not be in the parsed object. Examples are shown for the URL

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

• href: The full URL that was originally parsed. Both the protocol and host are lowercased.

  Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

• protocol: The request protocol, lowercased.

  Example: 'http:'

• host: The full lowercased host portion of the URL, including port information.

  Example: 'host.com:8080'

• auth: The authentication information portion of a URL.

  Example: 'user:pass'

• hostname: Just the lowercased hostname portion of the host.

  Example: 'host.com'

• port: The port number portion of the host.

  Example: '8080'

• pathname: The path section of the URL, that comes after the host and before the query, including the initial slash if present.

  Example: '/p/a/t/h'

• search: The 'query string' portion of the URL, including the leading question mark.

  Example: '?query=string'

• path: Concatenation of pathname and search.

  Example: '/p/a/t/h?query=string'

• query: Either the 'params' portion of the query string, or a querystring-parsed object.

  Example: 'query=string' or {'query':'string'}

• hash: The 'fragment' portion of the URL including the pound-sign.

  Example: '#hash'

The following methods are provided by the URL module:

url.parse(urlStr, [parseQueryString], [slashesDenoteHost])

Take a URL string, and return an object.

Pass true as the second argument to also parse the query string using the querystring module. Defaults to false.

Pass true as the third argument to treat //foo/bar as { host: 'foo', pathname: '/bar' } rather than { pathname: '//foo/bar' }. Defaults to false.

url.format(urlObj)

Take a parsed URL object, and return a formatted URL string.

• href will be ignored.
• protocol is treated the same with or without the trailing : (colon).
  • The protocols http, https, ftp, gopher, file will be postfixed with :// (colon-slash-slash).
  • All other protocols mailto, xmpp, aim, sftp, foo, etc will be postfixed with : (colon)
• auth will be used if present.
• hostname will only be used if host is absent.
• port will only be used if host is absent.
• host will be used in place of hostname and port
• pathname is treated the same with or without the leading / (slash)
• search will be used in place of query
• query (object; see querystring) will only be used if search is absent.
• search is treated the same with or without the leading ? (question mark)
• hash is treated the same with or without the leading # (pound sign, anchor)

url.resolve(from, to)

Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag. Examples:

url.resolve('/one/two/three', 'four')         // '/one/two/four'
url.resolve('http://example.com/', '/one')    // 'http://example.com/one'
url.resolve('http://example.com/one', '/two') // 'http://example.com/two'

Upstream issues and maintenance review

Upstream review

This independent fork preserves the legacy url@0.11.4 API, not the WHATWG URL constructor. Source: https://github.com/defunctzombie/node-url/tree/455a3e2106bf254498615efc50a8dd5527be4132. Original license and authors are retained. The exact npm artifact and file hashes are recorded in .stackline/upstream.json.

Open issue triage

Reviewed the open issue bodies collected on 2026-09-29:

• #32: reproduced protocol case changing the hostless payload. Normalize before protocol-table lookups; regression tests cover lower, upper and mixed case.
• #48: reproduced ignored slashes:false for a protocol-less host. Fixed with explicit false/true/default and https/mailto regressions.
• #25: array and nested-object serialization already works in 0.11.4 through qs. No change or claim of a new fix.
• #35: ws protocol parsing works for the reported protocol shape on this base. No new fix claimed.
• #5 and #40 concern interpreting strings without a protocol as a hostname. The legacy parser deliberately accepts relative paths; changing this heuristic is outside a compatible maintenance release.
• #33, #36, #37 and #63 request WHATWG URL/searchParams/pathToFileURL APIs absent from the selected legacy contract. No unsupported new export is advertised.
• #24 and #53 request a newer base or roadmap. The original consumer needs the existing legacy API; this release documents an explicit maintained compatibility line.
• #75 requests release notes. This fork adds CHANGELOG and immutable GitHub releases.

Upstream functional tests and the focused regressions run against source and the final tarball. Full dependency audits, CI, CodeQL, exact artifact/provenance verification and direct/aliased installs gate the GitHub publication. No claims about unsupported APIs or exhaustive historical issue coverage are made.

Release changes

Changelog

1.0.0

• Fix protocol-case handling for hostless URLs (upstream #32).

• Respect slashes:false when formatting protocol-less hostnames (upstream #48).

• Start Stackline maintenance of the documented upstream API.

• Preserve and verify published runtime files and TypeScript declarations.

• Run upstream functional suites against both source and the final package.

• Publish the reviewed CI artifact through GitHub Actions with provenance and immutable release evidence.

• Encode every hash in query strings, preventing accidental fragment creation. Preserve the single username/password separator with an explicit, tested operation.

Release files and references

• README.md
• UPSTREAM.md
• CHANGELOG.md
• LICENSE
• NOTICE
• Package and publication metadata
• Full text documentation

Package bytes, npm provenance and the immutable GitHub release were verified for this version. Security checks describe the reviewed release; documented compatibility risks and upstream reports are not blanket claims of resolution.