0
# parseurl
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: parseurl
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install parseurl`
10

11
## Core Imports
12

13
```javascript
14
const parseurl = require('parseurl');
15
```
16

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

19
## Architecture
20

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

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

27
## Basic Usage
28

29
```javascript
30
const parseurl = require('parseurl');
31
const http = require('http');
32

33
http.createServer((req, res) => {
34
  // Parse the request URL with memoization
35
  const parsed = parseurl(req);
36
  console.log('Path:', parsed.pathname);
37
  console.log('Query:', parsed.query);
38
  
39
  // Parse the original URL (useful with middleware that modifies req.url)
40
  const originalParsed = parseurl.original(req);
41
  console.log('Original path:', originalParsed.pathname);
42
  
43
  res.end('Hello World');
44
}).listen(3000);
45
```
46

47
## Capabilities
48

49
### URL Parsing with Memoization
50

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

53
```javascript { .api }
54
/**
55
 * Parse the req url with memoization
56
 * @param {http.IncomingMessage} req - HTTP request object (Node.js IncomingMessage with url property)
57
 * @returns {ParsedURL|undefined} Parsed URL object or undefined if req.url is undefined
58
 */
59
function parseurl(req);
60
```
61

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

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

70
```javascript { .api }
71
interface ParsedURL {
72
  /** Full URL string */
73
  href: string;
74
  /** Path portion of URL (pathname + search) */
75
  path: string;
76
  /** Path portion without query string */  
77
  pathname: string;
78
  /** Query string including '?' prefix (or null) */
79
  search: string | null;
80
  /** Query string without '?' prefix (or null) */
81
  query: string | null;
82
  /** Host portion including port (or null for relative URLs) */
83
  host: string | null;
84
  /** Host portion without port (or null for relative URLs) */
85
  hostname: string | null;
86
  /** Port portion (or null) */
87
  port: string | null;
88
}
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
const parseurl = require('parseurl');
95

96
// In an HTTP server
97
http.createServer((req, res) => {
98
  const url = parseurl(req);
99
  
100
  if (url.pathname === '/api/users') {
101
    // Handle users API
102
    console.log('Full path with query:', url.path); // '/api/users?limit=10&offset=0'
103
    
104
    if (url.query) {
105
      // Parse query parameters: url.query contains 'limit=10&offset=0'
106
      const params = new URLSearchParams(url.query);
107
      const limit = params.get('limit');
108
      const offset = params.get('offset');
109
    }
110
  }
111
  
112
  // Subsequent calls with same req.url are cached
113
  const cachedUrl = parseurl(req); // Returns cached result
114
});
115
```
116

117
### Original URL Parsing with Fallback
118

119
Parses the `req.originalUrl` with fallback to `req.url` and memoization.
120

121
```javascript { .api }
122
/**
123
 * Parse the req original url with fallback and memoization
124
 * @param {http.IncomingMessage} req - HTTP request object (Node.js IncomingMessage with url and optionally originalUrl properties)
125
 * @returns {ParsedURL|undefined} Parsed URL object or undefined if both originalUrl and url are unavailable
126
 */
127
function original(req);
128
```
129

130
**Fallback Logic:**
131
- If `req.originalUrl` is a string: parses `req.originalUrl`
132
- If `req.originalUrl` is not a string: falls back to `parseurl(req)`
133
- If both are unavailable: returns `undefined`
134

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

137
**Usage Examples:**
138

139
```javascript
140
const parseurl = require('parseurl');
141
const express = require('express');
142

143
const app = express();
144

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

152
app.get('/users', (req, res) => {
153
  res.json({ users: [] });
154
});
155
```
156

157
## Error Handling
158

159
parseurl handles errors gracefully:
160

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

165
```javascript
166
const parseurl = require('parseurl');
167

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

172
// Safe handling of non-string originalUrl
173
const original = parseurl.original({ 
174
  url: '/path',
175
  originalUrl: 123 // not a string
176
});
177
// Falls back to parsing req.url
178
console.log(original.pathname); // '/path'
179
```
180

181
## Performance Characteristics
182

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

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

190
**Benchmark Results** (operations per second):
191
- Simple path (`/foo/bar`): ~24M ops/sec vs ~7.5M ops/sec (native)
192
- Path with query (`/foo/bar?user=tj`): ~4.1M ops/sec vs ~2.6M ops/sec (native)  
193
- Same request (cached): ~14.9M ops/sec vs ~2.6M ops/sec (native)
194

195
## Platform Support
196

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