Files
site/node_modules/sitemap/dist/lib/sax-parser-stream.d.ts
T

64 lines
3.2 KiB
TypeScript

import type { QualifiedAttribute, QualifiedTag, SAXStream } from 'sax';
import { type Readable, Transform, type TransformCallback } from 'node:stream';
import { type Logger, type SaxParserStreamConfig, type SaxParserStreamOptions, ErrorLevel } from './types.js';
/**
* Shared plumbing for the XML parser streams: sax setup, character-data
* buffering, error collection, backpressure, and the entry cap. Subclasses
* supply tag semantics through the `on*` hooks and hand each finished
* entry to `emitEntry`.
*
* Emits `'maxEntriesExceeded'` (with the cap) once, when the first entry past
* `maxEntries` is seen. If nothing listens for that event, the stream logs the
* overflow through its logger instead.
*/
export declare abstract class SaxParserStream<T> extends Transform {
level: ErrorLevel;
logger: Logger;
/**
* Errors encountered during parsing, capped at LIMITS.MAX_PARSER_ERRORS entries
* to prevent memory DoS from malformed XML (BB-03).
* Use errorCount for the total number of errors regardless of the cap.
*/
errors: Error[];
/** Total number of errors seen, including those beyond the stored cap. */
errorCount: number;
/** Number of entries emitted or dropped past `maxEntries` */
entryCount: number;
saxStream: SAXStream;
private maxEntries;
private overflowMessage;
constructor(opts: SaxParserStreamOptions, config: SaxParserStreamConfig);
/** The first parse error, or null if there has been none */
get error(): Error | null;
/** Called for every opening tag, after unknown tags have been reported */
protected onOpenTag(tag: QualifiedTag): void;
/** Called once per element with its joined, trimmed character data */
protected abstract onCharData(tag: string, text: string): void;
/** Called for each attribute of the tag currently being opened */
protected abstract onAttribute(tag: string, attr: QualifiedAttribute): void;
/** Called for every closing tag, after its character data is handled */
protected abstract onCloseTag(tag: string): void;
/** Count a finished entry and push it, unless it is past the entry cap */
protected emitEntry(item: T): void;
_transform(data: string, encoding: string, callback: TransformCallback): void;
/**
* Tell sax the document has ended, so a truncated document (an unclosed
* element) fails the stream like any other malformed XML.
*/
_flush(callback: TransformCallback): void;
/** Log a message and record it as a parse error, with the same text */
protected report(level: Parameters<Logger>[0], msg: string): void;
/** Record a parse error, keeping at most LIMITS.MAX_PARSER_ERRORS */
protected err(msg: string): void;
}
/**
* Pipe `xml` through `parser` and resolve with every entry it emits. Rejects
* if either stream fails.
*
* Entries past the parser's cap are dropped, so once the cap is crossed this
* stops reading `xml` and destroys it instead of parsing the rest (BB-05).
* `onOverflow` then picks the outcome: return an Error to reject with it, or
* nothing to resolve with the entries emitted before the cap.
*/
export declare function collectEntries<T>(xml: Readable, parser: SaxParserStream<T>, onOverflow: (maxEntries: number) => Error | void): Promise<T[]>;