tessl/npm-sitemap

Sitemap-generating library and CLI tool for creating XML sitemaps that comply with the sitemaps.org protocol

—

Pending

Overview

Eval results

Files

Core Sitemap Generation

Name: tessl/npm-sitemap
Author: tessl

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.

Capabilities

SitemapStream

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

/**
 * A Transform stream for turning a Readable stream of SitemapItemOptions 
 * or url strings into a Sitemap XML stream
 */
class SitemapStream extends Transform {
  constructor(opts?: SitemapStreamOptions);
  
  /** Stream hostname for URL resolution */
  hostname?: string;
  
  /** Error handling level */
  level: ErrorLevel;
  
  /** Whether XML header has been output */
  hasHeadOutput: boolean;
  
  /** XML namespace configuration */
  xmlNS: NSArgs;
  
  /** XSL stylesheet URL */
  xslUrl?: string;
  
  /** Custom error handler */
  errorHandler?: ErrorHandler;
  
  /** Whether to include only date (no time) in lastmod */
  lastmodDateOnly: boolean;
}

interface SitemapStreamOptions extends TransformOptions {
  /** Base hostname for relative URLs */
  hostname?: string;
  
  /** How to handle validation errors */
  level?: ErrorLevel;
  
  /** Whether to output only date portion of lastmod */
  lastmodDateOnly?: boolean;
  
  /** XML namespace configuration */
  xmlns?: NSArgs;
  
  /** URL to XSL stylesheet for XML transformation */
  xslUrl?: string;
  
  /** Custom error handling function */
  errorHandler?: ErrorHandler;
}

interface NSArgs {
  /** Include news namespace */
  news: boolean;
  
  /** Include video namespace */
  video: boolean;
  
  /** Include xhtml namespace */
  xhtml: boolean;
  
  /** Include image namespace */
  image: boolean;
  
  /** Custom namespace declarations */
  custom?: string[];
}

Usage Examples:

import { SitemapStream } from "sitemap";
import { createWriteStream } from "fs";

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

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

// Pipe to file
sitemap.pipe(createWriteStream("sitemap.xml"));
sitemap.end();

// With advanced options
const advancedSitemap = new SitemapStream({
  hostname: "https://example.com",
  level: ErrorLevel.THROW,
  lastmodDateOnly: true,
  xslUrl: "https://example.com/sitemap.xsl",
  xmlns: {
    news: true,
    video: true,
    xhtml: true,
    image: true,
    custom: ['xmlns:custom="http://custom.namespace"']
  }
});

SitemapItemStream

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

/**
 * Takes a stream of SitemapItemOptions and outputs XML for each item
 */
class SitemapItemStream extends Transform {
  constructor(opts?: SitemapItemStreamOptions);
  
  /** Error handling level */
  level: ErrorLevel;
}

interface SitemapItemStreamOptions extends TransformOptions {
  /** How to handle validation errors */
  level?: ErrorLevel;
}

Stream Utilities

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

/**
 * Converts a readable stream into a promise that resolves with concatenated data
 * ⚠️ CAUTION: Holds entire file in memory - not recommended for production
 * @param stream - The readable stream to convert
 * @returns Promise resolving to Buffer with stream contents
 * @throws EmptyStream if stream is empty
 */
function streamToPromise(stream: Readable): Promise<Buffer>;

/**
 * Generates XSL stylesheet include directive for XML
 * @param url - URL to the XSL stylesheet
 * @returns XML processing instruction string
 */
function stylesheetInclude(url: string): string;

Usage Examples:

import { SitemapStream, streamToPromise } from "sitemap";

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

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

// Using stylesheet
const styledSitemap = new SitemapStream({
  hostname: "https://example.com",
  xslUrl: "https://example.com/sitemap.xsl"
});

Error Handling

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

enum ErrorLevel {
  /** Skip validation, log nothing */
  SILENT = 'silent',
  
  /** Log warnings to console */
  WARN = 'warn',
  
  /** Throw errors immediately */
  THROW = 'throw'
}

type ErrorHandler = (error: Error, level: ErrorLevel) => void;

Error Handling Examples:

import { SitemapStream, ErrorLevel } from "sitemap";

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

// Custom error handler
const customErrorSitemap = new SitemapStream({
  hostname: "https://example.com",
  level: ErrorLevel.WARN,
  errorHandler: (error, level) => {
    if (level === ErrorLevel.WARN) {
      console.log(`Sitemap warning: ${error.message}`);
    }
  }
});

XML Output Structure

SitemapStream generates XML with the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
        xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
  <url>
    <loc>https://example.com/page-1</loc>
    <lastmod>2023-01-01T00:00:00.000Z</lastmod>
    <changefreq>daily</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

Install with Tessl CLI