# API reference

Public functions, types and errors for reading and generating DOCX, with signatures generated from source.

The signatures and descriptions below are extracted automatically from the public entry of `@quirekit/lit-docx`. For LitAST node types, see [The LitAST node model](/en/guide/litast).

## Reading

### parseDocx

`@quirekit/lit-docx` · Commercial

Parses DOCX bytes into LitAST. Runs in browsers and Node; no file-system access is needed.
@param buffer - Complete DOCX file bytes.
@param options - Optional parsing behavior.
@returns The document tree and non-fatal warnings.
@throws DocxPackageError when the bytes are not a ZIP package, or are an OLE container such as an encrypted document or legacy `.doc`.

```ts
function parseDocx(buffer: Uint8Array, options?: ParseOptions): Promise<ParseResult>
```

### ParseOptions

`@quirekit/lit-docx` · Commercial

Options accepted by `parseDocx`.

```ts
interface ParseOptions {
    preserveRawXml?: boolean;
    plugins?: ParserPlugin[];
    chartSourceLimits?: ChartSourceLimits;
    numberingMode?: NumberingParseMode;
    malformedFieldMode?: 'best-effort' | 'strict';
}
```

**preserveRawXml** — Keeps unrecognized elements as `unknownBlock` / `unknownInline` nodes with their original XML in `rawXml`; only an explicit `false` drops them.

**plugins** — Extra parser plugins, consulted after the built-in plugins.

**chartSourceLimits** — Bounds for opaque chart source dependencies; overflow rejects import.

**numberingMode** — Numbering reconstruction: nested `list` / `listItem` nodes (default) or Word-style flat numbered paragraphs.

**malformedFieldMode** — Malformed complex-field tokens are kept with a warning (`best-effort`, default) or reject the current story (`strict`).

### ParseResult

`@quirekit/lit-docx` · Commercial

Result of `parseDocx`: the document tree and every non-fatal problem found while reading it.

```ts
interface ParseResult {
    ast: LitNode;
    warnings: ParseWarning[];
}
```

**ast** — LitAST root, a `document` node; package-level data such as raw parts and comments lives in `ast.meta`.

**warnings** — Non-fatal problems; content that triggered them is kept where possible.

### ParseWarning

`@quirekit/lit-docx` · Commercial

One non-fatal problem found while parsing.

```ts
interface ParseWarning {
    code: string;
    message: string;
    location?: string;
    element?: string;
}
```

**code** — Stable code for programmatic handling.

**message** — Human-readable explanation.

**location** — XML path or description of where the problem occurred.

**element** — Tag name of the element that triggered the warning.

### DocxPackageError

`@quirekit/lit-docx` · Commercial

Typed failure raised before document-part parsing begins.

```ts
export class DocxPackageError extends Error {
    readonly code: DocxPackageErrorCode;
    constructor(code: DocxPackageErrorCode, message: string, options?: ErrorOptions);
}
```

## Generating

### generateDocx

`@quirekit/lit-docx` · Commercial

Generates a complete DOCX file from LitAST, rebuilding the whole package from the tree. Runs in browsers and Node.
@param ast - Document AST root.
@returns Complete DOCX ZIP bytes.

```ts
function generateDocx(ast: LitAstNode): Promise<Uint8Array<ArrayBuffer>>
```