@opencraw/office-reader 0.0.2 → 0.0.3

package/README.md

@@ -4,7 +4,9 @@ Reads Office files into plain objects:
 
 - **workbooks** (`.xlsx`, `.xlsm`) as sheets of cells, with their merged ranges and hidden rows;
 - **presentations** (`.pptx`, `.pptm`, `.ppsx`) as slides of positioned text boxes, tables, chart data and
-  speaker notes.
+  speaker notes;
+- **documents** (`.docx`, `.docm`, `.dotx`) as paragraphs with their heading and list levels and links, tables
+  with their merged cells, headers, footers and notes.
 
 - **What the file holds, faithfully.** Formulas give their cached value, and nothing is evaluated. Dates are
   dates, in both the 1900 and 1904 systems. Merged ranges and hidden rows and sheets are reported, not
@@ -110,10 +112,10 @@ says what to do:
 
 | `code` | The file is |
 |---|---|
-| `legacy-format` | a legacy binary `.xls`, `.ppt` or `.doc`: save it as `.xlsx` / `.pptx`, or export it as PDF |
+| `legacy-format` | a legacy binary `.xls`, `.ppt` or `.doc`: save it as `.xlsx` / `.pptx` / `.docx`, or export it as PDF |
 | `encrypted` | password-protected |
-| `unsupported-format` | an OpenDocument `.ods` / `.odp` |
-| `not-xlsx` / `not-pptx` | a zip package of the other kind (a `.pptx` given to `readXlsx`, say) |
+| `unsupported-format` | an OpenDocument `.ods` / `.odp` / `.odt` |
+| `not-xlsx` / `not-pptx` / `not-docx` | a zip package of another kind (a `.pptx` given to `readXlsx`, say) |
 | `not-zip` | not a zip at all |
 | `too-large` | past the `limits` |
 | `malformed` | damaged: a part does not inflate |
@@ -171,6 +173,50 @@ Tested against the 100 presentations of Apache POI's test corpus. It reads 90 of
 28 charts), and every placeholder gets a position. The other 10 are fuzzer cases and a truncated zip, all
 refused with an `OfficeReadError`.
 
+## Read a Word document
+
+```ts
+import { readDocx } from '@opencraw/office-reader/docx'
+
+const document = await readDocx('./circolare.docx')
+```
+
+```ts
+// { title: 'Circolare giugno',
+//   body: [
+//     { kind: 'paragraph', text: 'Circolare incentivi giugno 2026', style: 'Title', heading: 1 },
+//     { kind: 'paragraph', text: 'Condizioni', style: 'Heading1', heading: 1 },
+//     { kind: 'paragraph', text: 'Solo rottamazione', style: 'ListBullet', list: { level: 0, ordered: false } },
+//     { kind: 'paragraph', text: 'Prezzi', style: 'Titolo2', heading: 2 },
+//     { kind: 'table', name: 'table 1', hidden: false, hiddenRows: [],
+//       rows: [['Modello', 'Prezzo', '', 'Sconto'], ['', 'Listino', 'Netto', ''], ['Pandina', '15.950', '13.955', '12,5%'], …],
+//       merges: ['B1:C1', 'A1:A2', 'D1:D2'] },
+//     { kind: 'paragraph', text: 'Listino completo: listino giugno', links: [{ text: 'listino giugno', href: 'https://…/listino.pdf' }] },
+//     … ],
+//   headers: [[{ kind: 'paragraph', text: 'Stellantis Italia – riservato' }]],
+//   footers: [[…]],
+//   notes: [{ kind: 'footnote', id: '1', text: 'Prezzi chiavi in mano, IPT esclusa.' }] }
+```
+
+`readDocx(source, options?)` takes the same sources as `readXlsx`. Options: `extras` (default `true`; `false`
+skips headers, footers and notes) and `limits`.
+
+- **Headings:** a paragraph whose style is named `heading N` (the built-in names stay English in every
+  language: an Italian `Titolo2` is still named `heading 2`), has an outline level (its own or its style's,
+  through `basedOn`), or is `Title` (level 1).
+- **Lists:** numbering from the paragraph or its style (`List Bullet`); `ordered` says whether the level is
+  numbered (`1.`, `a)`, `i.`) or bulleted.
+- **Tables:** grids like a workbook's sheets. A cell spanning columns (`gridSpan`) fills the columns after it
+  with `''`; a cell merged down (`vMerge`) leaves `''` below it; both are listed in `merges`. A table inside a
+  cell is a block of its own, and its text is in the cell too.
+- **Text:** tabs as `\t`, line breaks as `\n`. Tracked insertions read as text, deletions do not. Field codes
+  are left out, their results kept. A text box's paragraphs follow the paragraph that holds it, once (Word
+  also writes a fallback copy for old readers, which is skipped).
+- **Links:** external links by URL, internal ones as `#bookmark`.
+
+Tested against the 130 documents of Apache POI's test corpus. It reads 115 of them (1,500 paragraphs, 5,115
+tables, 352 links) and refuses the other 15, fuzzer cases and truncated zips, with an `OfficeReadError`.
+
 ## How it compares
 
 | | office-reader | SheetJS (`xlsx` on npm) | ExcelJS | read-excel-file |
