feat(utils): add streaming sitemap parsers (#635)

Author: harlan-zw

docs/content/3.api/2.xml-parsing.md

@@ -0,0 +1,58 @@
+---
+title: XML Parsing Utilities
+description: Parse sitemap XML from strings or streams with @nuxtjs/sitemap/utils.
+relatedPages:
+  - path: /docs/sitemap/advanced/performance
+    title: Performance
+---
+
+The `@nuxtjs/sitemap/utils` export provides parsers for URL sets and sitemap indexes.
+
+## Parse a string
+
+Use `parseSitemapXml` when the complete XML string is already in memory.
+
+```ts
+import { parseSitemapXml } from '@nuxtjs/sitemap/utils'
+
+const { urls, warnings } = await parseSitemapXml(xml)
+```
+
+A closed, empty `<urlset>` returns `{ urls: [], warnings: [] }`. Invalid XML and documents without a URL set throw an error.
+
+`parseSitemapIndex` parses an index string. `isSitemapIndex` provides a quick string check when the document is already buffered.
+
+## Parse a stream
+
+`parseSitemapStream` accepts a `ReadableStream`, including `Response.body`. It also accepts strings, `Uint8Array` values, and sync or async iterables of either chunk type.
+
+The first event identifies the document. Later events contain URL entries, index entries, or validation warnings.
+
+```ts
+import { parseSitemapStream } from '@nuxtjs/sitemap/utils'
+
+const response = await fetch('https://example.com/sitemap.xml')
+if (!response.body)
+  throw new Error('Missing response body')
+
+const urls = []
+events:
+for await (const event of parseSitemapStream(response.body)) {
+  if (event._tag === 'kind') {
+    console.log(event.kind) // "urlset" or "index"
+    continue
+  }
+  if (event._tag !== 'url')
+    continue
+
+  urls.push(event.url)
+  if (urls.length === 50_000)
+    break events
+}
+```
+
+Breaking iteration cancels the response body, so unread bytes are not downloaded or parsed. The unread tail is not validated. Reading through completion validates the closing root element.
+
+Use `parseSitemapXmlStream` when only a URL set is accepted. Use `parseSitemapIndexStream` when only an index is accepted. These variants omit the initial `kind` event.
+
+Each entry and the incomplete XML buffer are capped at 1 MiB by default. Pass `{ maxEntryBytes, maxBufferBytes }` to set different bounds.

src/utils/index.ts

@@ -2,5 +2,5 @@ export type * from '../runtime/types'
 export { parseHtmlExtractSitemapMeta } from './parseHtmlExtractSitemapMeta'
 export { isSitemapIndex, parseSitemapIndex } from './parseSitemapIndex'
 export type { SitemapIndexEntry, SitemapIndexParseResult } from './parseSitemapIndex'
-export { parseSitemapXml } from './parseSitemapXml'
-export type { SitemapParseResult, SitemapWarning } from './parseSitemapXml'
+export { parseSitemapIndexStream, parseSitemapStream, parseSitemapXml, parseSitemapXmlStream } from './parseSitemapXml'
+export type { SitemapIndexStreamEvent, SitemapKind, SitemapParseResult, SitemapStreamEvent, SitemapStreamOptions, SitemapWarning, SitemapXmlChunk, SitemapXmlInput, SitemapXmlStreamEvent } from './parseSitemapXml'

src/utils/parseSitemapIndex.ts

@@ -1,4 +1,5 @@
 import type { SitemapWarning } from './parseSitemapXml'
+import { XMLParser } from 'fast-xml-parser'
 
 export interface SitemapIndexEntry {
   loc: string
@@ -31,7 +32,6 @@ export async function parseSitemapIndex(xml: string): Promise<SitemapIndexParseR
   if (!xml)
     throw new Error('Empty XML input provided')
 
-  const { XMLParser } = await import('fast-xml-parser')
   const parser = new XMLParser({
     isArray: (tagName: string) => tagName === 'sitemap',
     removeNSPrefix: true,