stax-xml/dist/index.d.ts

// Generated by dts-bundle-generator v9.5.1

/**
 * XML 스트림 이벤트의 타입을 나타내는 열거형
 */
export declare enum XmlEventType {
	START_DOCUMENT = "START_DOCUMENT",
	END_DOCUMENT = "END_DOCUMENT",
	START_ELEMENT = "START_ELEMENT",
	END_ELEMENT = "END_ELEMENT",
	CHARACTERS = "CHARACTERS",
	CDATA = "CDATA",
	ERROR = "ERROR"
}
/**
 * 모든 XML 이벤트의 기본 인터페이스
 */
export interface XmlEvent {
	type: XmlEventType;
}
/**
 * START_ELEMENT 이벤트 인터페이스
 */
export interface StartElementEvent extends XmlEvent {
	type: XmlEventType.START_ELEMENT;
	name: string;
	localName?: string;
	prefix?: string;
	uri?: string;
	attributes: {
		[key: string]: string;
	};
	attributesWithPrefix?: {
		[key: string]: AttributeInfo;
	};
}
/**
 * END_ELEMENT 이벤트 인터페이스
 */
export interface EndElementEvent extends XmlEvent {
	type: XmlEventType.END_ELEMENT;
	name: string;
	localName?: string;
	prefix?: string;
	uri?: string;
}
/**
 * CHARACTERS 이벤트 인터페이스
 */
export interface CharactersEvent extends XmlEvent {
	type: XmlEventType.CHARACTERS;
	value: string;
}
/**
 * CDATA 이벤트 인터페이스
 */
export interface CdataEvent extends XmlEvent {
	type: XmlEventType.CDATA;
	value: string;
}
/**
 * ERROR 이벤트 인터FACE
 */
interface ErrorEvent$1 extends XmlEvent {
	type: XmlEventType.ERROR;
	error: Error;
}
/**
 * SimplifiedStaxParser가 반환할 수 있는 모든 이벤트 타입의 유니언
 */
export type AnyXmlEvent = XmlEvent | StartElementEvent | EndElementEvent | CharactersEvent | CdataEvent | ErrorEvent$1;
/**
 * 속성 인터페이스 (Writer용)
 */
export interface XmlAttribute {
	prefix?: string;
	localName: string;
	uri?: string;
	value: string;
}
/**
 * 네임스페이스 선언 인터페이스 (Writer용)
 * 이 간단한 구현에서는 사용되지 않습니다.
 */
export interface NamespaceDeclaration {
	prefix: string;
	uri: string;
}
/**
 * 속성 정보 인터페이스
 */
export interface AttributeInfo {
	value: string;
	localName: string;
	prefix?: string;
	uri?: string;
}
/**
 * 요소 작성 옵션 인터페이스 (Writer용)
 */
export interface WriteElementOptions {
	prefix?: string;
	uri?: string;
	attributes?: Record<string, string | AttributeInfo>;
	selfClosing?: boolean;
}
export interface StaxXmlParserOptions {
	encoding?: string;
	addEntities?: {
		entity: string;
		value: string;
	}[];
	autoDecodeEntities?: boolean;
	maxBufferSize?: number;
	enableBufferCompaction?: boolean;
}
/**
 * 웹 표준 ReadableStream을 직접 파싱하여 간소화된 StAX Pull 모델을 제공하는 XML 파서.
 * DTD, 네임스페이스, 복잡한 엔티티 등은 지원하지 않습니다.
 */
