64 lines
3.2 KiB
TypeScript
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[]>;
|