빠른 시작

이 가이드는 StAX-XML로 첫 번째 XML 문서를 파싱하는 방법을 도와드립니다.

ESM-only 패키지: 모든 예제는 import 문법을 사용합니다. require('stax-xml')는 지원되지 않습니다.

기본 비동기 파싱

비동기 event reader를 사용하여 ReadableStream에서 XML을 파싱하는 방법입니다:

import { EventReader, XmlEventType } from 'stax-xml';

const xmlContent = `
<bookstore>
  <book id="1">
    <title>위대한 개츠비</title>
    <author>F. 스콧 피츠제럴드</author>
    <price>12.99</price>
  </book>
  <book id="2">
    <title>앵무새 죽이기</title>
    <author>하퍼 리</author>
    <price>14.99</price>
  </book>
</bookstore>
`;

// XML 문자열에서 ReadableStream 생성
const stream = new ReadableStream({
  start(controller) {
    controller.enqueue(new TextEncoder().encode(xmlContent));
    controller.close();
  }
});

async function parseBooks() {
  const reader = new EventReader(stream);

  for await (const event of reader) {
    if (event.type === XmlEventType.START_ELEMENT) {
      console.log(`시작 요소: ${event.name}`);
      if (event.attributes) {
        console.log('속성:', event.attributes);
      }
    } else if (event.type === XmlEventType.CHARACTERS) {
      const text = event.value.trim();
      if (text) {
        console.log(`텍스트: ${text}`);
      }
    } else if (event.type === XmlEventType.END_ELEMENT) {
      console.log(`종료 요소: ${event.name}`);
    }
  }
}

parseBooks();

기본 동기 파싱

작은 XML 문자열의 경우 동기 event reader를 사용할 수 있습니다:

import { EventReaderSync, XmlEventType } from 'stax-xml';

const xmlString = '<greeting>안녕하세요, 세계!</greeting>';
const reader = new EventReaderSync(xmlString);

for (const event of reader) {
  console.log(event.type, event);
}

Unknown XML 파싱

import { parseXmlObjectSync, parseXmlTreeSync } from 'stax-xml';

const xmlString = `
<bookstore>
  <book id="1">
    <title>위대한 개츠비</title>
    <author>F. 스콧 피츠제럴드</author>
    <price>12.99</price>
  </book>
  <book id="2">
    <title>앵무새 죽이기</title>
    <author>하퍼 리</author>
    <price>14.99</price>
  </book>
</bookstore>
`;

const tree = parseXmlTreeSync(xmlString);
console.log(tree.children[0]);

const object = parseXmlObjectSync(xmlString);
console.log(object.bookstore);
// {
//   book: [
//     { '@id': '1', title: '위대한 개츠비', author: 'F. 스콧 피츠제럴드', price: '12.99' },
//     { '@id': '2', title: '앵무새 죽이기', author: '하퍼 리', price: '14.99' }
//   ]
// }

element 순서와 mixed content가 중요하면 parseXmlTreeSync()를 사용하세요. attribute가 @id 같은 key로 들어가는 compact object가 필요하면 parseXmlObjectSync()를 사용하세요. typed domain object가 필요하다면 converter API 또는 custom event loop를 사용하세요.

오류 처리

StAX-XML은 잘못된 형식의 XML에 대한 오류 이벤트를 제공합니다:

import { EventReaderSync, XmlEventType } from 'stax-xml';

const malformedXml = '<root><unclosed>';
const reader = new EventReaderSync(malformedXml);

for (const event of reader) {
  if (event.type === XmlEventType.ERROR) {
    console.error('XML 파싱 오류:', event.error.message);
  }
}

다음 단계

• 고급 사용 사례를 위한 예제 탐색하기
• 성능 비교를 위한 벤치마크 보기