@folijs/docx 0.6.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/CHANGELOG.md +124 -0
  2. package/README.md +12 -3
  3. package/dist/custom.d.ts +2 -0
  4. package/dist/custom.d.ts.map +1 -0
  5. package/dist/custom.js +216 -0
  6. package/dist/custom.js.map +1 -0
  7. package/dist/export/balance.d.ts +1 -16
  8. package/dist/export/balance.d.ts.map +1 -1
  9. package/dist/export/balance.js +1 -0
  10. package/dist/export/balance.js.map +1 -1
  11. package/dist/export/content.d.ts +1 -19
  12. package/dist/export/content.d.ts.map +1 -1
  13. package/dist/export/content.js +2 -0
  14. package/dist/export/content.js.map +1 -1
  15. package/dist/export/controls.d.ts +1 -17
  16. package/dist/export/controls.d.ts.map +1 -1
  17. package/dist/export/controls.js +1 -0
  18. package/dist/export/controls.js.map +1 -1
  19. package/dist/export/index.d.ts +8 -2
  20. package/dist/export/index.d.ts.map +1 -1
  21. package/dist/export/index.js +6 -2
  22. package/dist/export/index.js.map +1 -1
  23. package/dist/export/parts.d.ts +1 -24
  24. package/dist/export/parts.d.ts.map +1 -1
  25. package/dist/export/parts.js +23 -9
  26. package/dist/export/parts.js.map +1 -1
  27. package/dist/export/pictures.d.ts +0 -45
  28. package/dist/export/pictures.d.ts.map +1 -1
  29. package/dist/export/pictures.js +9 -2
  30. package/dist/export/pictures.js.map +1 -1
  31. package/dist/export/properties.d.ts +1 -41
  32. package/dist/export/properties.d.ts.map +1 -1
  33. package/dist/export/properties.js +19 -14
  34. package/dist/export/properties.js.map +1 -1
  35. package/dist/export/tables.d.ts +0 -19
  36. package/dist/export/tables.d.ts.map +1 -1
  37. package/dist/export/tables.js +15 -3
  38. package/dist/export/tables.js.map +1 -1
  39. package/dist/export/xmlout.d.ts +1 -61
  40. package/dist/export/xmlout.d.ts.map +1 -1
  41. package/dist/export/xmlout.js +34 -7
  42. package/dist/export/xmlout.js.map +1 -1
  43. package/dist/import/content.d.ts +1 -43
  44. package/dist/import/content.d.ts.map +1 -1
  45. package/dist/import/content.js +4 -1
  46. package/dist/import/content.js.map +1 -1
  47. package/dist/import/controls.d.ts +1 -13
  48. package/dist/import/controls.d.ts.map +1 -1
  49. package/dist/import/controls.js +5 -7
  50. package/dist/import/controls.js.map +1 -1
  51. package/dist/import/index.d.ts +1 -9
  52. package/dist/import/index.d.ts.map +1 -1
  53. package/dist/import/index.js +12 -5
  54. package/dist/import/index.js.map +1 -1
  55. package/dist/import/ooxml.d.ts +1 -41
  56. package/dist/import/ooxml.d.ts.map +1 -1
  57. package/dist/import/ooxml.js +40 -8
  58. package/dist/import/ooxml.js.map +1 -1
  59. package/dist/import/parts.d.ts +1 -33
  60. package/dist/import/parts.d.ts.map +1 -1
  61. package/dist/import/parts.js +35 -9
  62. package/dist/import/parts.js.map +1 -1
  63. package/dist/import/pictures.d.ts +1 -33
  64. package/dist/import/pictures.d.ts.map +1 -1
  65. package/dist/import/pictures.js +7 -1
  66. package/dist/import/pictures.js.map +1 -1
  67. package/dist/import/properties.d.ts +1 -45
  68. package/dist/import/properties.d.ts.map +1 -1
  69. package/dist/import/properties.js +30 -7
  70. package/dist/import/properties.js.map +1 -1
  71. package/dist/import/report.d.ts +0 -10
  72. package/dist/import/report.d.ts.map +1 -1
  73. package/dist/import/report.js +1 -0
  74. package/dist/import/report.js.map +1 -1
  75. package/dist/import/stories.d.ts +1 -18
  76. package/dist/import/stories.d.ts.map +1 -1
  77. package/dist/import/stories.js +16 -4
  78. package/dist/import/stories.js.map +1 -1
  79. package/dist/import/tables.d.ts +0 -24
  80. package/dist/import/tables.d.ts.map +1 -1
  81. package/dist/import/tables.js +25 -6
  82. package/dist/import/tables.js.map +1 -1
  83. package/dist/package.d.ts +8 -4
  84. package/dist/package.d.ts.map +1 -1
  85. package/dist/package.js +38 -4
  86. package/dist/package.js.map +1 -1
  87. package/dist/settings.d.ts +1 -21
  88. package/dist/settings.d.ts.map +1 -1
  89. package/dist/settings.js +17 -4
  90. package/dist/settings.js.map +1 -1
  91. package/dist/xml.d.ts +8 -0
  92. package/dist/xml.d.ts.map +1 -1
  93. package/dist/xml.js +30 -2
  94. package/dist/xml.js.map +1 -1
  95. package/dist/zip.d.ts +0 -47
  96. package/dist/zip.d.ts.map +1 -1
  97. package/dist/zip.js +11 -2
  98. package/dist/zip.js.map +1 -1
  99. package/package.json +5 -4
  100. package/src/custom.ts +254 -0
  101. package/src/export/balance.ts +1 -0
  102. package/src/export/content.ts +3 -0
  103. package/src/export/controls.ts +1 -0
  104. package/src/export/index.ts +16 -5
  105. package/src/export/parts.ts +23 -8
  106. package/src/export/pictures.ts +13 -3
  107. package/src/export/properties.ts +22 -16
  108. package/src/export/tables.ts +15 -3
  109. package/src/export/xmlout.ts +36 -7
  110. package/src/import/content.ts +6 -7
  111. package/src/import/controls.ts +6 -2
  112. package/src/import/index.ts +31 -23
  113. package/src/import/ooxml.ts +40 -8
  114. package/src/import/parts.ts +43 -18
  115. package/src/import/pictures.ts +8 -1
  116. package/src/import/properties.ts +32 -7
  117. package/src/import/report.ts +1 -0
  118. package/src/import/stories.ts +16 -4
  119. package/src/import/tables.ts +25 -6
  120. package/src/package.ts +56 -6
  121. package/src/settings.ts +17 -4
  122. package/src/xml.ts +42 -2
  123. package/src/zip.ts +17 -5
