js.documents 1.57.0 → 1.58.0

package/README.md

@@ -6,6 +6,35 @@
 
 `documents.js` depends on `ooxml.js` for lossless docx/pptx/xlsx ⇄ JSON handling and extends it in two directions `ooxml.js` deliberately does not cover: full PDF support (parsing arbitrary real-world PDFs and generating new ones), and a read-**and-write** manipulation API for docx/pptx content — `ooxml.js`'s own typed readers (`readDocx`/`readPptx`) are one-way and explicitly forbid write-back. PDF reading, writing, and the docx⇄PDF/pptx⇄PDF conversion pipeline are provided by [`pdf-codec`](https://github.com/ExaDev/pdf-codec), a sibling package extracted from this one: a hand-written, dependency-minimal PDF codec with no external PDF library (`pdf-lib`, `pdfjs-dist`, `mupdf`, or any other) as a dependency — see pdf-codec's own README for how it's built and what it embeds (including the vendored STIX Two Math font this package renders formulas through). `src/mathml/` (the MathML typesetting engine) stays in this package and is hand-written too, for the same "no supply-chain surface beyond what's already declared" reason, but consumes pdf-codec's embedded math font through a structurally-typed port rather than any font-parsing code of its own — see [Architecture](#architecture).
 
+```mermaid
+graph TD
+    schema("document-schema.js")
+    ooxml("ooxml.js")
+    odf("odf.js")
+    pdfcodec("pdf-codec")
+    documents("documents.js")
+    cli("document-cli")
+
+    schema --> ooxml
+    schema --> odf
+    schema --> pdfcodec
+    schema --> documents
+    ooxml --> documents
+    odf --> documents
+    pdfcodec --> documents
+    documents --> cli
+    odf --> cli
+
+    click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
+    click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
+    click odf "https://github.com/ExaDev/odf.js" "odf.js"
+    click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec"
+    click documents "https://github.com/ExaDev/documents.js" "documents.js"
+    click cli "https://github.com/ExaDev/document-cli" "document-cli"
+
+    style documents fill:#f9a825,stroke:#333,stroke-width:3px
+```
+
 ## Why
 
 Converting docx/pptx to PDF and back is usually solved by wrapping a mature third-party PDF library. This package takes the opposite approach for the PDF side of the equation: pdf-codec hand-writes every layer of the PDF format — the object model, the cross-reference table, the content-stream operators, standard-font metrics, the parser's cross-reference/object-stream resolution and content-stream interpreter — against the ISO 32000-1 specification, rather than wrapping one. That is a genuinely large undertaking, and it comes with an honest trade-off spelled out in [Fidelity](#fidelity) below and in pdf-codec's own README: this is not, and does not attempt to be, as robust against adversarial or badly malformed real-world PDFs as a library with 15+ years of hardening. What it buys instead is a dependency-free, fully auditable PDF implementation, with `documents.js`'s own supply-chain surface staying limited to `ooxml.js`, `odf.js`, `document-schema.js`, `pdf-codec`, and `fflate`.
