From 655b30b71f9614e326c5b21f7c95e1b5d516c878 Mon Sep 17 00:00:00 2001 From: Harold Hunt Date: Tue, 21 May 2024 22:17:27 -0400 Subject: [PATCH] Issue-423 - jsdocs for SitemapIndex classes --- lib/sitemap-index-stream.ts | 122 ++++++++++++++++++++++++++++++------ tests/sitemap-index.test.ts | 2 +- 2 files changed, 104 insertions(+), 20 deletions(-) diff --git a/lib/sitemap-index-stream.ts b/lib/sitemap-index-stream.ts index 7421bc7..af9c823 100644 --- a/lib/sitemap-index-stream.ts +++ b/lib/sitemap-index-stream.ts @@ -16,17 +16,57 @@ const sitemapIndexTagStart = ''; const closetag = ''; +/** + * Options for the SitemapIndexStream + */ export interface SitemapIndexStreamOptions extends TransformOptions { + /** + * Whether to output the lastmod date only (no time) + * + * @default false + */ lastmodDateOnly?: boolean; + + /** + * How to handle errors in passed in urls + * + * @default ErrorLevel.WARN + */ level?: ErrorLevel; + + /** + * URL to an XSL stylesheet to include in the XML + */ xslUrl?: string; } const defaultStreamOpts: SitemapIndexStreamOptions = {}; + +/** + * `SitemapIndexStream` is a Transform stream that takes `IndexItem`s or sitemap URL strings and outputs a stream of sitemap index XML. + * + * It automatically handles the XML declaration and the opening and closing tags for the sitemap index. + * + * ⚠️ CAUTION: This object is `readable` and must be read (e.g. piped to a file or to /dev/null) + * before `finish` will be emitted. Failure to read the stream will result in hangs. + * + * @extends {Transform} + */ export class SitemapIndexStream extends Transform { lastmodDateOnly: boolean; level: ErrorLevel; xslUrl?: string; private hasHeadOutput: boolean; + + /** + * `SitemapIndexStream` is a Transform stream that takes `IndexItem`s or sitemap URL strings and outputs a stream of sitemap index XML. + * + * It automatically handles the XML declaration and the opening and closing tags for the sitemap index. + * + * ⚠️ CAUTION: This object is `readable` and must be read (e.g. piped to a file or to /dev/null) + * before `finish` will be emitted. Failure to read the stream will result in hangs. + * + * @param {SitemapIndexStreamOptions} [opts=defaultStreamOpts] - Stream options. + */ constructor(opts = defaultStreamOpts) { opts.objectMode = true; super(opts); @@ -82,38 +122,82 @@ export class SitemapIndexStream extends Transform { } } -/** - * Callback for SitemapIndexAndStream that creates a new sitemap stream for a given sitemap index. - * - * Called when a new sitemap file is needed. - * - * The write stream is the destination where the sitemap was piped. - * SitemapAndIndexStream will wait for the `finish` event on each sitemap's - * write stream before moving on to the next sitemap. This ensures that the - * contents of the write stream will be fully written before being used - * by any following operations (e.g. uploading, reading contents for unit tests). - * - * @param i - The index of the sitemap file - * @returns A tuple containing the index item to be written into the sitemap index, the sitemap stream, and the write stream for the sitemap pipe destination - */ -type getSitemapStream = ( +type getSitemapStreamFunc = ( i: number ) => [IndexItem | string, SitemapStream, WriteStream]; +/** + * Options for the SitemapAndIndexStream + * + * @extends {SitemapIndexStreamOptions} + */ export interface SitemapAndIndexStreamOptions extends SitemapIndexStreamOptions { - level?: ErrorLevel; + /** + * Max number of items in each sitemap XML file. + * + * When the limit is reached the current sitemap file will be closed, + * a wait for `finish` on the target write stream will happen, + * and a new sitemap file will be created. + * + * Range: 1 - 50,000 + * + * @default 45000 + */ limit?: number; - getSitemapStream: getSitemapStream; + + /** + * Callback for SitemapIndexAndStream that creates a new sitemap stream for a given sitemap index. + * + * Called when a new sitemap file is needed. + * + * The write stream is the destination where the sitemap was piped. + * SitemapAndIndexStream will wait for the `finish` event on each sitemap's + * write stream before moving on to the next sitemap. This ensures that the + * contents of the write stream will be fully written before being used + * by any following operations (e.g. uploading, reading contents for unit tests). + * + * @param i - The index of the sitemap file + * @returns A tuple containing the index item to be written into the sitemap index, the sitemap stream, and the write stream for the sitemap pipe destination + */ + getSitemapStream: getSitemapStreamFunc; } +/** + * `SitemapAndIndexStream` is a Transform stream that takes in sitemap items, + * writes them to sitemap files, adds the sitemap files to a sitemap index, + * and creates new sitemap files when the count limit is reached. + * + * It waits for the target stream of the current sitemap file to finish before + * moving on to the next if the target stream is returned by the `getSitemapStream` + * callback in the 3rd position of the tuple. + * + * ⚠️ CAUTION: This object is `readable` and must be read (e.g. piped to a file or to /dev/null) + * before `finish` will be emitted. Failure to read the stream will result in hangs. + * + * @extends {SitemapIndexStream} + */ export class SitemapAndIndexStream extends SitemapIndexStream { private itemsWritten: number; - private getSitemapStream: getSitemapStream; + private getSitemapStream: getSitemapStreamFunc; private currentSitemap?: SitemapStream; private limit: number; private currentSitemapPipeline?: WriteStream; + /** + * `SitemapAndIndexStream` is a Transform stream that takes in sitemap items, + * writes them to sitemap files, adds the sitemap files to a sitemap index, + * and creates new sitemap files when the count limit is reached. + * + * It waits for the target stream of the current sitemap file to finish before + * moving on to the next if the target stream is returned by the `getSitemapStream` + * callback in the 3rd position of the tuple. + * + * ⚠️ CAUTION: This object is `readable` and must be read (e.g. piped to a file or to /dev/null) + * before `finish` will be emitted. Failure to read the stream will result in hangs. + * + * @param {SitemapAndIndexStreamOptions} opts - Stream options. + */ constructor(opts: SitemapAndIndexStreamOptions) { opts.objectMode = true; super(opts); @@ -213,7 +297,7 @@ export class SitemapAndIndexStream extends SitemapIndexStream { private createSitemap(encoding: string): void { const [idxItem, currentSitemap, currentSitemapPipeline] = this.getSitemapStream(this.itemsWritten / this.limit); - currentSitemap.on('error', (err: any) => this.emit('error', err)); + currentSitemap.on('error', (err) => this.emit('error', err)); this.currentSitemap = currentSitemap; this.currentSitemapPipeline = currentSitemapPipeline; super._transform(idxItem, encoding, () => { diff --git a/tests/sitemap-index.test.ts b/tests/sitemap-index.test.ts index c4b78eb..3dc79e8 100644 --- a/tests/sitemap-index.test.ts +++ b/tests/sitemap-index.test.ts @@ -13,7 +13,7 @@ import { } from '../lib/sitemap-index-stream'; import { streamToPromise } from '../lib/sitemap-stream'; import { finished as finishedCallback } from 'stream'; -import { readFileSync, WriteStream } from 'node:fs'; +import { readFileSync, WriteStream } from 'fs'; import { promisify } from 'util'; const finished = promisify(finishedCallback);