This major release modernizes the package with ESM-first architecture, drops support for Node.js < 20, and includes comprehensive security and robustness improvements.

[BREAKING CHANGES]

Dropped Node.js < 20 Support

• Node.js >=20.19.5 now required (previously >=14.0.0)
• npm >=10.8.2 now required (previously >=6.0.0)
• Dropped support for Node.js 14, 16, and 18

ESM Conversion with Dual Package Support

• Package now uses "type": "module" in package.json

• Built as dual ESM/CJS package with conditional exports

• Import paths in ESM require .js extensions (TypeScript will add these automatically)

• Both ESM and CommonJS imports continue to work:

  // ESM (new default)
  import { SitemapStream } from 'sitemap'
  
  // CommonJS (still supported)
  const { SitemapStream } = require('sitemap')

• CLI remains ESM-only at dist/esm/cli.js

Build Output Changes

• ESM output: dist/esm/ (was dist/)
• CJS output: dist/cjs/ (new)
• TypeScript definitions: dist/esm/index.d.ts (was dist/index.d.ts)

Node.js Modernization

• All built-in Node.js modules now use node: protocol imports (node:stream, node:fs, etc.)
• Uses native promise-based pipeline from node:stream/promises (instead of promisify(pipeline))
• TypeScript target updated to ES2023 (from ES2022)

New Exports

The following validation functions and constants are now part of the public API:

Validation Functions (from lib/validation.js):

• validateURL(), validatePath(), validateLimit(), validatePublicBasePath(), validateXSLUrl()
• Type guards: isPriceType(), isResolution(), isValidChangeFreq(), isValidYesNo(), isAllowDeny()
• validators - object containing regex validators for all sitemap fields

Constants (from lib/constants.js):

• LIMITS - security limits object (max URL length, max items per sitemap, video/news/image constraints, etc.)
• DEFAULT_SITEMAP_ITEM_LIMIT - default items per sitemap file (45,000)

New Type Export:

• SimpleSitemapAndIndexOptions interface now exported

Features

Comprehensive Security Validation