export declare class StaxXmlParser implements AsyncIterator<AnyXmlEvent> {
	private reader;
	private decoder;
	private buffer;
	private bufferLength;
	private position;
	private eventQueue;
	private resolveNext;
	private error;
	private isStreamEnded;
	private parserFinished;
	private currentTextBuffer;
	private elementStack;
	private namespaceStack;
	private options;
	constructor(xmlStream: ReadableStream<Uint8Array>, options?: StaxXmlParserOptions);
	private _startReading;
	private _parseBuffer;
	private _flushCharacters;
	/**
	 * 버퍼가 설정된 최대 크기를 초과하면 압축합니다.
	 * @private
	 */
	private _compactBufferIfNeeded;
	/**
	 * 버퍼를 압축하여 메모리 사용량을 줄입니다.
	 * @private
	 */
	private _compactBuffer;
	/**
	 * 버퍼 상태를 강제로 정리합니다.
	 * @private
	 */
	private _clearBuffers;
	private _addEvent;
	private _addError;
	private _popNextEvent;
	next(): Promise<IteratorResult<AnyXmlEvent>>;
	[Symbol.asyncIterator](): AsyncIterator<AnyXmlEvent>;
	/**
	 * XML 텍스트의 엔티티를 디코딩합니다.
	 * @param text 디코딩할 텍스트
	 * @returns 디코딩된 텍스트
	 * @private
	 */
	private _unescapeXml;
	/**
	 * qualified name을 파싱하여 localName, prefix, uri를 추출합니다.
	 * @param qname qualified name (예: "prefix:localName" 또는 "localName")
	 * @param namespaces 현재 네임스페이스 매핑
	 * @param isAttribute 속성인지 여부 (속성은 prefix가 없으면 네임스페이스에 속하지 않음)
	 * @returns 파싱된 네임스페이스 정보
	 * @private
	 */
	private _parseQualifiedName;
	get XmlEventType(): typeof XmlEventType;
	/**
	 * 새로운 바이트 데이터를 버퍼에 추가합니다.
	 * @param newData 추가할 바이트 데이터
	 * @private
	 */
	private _appendToBuffer;
	/**
	 * 버퍼의 현재 위치부터 지정된 길이만큼 문자열로 디코딩하고 position을 업데이트합니다.
	 * UTF-8 문자 경계를 고려하여 안전하게 디코딩합니다.
	 * @param length 디코딩할 바이트 길이 (선택적)
	 * @returns 디코딩된 문자열
	 * @private
	 */
	private _readBuffer;
	/**
	 * 현재 위치에서 패턴이 일치하는지 확인합니다.
	 * @param pattern 확인할 패턴
	 * @returns 패턴이 일치하면 true
	 * @private
	 */
	private _matchesPattern;
	/**
	 * 현재 위치부터 지정된 패턴을 찾습니다.
	 * @param pattern 찾을 문자열 패턴
	 * @returns 패턴이 발견된 위치 (바이트 오프셋), 없으면 -1
	 * @private
	 */
	private _findPattern;
	/**
	 * XML 선언을 파싱합니다.
	 * @returns 파싱이 완료되면 true, 더 많은 데이터가 필요하면 false
	 * @private
	 */
	private _parseXmlDeclaration;
	/**
	 * 주석을 파싱합니다.
	 * @returns 파싱이 완료되면 true, 더 많은 데이터가 필요하면 false
	 * @private
	 */
	private _parseComment;
	/**
	 * CDATA 섹션을 파싱합니다.
	 * @returns 파싱이 완료되면 true, 더 많은 데이터가 필요하면 false
	 * @private
	 */
	private _parseCData;
	/**
	 * 처리 명령을 파싱합니다.
	 * @returns 파싱이 완료되면 true, 더 많은 데이터가 필요하면 false
	 * @private
	 */
	private _parseProcessingInstruction;
	/**
	 * 종료 태그를 파싱합니다.
	 * @returns 파싱이 완료되면 true, 더 많은 데이터가 필요하면 false
	 * @private
	 */
	private _parseEndTag;
	/**
	 * 시작 태그를 파싱합니다.
	 * @returns 파싱이 완료되면 true, 더 많은 데이터가 필요하면 false
	 * @private
	 */
	private _parseStartTag;
}
export interface StaxXmlWriterOptions {
	encoding?: string;
	prettyPrint?: boolean;
	indentString?: string;
	addEntities?: {
		entity: string;
		value: string;
	}[];
	autoEncodeEntities?: boolean;
	namespaces?: NamespaceDeclaration[];
}
/**
 * StAX XMLStreamWriter와 유사하게 XML을 작성하는 클래스.
 * 네임스페이스 및 복잡한 PI/주석 관리는 지원하지 않는 간소화된 구현입니다.
 */
