@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/writer/streaming-writer.d.ts

@@ -0,0 +1,344 @@
+/**
+ * DOCX Module - Streaming Writer
+ *
+ * A DOCX generator that serializes body content incrementally and pushes it
+ * through a streaming compression pipeline. Uses the same streaming ZIP
+ * infrastructure as the Excel module:
+ *
+ * - `Zip` (StreamingZip) — streams ZIP entries to output
+ * - `ZipDeflate` — per-entry deflate compression
+ * - `StreamBuf` — event-driven pipe from XML to ZIP
+ * - `StringBuf` — efficient XML string builder with buffer reuse
+ *
+ * Data flow with sink (true end-to-end streaming):
+ * ```
+ * add(paragraph) → XML → StreamBuf → ZipDeflate → Zip
+ *                                                     ↓ (per-chunk callback)
+ *                                            await SinkAdapter.write(chunk)
+ *                                                     ↓
+ *                                           user-supplied WritableStream /
+ *                                           Node Writable / duck-typed sink
+ * ```
+ *
+ * Memory profile:
+ *   - Body model is never retained: each element is serialised and
+ *     compressed as it arrives, so peak per-element memory is
+ *     O(largest_single_element).
+ *   - When `options.sink` is provided, compressed bytes are pushed
+ *     into the sink as soon as they are produced (with backpressure
+ *     awaited via {@link SinkAdapter}). Total writer-side memory then
+ *     stays O(largest_part) regardless of final DOCX size.
+ *   - When `options.sink` is omitted, compressed bytes accumulate in
+ *     `_outputChunks` and `finalize()` returns the assembled
+ *     `Uint8Array`. Total memory is O(compressed_docx_size).
+ */
+import { type AnySink } from "../../stream/internal/sink-adapter.js";
+import type { WordSecurityPolicy } from "../security/policy.js";
+import type { AbstractNumbering, AppProperties, BodyContent, CommentDef, CoreProperties, CustomProperty, CustomXmlPart, DocDefaults, DocumentBackground, DocumentSettings, DocumentTheme, EmbeddedFont, EndnoteDef, FontDef, FooterDef, FootnoteDef, HeaderDef, ImageDef, NumberingInstance, OpaquePart, Paragraph, SectionProperties, StyleDef, Watermark } from "../types.js";
+/** Options for the streaming DOCX writer. */
+export interface StreamingDocxOptions {
+    /** Compression level (0-9). Default: 6. */
+    readonly compressionLevel?: number;
+    /** Progress callback interval: report after every N elements. Default: 1000. */
+    readonly chunkSize?: number;
+    /** Section properties for the final section. */
+    readonly sectionProperties?: SectionProperties;
+    /** Document styles. */
+    readonly styles?: readonly StyleDef[];
+    /** Document defaults. */
+    readonly docDefaults?: DocDefaults;
+    /** Abstract numbering definitions. */
+    readonly abstractNumberings?: readonly AbstractNumbering[];
+    /** Numbering instances. */
+    readonly numberingInstances?: readonly NumberingInstance[];
+    /** Headers. */
+    readonly headers?: ReadonlyMap<string, HeaderDef>;
+    /** Footers. */
+    readonly footers?: ReadonlyMap<string, FooterDef>;
+    /** Footnotes. */
+    readonly footnotes?: readonly FootnoteDef[];
+    /** Endnotes. */
+    readonly endnotes?: readonly EndnoteDef[];
+    /** Images. */
+    readonly images?: readonly ImageDef[];
+    /** Fonts. */
+    readonly fonts?: readonly FontDef[];
+    /** Document settings. */
+    readonly settings?: DocumentSettings;
+    /** Core properties. */
+    readonly coreProperties?: CoreProperties;
+    /** App properties. */
+    readonly appProperties?: AppProperties;
+    /** Comments. */
+    readonly comments?: readonly CommentDef[];
+    /** Background. */
+    readonly background?: DocumentBackground;
+    /** Custom properties. */
+    readonly customProperties?: readonly CustomProperty[];
+    /** Watermark. */
+    readonly watermark?: Watermark;
+    /** Theme. */
+    readonly theme?: DocumentTheme;
+    /** Custom XML parts (for SDT data binding). */
+    readonly customXmlParts?: readonly CustomXmlPart[];
+    /** Embedded font binaries (stored in word/fonts/). */
+    readonly embeddedFonts?: readonly EmbeddedFont[];
+    /** Opaque (unrecognized) parts preserved for round-trip fidelity. */
+    readonly opaqueParts?: readonly OpaquePart[];
+    /**
+     * How to handle image references whose binary is not in `images`.
+     *
+     * - `"throw"` (default): throw `DocxWriteError` from `add*` so the caller
+     *   notices the broken reference immediately.
+     * - `"warn"`: emit a `console.warn` and skip the rId. The output will be
+     *   missing this image's relationship — useful only for tooling that
+     *   knows it's intentionally producing a partial document.
+     *
+     * The previous behaviour (silent skip) is gone because it generated
+     * invalid DOCX files.
+     */
+    readonly missingImagePolicy?: "throw" | "warn";
+    /**
+     * Security policy. Currently used to surface `rawXmlPolicy` to the renderers
+     * (preserve / strip / reject) so opaque rawXml fields behave consistently
+     * with the buffered `packageDocx` writer.
+     */
+    readonly securityPolicy?: WordSecurityPolicy;
+    /**
+     * Output sink. When provided, compressed bytes flow through it as soon
+     * as the underlying ZIP pipeline produces them, with backpressure
+     * awaited via {@link SinkAdapter}. Total writer-side memory then
+     * stays O(largest_part) regardless of final DOCX size.
+     *
+     * Accepts:
+     *  - Web `WritableStream<Uint8Array>` (browser, Deno, modern Node)
+     *  - Node `Writable` (`fs.createWriteStream`, http response, …)
+     *  - Any duck-typed object exposing `write(chunk)` + `end()` plus
+     *    `once("drain"|"error"|"close"|"finish", …)` listeners
+     *
+     * When the sink is provided, {@link StreamingDocxWriter.finalize}
+     * resolves to a zero-length `Uint8Array` (the bytes have already
+     * been delivered to the sink — the empty return is a sentinel that
+     * keeps `finalize`'s return type stable across both modes). Use
+     * {@link StreamingDocxWriter.addAsync} (instead of
+     * {@link StreamingDocxWriter.add}) when you want each `add` call to
+     * await actual sink drain — that gives true end-to-end backpressure
+     * for tight production loops.
+     *
+     * When omitted, behaviour is unchanged: compressed bytes accumulate
+     * internally and `finalize()` returns the assembled `Uint8Array`.
+     */
+    readonly sink?: AnySink;
+}
+/** Progress callback for streaming writer. */
+export type StreamingProgressCallback = (info: {
+    /** Number of body elements written so far. */
+    elementsWritten: number;
+    /** Current phase: "body" | "finalizing". */
+    phase: string;
+}) => void;
+/**
+ * Streaming DOCX writer. Body elements are serialized to XML and compressed
+ * into the ZIP pipeline as they arrive, so the body **model** is not retained
+ * after each `add()`.
+ *
+ * When constructed with `options.sink`, compressed bytes are pushed into
+ * the sink as soon as the ZIP layer produces them, with backpressure
+ * awaited via {@link SinkAdapter}; in this mode peak memory is
+ * O(largest_part) and `finalize()` resolves to a zero-length
+ * `Uint8Array` (the bytes are already in the sink). Without a sink,
+ * compressed bytes accumulate in `_outputChunks` and `finalize()`
+ * returns the assembled `Uint8Array` (peak memory
+ * O(compressed_docx_size)).
+ *
+ * Use {@link addAsync} (instead of {@link add}) when driving the sink
+ * variant to obtain true end-to-end backpressure: each call awaits all
+ * pending sink writes before resolving.
+ */
+export declare class StreamingDocxWriter {
+    private readonly _options;
+    private _elementCount;
+    private _finalized;
+    private _onProgress?;
+    private readonly _xmlBuffer;
+    private _zip;
+    /** Compressed-byte accumulator used when no `sink` is supplied. */
+    private _outputChunks;
+    /** Sink-mode adapter (set when `options.sink` is provided). */
+    private _sinkAdapter?;
+    /**
+     * Promise chain serialising every sink write. The `Zip` callback fires
+     * synchronously, so we queue chunks via `.then(...)` and let
+     * `addAsync` / `finalize` await the chain.
+     */
+    private _pendingDrain;
+    private _documentStream;
+    private _documentZipFile;
+    private _headerWritten;
+    /**
+     * Whether the previously-written body element was a `<w:tbl>`. Tracked
+     * so we can insert a separator `<w:p>` between adjacent tables — Word
+     * rejects (and silently merges) two `<w:tbl>` blocks that share no
+     * paragraph between them per ECMA-376 §17.13.5.34.
+     */
+    private _prevWasTable;
+    /**
+     * First error reported by the underlying ZIP stream (compression failure,
+     * write-after-end, etc.). Stored synchronously by the `Zip` callback and
+     * surfaced from `finalize()` so callers receive a rejection instead of an
+     * indefinitely-pending promise.
+     */
+    private _streamError;
+    private _documentRels;
+    private _renderCtx;
+    /** Charts encountered in body content; rendered to `word/charts/chartN.xml` at finalize time. */
+    private readonly _bodyCharts;
+    /** ChartEx items encountered in body content. */
+    private readonly _bodyChartEx;
+    /**
+     * Per-chart sequence numbers fixed at registration time. Both classes
+     * use independent monotonic counters; the writer emits
+     * `word/charts/chart{n}.xml` for the regular chart family and
+     * `word/charts/chartEx{n}.xml` for the chartEx family.
+     *
+     * The previous scheme used `chartCount + chartExCount + 1` as the
+     * sequence number for both classes, which made the rId path encoded in
+     * documentRels disagree with the path used at finalize when the writer
+     * iterated the two arrays separately. The result was relationships
+     * pointing at non-existent chart parts.
+     */
+    private readonly _chartNum;
+    private _nextChartSeq;
+    private _nextChartExSeq;
+    /** Hyperlink object identities already registered (to keep one rId per object). */
+    private readonly _registeredHyperlinks;
+    /** Image rIds already registered to documentRels (avoid duplicates). */
+    private readonly _registeredImageRIds;
+    /** header map key → newly allocated rId. Populated by `_allocateHeaderFooterRIds`. */
+    private readonly _headerKeyToRid;
+    /** footer map key → newly allocated rId. */
+    private readonly _footerKeyToRid;
+    /** rId allocated for the auto-generated watermark header (if any). */
+    private _watermarkHeaderRid;
+    constructor(options?: StreamingDocxOptions);
+    /** Set a progress callback. */
+    onProgress(cb: StreamingProgressCallback): this;
+    /**
+     * Add a single body element. The element is immediately serialized to XML
+     * and pushed into the ZIP compression pipeline. After this call, the element
+     * can be garbage collected — it is not retained.
+     */
+    add(element: BodyContent): this;
+    /** Add multiple body elements at once. */
+    addMany(elements: readonly BodyContent[]): this;
+    /**
+     * Async variant of {@link add}. After serialising the element, awaits
+     * any pending writes to the configured `sink` so callers driving large
+     * input get true end-to-end backpressure rather than letting the
+     * sink-write queue grow unbounded inside the writer.
+     *
+     * Without `options.sink` this is equivalent to `add` (resolving
+     * synchronously after element serialisation).
+     *
+     * Throws if the sink reports an error: previous queued writes whose
+     * rejection was captured into `_streamError` surface here.
+     */
+    addAsync(element: BodyContent): Promise<this>;
+    /**
+     * Async variant of {@link addMany}. Awaits `addAsync` for each element
+     * so backpressure is honoured between every body element.
+     */
+    addManyAsync(elements: readonly BodyContent[]): Promise<this>;
+    /** Add a paragraph with simple text content. */
+    addText(content: string, properties?: Paragraph["properties"]): this;
+    /** Get the count of body elements written so far. */
+    get elementCount(): number;
+    /**
+     * Finalize the document.
+     *
+     * - Without `options.sink`: returns the assembled `Uint8Array`
+     *   containing the full DOCX file.
+     * - With `options.sink`: drains any pending sink writes, calls
+     *   `sink.end()`, and resolves to a zero-length `Uint8Array`. The
+     *   DOCX bytes have already been delivered to the sink — the empty
+     *   return is a sentinel signalling "writer is done; consumer keeps
+     *   the data".
+     */
+    finalize(): Promise<Uint8Array>;
+    /** Reset the writer for reuse. */
+    /**
+     * Reset the writer for reuse.
+     *
+     * Throws when the writer was constructed with an `options.sink`: a
+     * sink can only be `end()`ed once, so reusing the same writer would
+     * produce an undefined byte stream. Construct a new writer (with a
+     * new sink) for each document instead.
+     */
+    reset(): this;
+    private _initZip;
+    private _write;
+    private _writeDocumentHeader;
+    private _writeBodyElement;
+    /**
+     * Emit an empty `<w:p/>` to separate two adjacent tables. Required by
+     * ECMA-376 §17.13.5.34 — Word rejects packages where two `<w:tbl>`
+     * elements appear without a paragraph between them.
+     */
+    private _writeSeparatorParagraph;
+    /**
+     * Scan a single body element and register any chart / hyperlink / image
+     * references it introduces against the writer's accumulated state. This
+     * must run before the element is serialized so the render context already
+     * carries the relationships the renderer will look up.
+     */
+    private _registerElementReferences;
+    private _registerParagraphReferences;
+    private _registerChart;
+    private _registerChartEx;
+    private _registerHyperlink;
+    private _registerImageRId;
+    private _lookupImage;
+    private _writeDocumentFooter;
+    /**
+     * Allocate header/footer relationship IDs deterministically (in the same
+     * order auxiliary parts will be emitted). Called once during finalize so
+     * `_writeDocumentFooter` and `_addAuxiliaryParts` agree on which rId
+     * points at which header/footer XML part.
+     */
+    private _allocateHeaderFooterRIds;
+    private _rewireSectionRefs;
+    /**
+     * Synthesise section-property header references for every header part
+     * the caller registered. Recognised type keys (`default`/`first`/`even`)
+     * keep their semantics; any other key (round-tripped rId names from
+     * readDocx, custom strings) falls back to `"default"` so the header is
+     * actually referenced — without this fallback header parts can sit in
+     * the package as dangling content.
+     *
+     * If multiple keys map to the same logical type, only the first one is
+     * kept so we don't emit two `<w:headerReference w:type="default">`
+     * children (Word's behaviour with duplicates is implementation-defined).
+     */
+    private _synthesizeHeaderRefs;
+    private _synthesizeFooterRefs;
+    private _addAuxiliaryParts;
+    private _endStream;
+    private _assembleOutput;
+}
+/**
+ * Create a new streaming DOCX writer.
+ *
+ * @example
+ * ```ts
+ * const writer = createDocxStream({
+ *   styles: [{ type: "paragraph", styleId: "Normal", name: "Normal" }]
+ * });
+ *
+ * for (let i = 0; i < 100000; i++) {
+ *   writer.addText(`Paragraph ${i}`);
+ * }
+ *
+ * const buffer = await writer.finalize();
+ * ```
+ */
+export declare function createDocxStream(options?: StreamingDocxOptions): StreamingDocxWriter;