documents.js 4.0.21 → 4.0.23
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.
- package/README.md +23 -19
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# documents.js
|
|
2
2
|
|
|
3
|
-
[](https://github.com/ExaDev/documents.js) [](https://www.npmjs.com/package/documents.js) [](https://github.com/ExaDev/documents.js/tree/main/packages/documents.js) [](https://www.npmjs.com/package/documents.js) [](https://www.npmjs.com/package/documents.js) [](https://github.com/ExaDev/documents.js/actions)
|
|
4
4
|
|
|
5
|
-
> Converts between any two compatible document formats through a shared content/layout pivot. docx, pptx, odt, odp, ods, odg, xlsx, csv (TSV is the same format with a tab delimiter), svg, and markdown all read into and build from the same shared `ContentDocument` model (reported to callers as the tree-form `DocumentPackage`), with PDF — reached through pdf-codec's own `LayoutDocument` view — as the one format every variant can reach. A composition engine (`convertDocument`) routes 111 (source, target) pairs across the ten content formats and PDF, including twenty PDF-pivot round trips (the eight layout-engine formats, plus xlsx and csv composing through ods), twenty-four cross-format bridge functions (same-variant direct copies, cross-variant semantic transforms, and PDF-composed), plus special-case conversions for `.odm` master documents, `.odb` database front-ends (HSQLDB and Firebird, four storage tiers), standalone `.odf` formula documents, and a bounded SQL/rpt-formula engine for `.odb` reports. Also includes: read-and-write live-view editors for all six editable formats, docx comment/footnote/header-footer exposure via `readDocxExtras`, real font resolution (source-embedded faces ahead of caller-supplied, vendored substitutes, and the standard 14), a hand-written MathML typesetting engine with embedded-font PDF rendering and a matching MathML ⇄ OMML translator, LaTeX lowering into the schema's two-layer semantic math core (pinned temml parser, symbol tables from prose, a coherence lint), and a fully hand-written PDF codec. Built on [ooxml.js](
|
|
5
|
+
> Converts between any two compatible document formats through a shared content/layout pivot. docx, pptx, odt, odp, ods, odg, xlsx, csv (TSV is the same format with a tab delimiter), svg, and markdown all read into and build from the same shared `ContentDocument` model (reported to callers as the tree-form `DocumentPackage`), with PDF — reached through pdf-codec's own `LayoutDocument` view — as the one format every variant can reach. A composition engine (`convertDocument`) routes 111 (source, target) pairs across the ten content formats and PDF, including twenty PDF-pivot round trips (the eight layout-engine formats, plus xlsx and csv composing through ods), twenty-four cross-format bridge functions (same-variant direct copies, cross-variant semantic transforms, and PDF-composed), plus special-case conversions for `.odm` master documents, `.odb` database front-ends (HSQLDB and Firebird, four storage tiers), standalone `.odf` formula documents, and a bounded SQL/rpt-formula engine for `.odb` reports. Also includes: read-and-write live-view editors for all six editable formats, docx comment/footnote/header-footer exposure via `readDocxExtras`, real font resolution (source-embedded faces ahead of caller-supplied, vendored substitutes, and the standard 14), a hand-written MathML typesetting engine with embedded-font PDF rendering and a matching MathML ⇄ OMML translator, LaTeX lowering into the schema's two-layer semantic math core (pinned temml parser, symbol tables from prose, a coherence lint), and a fully hand-written PDF codec. Built on [ooxml.js](../ooxml.js/README.md), [odf.js](../odf.js/README.md), [pdf-codec](../pdf-codec/README.md), [markdown-codec](../markdown-codec/README.md), and [document-schema.js](../document-schema.js/README.md).
|
|
6
6
|
|
|
7
7
|
`documents.js` extends `ooxml.js` in two directions `ooxml.js` deliberately does not cover: full PDF support (parsing and generating, via `pdf-codec`), and a read-**and-write** manipulation API for docx/pptx content — `ooxml.js`'s own typed readers are one-way. The PDF codec is hand-written against ISO 32000-1, with no external PDF library as a dependency — see [Fidelity](#fidelity) and pdf-codec's own README for the honest trade-off (not as robust against adversarial PDFs as a 15+-year-hardened library; fully auditable and dependency-free instead). `src/mathml/` (the MathML typesetting engine) stays in this package and is hand-written too, for the same supply-chain reason. The one deliberate exception on the math side is the LaTeX parser: `src/latex/` lowers LaTeX into the schema's semantic core over a pinned exact-version [temml](https://temml.org) dependency — see [LaTeX lowering into the semantic core](#latex-lowering-into-the-semantic-core) for why a LaTeX grammar is the one component not worth hand-writing and what the pin guarantees.
|
|
8
8
|
|
|
@@ -35,15 +35,15 @@ graph TD
|
|
|
35
35
|
odf --> cli
|
|
36
36
|
pdfcodec --> cli
|
|
37
37
|
|
|
38
|
-
click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
|
|
39
|
-
click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
|
|
40
|
-
click odf "https://github.com/ExaDev/odf.js" "odf.js"
|
|
41
|
-
click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec"
|
|
42
|
-
click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
|
|
43
|
-
click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec"
|
|
38
|
+
click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
|
|
39
|
+
click ooxml "https://github.com/ExaDev/documents.js/tree/main/packages/ooxml.js" "ooxml.js"
|
|
40
|
+
click odf "https://github.com/ExaDev/documents.js/tree/main/packages/odf.js" "odf.js"
|
|
41
|
+
click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
|
|
42
|
+
click mdcodec "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec" "markdown-codec"
|
|
43
|
+
click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
|
|
44
44
|
click documents "https://github.com/ExaDev/documents.js" "documents.js"
|
|
45
|
-
click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
|
|
46
|
-
click cli "https://github.com/ExaDev/document-cli" "document-cli"
|
|
45
|
+
click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
|
|
46
|
+
click cli "https://github.com/ExaDev/documents.js/tree/main/packages/document-cli" "document-cli"
|
|
47
47
|
|
|
48
48
|
style documents fill:#f9a825,stroke:#333,stroke-width:3px
|
|
49
49
|
```
|
|
@@ -159,6 +159,8 @@ const { document, diagnostics } = await converter.convert(
|
|
|
159
159
|
|
|
160
160
|
`DocumentFormat` includes `docx`/`pptx`/`xlsx`/`odt`/`odp`/`ods`/`odg`/`svg`/`odf`/`csv`/`markdown`/`pdf` — twelve members. The port's `conversions` list is derived from `resolveCompositionPlan` plus the `odf`→`pdf` special case — 111 pairs total. `DocumentFormat` is inferred from `DocumentFormatSchema` (a real Zod schema); `DOCUMENT_FORMATS` is exported as a plain array derived from the same schema:
|
|
161
161
|
|
|
162
|
+
The port also exposes `contractVersion: number`, bumped only when `DocumentConverter`'s own contract shape changes — a new field on `ConversionResult` a caller might need to branch on, or a new `ConversionOptions` field an implementation is now expected to honour — never when the `conversions` table simply grows with more supported source/target pairs (that's discoverable at runtime via `conversions` itself). It is currently `7`: the bump from `6` reflects `ConversionResult.package` changing type to the tree-form `DocumentPackage` described below, which a caller reading that field must now flatten rather than read directly.
|
|
163
|
+
|
|
162
164
|
```ts
|
|
163
165
|
import { DOCUMENT_FORMATS, DocumentFormatSchema } from 'documents.js';
|
|
164
166
|
|
|
@@ -722,29 +724,31 @@ Read as **row → column**. `✓` lossless, `~` bounded, `✗` lossy, `✗✗` s
|
|
|
722
724
|
|
|
723
725
|
## Release and publishing
|
|
724
726
|
|
|
725
|
-
|
|
727
|
+
Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism (topological per-package `semantic-release` via `@exadev/semantic-release-workspace`, OIDC trusted npm publishing, automatic sibling dependency-range rewriting) and its [known gap](../../README.md#releases) note on GitHub Packages republishing and SBOM/provenance signing, both dropped in the migration to this monorepo and not yet restored.
|
|
726
728
|
|
|
727
729
|
## Contributing
|
|
728
730
|
|
|
729
|
-
Conventional Commits
|
|
731
|
+
Conventional Commits, enforced workspace-wide by commitlint through a root `commit-msg` hook. Work inside `packages/documents.js/`; see the [root README](../../README.md#contributing) for the shared git hooks and history conventions.
|
|
730
732
|
|
|
731
733
|
## References
|
|
732
734
|
|
|
733
|
-
- [ooxml.js](
|
|
734
|
-
- [document-schema.js](
|
|
735
|
-
- [markdown-codec](
|
|
736
|
-
- [pdf-codec](
|
|
737
|
-
- [byte-codec](
|
|
738
|
-
- [odf.js](
|
|
735
|
+
- [ooxml.js](../ooxml.js/README.md) — docx/pptx/xlsx ⇄ JSON handling and typed reading, including `readXlsxContent` and the flat spreadsheet builder it pairs with, `buildXlsxPackageFromContent` (consumed by the `odsToXlsx`/`xlsxToOds` bridge and internal codecs, and re-exported directly from this package's own surface under the long-standing `buildXlsxPackage` name — see [Reading and building xlsx content directly](#reading-and-building-xlsx-content-directly)).
|
|
736
|
+
- [document-schema.js](../document-schema.js/README.md) — owns `ContentDocument`, the tree-form `DocumentPackage` and its styles-table facility, and the port contracts; shared by all sibling packages.
|
|
737
|
+
- [markdown-codec](../markdown-codec/README.md) — CommonMark+GFM ⇄ `ContentDocument` handling. The third format (after docx/odt) sharing the wordprocessing pivot.
|
|
738
|
+
- [pdf-codec](../pdf-codec/README.md) — the hand-written PDF codec (`readPdf`/`writePdf`/`pdfCodec`), the embedded STIX Two Math font, and text-measurement/font-resolution primitives.
|
|
739
|
+
- [byte-codec](../byte-codec/README.md) — generic byte/image utilities (ByteWriter, CRC-32, deflate/inflate, PNG/JPEG), extracted from pdf-codec.
|
|
740
|
+
- [odf.js](../odf.js/README.md) — ODF codec (odt/ods/odp/odg), also built on `document-schema.js`. Style interning, rotation, `svg:d` parsing, and manifest handling consumed directly.
|
|
739
741
|
- [STIX Two Math](https://github.com/stipub/stixfonts) — the embedded math font. Vendored within pdf-codec (OFL-1.1).
|
|
740
742
|
- [firebirdsql/firebird](https://github.com/FirebirdSQL/firebird) — ground truth for `src/firebird/`, since gbak backup format has no ratified spec. Read as source material only, not a build/runtime dependency.
|
|
741
743
|
|
|
742
744
|
## npm aliases
|
|
743
745
|
|
|
744
|
-
This package also
|
|
746
|
+
This package also published under an alternate name from the pre-monorepo pipeline:
|
|
745
747
|
|
|
746
748
|
- [js.documents](https://www.npmjs.com/package/js.documents)
|
|
747
749
|
|
|
750
|
+
**Frozen since the monorepo migration** — see the [root README's release note](../../README.md#releases): the alias republish step was dropped along with GitHub Packages mirroring and SBOM/provenance signing, and nothing today keeps this name in sync with `documents.js`'s own releases. Tracked in [ExaDev/documents.js#731](https://github.com/ExaDev/documents.js/issues/731).
|
|
751
|
+
|
|
748
752
|
## License
|
|
749
753
|
|
|
750
754
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "documents.js",
|
|
3
|
-
"version": "4.0.
|
|
3
|
+
"version": "4.0.23",
|
|
4
4
|
"description": "Bidirectional docx/pptx <-> PDF conversion and a read+write editable OOXML document model, built on ooxml.js and Zod 4 codecs.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -84,13 +84,13 @@
|
|
|
84
84
|
"license": "MIT",
|
|
85
85
|
"packageManager": "pnpm@11.6.0",
|
|
86
86
|
"dependencies": {
|
|
87
|
-
"byte-codec": "^1.1.
|
|
88
|
-
"document-schema.js": "^4.3.
|
|
87
|
+
"byte-codec": "^1.1.12",
|
|
88
|
+
"document-schema.js": "^4.3.6",
|
|
89
89
|
"fflate": "^0.8.3",
|
|
90
|
-
"markdown-codec": "^4.0.
|
|
91
|
-
"odf.js": "^5.0.
|
|
92
|
-
"ooxml.js": "^4.0.
|
|
93
|
-
"pdf-codec": "^3.0.
|
|
90
|
+
"markdown-codec": "^4.0.9",
|
|
91
|
+
"odf.js": "^5.0.6",
|
|
92
|
+
"ooxml.js": "^4.0.11",
|
|
93
|
+
"pdf-codec": "^3.0.11",
|
|
94
94
|
"temml": "0.13.4",
|
|
95
95
|
"zod": "^4.4.3"
|
|
96
96
|
},
|