@@ -298,6 +327,15 @@ const { box, diagnostics } = layoutFormula(mathml, { metrics: metricsAt(12), siz
 // diagnostics: a 'missing-glyph' or 'unsupported-element' entry for anything this engine couldn't render faithfully -- see Fidelity
 ```
 
+Every module under `src/` is also directly deep-importable by its package-relative path, without going through the barrel — useful for a caller that wants exactly one conversion function and nothing else pulled in:
+
+```ts
+import { emuToPt } from 'documents.js/model/units';
+import { buildOdtPackage } from 'documents.js/edit/odt/content';
+```
+
+This works via a `"./*"` wildcard entry in `package.json`'s `exports` map, resolving any subpath to the correspondingly-named file under `dist/` — the same directory structure `src/` has, one output file per source module, so `src/edit/odt/content.ts` becomes `dist/edit/odt/content.js`/`.cjs`/`.d.ts`/`.d.cts`.
+
 ## Architecture
 
 The package is layered from generic primitives outward to the two conversion directions:

package/dist/blr-types-CYYC3yYU.d.cts

@@ -0,0 +1,35 @@
+//#region src/firebird/blr-types.d.ts
+declare const BLR_SHORT = 7;
+declare const BLR_LONG = 8;
+declare const BLR_QUAD = 9;
+declare const BLR_FLOAT = 10;
+declare const BLR_D_FLOAT = 11;
+declare const BLR_SQL_DATE = 12;
+declare const BLR_SQL_TIME = 13;
+declare const BLR_TEXT = 14;
+declare const BLR_TEXT2 = 15;
+declare const BLR_INT64 = 16;
+declare const BLR_BOOL = 23;
+declare const BLR_DEC64 = 24;
+declare const BLR_DEC128 = 25;
+declare const BLR_INT128 = 26;
+declare const BLR_DOUBLE = 27;
+declare const BLR_SQL_TIME_TZ = 28;
+declare const BLR_TIMESTAMP_TZ = 29;
+declare const BLR_EX_TIME_TZ = 30;
+declare const BLR_EX_TIMESTAMP_TZ = 31;
+declare const BLR_TIMESTAMP = 35;
+declare const BLR_VARYING = 37;
+declare const BLR_VARYING2 = 38;
+declare const BLR_CSTRING = 40;
+declare const BLR_CSTRING2 = 41;
+declare const BLR_BLOB = 261;
+type FirebirdPhysicalType = 'short' | 'long' | 'int64' | 'real' | 'double' | 'sql_date' | 'sql_time' | 'timestamp' | 'text' | 'varying' | 'cstring' | 'boolean' | 'blob' | 'quad' | 'int128' | 'dec64' | 'dec128' | 'unsupported-tz';
+declare class FirebirdUnsupportedFieldTypeError extends Error {
+  readonly blrType: number;
+  constructor(blrType: number);
+}
+declare function decodeBlrType(blrType: number): FirebirdPhysicalType;
+declare function describeFieldType(physical: FirebirdPhysicalType, lengthBytes: number, scale: number, characterLength: number | undefined): string;
+//#endregion
+export { BLR_TIMESTAMP_TZ as C, FirebirdUnsupportedFieldTypeError as D, FirebirdPhysicalType as E, decodeBlrType as O, BLR_TIMESTAMP as S, BLR_VARYING2 as T, BLR_SQL_DATE as _, BLR_DEC128 as a, BLR_TEXT as b, BLR_D_FLOAT as c, BLR_FLOAT as d, BLR_INT128 as f, BLR_SHORT as g, BLR_QUAD as h, BLR_CSTRING2 as i, describeFieldType as k, BLR_EX_TIMESTAMP_TZ as l, BLR_LONG as m, BLR_BOOL as n, BLR_DEC64 as o, BLR_INT64 as p, BLR_CSTRING as r, BLR_DOUBLE as s, BLR_BLOB as t, BLR_EX_TIME_TZ as u, BLR_SQL_TIME as v, BLR_VARYING as w, BLR_TEXT2 as x, BLR_SQL_TIME_TZ as y };

package/dist/blr-types-CYYC3yYU.d.ts

@@ -0,0 +1,35 @@
+//#region src/firebird/blr-types.d.ts
+declare const BLR_SHORT = 7;
+declare const BLR_LONG = 8;
+declare const BLR_QUAD = 9;
+declare const BLR_FLOAT = 10;
+declare const BLR_D_FLOAT = 11;
+declare const BLR_SQL_DATE = 12;
+declare const BLR_SQL_TIME = 13;
+declare const BLR_TEXT = 14;
+declare const BLR_TEXT2 = 15;
+declare const BLR_INT64 = 16;
+declare const BLR_BOOL = 23;
+declare const BLR_DEC64 = 24;
+declare const BLR_DEC128 = 25;
+declare const BLR_INT128 = 26;
+declare const BLR_DOUBLE = 27;
+declare const BLR_SQL_TIME_TZ = 28;
+declare const BLR_TIMESTAMP_TZ = 29;
+declare const BLR_EX_TIME_TZ = 30;
+declare const BLR_EX_TIMESTAMP_TZ = 31;
+declare const BLR_TIMESTAMP = 35;
+declare const BLR_VARYING = 37;
+declare const BLR_VARYING2 = 38;
+declare const BLR_CSTRING = 40;
+declare const BLR_CSTRING2 = 41;
+declare const BLR_BLOB = 261;
+type FirebirdPhysicalType = 'short' | 'long' | 'int64' | 'real' | 'double' | 'sql_date' | 'sql_time' | 'timestamp' | 'text' | 'varying' | 'cstring' | 'boolean' | 'blob' | 'quad' | 'int128' | 'dec64' | 'dec128' | 'unsupported-tz';
+declare class FirebirdUnsupportedFieldTypeError extends Error {
+  readonly blrType: number;
+  constructor(blrType: number);
+}
+declare function decodeBlrType(blrType: number): FirebirdPhysicalType;
+declare function describeFieldType(physical: FirebirdPhysicalType, lengthBytes: number, scale: number, characterLength: number | undefined): string;
+//#endregion
+export { BLR_TIMESTAMP_TZ as C, FirebirdUnsupportedFieldTypeError as D, FirebirdPhysicalType as E, decodeBlrType as O, BLR_TIMESTAMP as S, BLR_VARYING2 as T, BLR_SQL_DATE as _, BLR_DEC128 as a, BLR_TEXT as b, BLR_D_FLOAT as c, BLR_FLOAT as d, BLR_INT128 as f, BLR_SHORT as g, BLR_QUAD as h, BLR_CSTRING2 as i, describeFieldType as k, BLR_EX_TIMESTAMP_TZ as l, BLR_LONG as m, BLR_BOOL as n, BLR_DEC64 as o, BLR_INT64 as p, BLR_CSTRING as r, BLR_DOUBLE as s, BLR_BLOB as t, BLR_EX_TIME_TZ as u, BLR_SQL_TIME as v, BLR_VARYING as w, BLR_TEXT2 as x, BLR_SQL_TIME_TZ as y };

package/dist/cell-CNHPsDEk.d.cts

@@ -0,0 +1,17 @@
+import { ContentCellValue, ContentRun } from "document-schema.js";
+import { Package, XmlElement } from "odf.js";
+//#region src/edit/ods/cell.d.ts
+declare class OdsCell {
+  private readonly node;
+  private readonly pkg;
+  constructor(node: XmlElement, pkg: Package);
+  get value(): ContentCellValue;
+  set value(value: ContentCellValue);
+  get formula(): string | undefined;
+  set formula(value: string | undefined);
+  get displayText(): string;
+  set displayText(value: string);
+  setStyledRuns(runs: readonly ContentRun[]): void;
+}
+//#endregion
+export { OdsCell as t };

package/dist/cell-CNHPsDEk.d.ts

@@ -0,0 +1,17 @@
+import { ContentCellValue, ContentRun } from "document-schema.js";
+import { Package, XmlElement } from "odf.js";
+//#region src/edit/ods/cell.d.ts
+declare class OdsCell {
+  private readonly node;
+  private readonly pkg;
+  constructor(node: XmlElement, pkg: Package);
+  get value(): ContentCellValue;
+  set value(value: ContentCellValue);
+  get formula(): string | undefined;
+  set formula(value: string | undefined);
+  get displayText(): string;
+  set displayText(value: string);
+  setStyledRuns(runs: readonly ContentRun[]): void;
+}
+//#endregion
+export { OdsCell as t };

package/dist/color-71eoF1Up.d.cts

@@ -0,0 +1,2 @@
+import { COLOR_BLACK, Color as LayoutColor, ColorSchema as LayoutColorSchema, colorToRgbHex, rgbHexToColor } from "document-schema.js";
+export { rgbHexToColor as a, colorToRgbHex as i, LayoutColor as n, LayoutColorSchema as r, COLOR_BLACK as t };

package/dist/color-Bo228AY2.d.ts

@@ -0,0 +1,2 @@
+import { COLOR_BLACK as COLOR_BLACK$1, Color as LayoutColor, ColorSchema as LayoutColorSchema, colorToRgbHex, rgbHexToColor } from "document-schema.js";
+export { rgbHexToColor as a, colorToRgbHex as i, LayoutColor as n, LayoutColorSchema as r, COLOR_BLACK$1 as t };

package/dist/convert/codec.cjs

@@ -0,0 +1,51 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_model_bytes = require("../model/bytes.cjs");
+const require_convert_convert = require("./convert.cjs");
+let zod = require("zod");
+//#region src/convert/codec.ts
+const docxPdfCodec = zod.z.codec(require_model_bytes.DocxBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (docxBytes) => require_convert_convert.docxToPdf(docxBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToDocx(pdfBytes)
+});
+const pptxPdfCodec = zod.z.codec(require_model_bytes.PptxBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (pptxBytes) => require_convert_convert.pptxToPdf(pptxBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToPptx(pdfBytes)
+});
+const odtPdfCodec = zod.z.codec(require_model_bytes.OdtBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (odtBytes) => require_convert_convert.odtToPdf(odtBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToOdt(pdfBytes)
+});
+const odpPdfCodec = zod.z.codec(require_model_bytes.OdpBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (odpBytes) => require_convert_convert.odpToPdf(odpBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToOdp(pdfBytes)
+});
+const odsPdfCodec = zod.z.codec(require_model_bytes.OdsBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (odsBytes) => require_convert_convert.odsToPdf(odsBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToOds(pdfBytes)
+});
+const odgPdfCodec = zod.z.codec(require_model_bytes.OdgBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (odgBytes) => require_convert_convert.odgToPdf(odgBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToOdg(pdfBytes)
+});
+const odtDocxCodec = zod.z.codec(require_model_bytes.OdtBytesSchema, require_model_bytes.DocxBytesSchema, {
+	decode: (odtBytes) => require_convert_convert.odtToDocx(odtBytes),
+	encode: (docxBytes) => require_convert_convert.docxToOdt(docxBytes)
+});
+const odpPptxCodec = zod.z.codec(require_model_bytes.OdpBytesSchema, require_model_bytes.PptxBytesSchema, {
+	decode: (odpBytes) => require_convert_convert.odpToPptx(odpBytes),
+	encode: (pptxBytes) => require_convert_convert.pptxToOdp(pptxBytes)
+});
+const odsXlsxCodec = zod.z.codec(require_model_bytes.OdsBytesSchema, require_model_bytes.XlsxBytesSchema, {
+	decode: (odsBytes) => require_convert_convert.odsToXlsx(odsBytes),
+	encode: (xlsxBytes) => require_convert_convert.xlsxToOds(xlsxBytes)
+});
+//#endregion
+exports.docxPdfCodec = docxPdfCodec;
+exports.odgPdfCodec = odgPdfCodec;
+exports.odpPdfCodec = odpPdfCodec;
+exports.odpPptxCodec = odpPptxCodec;
+exports.odsPdfCodec = odsPdfCodec;
+exports.odsXlsxCodec = odsXlsxCodec;
+exports.odtDocxCodec = odtDocxCodec;
+exports.odtPdfCodec = odtPdfCodec;
+exports.pptxPdfCodec = pptxPdfCodec;

package/dist/convert/codec.d.cts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+//#region src/convert/codec.d.ts
+declare const docxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const pptxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odtPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odpPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odsPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odgPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odtDocxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odpPptxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odsXlsxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+//#endregion
+export { docxPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec };

package/dist/convert/codec.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+//#region src/convert/codec.d.ts
+declare const docxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const pptxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odtPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odpPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odsPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odgPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odtDocxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odpPptxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odsXlsxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+//#endregion
+export { docxPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec };

package/dist/convert/codec.js

@@ -0,0 +1,42 @@
+import { DocxBytesSchema, OdgBytesSchema, OdpBytesSchema, OdsBytesSchema, OdtBytesSchema, PdfBytesSchema, PptxBytesSchema, XlsxBytesSchema } from "../model/bytes.js";
+import { docxToOdt, docxToPdf, odgToPdf, odpToPdf, odpToPptx, odsToPdf, odsToXlsx, odtToDocx, odtToPdf, pdfToDocx, pdfToOdg, pdfToOdp, pdfToOds, pdfToOdt, pdfToPptx, pptxToOdp, pptxToPdf, xlsxToOds } from "./convert.js";
+import { z } from "zod";
+//#region src/convert/codec.ts
+const docxPdfCodec = z.codec(DocxBytesSchema, PdfBytesSchema, {
+	decode: (docxBytes) => docxToPdf(docxBytes),
+	encode: (pdfBytes) => pdfToDocx(pdfBytes)
+});
+const pptxPdfCodec = z.codec(PptxBytesSchema, PdfBytesSchema, {
+	decode: (pptxBytes) => pptxToPdf(pptxBytes),
+	encode: (pdfBytes) => pdfToPptx(pdfBytes)
+});
+const odtPdfCodec = z.codec(OdtBytesSchema, PdfBytesSchema, {
+	decode: (odtBytes) => odtToPdf(odtBytes),
+	encode: (pdfBytes) => pdfToOdt(pdfBytes)
+});
+const odpPdfCodec = z.codec(OdpBytesSchema, PdfBytesSchema, {
+	decode: (odpBytes) => odpToPdf(odpBytes),
+	encode: (pdfBytes) => pdfToOdp(pdfBytes)
+});
+const odsPdfCodec = z.codec(OdsBytesSchema, PdfBytesSchema, {
+	decode: (odsBytes) => odsToPdf(odsBytes),
+	encode: (pdfBytes) => pdfToOds(pdfBytes)
+});
+const odgPdfCodec = z.codec(OdgBytesSchema, PdfBytesSchema, {
+	decode: (odgBytes) => odgToPdf(odgBytes),
+	encode: (pdfBytes) => pdfToOdg(pdfBytes)
+});
+const odtDocxCodec = z.codec(OdtBytesSchema, DocxBytesSchema, {
+	decode: (odtBytes) => odtToDocx(odtBytes),
+	encode: (docxBytes) => docxToOdt(docxBytes)
+});
+const odpPptxCodec = z.codec(OdpBytesSchema, PptxBytesSchema, {
+	decode: (odpBytes) => odpToPptx(odpBytes),
+	encode: (pptxBytes) => pptxToOdp(pptxBytes)
+});
+const odsXlsxCodec = z.codec(OdsBytesSchema, XlsxBytesSchema, {
+	decode: (odsBytes) => odsToXlsx(odsBytes),
+	encode: (xlsxBytes) => xlsxToOds(xlsxBytes)
+});
+//#endregion
+export { docxPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec };