or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-parseurl

Parse a URL with memoization for high-performance HTTP request processing

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/parseurl@1.3.x

To install, run

npx @tessl/cli install tessl/npm-parseurl@1.3.0

parseurl

parseurl provides high-performance URL parsing functionality with built-in memoization capabilities for HTTP request objects. It offers optimized parsing that significantly outperforms Node.js native URL parsing, particularly for relative URLs and repeated parsing scenarios.

Package Information

Package Name: parseurl
Package Type: npm
Language: JavaScript
Installation: npm install parseurl

Core Imports

const parseurl = require('parseurl');

Note: parseurl is a CommonJS module and does not provide native ES module support.

Architecture

parseurl implements a high-performance URL parsing system with three key components:

Fast-path Parser: Optimized parsing logic for relative URLs starting with '/' that avoids regex and provides 3-5x performance improvements
Memoization Layer: Intelligent caching system that stores parsed results on request objects (req._parsedUrl and req._parsedOriginalUrl) with automatic cache invalidation
Fallback System: Graceful degradation to Node.js native url.parse() for complex URLs and robust error handling

Basic Usage

const parseurl = require('parseurl');
const http = require('http');

http.createServer((req, res) => {
  // Parse the request URL with memoization
  const parsed = parseurl(req);
  console.log('Path:', parsed.pathname);
  console.log('Query:', parsed.query);
  
  // Parse the original URL (useful with middleware that modifies req.url)
  const originalParsed = parseurl.original(req);
  console.log('Original path:', originalParsed.pathname);
  
  res.end('Hello World');
}).listen(3000);

Capabilities

URL Parsing with Memoization

Parses the req.url with intelligent caching to avoid redundant parsing operations.

/**
 * Parse the req url with memoization
 * @param {http.IncomingMessage} req - HTTP request object (Node.js IncomingMessage with url property)
 * @returns {ParsedURL|undefined} Parsed URL object or undefined if req.url is undefined
 */
function parseurl(req);

Performance Features:

Fast-path optimization: Significantly faster parsing for relative URLs starting with '/'
Intelligent caching: Stores parsed URL objects on req._parsedUrl to avoid redundant parsing
Cache validation: Automatically detects URL changes and re-parses when needed

Return Value: The function returns a URL object with the same structure as Node.js url.parse():

interface ParsedURL {
  /** Full URL string */
  href: string;
  /** Path portion of URL (pathname + search) */
  path: string;
  /** Path portion without query string */  
  pathname: string;
  /** Query string including '?' prefix (or null) */
  search: string | null;
  /** Query string without '?' prefix (or null) */
  query: string | null;
  /** Host portion including port (or null for relative URLs) */
  host: string | null;
  /** Host portion without port (or null for relative URLs) */
  hostname: string | null;
  /** Port portion (or null) */
  port: string | null;
}

Usage Examples:

const parseurl = require('parseurl');

// In an HTTP server
http.createServer((req, res) => {
  const url = parseurl(req);
  
  if (url.pathname === '/api/users') {
    // Handle users API
    console.log('Full path with query:', url.path); // '/api/users?limit=10&offset=0'
    
    if (url.query) {
      // Parse query parameters: url.query contains 'limit=10&offset=0'
      const params = new URLSearchParams(url.query);
      const limit = params.get('limit');
      const offset = params.get('offset');
    }
  }
  
  // Subsequent calls with same req.url are cached
  const cachedUrl = parseurl(req); // Returns cached result
});

Original URL Parsing with Fallback

Parses the req.originalUrl with fallback to req.url and memoization.

/**
 * Parse the req original url with fallback and memoization
 * @param {http.IncomingMessage} req - HTTP request object (Node.js IncomingMessage with url and optionally originalUrl properties)
 * @returns {ParsedURL|undefined} Parsed URL object or undefined if both originalUrl and url are unavailable
 */
function original(req);

Fallback Logic:

If req.originalUrl is a string: parses req.originalUrl
If req.originalUrl is not a string: falls back to parseurl(req)
If both are unavailable: returns undefined

Caching: Uses req._parsedOriginalUrl property for memoization, separate from the main parseurl() cache.

Usage Examples:

const parseurl = require('parseurl');
const express = require('express');

const app = express();

// Middleware that modifies req.url
app.use('/api', (req, res, next) => {
  console.log('Current URL:', parseurl(req).pathname);        // '/users' (modified)
  console.log('Original URL:', parseurl.original(req).pathname); // '/api/users' (original)
  next();
});

app.get('/users', (req, res) => {
  res.json({ users: [] });
});

Error Handling

parseurl handles errors gracefully:

Missing URLs: Returns undefined instead of throwing errors
Invalid URLs: Delegates error handling to Node.js url.parse() which may throw for malformed URLs
Type Safety: Checks if req.originalUrl is a string before attempting to parse

const parseurl = require('parseurl');

// Safe handling of missing URLs
const parsed = parseurl({ /* no url property */ });
console.log(parsed); // undefined

// Safe handling of non-string originalUrl
const original = parseurl.original({ 
  url: '/path',
  originalUrl: 123 // not a string
});
// Falls back to parsing req.url
console.log(original.pathname); // '/path'

Performance Characteristics

parseurl provides significant performance improvements over native Node.js URL parsing:

Relative URLs: Up to 3-5x faster than url.parse() for simple paths
Memoization: Up to 10-15x faster for repeated parsing of the same URL
Memory Efficient: Reuses cached objects when URLs haven't changed
Zero Dependencies: No external dependencies for maximum performance

Benchmark Results (operations per second):

Simple path (/foo/bar): ~24M ops/sec vs ~7.5M ops/sec (native)
Path with query (/foo/bar?user=tj): ~4.1M ops/sec vs ~2.6M ops/sec (native)
Same request (cached): ~14.9M ops/sec vs ~2.6M ops/sec (native)

Platform Support

Node.js: >= 0.8
Environment: Server-side only (requires HTTP request objects)
Dependencies: Node.js built-in url module only