@@ -196,6 +242,7 @@ Tested against the 367 workbooks of Apache POI's test corpus, real files and fuz
 
 - **Writing files.**
 - **Evaluating formulas, and applying display formats.** A percentage stays `0.125` and a price stays `15950`.
-- **Legacy `.xls`, `.ppt`, `.xlsb` and OpenDocument `.ods` / `.odp`.** These are refused with a code.
+- **Legacy `.xls`, `.ppt`, `.doc`, `.xlsb` and OpenDocument `.ods` / `.odp` / `.odt`.** These are refused with a code.
 - **In workbooks:** charts, pivot tables, images, comments and data validation.
 - **In presentations:** SmartArt text, text inside images (no OCR), animations and themes.
+- **In documents:** comments, formatting (bold, colours, fonts), images, equations, and the text of charts.

package/dist/docx.d.ts

@@ -0,0 +1 @@
+export * from "./src/document/index.js";

package/dist/docx.esm.js

@@ -0,0 +1,5 @@
+export { r as readDocx } from './read-docx.use-case.esm.js';
+export { O as OfficeReadError } from './read-source.client.esm.js';
+import 'fflate';
+import 'htmlparser2';
+//# sourceMappingURL=docx.esm.js.map

package/dist/index.esm.js

@@ -1,4 +1,5 @@
 export { O as OfficeReadError } from './read-source.client.esm.js';
+export { r as readDocx } from './read-docx.use-case.esm.js';
 export { r as readPptx } from './read-pptx.use-case.esm.js';
 export { r as readXlsx } from './read-xlsx.use-case.esm.js';
 import 'fflate';

package/dist/read-docx.use-case.esm.js