export declare class StaxXmlWriter {
	private xmlString;
	private state;
	private elementStack;
	private hasTextContentStack;
	private namespaceStack;
	private options;
	private currentIndentLevel;
	private needsIndent;
	private entityMap;
	constructor(options?: StaxXmlWriterOptions);
	/**
	 * XML 선언을 작성합니다 (예: <?xml version="1.0" encoding="UTF-8"?>).
	 * 문서의 가장 처음에 한 번만 호출해야 합니다.
	 * @param version XML 버전 (기본값: "1.0")
	 * @param encoding 인코딩 (기본값: 생성자에서 설정된 값)
	 * @param standalone 독립 실행형 문서 여부 (기본값: undefined)
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시
	 */
	writeStartDocument(version?: string, encoding?: string): this;
	/**
	 * 문서의 끝을 나타내며, 열린 모든 요소를 자동으로 닫습니다.
	 * @returns Promise<void> 스트림이 플러시될 때 resolve되는 Promise
	 */
	writeEndDocument(): void;
	/**
	 * 작성된 XML 문자열을 반환합니다.
	 * writeEndDocument() 호출 이후에 호출해야 완전한 XML을 얻을 수 있습니다.
	 * @returns 작성된 XML 문자열
	 */
	getXmlString(): string;
	/**
	 * 시작 요소를 작성합니다 (예: <element> 또는 <prefix:element>).
	 * @param localName 요소의 로컬 이름
	 * @param options 요소 작성 옵션 (prefix, uri, attributes, selfClosing)
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시
	 */
	writeStartElement(localName: string, options?: WriteElementOptions): this;
	/**
	 * 속성을 작성합니다. writeStartElement() 호출 직후에만 호출할 수 있습니다.
	 * @param localName 속성의 로컬 이름
	 * @param value 속성 값
	 * @param prefix 속성의 네임스페이스 접두사 (이 구현에서는 네임스페이스 매핑을 관리하지 않으므로 주의)
	 * @param uri 속성의 네임스페이스 URI (이 구현에서는 네임스페이스 매핑을 관리하지 않으므로 주의)
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시
	 */
	writeAttribute(localName: string, value: string, prefix?: string): this;
	/**
	 * 네임스페이스 선언을 작성합니다. writeStartElement() 호출 직후에만 호출할 수 있습니다.
	 * 이 구현에서는 단순하게 xmlns:prefix="uri" 또는 xmlns="uri" 형태로 문자열을 작성합니다.
	 * 실제 네임스페이스 유효성 검사/관리 로직은 포함되지 않습니다.
	 * @param prefix 네임스페이스 접두사
	 * @param uri 네임스페이스 URI
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시
	 */
	writeNamespace(prefix: string, uri: string): this;
	/**
	 * 텍스트 내용을 작성합니다.
	 * @param text 작성할 텍스트
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시
	 */
	writeCharacters(text: string): this;
	/**
	 * CDATA 섹션을 작성합니다.
	 * @param cdata CDATA 내용
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시 (특히 ']]>' 시퀀스 포함 시)
	 */
	writeCData(cdata: string): this;
	/**
	 * 주석을 작성합니다.
	 * @param comment 주석 내용
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시 (특히 '--' 시퀀스 포함 시)
	 */
	writeComment(comment: string): this;
	/**
	 * 처리 명령 (Processing Instruction)을 작성합니다.
	 * @param target PI의 대상
	 * @param data PI의 데이터 (선택 사항)
	 * @returns this (체이닝 가능)
	 * @throws Error 잘못된 상태에서 호출 시 (특히 '?>' 시퀀스 포함 시)
	 */
	writeProcessingInstruction(target: string, data?: string): this;
	/**
	 * 현재 열려있는 요소를 닫습니다 (예: </element> 또는 </prefix:element>).
	 * @returns this (체이닝 가능)
	 * @throws Error 열린 요소가 없을 때 호출 시
	 */
	writeEndElement(): this;
	/**
	 * Pretty print 기능을 활성화/비활성화합니다.
	 * @param enabled Pretty print 활성화 여부
	 * @returns this (체이닝 가능)
	 */
	setPrettyPrint(enabled: boolean): this;
	/**
	 * 들여쓰기 문자열을 설정합니다.
	 * @param indentString 들여쓰기에 사용할 문자열 (예: '  ', '\t', '    ')
	 * @returns this (체이닝 가능)
	 */
	setIndentString(indentString: string): this;
	/**
	 * 현재 Pretty print 설정을 반환합니다.
	 * @returns Pretty print 활성화 여부
	 */
	isPrettyPrintEnabled(): boolean;
	/**
	 * 현재 들여쓰기 문자열을 반환합니다.
	 * @returns 현재 설정된 들여쓰기 문자열
	 */
	getIndentString(): string;
	/**
	 * 현재 열려있는 시작 요소 태그를 닫습니다 ('>' 추가).
	 * 예를 들어, <element 를 <element> 로 만듭니다.
	 * @private
	 */
	private _closeStartElementTag;
	/**
	 * Pretty print용 들여쓰기를 적용합니다.
	 * @private
	 */
	private _writeIndent;
	/**
	 * Pretty print용 줄바꿈을 추가합니다.
	 * @private
	 */
	private _writeNewline;
	/**
	 * 문자열을 출력 스트림에 씁니다.
	 * @param chunk 작성할 문자열
	 * @private
	 */
	private _write;
	/**
	 * XML 텍스트를 이스케이프합니다.
	 * @param text 이스케이프할 텍스트
	 * @returns 이스케이프된 텍스트
	 * @private
	 */
	private _escapeXml;
}
export interface StaxXmlParserSyncOptions {
	autoDecodeEntities?: boolean;
	addEntities?: {
		entity: string;
		value: string;
	}[];
}
/**
 * A synchronous, iterable XML parser that processes an entire XML string.
 *
 * This parser is designed for speed and is ideal for environments where the entire
 * XML document is already in memory, such as in web servers handling small to
 * medium-sized XML payloads. It avoids the overhead of asynchronous streams.
 *
 * It implements the `Iterable<AnyXmlEvent>` interface, allowing you to use it
 * directly in `for...of` loops.
 *
 * @example
 * ```typescript
 * const xml = '<root><item>Hello</item></root>';
 * const parser = new StaxXmlParserSync(xml);
 * for (const event of parser) {
 *   if (event.type === XmlEventType.START_ELEMENT) {
 *     console.log(`Start Element: ${event.name}`);
 *   }
 * }
 * ```
 */