• Parser Security (#461): Added resource limits and comprehensive validation to sitemap index parser and stream

  • Max 50K URLs per sitemap, 1K images, 100 videos per entry
  • String length limits on all fields
  • URL validation (http/https only, max 2048 chars)
  • Protocol injection prevention (blocks javascript:, data:, file:, ftp:)
  • Path traversal prevention (blocks .. sequences)

• Stream Validation (#456, #455, #454): Added comprehensive validation to all stream classes

  • Enhanced XML entity escaping (including > character)
  • Attribute name validation
  • Date format validation (ISO 8601)
  • Input validation for numbers (reject NaN/Infinity), dates (check Invalid Date)
  • XSL URL validation to prevent script injection
  • Custom namespace validation (max 20 namespaces, max 512 chars each)

• XML Generation Security (#457): Comprehensive validation and documentation in sitemap-xml

  • Safe XML attribute and element generation
  • Protection against XML injection attacks

Robustness Improvements

• Sitemap Item Stream (#453): Improved robustness and type safety
• Sitemap Index Stream (#449): Enhanced robustness and test coverage
• Sitemap Index Parser (#448): Improved error handling and robustness
• Code Quality (#458): Comprehensive security and code quality improvements across codebase

Fixes

• Fixed TS151002 warning and test race condition (#455)
• Improved sitemap-item-stream robustness and type safety (#453)
• Enhanced sitemap-index-stream error handling (#449)
• Improved sitemap-index-parser error handling (#448)
• Fixed coverage reporting (#399, #434)
• Fixed invalid XML regex for better performance (#437, #417)
• Improved normalizeURL performance (#416)

Refactoring

• Architecture Reorganization (#460): Consolidated constants and validation
  • Created lib/constants.ts - single source of truth for all shared constants
  • Created lib/validation.ts - centralized all validation logic and type guards
  • Eliminated duplicate constants and validation code across files
  • Prevents inconsistencies where different files used different values

Infrastructure

Build System

• Dual ESM/CJS build with separate TypeScript configurations
  • tsconfig.json - ESM build (NodeNext module resolution)
  • tsconfig.cjs.json - CJS build (CommonJS module)
• Build outputs package.json with "type": "commonjs" to dist/cjs/
• Test infrastructure converted to ESM
• Updated Jest configuration for ESM support

Testing

• Converted to ts-jest for better TypeScript support (#434)
• All 172+ tests passing with 91%+ code coverage
• Enhanced security-focused test coverage
• Performance tests converted to .mjs format

Dependencies

• Updated sax from ^1.2.4 to ^1.4.1
• Updated @types/node from ^17.0.5 to ^24.7.2
• Removed unused dependencies (#459)
• Updated all dev dependencies to latest versions
• Replaced babel-based test setup with ts-jest

Developer Experience

• Updated examples to ESM syntax in README (#452)
• Updated API documentation for accuracy and ESM syntax (#452)
• Added comprehensive CLAUDE.md with architecture documentation
• Improved ESLint and Prettier integration
• Updated git hooks with Husky 9.x

Upgrade Guide for 9.0.0

1. Update Node.js Version

Ensure you are running Node.js >=20.19.5 and npm >=10.8.2:

node --version  # Should be 20.19.5 or higher
npm --version   # Should be 10.8.2 or higher

2. Update Package

npm install sitemap@9.0.0

3. Import Syntax (No Changes Required for Most Users)

Both ESM and CommonJS imports continue to work:

// ESM - works the same as before
import { SitemapStream, streamToPromise } from 'sitemap'

// CommonJS - works the same as before
const { SitemapStream, streamToPromise } = require('sitemap')

Note: If you're importing from the package in an ESM context, the module resolution happens automatically. If you're directly importing library files (not recommended), you'll need .js extensions.

4. Existing Code Compatibility

• ✅ All existing valid data continues to work unchanged
• ✅ Public API is fully compatible - same classes, methods, and options
• ✅ Stream behavior unchanged - all streaming patterns continue to work
• ✅ Error handling unchanged - ErrorLevel.WARN default behavior maintained
• ⚠️ Invalid data may now be rejected due to enhanced security validation
  • URLs must be http/https protocol (no javascript:, data:, etc.)
  • String lengths enforced per sitemaps.org spec
  • Resource limits enforced (50K URLs, 1K images, 100 videos per entry)

5. TypeScript Users

• Update tsconfig.json if needed to support ES2023
• Type definitions are now at dist/esm/index.d.ts (automatically resolved by package.json exports)
• No changes needed to your TypeScript code

6. New Optional Features

You can now import validation utilities and constants if needed:

import { LIMITS, validateURL, validators } from 'sitemap'

// Check limits
console.log(LIMITS.MAX_URL_LENGTH) // 2048

// Validate URLs
const url = validateURL('https://example.com/page')

// Use validators
if (validators['video:rating'].test('4.5')) {
  // valid rating
}

🐛 Bug Fix Release

This release fixes issue #464 where xsi:schemaLocation attributes were incorrectly rejected by the custom namespace validator introduced in 8.0.1.

✅ Backward Compatibility

• 100% API compatible with 8.0.1
• No breaking changes
• All existing code continues to work

🔧 Bug Fixes

#464 - Support xsi:schemaLocation in custom namespaces (thanks @dzakki)

• Extended validation to accept namespace-qualified attributes like xsi:schemaLocation
• Previously only xmlns:prefix="uri" format was accepted
• Now also accepts prefix:attribute="value" format
• Maintains all security validations from 8.0.1

📝 Example

The following now works correctly (as documented in README):

```javascript
const sms = new SitemapStream({
xmlns: {
custom: [
'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
'xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"'
]
}
});
```

📊 Testing

• ✅ All tests passing (116 existing + 8 new tests)
• ✅ Security regression tests added
• ✅ TypeScript compilation successful

📝 Installation

```bash
npm install sitemap@8.0.2
```

See CHANGELOG.md for complete details.

🤖 Generated with Claude Code

🔒 Security Patch Release

This release backports comprehensive security fixes from 9.0.0 to the 8.0.x branch. Upgrading is strongly recommended for all 8.0.0 users.

✅ Backward Compatibility

• 100% API compatible with 8.0.0
• No breaking changes
• All existing valid inputs continue to work
• Only rejects invalid/malicious inputs

🛡️ Security Fixes

High Priority:

• XML Injection Prevention (XSS protection via enhanced escaping)
• Protocol Injection Prevention (blocks javascript:, data:, file: URLs)
• Path Traversal Prevention (blocks .. sequences)
• Command Injection Fix (xmllint security hardening)

Medium Priority:

• DoS Protection (resource limits, memory exhaustion prevention)
• Input Validation (comprehensive validation for all user inputs)
• XSS Prevention (XSL URL validation)

Infrastructure:

• Added centralized security limits and validation framework
• Enhanced error handling with comprehensive error reporting

📦 Dependencies Updated

• sax: ^1.2.4 → ^1.4.1

📊 Testing

• ✅ All 94 tests passing
• ✅ TypeScript compilation successful
• ✅ ESLint clean

📝 Installation

npm install sitemap@8.0.1

See CHANGELOG.md for complete details.

🤖 Generated with Claude Code

What's Changed

• drop node-12 by @derduher in #433
• fix #423 via #424 thanks @huntharo - Propagate errors in SitemapAndIndexStream

Full Changelog: 7.1.2...8.0.0

What's Changed

• respect backpressure by @derduher in #388
• fix #425 via #426 thanks to @huntharo update streamToPromise to bubble up errors + jsDoc
• fix #415 thanks to @mohd-akram Fix circular dependency breaking Node.js 20.6
• Remove duplicate License field by @huntharo in #422
• non-breaking updates of dependent packages in #427

New Contributors

• @mohd-akram made their first contribution in #415

Full Changelog: 7.1.1...7.1.2

7.1.1

• fix #378 exit code not set on parse failure. A proper error will be set on the stream now.
• fix #384 thanks @tomcek112 parseSitemapIndex not included in 7.1.0 release
• fix #356 thanks @vandres - SitemapIndexStream now has lastmodDateOnly
• Fix #375 thanks @huntharo parseSitemap and parseSitemapIndex uncatchable errors
• Filter out null as well when writing XML thanks @huntharo #376

What's Changed

• Filter out null as well when writing XML by @huntharo in #376
• Fix parseSitemap and parseSitemapIndex uncatchable errors by @huntharo in #375
• implemented lastmodDateOnly for SitemapIndexStream, fixes #356 by @vandres in #373
• Add XML ingest performance tests by @huntharo in #371
• fixes #363 by @derduher in #381
• Fix exports for sitemap index parsing (fixes #384) by @tomcek112 in #385
• Fix cli exit code by @derduher in #386

New Contributors

• @vandres made their first contribution in #373
• @tomcek112 made their first contribution in #385

Full Changelog: 7.1.0...7.1.1

7.1.0

• bumped types dependency for node
• bumped all dev dependencies - includes some prettier changes
• package-lock updated to version 2

7.0.0

[BREAKING]

• dropped support for Node 10, added support for Node 16
• removed deprecated createSitemapsAndIndex. use SitemapAndIndexStream or simpleSitemapAndIndex
• dropped deprecated getSitemapStream option for SitemapAndIndexStream that does not return a write stream
• fixed invalid documentation for #357

non-breaking

• Added option to simplesitemap publicBasePath: allows the user to set the location of sitemap files hosted on the site fixes [#359]
• bumped dependencies

6.4.0

• added support for content_loc parsing #347 and uploader info attr
• added error handler option to sitemapstream #349 Thanks @marcoreni

#346