@@ -0,0 +1,594 @@
+import { w as walkXml, n as namespacedAttribute, a as OoxmlPackage, r as readSource, b as relationshipsOf, c as relationshipOfType, O as OfficeReadError, h as hyperlinksOf } from './read-source.client.esm.js';
+import 'fflate';
+
+/** Elements whose content is not part of the document's text: deleted runs, field codes, the fallback copy of alternate content. */
+const SKIPPED = new Set(['del', 'moveFrom', 'instrText', 'delInstrText', 'Fallback']);
+/**
+ * Reads the blocks of a WordprocessingML part (the body, a header, a note):
+ * paragraphs with their style, heading level, list level and links, and
+ * tables as grids with merged cells (`gridSpan` across, `vMerge` down) as
+ * ranges. Tracked insertions read as text, deletions do not. A paragraph in a
+ * text box comes after the paragraph that holds the box; a table inside a
+ * cell is a block of its own, and its text also joins the cell's.
+ *
+ * Footnotes and endnotes (`footnotes.xml`, `endnotes.xml`) come back as
+ * notes, one per note, their paragraphs joined.
+ *
+ * @param xml - The part.
+ * @param context - Styles, numbering, links.
+ * @returns The blocks, in document order, and the notes.
+ */
+function readBlocks(xml, context) {
+  const blocks = [];
+  const notes = [];
+  let note;
+  let inProperties = false;
+  const paragraphs = [];
+  const tables = [];
+  // Where a paragraph that closes goes: a table cell, or the list of blocks (the body, a text box).
+  const containers = ['blocks'];
+  let skipping = 0;
+  let inText = false;
+  let inNumbering = false;
+  let tableCount = 0;
+  const append = text => {
+    const paragraph = paragraphs.at(-1);
+    if (paragraph !== undefined && skipping === 0) paragraph.text += text;
+  };
+  walkXml(xml, {
+    open: (name, attributes) => {
+      if (SKIPPED.has(name)) {
+        skipping += 1;
+        return;
+      }
+      if (skipping > 0) return;
+      const paragraph = paragraphs.at(-1);
+      const table = tables.at(-1);
+      const value = namespacedAttribute(attributes, 'val');
+      switch (name) {
+        case 'p':
+          {
+            paragraphs.push({
+              text: '',
+              links: [],
+              boxed: []
+            });
+            break;
+          }
+        case 'pPr':
+          {
+            inProperties = true;
+            break;
+          }
+        case 'footnote':
+        case 'endnote':
+          {
+            note = {
+              kind: name,
+              id: namespacedAttribute(attributes, 'id') ?? '',
+              start: blocks.length
+            };
+            break;
+          }
+        case 'pStyle':
+          {
+            if (paragraph !== undefined) paragraph.style = value;
+            break;
+          }
+        case 'outlineLvl':
+          {
+            if (paragraph !== undefined) paragraph.outline = Number(value);
+            break;
+          }
+        case 'numPr':
+          {
+            inNumbering = true;
+            break;
+          }
+        case 'numId':
+          {
+            if (inNumbering && paragraph !== undefined) paragraph.numId = value;
+            break;
+          }
+        case 'ilvl':
+          {
+            if (inNumbering && paragraph !== undefined) paragraph.level = Number(value);
+            break;
+          }
+        case 't':
+          {
+            inText = true;
+            break;
+          }
+        case 'tab':
+        case 'ptab':
+          {
+            // A tab stop in the paragraph's properties is not a tab in its text.
+            if (!inProperties) append('\t');
+            break;
+          }
+        case 'br':
+        case 'cr':
+          {
+            append('\n');
+            break;
+          }
+        case 'noBreakHyphen':
+          {
+            append('-');
+            break;
+          }
+        case 'hyperlink':
+          {
+            const id = namespacedAttribute(attributes, 'id');
+            const anchor = namespacedAttribute(attributes, 'anchor');
+            const href = id === undefined ? anchor === undefined ? undefined : `#${anchor}` : context.links.get(id);
+            if (paragraph !== undefined && href !== undefined) paragraph.link = {
+              href,
+              from: paragraph.text.length
+            };
+            break;
+          }
+        case 'txbxContent':
+          {
+            containers.push('blocks');
+            break;
+          }
+        case 'tbl':
+          {
+            tables.push({
+              rows: [],
+              merges: [],
+              vertical: new Map()
+            });
+            break;
+          }
+        case 'tr':
+          {
+            if (table !== undefined) table.row = [];
+            break;
+          }
+        case 'gridBefore':
+          {
+            if (table?.row !== undefined) table.row.push(...Array.from({
+              length: Number(value ?? 0)
+            }, () => ''));
+            break;
+          }
+        case 'tc':
+          {
+            if (table !== undefined) table.cell = {
+              paragraphs: [],
+              span: 1
+            };
+            containers.push('cell');
+            break;
+          }
+        case 'gridSpan':
+          {
+            if (table?.cell !== undefined) table.cell.span = Math.max(1, Number(value ?? 1));
+            break;
+          }
+        case 'vMerge':
+          {
+            if (table?.cell !== undefined) table.cell.vMerge = value === 'restart' ? 'restart' : 'continue';
+            break;
+          }
+        // No default
+      }
+    },
+    text: text => {
+      if (inText) append(text);
+    },
+    close: name => {
+      if (SKIPPED.has(name)) {
+        skipping -= 1;
+        return;
+      }
+      if (skipping > 0) return;
+      switch (name) {
+        case 't':
+          {
+            inText = false;
+            break;
+          }
+        case 'numPr':
+          {
+            inNumbering = false;
+            break;
+          }
+        case 'pPr':
+          {
+            inProperties = false;
+            break;
+          }
+        case 'footnote':
+        case 'endnote':
+          {
+            if (note === undefined) break;
+            const text = blocks.splice(note.start).map(block => block.kind === 'paragraph' ? block.text : block.rows.map(row => row.join(' ')).join('\n')).join('\n');
+            if (text !== '') notes.push({
+              kind: note.kind,
+              id: note.id,
+              text
+            });
+            note = undefined;
+            break;
+          }
+        case 'hyperlink':
+          {
+            const paragraph = paragraphs.at(-1);
+            if (paragraph?.link !== undefined) {
+              const text = paragraph.text.slice(paragraph.link.from).trim();
+              if (text !== '') paragraph.links.push({
+                text,
+                href: paragraph.link.href
+              });
+              paragraph.link = undefined;
+            }
+            break;
+          }
+        case 'p':
+          {
+            const open = paragraphs.pop();
+            if (open === undefined) break;
+            const block = paragraphBlock(open, context);
+            const emitted = [...(block === undefined ? [] : [block]), ...open.boxed];
+            const host = paragraphs.at(-1);
+            if (containers.at(-1) === 'cell') tables.at(-1)?.cell?.paragraphs.push(open.text, ...open.boxed.map(boxed => boxed.kind === 'paragraph' ? boxed.text : ''));
+            // A paragraph in a text box waits for the paragraph holding the box.
+            else if (host === undefined) blocks.push(...emitted);else host.boxed.push(...emitted);
+            break;
+          }
+        case 'txbxContent':
+          {
+            containers.pop();
+            break;
+          }
+        case 'tc':
+          {
+            containers.pop();
+            const table = tables.at(-1);
+            if (table?.cell !== undefined && table.row !== undefined) closeCell(table, table.cell, table.row);
+            if (table !== undefined) table.cell = undefined;
+            break;
+          }
+        case 'tr':
+          {
+            const table = tables.at(-1);
+            if (table?.row !== undefined) table.rows.push(table.row);
+            if (table !== undefined) table.row = undefined;
+            break;
+          }
+        case 'tbl':
+          {
+            const table = tables.pop();
+            if (table === undefined) break;
+            for (const [column, open] of table.vertical) closeVertical(table, column, open);
+            tableCount += 1;
+            const block = {
+              kind: 'table',
+              name: `table ${tableCount}`,
+              hidden: false,
+              rows: table.rows,
+              hiddenRows: [],
+              merges: table.merges
+            };
+            blocks.push(block);
+            // A table inside a cell: its text belongs to the cell too.
+            tables.at(-1)?.cell?.paragraphs.push(table.rows.map(row => row.filter(cell => cell !== '').join(' ')).join('\n'));
+            break;
+          }
+        // No default
+      }
+    }
+  });
+  return {
+    blocks,
+    notes
+  };
+}
+function paragraphBlock(open, context) {
+  const text = open.text.replaceAll(/[ \t]+\n/g, '\n').trim();
+  if (text === '') return undefined;
+  const heading = open.outline !== undefined && open.outline < 9 ? open.outline + 1 : context.styles.heading(open.style);
+  const numbering = open.numId === undefined ? context.styles.list(open.style) : {
+    numId: open.numId,
+    level: open.level ?? 0
+  };
+  const list = heading !== undefined || numbering === undefined || numbering.numId === '0' ? undefined : {
+    level: numbering.level,
+    ordered: context.ordered(numbering.numId, numbering.level)
+  };
+  return {
+    kind: 'paragraph',
+    text,
+    ...(open.style !== undefined && {
+      style: open.style
+    }),
+    ...(heading !== undefined && {
+      heading
+    }),
+    ...(list !== undefined && {
+      list
+    }),
+    ...(open.links.length > 0 && {
+      links: open.links
+    })
+  };
+}
+/** Places a closed cell in its row: its text, then a blank for each extra grid column it spans; tracks merges. */
+function closeCell(table, cell, row) {
+  const column = row.length;
+  const rowIndex = table.rows.length;
+  const open = table.vertical.get(column);
+  if (open !== undefined && cell.vMerge === 'continue') {
+    open.end = rowIndex;
+    row.push(...Array.from({
+      length: cell.span
+    }, () => ''));
+    return;
+  }
+  if (open !== undefined) closeVertical(table, column, open);
+  row.push(cell.paragraphs.join('\n').trim(), ...Array.from({
+    length: cell.span - 1
+  }, () => ''));
+  if (cell.vMerge === 'restart') table.vertical.set(column, {
+    row: rowIndex,
+    end: rowIndex,
+    span: cell.span
+  });else if (cell.span > 1) table.merges.push(rangeOf(rowIndex, column, 1, cell.span));
+}
+function closeVertical(table, column, open) {
+  table.vertical.delete(column);
+  if (open.end > open.row || open.span > 1) table.merges.push(rangeOf(open.row, column, open.end - open.row + 1, open.span));
+}
+/** A merged range as an A1 reference (`A1:D1`). */
+function rangeOf(row, column, rowSpan, columnSpan) {
+  return `${columnLetter(column)}${row + 1}:${columnLetter(column + columnSpan - 1)}${row + rowSpan}`;
+}
+function columnLetter(index) {
+  let letters = '';
+  for (let rest = index + 1; rest > 0; rest = Math.floor((rest - 1) / 26)) letters = String.fromCodePoint(65 + (rest - 1) % 26) + letters;
+  return letters;
+}
+
+/** Formats that do not number: a bullet, or nothing. */
+const UNNUMBERED = new Set(['bullet', 'none']);
+/**
+ * Reads `numbering.xml`: for a list (`numId`) at a level, whether its items
+ * are numbered (`1.`, `a)`, `i.`) or bulleted.
+ *
+ * @param xml - The numbering part; empty when the document has none.
+ * @returns Whether a list level is ordered.
+ */
+function readNumbering(xml) {
+  const formats = new Map();
+  const abstractOf = new Map();
+  let abstract;
+  let level;
+  let num;
+  walkXml(xml, {
+    open: (name, attributes) => {
+      switch (name) {
+        case 'abstractNum':
+          {
+            abstract = new Map();
+            formats.set(namespacedAttribute(attributes, 'abstractNumId') ?? '', abstract);
+            break;
+          }
+        case 'lvl':
+          {
+            level = Number(namespacedAttribute(attributes, 'ilvl') ?? 0);
+            break;
+          }
+        case 'numFmt':
+          {
+            if (abstract !== undefined && level !== undefined) abstract.set(level, namespacedAttribute(attributes, 'val') ?? 'decimal');
+            break;
+          }
+        case 'num':
+          {
+            num = namespacedAttribute(attributes, 'numId');
+            break;
+          }
+        case 'abstractNumId':
+          {
+            if (num !== undefined) abstractOf.set(num, namespacedAttribute(attributes, 'val') ?? '');
+            break;
+          }
+        // No default
+      }
+    },
+    close: name => {
+      switch (name) {
+        case 'abstractNum':
+          {
+            abstract = undefined;
+            break;
+          }
+        case 'lvl':
+          {
+            level = undefined;
+            break;
+          }
+        case 'num':
+          {
+            {
+              num = undefined;
+              // No default
+            }
+            break;
+          }
+      }
+    }
+  });
+  return (numId, at) => {
+    const format = formats.get(abstractOf.get(numId) ?? '')?.get(at) ?? 'bullet';
+    return !UNNUMBERED.has(format);
+  };
+}
+
+/**
+ * Reads the paragraph styles of `styles.xml`. A heading is a style named
+ * `heading N` (the built-in names stay English whatever the document's
+ * language: an Italian `Titolo1` is still named `heading 1`), a style with an
+ * outline level, or `Title`; either can be inherited through `basedOn`. A
+ * style can also carry list numbering (`List Bullet`).
+ *
+ * @param xml - The styles part; empty when the document has none.
+ * @returns The lookups.
+ */
+function readStyles(xml) {
+  const styles = new Map();
+  let current;
+  let inNumbering = false;
+  walkXml(xml, {
+    open: (name, attributes) => {
+      const value = namespacedAttribute(attributes, 'val');
+      if (name === 'style') {
+        current = namespacedAttribute(attributes, 'type') === 'paragraph' ? {
+          name: ''
+        } : undefined;
+        if (current !== undefined) styles.set(namespacedAttribute(attributes, 'styleId') ?? '', current);
+        return;
+      }
+      if (current === undefined) return;
+      switch (name) {
+        case 'name':
+          {
+            current.name = (value ?? '').toLowerCase();
+            break;
+          }
+        case 'basedOn':
+          {
+            current.basedOn = value;
+            break;
+          }
+        case 'outlineLvl':
+          {
+            current.outline = Number(value);
+            break;
+          }
+        case 'numPr':
+          {
+            inNumbering = true;
+            break;
+          }
+        default:
+          {
+            if (inNumbering && name === 'numId') current.numId = value;else if (inNumbering && name === 'ilvl') current.level = Number(value);
+          }
+      }
+    },
+    close: name => {
+      if (name === 'numPr') inNumbering = false;else if (name === 'style') current = undefined;
+    }
+  });
+  const chain = styleId => {
+    const seen = [];
+    for (let id = styleId, facts = id === undefined ? undefined : styles.get(id); facts !== undefined && seen.length < 20; id = facts.basedOn, facts = id === undefined ? undefined : styles.get(id)) seen.push(facts);
+    return seen;
+  };
+  return {
+    heading: styleId => {
+      for (const facts of chain(styleId)) {
+        const named = /^heading ([1-9])$/.exec(facts.name);
+        if (named !== null) return Number(named[1]);
+        if (facts.name === 'title') return 1;
+        if (facts.outline !== undefined && facts.outline < 9) return facts.outline + 1;
+      }
+      return;
+    },
+    list: styleId => {
+      const facts = chain(styleId).find(entry => entry.numId !== undefined);
+      return facts?.numId === undefined ? undefined : {
+        numId: facts.numId,
+        level: facts.level ?? 0
+      };
+    }
+  };
+}
+
+/**
+ * Reads a `.docx` Word document (also `.docm`, `.dotx`): its body as
+ * paragraphs (with heading and list levels, and links) and tables (with
+ * merged cells), its headers and footers, its footnotes and endnotes, and its
+ * title.
+ *
+ * @param source - A path, bytes, a Blob or a stream (see {@link OfficeSource}).
+ * @param options - Whether to read headers, footers and notes; the limits.
+ * @returns The document.
+ * @throws OfficeReadError for a file that is not a readable Word document: `legacy-format` (`.doc`), `encrypted`, `unsupported-format` (`.odt`), `not-docx`, `too-large`…
+ */
+async function readDocx(source, options = {}) {
+  const pkg = OoxmlPackage.open(await readSource(source), options.limits);
+  const packageRelationships = relationshipsOf(pkg, '');
+  const main = relationshipOfType(packageRelationships, 'officeDocument')?.target ?? (pkg.has('word/document.xml') ? 'word/document.xml' : '');
+  const xml = main === '' ? '' : pkg.text(main);
+  if (!/<(?:\w+:)?document[\s>]/.test(xml.slice(0, 4096)) || !/<(?:\w+:)?body[\s>]/.test(xml)) {
+    const other = main.endsWith('workbook.xml') ? ' (a spreadsheet: read it with readXlsx)' : main.endsWith('presentation.xml') ? ' (a presentation: read it with readPptx)' : '';
+    throw new OfficeReadError('not-docx', `not a Word document: the package's main part is ${main === '' ? 'missing' : main}${other}`);
+  }
+  const relationships = relationshipsOf(pkg, main);
+  const part = type => {
+    const target = relationshipOfType(relationships, type)?.target;
+    return target === undefined ? '' : pkg.text(target);
+  };
+  const styles = readStyles(part('styles'));
+  const ordered = readNumbering(part('numbering'));
+  const context = partName => ({
+    styles,
+    ordered,
+    links: hyperlinksOf(pkg, partName)
+  });
+  const {
+    blocks: body
+  } = readBlocks(xml, context(main));
+  const headers = [];
+  const footers = [];
+  const notes = [];
+  if (options.extras !== false) {
+    for (const relationship of relationships.values()) {
+      if (relationship.type === 'header' || relationship.type === 'footer') {
+        const {
+          blocks
+        } = readBlocks(pkg.text(relationship.target), context(relationship.target));
+        if (blocks.length > 0) (relationship.type === 'header' ? headers : footers).push(blocks);
+      } else if (relationship.type === 'footnotes' || relationship.type === 'endnotes') {
+        notes.push(...readBlocks(pkg.text(relationship.target), context(relationship.target)).notes);
+      }
+    }
+  }
+  const title = titleOf(pkg.text(relationshipOfType(packageRelationships, 'core-properties')?.target ?? 'docProps/core.xml'));
+  return {
+    ...(title !== undefined && {
+      title
+    }),
+    body,
+    headers,
+    footers,
+    notes
+  };
+}
+/** The `dc:title` of the core properties part, when set. */
+function titleOf(xml) {
+  let inTitle = false;
+  let title = '';
+  walkXml(xml, {
+    open: name => {
+      inTitle = name === 'title';
+    },
+    text: text => {
+      if (inTitle) title += text;
+    },
+    close: () => {
+      inTitle = false;
+    }
+  });
+  title = title.trim();
+  return title === '' ? undefined : title;
+}
+
+export { readDocx as r };
+//# sourceMappingURL=read-docx.use-case.esm.js.map