@@ -1,16 +1,15 @@
1
1
  /** The parts beside the document: styles, numbering, theme, comments. */
2
2
 
3
- import {
4
- type AbstractNumberingJSON,
5
- type CommentJSON,
6
- type MarkJSON,
7
- type NumberingInstanceJSON,
8
- type NumberingLevelJSON,
9
- RUN_PROPERTY_MARKS,
10
- type StyleJSON,
11
- schema,
12
- type ThemeJSON,
3
+ import type {
4
+ AbstractNumberingJSON,
5
+ CommentJSON,
6
+ MarkJSON,
7
+ NumberingInstanceJSON,
8
+ NumberingLevelJSON,
9
+ StyleJSON,
10
+ ThemeJSON,
13
11
  } from "@folijs/core";
12
+ import { RUN_PROPERTY_MARKS, schema } from "@folijs/core/internal";
14
13
  import type { XmlElement } from "../xml.js";
15
14
  import { blocks, type ContentContext } from "./content.js";
16
15
  import { A, attr, child, compact, elements, integer, isW, toggle, W14, W15 } from "./ooxml.js";
@@ -46,7 +45,10 @@ function id(
46
45
  return n;
47
46
  }
48
47
 
49
- /** `w:styles`: the document defaults and the styles (each with its element verbatim). */
48
+ /**
49
+ * `w:styles`: the document defaults and the styles (each with its element verbatim).
50
+ * @internal
51
+ */
50
52
  export function styles(
51
53
  root: XmlElement,
52
54
  context: Context,
@@ -71,7 +73,10 @@ export function styles(
71
73
  return { defaults, styles: list };
72
74
  }
73
75
 
74
- /** `w:docDefaults` as the envelope's defaults (with the element verbatim). */
76
+ /**
77
+ * `w:docDefaults` as the envelope's defaults (with the element verbatim).
78
+ * @internal
79
+ */
75
80
  export function defaultsOf(docDefaults: XmlElement, context: Context): Record<string, unknown> {
76
81
  const pPr = child(child(docDefaults, "pPrDefault") ?? docDefaults, "pPr");
77
82
  const rPr = child(child(docDefaults, "rPrDefault") ?? docDefaults, "rPr");
@@ -84,7 +89,10 @@ export function defaultsOf(docDefaults: XmlElement, context: Context): Record<st
84
89
  };
85
90
  }
86
91
 
87
- /** Whether import keeps a `w:style` (it has a usable id and type); others stay in the part only. */
92
+ /**
93
+ * Whether import keeps a `w:style` (it has a usable id and type); others stay in the part only.
94
+ * @internal
95
+ */
88
96
  export function usableStyle(el: XmlElement): boolean {
89
97
  const styleId = attr(el, "styleId");
90
98
  return (
@@ -92,7 +100,10 @@ export function usableStyle(el: XmlElement): boolean {
92
100
  );
93
101
  }
94
102
 
95
- /** A `w:style` as a style (with the element verbatim); undefined (reported) when unusable. */
103
+ /**
104
+ * A `w:style` as a style (with the element verbatim); undefined (reported) when unusable.
105
+ * @internal
106
+ */
96
107
  export function styleOf(el: XmlElement, context: Context): StyleJSON | undefined {
97
108
  const styleId = attr(el, "styleId");
98
109
  const type = attr(el, "type") ?? "paragraph";
@@ -170,6 +181,7 @@ function breakCycles<T>(
170
181
  });
171
182
  }
172
183
 
184
+ /** @internal */
173
185
  export function level(lvl: XmlElement, context: Context): NumberingLevelJSON | undefined {
174
186
  const index = integer(attr(lvl, "ilvl"));
175
187
  if (index === undefined || index < 0 || index > 8) {
@@ -226,7 +238,10 @@ function checked(
226
238
  return out;
227
239
  }
228
240
 
229
- /** `w:numbering`: abstract definitions and instances (each with its element verbatim). */
241
+ /**
242
+ * `w:numbering`: abstract definitions and instances (each with its element verbatim).
243
+ * @internal
244
+ */
230
245
  export function numbering(
231
246
  root: XmlElement,
232
247
  context: Context,
@@ -245,7 +260,10 @@ export function numbering(
245
260
  return { abstracts, instances };
246
261
  }
247
262
 
248
- /** A `w:abstractNum` as a definition (with the element verbatim); undefined (reported) when unusable. */
263
+ /**
264
+ * A `w:abstractNum` as a definition (with the element verbatim); undefined (reported) when unusable.
265
+ * @internal
266
+ */
249
267
  export function abstractOf(el: XmlElement, context: Context): AbstractNumberingJSON | undefined {
250
268
  const abstractId = id(attr(el, "abstractNumId"), 0, "w:abstractNum", context);
251
269
  if (abstractId === undefined) return undefined;
@@ -278,7 +296,10 @@ export function abstractOf(el: XmlElement, context: Context): AbstractNumberingJ
278
296
  }) as AbstractNumberingJSON;
279
297
  }
280
298
 
281
- /** A `w:num` as an instance (with the element verbatim); undefined (reported) when unusable. */
299
+ /**
300
+ * A `w:num` as an instance (with the element verbatim); undefined (reported) when unusable.
301
+ * @internal
302
+ */
282
303
  export function instanceOf(el: XmlElement, context: Context): NumberingInstanceJSON | undefined {
283
304
  const numId = id(attr(el, "numId"), 1, "w:num", context);
284
305
  const abstract = id(attr(child(el, "abstractNumId"), "val"), 0, "w:num/w:abstractNumId", context);
@@ -332,7 +353,10 @@ const THEME_COLORS = [
332
353
  "folHlink",
333
354
  ];
334
355
 
335
- /** `a:theme`'s fonts and colors; undefined (reported) when its fonts are missing or unusable. */
356
+ /**
357
+ * `a:theme`'s fonts and colors; undefined (reported) when its fonts are missing or unusable.
358
+ * @internal
359
+ */
336
360
  export function theme(root: XmlElement, context: Context): ThemeJSON | undefined {
337
361
  const a = (el: XmlElement | undefined, local: string) =>
338
362
  el?.children.find(
@@ -374,6 +398,7 @@ export function theme(root: XmlElement, context: Context): ThemeJSON | undefined
374
398
  * `w:comments`, with replies and resolved state from `commentsExtended` (keyed by the
375
399
  * `w14:paraId` of each comment's last paragraph). Each comment keeps its start tag verbatim
376
400
  * (`ext`): values the model cannot hold (a long author, a date without a time) stay there.
401
+ * @internal
377
402
  */
378
403
  export function comments(
379
404
  root: XmlElement,
@@ -9,7 +9,9 @@ import type { XmlElement } from "../xml.js";
9
9
  import { A, attr, integer, R, textOf } from "./ooxml.js";
10
10
  import { type Context, sourceOf } from "./properties.js";
11
11
 
12
+ /** @internal */
12
13
  export const WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
14
+ /** @internal */
13
15
  export const PIC = "http://schemas.openxmlformats.org/drawingml/2006/picture";
14
16
  const ADEC = "http://schemas.microsoft.com/office/drawing/2017/decorative";
15
17
  const IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
@@ -24,6 +26,7 @@ const WRAPS: Record<string, string> = {
24
26
  };
25
27
  const SIDES = new Set(["bothSides", "left", "right", "largest"]);
26
28
 
29
+ /** @internal */
27
30
  export interface PictureContext extends Context {
28
31
  /** The part's relationship with this id. */
29
32
  readonly relationship: (
@@ -74,7 +77,10 @@ function position(el: XmlElement | undefined) {
74
77
  return undefined;
75
78
  }
76
79
 
77
- /** The `float` of a `wp:anchor`: undefined for one the model cannot hold (kept opaque). */
80
+ /**
81
+ * The `float` of a `wp:anchor`: undefined for one the model cannot hold (kept opaque).
82
+ * @internal
83
+ */
78
84
  export function floatOf(anchor: XmlElement): Record<string, unknown> | undefined {
79
85
  const horizontal = position(kid(anchor, WP, "positionH"));
80
86
  const vertical = position(kid(anchor, WP, "positionV"));
@@ -130,6 +136,7 @@ export function floatOf(anchor: XmlElement): Record<string, unknown> | undefined
130
136
  /**
131
137
  * The picture node's attributes for `drawing`, its image added to `resources`; undefined for
132
138
  * a drawing Foli keeps opaque (not one inline picture, no embedded image part).
139
+ * @internal
133
140
  */
134
141
  export function pictureAttrs(
135
142
  drawing: XmlElement,
@@ -5,21 +5,27 @@
5
5
  * element's verbatim `ext`, so nothing is lost.
6
6
  */
7
7
 
8
- import { checkSection, type MarkJSON, RUN_PROPERTY_MARKS, schema } from "@folijs/core";
8
+ import type { MarkJSON } from "@folijs/core";
9
+ import { checkSection, RUN_PROPERTY_MARKS, schema } from "@folijs/core/internal";
9
10
  import type { XmlElement } from "../xml.js";
10
11
  import { attr, child, compact, elements, integer, isW, R, toggle, W } from "./ooxml.js";
11
12
  import type { Recorder } from "./report.js";
12
13
 
14
+ /** @internal */
13
15
  export interface Context {
14
16
  readonly source: string;
15
17
  readonly report: Recorder;
16
18
  }
17
19
 
20
+ /** @internal */
18
21
  export function sourceOf(context: Context, element: XmlElement): string {
19
22
  return context.source.slice(element.start, element.end);
20
23
  }
21
24
 
22
- /** `object` without its undefined values. */
25
+ /**
26
+ * `object` without its undefined values.
27
+ * @internal
28
+ */
23
29
  export function compactDefined<T extends Record<string, unknown>>(object: T): Partial<T> {
24
30
  return Object.fromEntries(
25
31
  Object.entries(object).filter(([, value]) => value !== undefined),
@@ -31,6 +37,7 @@ const ATTRIBUTE_NAME = /^[A-Za-z_][\w.-]*(:[A-Za-z_][\w.-]*)?$/;
31
37
  /**
32
38
  * An element's attributes not in `modeled`, as an `attributes` bag (undefined when none). One
33
39
  * the bag cannot hold (a name outside its pattern, a value over 64 KiB, past 64) is reported.
40
+ * @internal
34
41
  */
35
42
  export function attributeBag(
36
43
  element: XmlElement,
@@ -58,7 +65,10 @@ export function attributeBag(
58
65
 
59
66
  const PARAGRAPH_ATTRS = schema.nodes.paragraph?.spec.attrs ?? {};
60
67
 
61
- /** Keeps `value` as paragraph attribute `name` if the schema accepts it; reports it otherwise. */
68
+ /**
69
+ * Keeps `value` as paragraph attribute `name` if the schema accepts it; reports it otherwise.
70
+ * @internal
71
+ */
62
72
  export function setParagraph(
63
73
  out: Record<string, unknown>,
64
74
  name: string,
@@ -72,7 +82,10 @@ export function setParagraph(
72
82
  else out[name] = value;
73
83
  }
74
84
 
75
- /** The mark if the schema accepts it; reported and left out otherwise. */
85
+ /**
86
+ * The mark if the schema accepts it; reported and left out otherwise.
87
+ * @internal
88
+ */
76
89
  export function mark(json: MarkJSON, element: string, context: Context): MarkJSON | undefined {
77
90
  try {
78
91
  schema.markFromJSON(json);
@@ -83,7 +96,10 @@ export function mark(json: MarkJSON, element: string, context: Context): MarkJSO
83
96
  }
84
97
  }
85
98
 
86
- /** Who and when, for tracked changes (`w:ins`, `w:del`, `w:rPrChange`…). */
99
+ /**
100
+ * Who and when, for tracked changes (`w:ins`, `w:del`, `w:rPrChange`…).
101
+ * @internal
102
+ */
87
103
  export function revisionOf(element: XmlElement): {
88
104
  id: number | undefined;
89
105
  author: string;
@@ -99,6 +115,7 @@ export function revisionOf(element: XmlElement): {
99
115
  /**
100
116
  * A tracked change's mark (`insertion`, `deletion`, with `move` for `w:moveFrom`/`w:moveTo`).
101
117
  * An invalid date is left out rather than losing the change.
118
+ * @internal
102
119
  */
103
120
  export function revisionMark(
104
121
  type: "insertion" | "deletion",
@@ -131,6 +148,7 @@ const TOGGLES: Record<string, string> = {
131
148
  * `w:rPr`'s run properties as marks (without `runExt`, the caller's). Tracked changes of the
132
149
  * paragraph mark (`w:ins`/`w:del` in a paragraph's `w:rPr`) are not run properties: see
133
150
  * `paragraphRevision`.
151
+ * @internal
134
152
  */
135
153
  export function runProperties(rPr: XmlElement | undefined, context: Context): MarkJSON[] {
136
154
  if (!rPr) return [];
@@ -312,7 +330,10 @@ function whole(
312
330
  return n;
313
331
  }
314
332
 
315
- /** An ST_OnOff attribute (`w:beforeAutospacing="1"`); another value is reported, read as missing. */
333
+ /**
334
+ * An ST_OnOff attribute (`w:beforeAutospacing="1"`); another value is reported, read as missing.
335
+ * @internal
336
+ */
316
337
  export function onOff(
317
338
  element: XmlElement | undefined,
318
339
  local: string,
@@ -332,6 +353,7 @@ const toggleProperty = (el: XmlElement | undefined) => (el ? toggle(el) : undefi
332
353
  /**
333
354
  * `w:pPr` as paragraph attributes. With `paragraph`, also what only a paragraph has (its
334
355
  * section, the paragraph mark's revisions, a formatting change, the verbatim `ext`).
356
+ * @internal
335
357
  */
336
358
  export function paragraphProperties(
337
359
  pPr: XmlElement | undefined,
@@ -509,7 +531,10 @@ function sectionChange(element: XmlElement | undefined, context: Context) {
509
531
  });
510
532
  }
511
533
 
512
- /** `w:sectPr` as a section; every part checked on its own. */
534
+ /**
535
+ * `w:sectPr` as a section; every part checked on its own.
536
+ * @internal
537
+ */
513
538
  export function section(sectPr: XmlElement, context: Context): Record<string, unknown> {
514
539
  const pgSz = child(sectPr, "pgSz");
515
540
  const pgNumType = child(sectPr, "pgNumType");
@@ -22,6 +22,7 @@ export interface ImportReport {
22
22
  readonly picturesWithoutAlt: number;
23
23
  }
24
24
 
25
+ /** @internal */
25
26
  export class Recorder {
26
27
  // Maps, not objects: element names such as `constructor` are only names.
27
28
  readonly #opaque = new Map<string, number>();
@@ -12,7 +12,10 @@ import { attr, elements, integer, isW, REL } from "./ooxml.js";
12
12
 
13
13
  const NOTE_TYPES = new Set(["normal", "separator", "continuationSeparator", "continuationNotice"]);
14
14
 
15
- /** The notes of a footnotes or endnotes part that the model holds, by story id. */
15
+ /**
16
+ * The notes of a footnotes or endnotes part that the model holds, by story id.
17
+ * @internal
18
+ */
16
19
  export function notesOf(root: XmlElement, kind: "footnote" | "endnote"): Map<string, XmlElement> {
17
20
  const out = new Map<string, XmlElement>();
18
21
  for (const el of elements(root)) {
@@ -31,7 +34,10 @@ const docOf = (content: StoryJSON["content"]["content"]): StoryJSON["content"] =
31
34
  content: content?.length ? content : [{ type: "paragraph" }],
32
35
  });
33
36
 
34
- /** Every story of the package, by id. `contextFor` gives the reading context of a part. */
37
+ /**
38
+ * Every story of the package, by id. `contextFor` gives the reading context of a part.
39
+ * @internal
40
+ */
35
41
  export function readStories(
36
42
  pkg: DocxPackage,
37
43
  contextFor: (part: string, source: string) => ContentContext,
@@ -88,7 +94,10 @@ export function readStories(
88
94
  return stories;
89
95
  }
90
96
 
91
- /** The ids of every note in the package's notes parts, those the model does not hold too. */
97
+ /**
98
+ * The ids of every note in the package's notes parts, those the model does not hold too.
99
+ * @internal
100
+ */
92
101
  export function noteIds(pkg: DocxPackage): Set<string> {
93
102
  const ids = new Set<string>();
94
103
  for (const [type, kind] of [
@@ -111,7 +120,10 @@ export function noteIds(pkg: DocxPackage): Set<string> {
111
120
  return ids;
112
121
  }
113
122
 
114
- /** The stories in the form a validated document holds them, to compare with one. */
123
+ /**
124
+ * The stories in the form a validated document holds them, to compare with one.
125
+ * @internal
126
+ */
115
127
  export function canonicalStories(
116
128
  pkg: DocxPackage,
117
129
  contextFor: (part: string, source: string) => ContentContext,
@@ -4,7 +4,8 @@
4
4
  * against the schema: one the model cannot hold is reported and stays in the element's `ext`.
5
5
  */
6
6
 
7
- import { type AttributeSpec, schema, TABLE_CONDITIONS } from "@folijs/core";
7
+ import { type AttributeSpec, TABLE_CONDITIONS } from "@folijs/core";
8
+ import { schema } from "@folijs/core/internal";
8
9
  import type { XmlElement } from "../xml.js";
9
10
  import { attr, child, compact, elements, integer, toggle } from "./ooxml.js";
10
11
  import { type Context, onOff, revisionOf, sourceOf } from "./properties.js";
@@ -37,6 +38,7 @@ function set(
37
38
  /**
38
39
  * A measure (`w:tblW`, `w:tcW`, `w:tblInd`, a margin): `w:w` in twips or fiftieths of a percent
39
40
  * (`pct`, which Strict files may write as `50%`). Undefined, reported, when unreadable.
41
+ * @internal
40
42
  */
41
43
  export function measure(el: XmlElement | undefined, context: Context): Json | undefined {
42
44
  if (!el) return undefined;
@@ -56,7 +58,10 @@ export function measure(el: XmlElement | undefined, context: Context): Json | un
56
58
  return { value, type };
57
59
  }
58
60
 
59
- /** A border element's attributes. */
61
+ /**
62
+ * A border element's attributes.
63
+ * @internal
64
+ */
60
65
  export function border(el: XmlElement, context: Context): Json | undefined {
61
66
  const whole = (local: string) => {
62
67
  const value = attr(el, local);
@@ -88,6 +93,7 @@ function margins(el: XmlElement | undefined, context: Context): Json | undefined
88
93
  );
89
94
  }
90
95
 
96
+ /** @internal */
91
97
  export function shading(el: XmlElement | undefined): Json | undefined {
92
98
  if (!el) return undefined;
93
99
  return compact({
@@ -126,6 +132,7 @@ const on = (el: XmlElement | undefined) => (el ? toggle(el) : undefined);
126
132
  /**
127
133
  * `w:tblPr` (or `w:tblPrEx`) as table properties. With `ext`, the element itself is kept
128
134
  * verbatim (a table's and a row's exceptions; a style's are in its own `ext`).
135
+ * @internal
129
136
  */
130
137
  export function tableProperties(el: XmlElement | undefined, context: Context, ext: boolean): Json {
131
138
  const out: Json = {};
@@ -149,7 +156,10 @@ export function tableProperties(el: XmlElement | undefined, context: Context, ex
149
156
  return out;
150
157
  }
151
158
 
152
- /** `w:tblGrid`'s column widths. */
159
+ /**
160
+ * `w:tblGrid`'s column widths.
161
+ * @internal
162
+ */
153
163
  export function grid(el: XmlElement | undefined, context: Context): number[] {
154
164
  if (!el) return [];
155
165
  const widths = elements(el)
@@ -163,7 +173,10 @@ export function grid(el: XmlElement | undefined, context: Context): number[] {
163
173
  return widths;
164
174
  }
165
175
 
166
- /** `w:trPr` as row properties; with `node`, also the row's revision and the element verbatim. */
176
+ /**
177
+ * `w:trPr` as row properties; with `node`, also the row's revision and the element verbatim.
178
+ * @internal
179
+ */
167
180
  export function rowProperties(el: XmlElement | undefined, context: Context, node: boolean): Json {
168
181
  const out: Json = {};
169
182
  if (!el) return out;
@@ -196,7 +209,10 @@ export function rowProperties(el: XmlElement | undefined, context: Context, node
196
209
  return out;
197
210
  }
198
211
 
199
- /** `w:tcPr` as cell properties; with `node`, also the element verbatim. */
212
+ /**
213
+ * `w:tcPr` as cell properties; with `node`, also the element verbatim.
214
+ * @internal
215
+ */
200
216
  export function cellProperties(el: XmlElement | undefined, context: Context, node: boolean): Json {
201
217
  const out: Json = {};
202
218
  if (!el) return out;
@@ -220,7 +236,10 @@ export function cellProperties(el: XmlElement | undefined, context: Context, nod
220
236
 
221
237
  const nonEmpty = (json: Json) => (Object.keys(json).length ? json : undefined);
222
238
 
223
- /** A table style's parts (`w:tblPr`, `w:trPr`, `w:tcPr`, `w:tblStylePr`) for its `StyleJSON`. */
239
+ /**
240
+ * A table style's parts (`w:tblPr`, `w:trPr`, `w:tcPr`, `w:tblStylePr`) for its `StyleJSON`.
241
+ * @internal
242
+ */
224
243
  export function tableStyleParts(
225
244
  style: XmlElement,
226
245
  context: Context,
package/src/package.ts CHANGED
@@ -4,7 +4,13 @@
4
4
  * was not asked to replace copied from the original file byte for byte.
5
5
  */
6
6
 
7
- import { type ParseXmlOptions, parseXml, type XmlDocument, type XmlElement } from "./xml.js";
7
+ import {
8
+ type ParseXmlOptions,
9
+ parseXmlCosting,
10
+ type XmlDocument,
11
+ type XmlElement,
12
+ XmlLimitError,
13
+ } from "./xml.js";
8
14
  import {
9
15
  deflateEntry,
10
16
  inflateEntry,
@@ -37,7 +43,30 @@ export interface Relationship {
37
43
  readonly partName?: string;
38
44
  }
39
45
 
40
- export interface ReadPackageOptions extends ZipLimits, ParseXmlOptions {}
46
+ /**
47
+ * Measured in 12.11 (Node, built packages): a 659-page Word document of dense tables (250 tables
48
+ * of 30 × 5 cells, 46 000 paragraphs) counts 1.9 million and takes 0.8 GB at its peak to import;
49
+ * 4 million of the costliest crafted content (empty paragraphs, or paragraphs of one tab) about
50
+ * 2.3 GB and 12-28 s depending on heap headroom. Far below a file's 512 MiB `maxSize`.
51
+ */
52
+ const DEFAULT_MAX_NODES = 4_000_000;
53
+ const W_MAIN = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
54
+ /**
55
+ * A paragraph costs about four times what other nodes do once imported (its node, properties
56
+ * and JSON: 1.4 KB at the peak against 0.1-0.5 KB), so a file of empty paragraphs is no cheaper
57
+ * way past the limit.
58
+ */
59
+ const PARAGRAPH_COST = 4;
60
+ const cost = (ns: string, local: string) => (local === "p" && ns === W_MAIN ? PARAGRAPH_COST : 1);
61
+
62
+ export interface ReadPackageOptions extends ZipLimits, ParseXmlOptions {
63
+ /**
64
+ * Most XML nodes in all the parts read, together: each element, attribute, text, comment and
65
+ * processing instruction counts one, a paragraph (`w:p`) four. Default 4 000 000: a 659-page
66
+ * document of dense tables counts 1.9 million; at the limit an import can take about 2.3 GB.
67
+ */
68
+ readonly maxNodes?: number;
69
+ }
41
70
 
42
71
  /** A file that is not a `.docx` package, or is damaged. */
43
72
  export class DocxError extends Error {
@@ -69,6 +98,10 @@ export class DocxPackage {
69
98
  readonly mainDocument: string;
70
99
  readonly #entries: readonly ZipEntry[];
71
100
  readonly #options: ParseXmlOptions;
101
+ /** `maxNodes`: for the whole package, every part read counting towards it. */
102
+ readonly #maxNodes: number;
103
+ /** Nodes the parts parsed from now on may still hold. */
104
+ #nodes: number;
72
105
  readonly #byName = new Map<string, DocxPart>();
73
106
  readonly #relationships = new Map<string, readonly Relationship[]>();
74
107
  readonly #xml = new Map<string, XmlDocument>();
@@ -80,9 +113,11 @@ export class DocxPackage {
80
113
  constructor(entries: readonly ZipEntry[], data: readonly Uint8Array[], options: ParseXmlOptions) {
81
114
  this.#entries = entries;
82
115
  this.#options = options.maxDepth === undefined ? {} : { maxDepth: options.maxDepth };
116
+ this.#maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
117
+ this.#nodes = this.#maxNodes;
83
118
  const index = entries.findIndex((e) => key(partName(e.name)) === key(CONTENT_TYPES));
84
119
  if (index === -1) throw new DocxError("Not a .docx: no [Content_Types].xml");
85
- const typesXml = xml(data[index] as Uint8Array, CONTENT_TYPES, this.#options);
120
+ const typesXml = this.#parse(data[index] as Uint8Array, CONTENT_TYPES);
86
121
  const types = contentTypes(typesXml.root);
87
122
  this.#defaults = types.defaults;
88
123
  this.#overridden = new Set(types.overrides.keys());
@@ -138,13 +173,28 @@ export class DocxPackage {
138
173
  return text(part.data, part.name);
139
174
  }
140
175
 
176
+ #parse(data: Uint8Array, name: string): XmlDocument {
177
+ try {
178
+ const doc = xml(data, name, { ...this.#options, maxNodes: this.#nodes });
179
+ this.#nodes -= doc.nodes;
180
+ return doc;
181
+ } catch (error) {
182
+ if (!((error as Error).cause instanceof XmlLimitError)) throw error;
183
+ throw new DocxError(
184
+ `${name}: the package holds more than ${this.#maxNodes} XML nodes, the limit ` +
185
+ "(maxNodes) of elements, attributes, text and comments read",
186
+ { cause: (error as Error).cause },
187
+ );
188
+ }
189
+ }
190
+
141
191
  /** The part parsed as XML (once); every node keeps its offsets into the part's text. */
142
192
  xml(name: string): XmlDocument {
143
193
  const part = this.part(name);
144
194
  if (!part) throw new DocxError(`No part ${name}`);
145
195
  let doc = this.#xml.get(key(part.name));
146
196
  if (!doc) {
147
- doc = xml(part.data, part.name, this.#options);
197
+ doc = this.#parse(part.data, part.name);
148
198
  this.#xml.set(key(part.name), doc);
149
199
  }
150
200
  return doc;
@@ -160,7 +210,7 @@ export class DocxPackage {
160
210
  async write(
161
211
  replace: ReadonlyMap<string, Uint8Array> = new Map(),
162
212
  add: readonly NewPart[] = [],
163
- ): Promise<Uint8Array> {
213
+ ): Promise<Uint8Array<ArrayBuffer>> {
164
214
  const pending = new Map<string, Uint8Array>();
165
215
  for (const [name, data] of replace) {
166
216
  const part = this.part(name);
@@ -320,7 +370,7 @@ function text(data: Uint8Array, name: string): string {
320
370
  function xml(data: Uint8Array, name: string, options: ParseXmlOptions): XmlDocument {
321
371
  const source = text(data, name);
322
372
  try {
323
- return parseXml(source, options);
373
+ return parseXmlCosting(source, options, cost);
324
374
  } catch (error) {
325
375
  // The XmlError (with its offset) stays reachable as the cause.
326
376
  throw new DocxError(`${name}: ${(error as Error).message}`, { cause: error });
package/src/settings.ts CHANGED
@@ -21,7 +21,10 @@ function isOn(settings: XmlElement | undefined, local: string): boolean {
21
21
  return value === undefined || !["false", "0", "off"].includes(value);
22
22
  }
23
23
 
24
- /** Whether `settings` (the `w:settings` root) turns tracked changes on. */
24
+ /**
25
+ * Whether `settings` (the `w:settings` root) turns tracked changes on.
26
+ * @internal
27
+ */
25
28
  export const trackRevisionsOf = (settings: XmlElement | undefined): boolean =>
26
29
  isOn(settings, "trackRevisions");
27
30
 
@@ -47,7 +50,10 @@ function noteProperties(element: XmlElement | undefined): NotePropertiesJSON {
47
50
  };
48
51
  }
49
52
 
50
- /** What the document's `settings` model holds of the part, undefined when nothing. */
53
+ /**
54
+ * What the document's `settings` model holds of the part, undefined when nothing.
55
+ * @internal
56
+ */
51
57
  export function readSettings(settings: XmlElement | undefined): WordSettingsJSON | undefined {
52
58
  if (!settings) return undefined;
53
59
  const notes = (local: string) => noteProperties(elementsOf(settings).find((c) => isW(c, local)));
@@ -166,7 +172,10 @@ function placed(source: string, root: XmlElement, local: string, element: string
166
172
 
167
173
  const prefixOf = (root: XmlElement) => (root.prefix ? `${root.prefix}:` : "");
168
174
 
169
- /** `source` (a settings part, `root` its `w:settings`) with tracked changes `on`. */
175
+ /**
176
+ * `source` (a settings part, `root` its `w:settings`) with tracked changes `on`.
177
+ * @internal
178
+ */
170
179
  export function withTrackRevisions(source: string, root: XmlElement, on: boolean): string {
171
180
  if (trackRevisionsOf(root) === on) return source;
172
181
  return placed(source, root, "trackRevisions", on ? `<${prefixOf(root)}trackRevisions/>` : "");
@@ -200,6 +209,7 @@ const sameNotes = (a: NotePropertiesJSON, b: NotePropertiesJSON) =>
200
209
  /**
201
210
  * `source` saying what `settings` says. What they leave out stays as the file has it, and a part
202
211
  * that already says it is returned as it is.
212
+ * @internal
203
213
  */
204
214
  export function withSettings(source: string, root: XmlElement, settings: WordSettingsJSON): string {
205
215
  let text = source;
@@ -226,7 +236,10 @@ export function withSettings(source: string, root: XmlElement, settings: WordSet
226
236
  return text;
227
237
  }
228
238
 
229
- /** A new settings part. */
239
+ /**
240
+ * A new settings part.
241
+ * @internal
242
+ */
230
243
  export function newSettingsXml(trackRevisions: boolean, settings: WordSettingsJSON = {}): string {
231
244
  const children =
232
245
  (trackRevisions ? "<w:trackRevisions/>" : "") +