export declare class StaxXmlParserSync implements Iterable<AnyXmlEvent> {
	private readonly xml;
	private pos;
	private readonly elementStack;
	private namespaceStack;
	private options;
	private readonly xmlnsRegex;
	private readonly attrRegex;
	constructor(xml: string, options?: StaxXmlParserSyncOptions);
	[Symbol.iterator](): Iterator<AnyXmlEvent>;
	private _parseEndTag;
	private _parseCdataCommentDoctype;
	private _parseProcessingInstruction;
	private _parseStartTag;
	private _findTagEnd;
	/**
	 * XML 텍스트의 엔티티를 디코딩합니다.
	 * @param text 디코딩할 텍스트
	 * @returns 디코딩된 텍스트
	 * @private
	 */
	private _unescapeXml;
	/**
	 * qualified name을 파싱하여 localName, prefix, uri를 추출합니다.
	 * @param qname qualified name (예: "prefix:localName" 또는 "localName")
	 * @param namespaces 현재 네임스페이스 매핑
	 * @param isAttribute 속성인지 여부 (속성은 prefix가 없으면 네임스페이스에 속하지 않음)
	 * @returns 파싱된 네임스페이스 정보
	 * @private
	 */
	private _parseQualifiedName;
}

export {
	ErrorEvent$1 as ErrorEvent,
};

export {};