package/dist/read-pptx.use-case.esm.js

@@ -1,4 +1,4 @@
-import { w as walkXml, n as namespacedAttribute, i as isOn, a as OoxmlPackage, r as readSource, b as relationshipOfType, c as relationshipsOf, O as OfficeReadError } from './read-source.client.esm.js';
+import { w as walkXml, n as namespacedAttribute, i as isOn, a as OoxmlPackage, r as readSource, c as relationshipOfType, b as relationshipsOf, O as OfficeReadError } from './read-source.client.esm.js';
 import 'fflate';
 
 /**

package/dist/read-source.client.esm.js

@@ -32,7 +32,7 @@ class OoxmlPackage {
   static open(bytes, limits = {}) {
     if (isCompoundFile(bytes)) {
       if (holdsEncryptionInfo(bytes)) throw new OfficeReadError('encrypted', 'a password-protected Office file: remove the password and save it again');
-      throw new OfficeReadError('legacy-format', 'a legacy binary Office file (.xls, .ppt, .doc): save it as .xlsx or .pptx, or export it as PDF');
+      throw new OfficeReadError('legacy-format', 'a legacy binary Office file (.xls, .ppt, .doc): save it as .xlsx, .pptx or .docx, or export it as PDF');
     }
     const entries = new Map();
     try {
@@ -55,7 +55,7 @@ class OoxmlPackage {
       totalBytes: limits.totalBytes ?? DEFAULT_TOTAL_BYTES
     });
     const mimetype = opened.has('mimetype') ? opened.text('mimetype').trim() : '';
-    if (mimetype.startsWith('application/vnd.oasis.opendocument')) throw new OfficeReadError('unsupported-format', `an OpenDocument file (${mimetype}): save it as .xlsx or .pptx`);
+    if (mimetype.startsWith('application/vnd.oasis.opendocument')) throw new OfficeReadError('unsupported-format', `an OpenDocument file (${mimetype}): save it as .xlsx, .pptx or .docx`);
     return opened;
   }
   declared = 0;
@@ -195,6 +195,24 @@ function relationshipsOf(pkg, part) {
   });
   return relationships;
 }
+/**
+ * A part's hyperlinks: the external targets its relationships point at, by id.
+ *
+ * @param pkg - The package.
+ * @param part - The part (`word/document.xml`).
+ * @returns The URLs by relationship id.
+ */
+function hyperlinksOf(pkg, part) {
+  const directory = part.includes('/') ? part.slice(0, part.lastIndexOf('/')) : '';
+  const file = part.slice(part.lastIndexOf('/') + 1);
+  const links = new Map();
+  walkXml(pkg.text(`${directory === '' ? '' : `${directory}/`}_rels/${file}.rels`), {
+    open: (name, attributes) => {
+      if (name === 'Relationship' && attributes.TargetMode === 'External' && attributes.Id !== undefined && attributes.Target !== undefined) links.set(attributes.Id, attributes.Target);
+    }
+  });
+  return links;
+}
 /**
  * The first relationship of a type.
  *
@@ -285,5 +303,5 @@ function concat(chunks) {
   return bytes;
 }
 
-export { OfficeReadError as O, OoxmlPackage as a, relationshipOfType as b, relationshipsOf as c, isOn as i, namespacedAttribute as n, readSource as r, walkXml as w };
+export { OfficeReadError as O, OoxmlPackage as a, relationshipsOf as b, relationshipOfType as c, hyperlinksOf as h, isOn as i, namespacedAttribute as n, readSource as r, walkXml as w };
 //# sourceMappingURL=read-source.client.esm.js.map

package/dist/read-xlsx.use-case.esm.js

@@ -1,4 +1,4 @@
-import { w as walkXml, i as isOn, a as OoxmlPackage, r as readSource, O as OfficeReadError, b as relationshipOfType, c as relationshipsOf, n as namespacedAttribute } from './read-source.client.esm.js';
+import { w as walkXml, i as isOn, a as OoxmlPackage, r as readSource, O as OfficeReadError, c as relationshipOfType, b as relationshipsOf, n as namespacedAttribute } from './read-source.client.esm.js';
 import 'fflate';
 
 /** Built-in number formats that show a date (14–17, 22 and the East Asian ones) or a time of day (18–21, 45–47). */

