harshankur/officeParser

개요

officeParser는 Node.js와 호환되는 라이브러리로, 일반적인 오피스 문서 형식(DOCX, PPTX, XLSX, PDF 등)을 읽어 **엄격하게 타입이 지정된 추상 구문 트리(AST)**로 변환할 수 있습니다. 동일한 AST를 DOCX, ODT, LaTeX, Markdown, HTML, CSV, RTF, PDF, EPUB 등 다양한 대상 형식으로 다시 작성할 수 있으며, 검색 증강 생성(RAG) 파이프라인을 위한 RAG-ready chunks 생성도 지원합니다.

이 프로젝트는 프로그래밍 방식 API(JavaScript/TypeScript 코드용)와 명령줄에서 빠르게 변환할 수 있는 CLI(npx officeparser …)를 모두 제공합니다. 브라우저 기반 시각화 도구를 사용하면 파일을 업로드하고 생성된 AST를 확인하며, 옵션을 조정하고 결과를 즉시 미리 볼 수 있습니다.

---

주요 기능

기능	설명
다중 형식 파싱	DOCX, PPTX, XLSX, ODT/ODP/ODS/ODG, PDF, RTF, CSV, Markdown, HTML, EPUB, LaTeX(Overleaf zip 프로젝트 포함)를 읽어 통합된 AST를 생성합니다.
다중 형식 생성	AST에서 DOCX, ODT, LaTeX, Markdown, HTML, CSV, RTF, PDF(pdf-lib 또는 Puppeteer를 통한 네이티브 지원), EPUB, 일반 텍스트 또는 RAG-chunks를 출력할 수 있습니다.
네이티브 PDF 엔진	헤드리스 브라우저가 필요 없습니다. pdf-lib를 사용하여 Node 또는 브라우저에서 직접 PDF 바이트를 생성합니다.
암호 처리	단일 password/onPassword 옵션으로 암호화된 PDF, OOXML 및 ODF 파일을 처리합니다.
템플릿 / 메일 머지	OfficeTemplate.render는 DOCX/ODT 템플릿의 {{placeholders}}를 채우며 배치 렌더링을 지원합니다.
OCR 통합	추출된 이미지에 대해 Tesseract 기반 OCR을 선택적으로 실행할 수 있습니다(스캔된 PDF나 PPTX 슬라이드에 유용).
RAG 청킹	내장된 chunks 출력은 문서를 검색 가능한 조각으로 분할하며, 크기와 중첩 정도를 설정할 수 있습니다.
세밀한 설정	수백 개의 CLI 플래그 / TypeScript 옵션으로 제목 감지, 열 레이아웃, 색상 추출, 이미지 처리, LaTeX 문서 클래스 등을 제어합니다.
브라우저 시각화 도구	대화형 웹 UI(/officeParser/)에서 AST 트리를 표시하고, 설정을 편집하며 생성된 파일을 실시간으로 미리 볼 수 있습니다.
타입 안전 API	TypeScript로 작성되었으며, AST와 모든 공개 함수는 엄격한 타입 정의를 갖추고 있습니다.

---

일반적인 사용 사례

시나리오	officeParser 사용 방법
인덱싱을 위한 일반 텍스트 추출	await officeParser.parseOffice('file.pdf'); 후 await ast.to('text'); – 텍스트는 원래 레이아웃(열, 표, 제목)을 유지합니다.
Word 문서를 Markdown으로 변환	CLI: npx officeparser report.docx --to=md --output=report.md 또는 프로그래밍 방식: await OfficeConverter.convert('report.docx', 'md');
헤드리스 브라우저 없이 DOCX에서 PDF 생성	pdfConfig.engine: 'native'를 설정하고 ast.to('pdf')를 호출합니다.
메일 머지 배치 생성	DOCX 템플릿을 로드하고 OfficeTemplate.render([{name:'Alice'}, {name:'Bob'}])를 호출하여 개별 문서를 생성합니다.
RAG 파이프라인에 문서 공급	npx officeparser big_report.pdf --to=chunks 또는 OfficeConverter.convert(file, 'chunks', {chunkingConfig:{maxTokens:500}})를 사용합니다.
스캔된 PDF 처리	--ocr(또는 코드에서 ocr: true)을 extractAttachments와 함께 활성화합니다. 추출된 각 이미지에 대해 OCR이 실행되며 인식된 텍스트가 AST의 일부가 됩니다.

---

시작하기

# 라이브러리 설치
npm i officeparser   # Node >= 22.13 필요

빠른 프로그래밍 예제 (Node)

import { OfficeParser, OfficeConverter } from 'officeparser';

// DOCX 파일 파싱
const ast = await OfficeParser.parseOffice('proposal.docx', {
  extractAttachments: true,
  ocr: true,               // 포함된 이미지에 대해 OCR 실행
});

// 동일한 문서를 HTML로 변환
const html = await ast.to('html');
console.log(html.value);

// 또는 한 단계로 변환
await OfficeConverter.convert('proposal.docx', 'pdf', {
  pdfConfig: { engine: 'native' },
  output: 'proposal.pdf',
});

CLI 한 줄 명령어

npx officeparser presentation.pptx \
  --ocr --extractAttachments \
  --to=html --output=preview.html

---

제한 사항 및 알려진 문제

• 매우 큰 PDF는 별도의 pdf.js 프로세스의 기본 메모리 제한에 도달할 수 있습니다. 필요한 경우 pdfParserConfig.processMemoryMb를 늘리십시오.
• 텍스트 기반 형식(MD, HTML, CSV, TEX)은 매직 바이트가 없으므로 원시 버퍼로 제공될 때 명시적인 fileType이 필요합니다.
• 네이티브 PDF 엔진은 고급 CSS 기반 레이아웃을 지원하지 않습니다. 복잡한 스타일링이 필요한 경우 html(Puppeteer) 엔진을 사용하십시오.
• OCR은 CPU 집약적이므로 큰 문서에서는 느려질 수 있습니다. AbortSignal을 통해 취소할 수 있습니다.

---

라이선스

MIT – 상업적 및 개인적 용도로 무료 사용 가능.

---

officeParser는 오피스 스타일 문서를 수집, 변환 또는 생성해야 하는 개발자를 위한 원스톱 솔루션을 지향하며, 특히 해당 문서가 AI 또는 RAG 워크플로우로 전달될 때 유용합니다.