0
# Core Sitemap Generation
1

2
Primary streaming interfaces for generating XML sitemaps with full control over the output format and validation. These classes provide the foundation for all sitemap generation functionality.
3

4
## Capabilities
5

6
### SitemapStream
7

8
The main Transform stream for converting sitemap items into XML format. Handles XML declaration, namespaces, and proper sitemap structure.
9

10
```typescript { .api }
11
/**
12
 * A Transform stream for turning a Readable stream of SitemapItemOptions 
13
 * or url strings into a Sitemap XML stream
14
 */
15
class SitemapStream extends Transform {
16
  constructor(opts?: SitemapStreamOptions);
17
  
18
  /** Stream hostname for URL resolution */
19
  hostname?: string;
20
  
21
  /** Error handling level */
22
  level: ErrorLevel;
23
  
24
  /** Whether XML header has been output */
25
  hasHeadOutput: boolean;
26
  
27
  /** XML namespace configuration */
28
  xmlNS: NSArgs;
29
  
30
  /** XSL stylesheet URL */
31
  xslUrl?: string;
32
  
33
  /** Custom error handler */
34
  errorHandler?: ErrorHandler;
35
  
36
  /** Whether to include only date (no time) in lastmod */
37
  lastmodDateOnly: boolean;
38
}
39

40
interface SitemapStreamOptions extends TransformOptions {
41
  /** Base hostname for relative URLs */
42
  hostname?: string;
43
  
44
  /** How to handle validation errors */
45
  level?: ErrorLevel;
46
  
47
  /** Whether to output only date portion of lastmod */
48
  lastmodDateOnly?: boolean;
49
  
50
  /** XML namespace configuration */
51
  xmlns?: NSArgs;
52
  
53
  /** URL to XSL stylesheet for XML transformation */
54
  xslUrl?: string;
55
  
56
  /** Custom error handling function */
57
  errorHandler?: ErrorHandler;
58
}
59

60
interface NSArgs {
61
  /** Include news namespace */
62
  news: boolean;
63
  
64
  /** Include video namespace */
65
  video: boolean;
66
  
67
  /** Include xhtml namespace */
68
  xhtml: boolean;
69
  
70
  /** Include image namespace */
71
  image: boolean;
72
  
73
  /** Custom namespace declarations */
74
  custom?: string[];
75
}
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { SitemapStream } from "sitemap";
82
import { createWriteStream } from "fs";
83

84
// Basic sitemap with hostname
85
const sitemap = new SitemapStream({ 
86
  hostname: "https://example.com" 
87
});
88

89
// Add URLs
90
sitemap.write({ url: "/page-1", changefreq: "daily", priority: 0.8 });
91
sitemap.write({ url: "/page-2", changefreq: "weekly", priority: 0.5 });
92

93
// Pipe to file
94
sitemap.pipe(createWriteStream("sitemap.xml"));
95
sitemap.end();
96

97
// With advanced options
98
const advancedSitemap = new SitemapStream({
99
  hostname: "https://example.com",
100
  level: ErrorLevel.THROW,
101
  lastmodDateOnly: true,
102
  xslUrl: "https://example.com/sitemap.xsl",
103
  xmlns: {
104
    news: true,
105
    video: true,
106
    xhtml: true,
107
    image: true,
108
    custom: ['xmlns:custom="http://custom.namespace"']
109
  }
110
});
111
```
112

113
### SitemapItemStream
114

115
Internal stream for processing individual sitemap items and converting them to XML elements. Generally used internally by SitemapStream.
116

117
```typescript { .api }
118
/**
119
 * Takes a stream of SitemapItemOptions and outputs XML for each item
120
 */
121
class SitemapItemStream extends Transform {
122
  constructor(opts?: SitemapItemStreamOptions);
123
  
124
  /** Error handling level */
125
  level: ErrorLevel;
126
}
127

128
interface SitemapItemStreamOptions extends TransformOptions {
129
  /** How to handle validation errors */
130
  level?: ErrorLevel;
131
}
132
```
133

134
### Stream Utilities
135

136
Utility functions for working with streams and converting them to promises.
137

138
```typescript { .api }
139
/**
140
 * Converts a readable stream into a promise that resolves with concatenated data
141
 * ⚠️ CAUTION: Holds entire file in memory - not recommended for production
142
 * @param stream - The readable stream to convert
143
 * @returns Promise resolving to Buffer with stream contents
144
 * @throws EmptyStream if stream is empty
145
 */
146
function streamToPromise(stream: Readable): Promise<Buffer>;
147

148
/**
149
 * Generates XSL stylesheet include directive for XML
150
 * @param url - URL to the XSL stylesheet
151
 * @returns XML processing instruction string
152
 */
153
function stylesheetInclude(url: string): string;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { SitemapStream, streamToPromise } from "sitemap";
160

161
// Convert stream to buffer
162
const sitemap = new SitemapStream({ hostname: "https://example.com" });
163
sitemap.write({ url: "/page-1" });
164
sitemap.end();
165

166
const xmlBuffer = await streamToPromise(sitemap);
167
console.log(xmlBuffer.toString());
168

169
// Using stylesheet
170
const styledSitemap = new SitemapStream({
171
  hostname: "https://example.com",
172
  xslUrl: "https://example.com/sitemap.xsl"
173
});
174
```
175

176
## Error Handling
177

178
The streaming classes support different error handling levels through the `ErrorLevel` enum:
179

180
```typescript { .api }
181
enum ErrorLevel {
182
  /** Skip validation, log nothing */
183
  SILENT = 'silent',
184
  
185
  /** Log warnings to console */
186
  WARN = 'warn',
187
  
188
  /** Throw errors immediately */
189
  THROW = 'throw'
190
}
191

192
type ErrorHandler = (error: Error, level: ErrorLevel) => void;
193
```
194

195
**Error Handling Examples:**
196

197
```typescript
198
import { SitemapStream, ErrorLevel } from "sitemap";
199

200
// Throw on validation errors
201
const strictSitemap = new SitemapStream({
202
  hostname: "https://example.com",
203
  level: ErrorLevel.THROW
204
});
205

206
// Custom error handler
207
const customErrorSitemap = new SitemapStream({
208
  hostname: "https://example.com",
209
  level: ErrorLevel.WARN,
210
  errorHandler: (error, level) => {
211
    if (level === ErrorLevel.WARN) {
212
      console.log(`Sitemap warning: ${error.message}`);
213
    }
214
  }
215
});
216
```
217

218
## XML Output Structure
219

220
SitemapStream generates XML with the following structure:
221

222
```xml
223
<?xml version="1.0" encoding="UTF-8"?>
224
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
225
        xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"
226
        xmlns:xhtml="http://www.w3.org/1999/xhtml"
227
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
228
        xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
229
  <url>
230
    <loc>https://example.com/page-1</loc>
231
    <lastmod>2023-01-01T00:00:00.000Z</lastmod>
232
    <changefreq>daily</changefreq>
233
    <priority>0.8</priority>
234
  </url>
235
</urlset>
236
```