package/dist/src/document/body.mapper.d.ts

@@ -0,0 +1,29 @@
+import type { DocumentBlock, DocumentNote } from './word-document.model.js';
+import type { ParagraphStyles } from './styles.mapper.js';
+/** What reading a part needs from the rest of the document. */
+export interface BodyContext {
+    styles: ParagraphStyles;
+    ordered: (numId: string, level: number) => boolean;
+    /** The part's relationships: a hyperlink's `r:id` to its URL. */
+    links: ReadonlyMap<string, string>;
+}
+/**
+ * Reads the blocks of a WordprocessingML part (the body, a header, a note):
+ * paragraphs with their style, heading level, list level and links, and
+ * tables as grids with merged cells (`gridSpan` across, `vMerge` down) as
+ * ranges. Tracked insertions read as text, deletions do not. A paragraph in a
+ * text box comes after the paragraph that holds the box; a table inside a
+ * cell is a block of its own, and its text also joins the cell's.
+ *
+ * Footnotes and endnotes (`footnotes.xml`, `endnotes.xml`) come back as
+ * notes, one per note, their paragraphs joined.
+ *
+ * @param xml - The part.
+ * @param context - Styles, numbering, links.
+ * @returns The blocks, in document order, and the notes.
+ */
+export declare function readBlocks(xml: string, context: BodyContext): {
+    blocks: DocumentBlock[];
+    notes: DocumentNote[];
+};
+//# sourceMappingURL=body.mapper.d.ts.map

