WHATWG URL API performance issue

[SukkaW]

Since hexojs/hexo-util#114, we start to mitigate deprecated Legacy URL API to newer WHATWG URL API. Current status of mitigation can be found at this project board.

In order to fix #3796 (comment), I mitigate external_link filter from Legacy URL API to WHATWG URL API after #3812 & hexojs/hexo-util#119.

But immediately a critical performance issue came up after #3812 is merged (see #3833). @curbengh trying to revert #3812 in #3834) and it seems clear that WHATWG API is the cause.

I have carried out series of test trying to optimize external_link filter (#3839). During the research of WHATWG URL API, I have noticed a comment from maintainer of BootstrapCDN: jsdelivr/bootstrapcdn#1391

While deprecated, it's much cleaner to use this when we have relative URLs. It also appears to be a lot faster.

So I bring up a benchmark:

const Benchmark = require('benchmark');
const Suite = new Benchmark.Suite;
const { parse, URL } = require('url');
const urlObj = (str) => {
  try {
    return new URL(str);
  } catch (e) {
    return str;
  }
};
 
// add tests
Suite.add('Legacy URL parse()', () => {
  parse('https://skk.moe/path/to/something');
  parse('/path/to/something');
}).add('WHATWG URL API', () => {
  new URL('https://skk.moe/path/to/something');
  new URL('/path/to/something', 'https://skk.moe/');
}).add('safe WHATWG URL', () => {
  urlObj('https://skk.moe/path/to/something');
  urlObj('/path/to/something');
}).on('cycle', function(event) {
  console.info(String(event.target));
}).on('complete', function() {
  console.info('Fastest is ' + this.filter('fastest').map('name'));
}).run();

Result is clear, Legacy URL API is at least 4x faster than WHATWG URL API. And the approach (urlObj()) we came up to handle relative URL is even slower:

Based on the benchmark, I bring up 20d4ae4 in #3839 , avoid urlObj() by passing a base to new URL() to handle relative path. The generation performance backs to normal after this commit.

IMHO, although WHATWG URL API is powerful and safer, since the Legacy URL API is much faster and quite useful when handling relative path, we should use WHATWG URL API only when necessary.

Another idea is we should try to avoid urlObj() approach because try ... catch (err) ... is just too expensive. Takes hexojs/hexo-util#114 as an example, for those function that requires bind(hexo)(like full_url_for() and url_for()), we should pass hexo.config.url as a base to new URL() instead of using urlObj().

[stevenjoezhang]

New result of Node.js 25:

❯ node -v
v25.1.0

❯ node bench.js
Legacy URL parse() x 83,364 ops/sec ±2.13% (69 runs sampled)
WHATWG URL API x 1,480,457 ops/sec ±2.19% (95 runs sampled)
safe WHATWG URL x 145,393 ops/sec ±0.84% (97 runs sampled)
Fastest is WHATWG URL API

WHATWG URL API is now much faster

cc @SukkaW @hexojs/core

[SukkaW]

145,393

The try-catch stuff still sucks, and there is no safe way to do new URL() with arbitrary input.

[stevenjoezhang]

I have opened hexojs/hexo-util#449 to raise the minimum Node.js version to 22.1.0 and update the CI matrix to Node.js 22, 24, and 26. Node.js 22.1.0 is the first Node 22 release providing the non-throwing WHATWG URL.parse() API.

Once that PR is merged, I plan to replace all five remaining legacy url.parse() call sites in hexo-util with WHATWG URL.parse(). I also plan to cache the parsed site URL used by url_for(), full_url_for(), and isExternalLink(), avoiding repeated parsing for different paths and links.

I also reran the benchmark on Node.js v26.7.0. Each implementation parsed the same 5,000,000 unique valid absolute URLs, exactly once per input. A separate set of 100,000 unique URLs was used for warm-up. The execution order was alternated over 10 rounds, and both implementations produced identical checksums.

Implementation	Total time	Aggregate throughput	Median
legacy url.parse()	8,548.522 ms	584,896 ops/s	579,865 ops/s
WHATWG URL.parse()	2,747.175 ms	1,820,052 ops/s	1,844,364 ops/s

In this benchmark, URL.parse() was about 3.1× faster than legacy url.parse(). Therefore, on Node.js 26, performance does not appear to be a reason to retain the legacy API.

Benchmark code

const os = require('node:os');
const legacyUrl = require('node:url');

const URLS_PER_ROUND = 500_000;
const ROUNDS = 10;
const WARMUP_URLS = 100_000;

function makeUrls(round, count) {
  const urls = new Array(count);

  for (let i = 0; i < count; i++) {
    const n = round * URLS_PER_ROUND + i;
    const scheme = n % 2 === 0 ? 'https' : 'http';
    const port = n % 5 === 0 ? ':8080' : '';

    urls[i] =
      scheme + '://user' + n + ':pass' + round +
      '@sub' + n + '.example.com' + port +
      '/posts/' + round + '/' + i + '/index.html' +
      '?q=' + n + '&lang=en#section-' + i;
  }

  return urls;
}

function parseLegacy(input) {
  return legacyUrl.parse(input);
}

function parseWhatwg(input) {
  return URL.parse(input);
}

function consume(parsed) {
  return parsed.protocol.length +
    parsed.hostname.length +
    parsed.pathname.length +
    parsed.search.length +
    parsed.hash.length;
}

function runOnce(round, implementation, parse, urls) {
  global.gc();

  let checksum = 0;
  const started = process.hrtime.bigint();

  for (let i = 0; i < urls.length; i++) {
    checksum += consume(parse(urls[i]));
  }

  const elapsedNs = Number(process.hrtime.bigint() - started);

  return {
    round,
    implementation,
    urls: urls.length,
    elapsedMs: elapsedNs / 1e6,
    opsPerSec: urls.length / (elapsedNs / 1e9),
    checksum
  };
}

function summarize(results) {
  const values = results.map(result => result.opsPerSec);
  const sorted = [...values].sort((a, b) => a - b);
  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
  const variance = values.reduce(
    (sum, value) => sum + (value - mean) ** 2,
    0
  ) / values.length;

  return {
    rounds: values.length,
    meanOpsPerSec: mean,
    medianOpsPerSec:
      (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2,
    minOpsPerSec: sorted[0],
    maxOpsPerSec: sorted[sorted.length - 1],
    standardDeviation: Math.sqrt(variance)
  };
}

console.log(JSON.stringify({
  environment: {
    node: process.version,
    v8: process.versions.v8,
    platform: process.platform,
    release: os.release(),
    arch: process.arch,
    cpu: os.cpus()[0].model,
    logicalCpus: os.cpus().length,
    memoryGiB: os.totalmem() / 1024 ** 3
  },
  configuration: {
    urlsPerRound: URLS_PER_ROUND,
    rounds: ROUNDS,
    warmupUrlsPerImplementation: WARMUP_URLS
  }
}));

const implementations = {
  'legacy url.parse()': parseLegacy,
  'WHATWG URL.parse()': parseWhatwg
};

const warmupUrls = makeUrls(1000, WARMUP_URLS);
for (const parse of Object.values(implementations)) {
  let checksum = 0;
  for (let i = 0; i < warmupUrls.length; i++) {
    checksum += consume(parse(warmupUrls[i]));
  }
  if (checksum === 0) throw new Error('Warm-up was not consumed');
}

const results = [];

for (let round = 0; round < ROUNDS; round++) {
  const urls = makeUrls(round, URLS_PER_ROUND);
  const order = round % 2 === 0
    ? ['legacy url.parse()', 'WHATWG URL.parse()']
    : ['WHATWG URL.parse()', 'legacy url.parse()'];
  const roundResults = [];

  for (const implementation of order) {
    const result = runOnce(
      round + 1,
      implementation,
      implementations[implementation],
      urls
    );
    results.push(result);
    roundResults.push(result);
    console.log(JSON.stringify(result));
  }

  if (roundResults[0].checksum !== roundResults[1].checksum) {
    throw new Error('Checksum mismatch in round ' + (round + 1));
  }
}

for (const implementation of Object.keys(implementations)) {
  const implementationResults = results.filter(
    result => result.implementation === implementation
  );
  console.log(JSON.stringify({
    implementation,
    summary: summarize(implementationResults)
  }));
}

Run with:

node --expose-gc --no-deprecation benchmark-url-parse.js

Raw results

{"environment":{"node":"v26.7.0","v8":"14.6.202.34-node.28","platform":"darwin","release":"24.6.0","arch":"arm64","cpu":"Apple M1 Pro","logicalCpus":10,"memoryGiB":32},"configuration":{"urlsPerRound":500000,"rounds":10,"warmupUrlsPerImplementation":100000}}
{"round":1,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":865.47275,"opsPerSec":577718.9403132566,"checksum":41805560}
{"round":1,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":241.184291,"opsPerSec":2073103.5090506787,"checksum":41805560}
{"round":2,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":308.01425,"opsPerSec":1623301.519329057,"checksum":42027780}
{"round":2,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":767.373709,"opsPerSec":651573.0134298881,"checksum":42027780}
{"round":3,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":899.767041,"opsPerSec":555699.3946391953,"checksum":43027780}
{"round":3,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":243.028834,"opsPerSec":2057369.0445307407,"checksum":43027780}
{"round":4,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":306.438125,"opsPerSec":1631650.7614710147,"checksum":43027780}
{"round":4,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":859.090209,"opsPerSec":582011.0563034016,"checksum":43027780}
{"round":5,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":892.065708,"opsPerSec":560496.8283345334,"checksum":43027780}
{"round":5,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":240.070708,"opsPerSec":2082719.7293890598,"checksum":43027780}
{"round":6,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":306.428166,"opsPerSec":1631703.7905712624,"checksum":43027780}
{"round":6,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":810.585875,"opsPerSec":616837.7903204889,"checksum":43027780}
{"round":7,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":898.29975,"opsPerSec":556607.0790958141,"checksum":43027780}
{"round":7,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":243.0695,"opsPerSec":2057024.8426890252,"checksum":43027780}
{"round":8,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":307.756958,"opsPerSec":1624658.6372874142,"checksum":43027780}
{"round":8,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":842.284875,"opsPerSec":593623.3866243887,"checksum":43027780}
{"round":9,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":893.284,"opsPerSec":559732.4031327104,"checksum":43027780}
{"round":9,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":239.740833,"opsPerSec":2085585.4788825233,"checksum":43027780}
{"round":10,"implementation":"WHATWG URL.parse()","urls":500000,"elapsedMs":311.443125,"opsPerSec":1605429.5627813265,"checksum":43027780}
{"round":10,"implementation":"legacy url.parse()","urls":500000,"elapsedMs":820.297958,"opsPerSec":609534.614981938,"checksum":43027780}
{"implementation":"legacy url.parse()","summary":{"rounds":10,"meanOpsPerSec":586383.4507175615,"medianOpsPerSec":579864.9983083291,"minOpsPerSec":555699.3946391953,"maxOpsPerSec":651573.0134298881,"standardDeviation":30113.567871664425}}
{"implementation":"WHATWG URL.parse()","summary":{"rounds":10,"meanOpsPerSec":1847254.6875982103,"medianOpsPerSec":1844364.3166301437,"minOpsPerSec":1605429.5627813265,"maxOpsPerSec":2085585.4788825233,"standardDeviation":224172.9821906021}}