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チャンクを出力できます。
ネイティブ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ドキュメントクラスなどを制御できます。
ブラウザビジュアライザー	インタラクティブなWeb 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ワークフローに供給する場合に最適です。