package/dist/src/document/index.d.ts

@@ -0,0 +1,6 @@
+export { readDocx } from './read-docx.use-case.js';
+export type { ReadDocxOptions } from './read-docx.use-case.js';
+export type { WordDocument, DocumentBlock, Paragraph, DocumentTable, DocumentNote, DocumentLink } from './word-document.model.js';
+export { OfficeReadError } from '../read-error/index.js';
+export type { OfficeReadErrorCode } from '../read-error/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/document/numbering.mapper.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads `numbering.xml`: for a list (`numId`) at a level, whether its items
+ * are numbered (`1.`, `a)`, `i.`) or bulleted.
+ *
+ * @param xml - The numbering part; empty when the document has none.
+ * @returns Whether a list level is ordered.
+ */
+export declare function readNumbering(xml: string): (numId: string, level: number) => boolean;
+//# sourceMappingURL=numbering.mapper.d.ts.map

package/dist/src/document/read-docx.use-case.d.ts

@@ -0,0 +1,23 @@
+import type { PackageLimits } from '../ooxml-package/index.js';
+import type { OfficeSource } from '../source-bytes/index.js';
+import type { WordDocument } from './word-document.model.js';
+/** How to read a Word document. */
+export interface ReadDocxOptions {
+    /** Read headers, footers and notes; default true. */
+    extras?: boolean;
+    /** How much the file may inflate to. */
+    limits?: PackageLimits;
+}
+/**
+ * Reads a `.docx` Word document (also `.docm`, `.dotx`): its body as
+ * paragraphs (with heading and list levels, and links) and tables (with
+ * merged cells), its headers and footers, its footnotes and endnotes, and its
+ * title.
+ *
+ * @param source - A path, bytes, a Blob or a stream (see {@link OfficeSource}).
+ * @param options - Whether to read headers, footers and notes; the limits.
+ * @returns The document.
+ * @throws OfficeReadError for a file that is not a readable Word document: `legacy-format` (`.doc`), `encrypted`, `unsupported-format` (`.odt`), `not-docx`, `too-large`…
+ */
+export declare function readDocx(source: OfficeSource, options?: ReadDocxOptions): Promise<WordDocument>;
+//# sourceMappingURL=read-docx.use-case.d.ts.map

package/dist/src/document/styles.mapper.d.ts

@@ -0,0 +1,20 @@
+/** How a paragraph style reads: as a heading of some level, as a list, or neither. */
+export interface ParagraphStyles {
+    heading: (styleId: string | undefined) => number | undefined;
+    list: (styleId: string | undefined) => {
+        numId: string;
+        level: number;
+    } | undefined;
+}
+/**
+ * Reads the paragraph styles of `styles.xml`. A heading is a style named
+ * `heading N` (the built-in names stay English whatever the document's
+ * language: an Italian `Titolo1` is still named `heading 1`), a style with an
+ * outline level, or `Title`; either can be inherited through `basedOn`. A
+ * style can also carry list numbering (`List Bullet`).
+ *
+ * @param xml - The styles part; empty when the document has none.
+ * @returns The lookups.
+ */
+export declare function readStyles(xml: string): ParagraphStyles;
+//# sourceMappingURL=styles.mapper.d.ts.map

package/dist/src/document/word-document.model.d.ts

@@ -0,0 +1,44 @@
+import type { Sheet } from '../spreadsheet/index.js';
+/** A run of text that links somewhere: a URL, or a bookmark in the document (`#name`). */
+export interface DocumentLink {
+    text: string;
+    href: string;
+}
+/** A paragraph, with what Word says it is: a heading, a list item, or plain text. */
+export interface Paragraph {
+    kind: 'paragraph';
+    text: string;
+    /** The paragraph style's id (`Heading1`, `ListBullet`, a custom `Prezzo`). */
+    style?: string;
+    /** 1 to 9 for a heading (a `Heading N` style, a style with an outline level, or `Title` as 1). */
+    heading?: number;
+    /** For a list item: its level from 0, and whether it is numbered. */
+    list?: {
+        level: number;
+        ordered: boolean;
+    };
+    links?: DocumentLink[];
+}
+/** A table as a grid: rows of cell texts, merged cells as A1 ranges whose value sits in the top-left cell. */
+export type DocumentTable = {
+    kind: 'table';
+} & Sheet<string>;
+export type DocumentBlock = Paragraph | DocumentTable;
+/** A footnote or an endnote. */
+export interface DocumentNote {
+    kind: 'footnote' | 'endnote';
+    id: string;
+    text: string;
+}
+/** What a Word document holds. */
+export interface WordDocument {
+    /** The title in the document's properties, when it has one. */
+    title?: string;
+    /** The body, in order: paragraphs and tables. Text boxes come after the paragraph they sit in. */
+    body: DocumentBlock[];
+    /** Each header part's blocks (first page, odd, even pages…). */
+    headers: DocumentBlock[][];
+    footers: DocumentBlock[][];
+    notes: DocumentNote[];
+}
+//# sourceMappingURL=word-document.model.d.ts.map

package/dist/src/index.d.ts

@@ -2,6 +2,8 @@ export { readXlsx } from './spreadsheet/index.js';
 export type { ReadXlsxOptions, CellValue, Sheet, Workbook, ValueMode, SheetFilter } from './spreadsheet/index.js';
 export { readPptx } from './presentation/index.js';
 export type { ReadPptxOptions, Deck, Slide, SlideShape, SlideChart, ChartSeries, SlideFilter } from './presentation/index.js';
+export { readDocx } from './document/index.js';
+export type { ReadDocxOptions, WordDocument, DocumentBlock, Paragraph, DocumentTable, DocumentNote, DocumentLink } from './document/index.js';
 export { OfficeReadError } from './read-error/index.js';
 export type { OfficeReadErrorCode } from './read-error/index.js';
 export type { OfficeSource } from './source-bytes/index.js';

package/dist/src/ooxml-package/index.d.ts

@@ -2,6 +2,6 @@ export { OoxmlPackage } from './ooxml-package.client.js';
 export type { PackageLimits } from './ooxml-package.client.js';
 export { walkXml, namespacedAttribute, isOn } from './xml-walk.algorithm.js';
 export type { XmlHandlers } from './xml-walk.algorithm.js';
-export { relationshipsOf, relationshipOfType } from './relationships.mapper.js';
+export { relationshipsOf, relationshipOfType, hyperlinksOf } from './relationships.mapper.js';
 export type { Relationship } from './relationships.mapper.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/ooxml-package/relationships.mapper.d.ts

@@ -16,6 +16,14 @@ export interface Relationship {
  * @returns The relationships by id.
  */
 export declare function relationshipsOf(pkg: OoxmlPackage, part: string): Map<string, Relationship>;
+/**
+ * A part's hyperlinks: the external targets its relationships point at, by id.
+ *
+ * @param pkg - The package.
+ * @param part - The part (`word/document.xml`).
+ * @returns The URLs by relationship id.
+ */
+export declare function hyperlinksOf(pkg: OoxmlPackage, part: string): Map<string, string>;
 /**
  * The first relationship of a type.
  *

package/dist/src/read-error/office-read.error.d.ts

@@ -16,6 +16,8 @@ export type OfficeReadErrorCode =
 'not-xlsx' | 
 /** A zip package that is not a presentation. */
 'not-pptx' | 
+/** A zip package that is not a Word document. */
+'not-docx' | 
 /** A part the package needs is missing or malformed. */
 'malformed';
 /** A file `office-reader` cannot read, with a `code` to branch on and a message that says what to do. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/office-reader",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",
@@ -21,6 +21,11 @@
       "types": "./dist/src/presentation/index.d.ts",
       "import": "./dist/pptx.esm.js",
       "default": "./dist/pptx.esm.js"
+    },
+    "./docx": {
+      "types": "./dist/src/document/index.d.ts",
+      "import": "./dist/docx.esm.js",
+      "default": "./dist/docx.esm.js"
     }
   },
   "files": [
@@ -36,7 +41,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "description": "Reads Office files (.xlsx workbooks, .pptx presentations) into plain objects: cells with merged ranges and hidden rows, slides with positioned text, tables and chart data. No Node built-ins beyond reading a path: runs in Node, browsers, workers and edge runtimes.",
+  "description": "Reads Office files (.xlsx workbooks, .pptx presentations, .docx documents) into plain objects: cells with merged ranges and hidden rows, slides with positioned text, tables and chart data, document paragraphs with headings, lists and tables. No Node built-ins beyond reading a path: runs in Node, browsers, workers and edge runtimes.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -50,6 +55,8 @@
     "pptx",
     "powerpoint",
     "presentation",
+    "docx",
+    "word",
     "office",
     "ooxml",
     "reader",