rescript-docx

rescript-docx

Report Bug • API docs • Contribute • docx.js

A ReScript wrapper for the docx JS/TS library.

Table Of Contents

• Usage
  • Examples
    • Local
    • Real world
• API coverage
• Binding conventions
  • Primitives
  • Enums
  • Polymorphic constructors
  • Inline variant types
  • Reserved keywords
  • Interface inheritance
• Sponsors

Usage

yarn add -D rescript-docx

Examples

Local

Some examples are available in examples/. To run them simply:

# Compile the project with the dependencies
yarn && yarn build

# Run the compiled JS file with Node
npx node examples/<fileName>.bs.js

# The result is stored in the root with the corresponding name: <fileName>.docx

Real world

• catala-explain - A module for explicability from the trace of a catala program

API coverage

List of supported features:

• ✅ Document
• 🚧 Sections
• ✅ Paragraph
• 🚧 Text
• 🚧 Images (Missing correct modelization of the ImageRun.options.data type)
• ✅ Headers & Footers
• ✅ Bullet Points
• ✅ Hyperlinks
• ✅ Numbering
• ✅ Tables
• ✅ Tabs
• ✅ Table Of Contents
• ✅ Page Numbers
• ❌ Change Tracking
• ❌ Math
• ❌ Comments
• ❌ Footnotes
• ❌ Fields
• ✅ Packers

Binding conventions

For the binding, several conventions has been used:

Primitives

By default JavaScript number are converted to float, but if it's expected to be integers then to int.

Enums

Enums are bound to a polymorphic variant:

// In TypeScript
enum AlignmentType = {
    START = "start",
    CENTER = "center",
    NUM_TAB = "numTab",
    ...
}

// Corresponding AlignmentType.res file
type t = [
    | #start,
    | #center,
    | #numTab,
    ...
]

🔜 In the incoming ReScript 11.0, this could be done cleaner by using the new tagged variants.

Polymorphic constructors

Each docx classes has its corresponding ReScript module.

For example the Paragraph classes has its corresponding Parapraph module in the Paragraph.res file.

To emulate polymorphic constructors call, the following convention has been taken:

// In TypeScript
const p = new Paragraph("Lorem ipsum")
const q = new Paragraph({
    text: "Lorem ipsum",
    heading: HeadingLevel.HEADING_1,
})

// In ReScript
let p = Paragraph.make("Lorem Ipsum")
let q = Paragraph.make'({
    text: "Lorem ipsum",
    heading: #Heading1,
})

Inline variant types

TypeScript inline variant types are encoded in a dedicated module in Util.Types as:

// TypeScript variant
type t = {
    value: number | string
}

// In ReScript
open Util

type t = { value: Types.NumberOrString.t }

let float: t = { value: Types.NumberOrString.fromFloat(10.0) }

let string: t = { value: Types.NumberOrString.fromString("Hello") }

🔜 In the incoming ReScript 11, this could be done more simply by using the new untagged variants.

Reserved keywords

Some used JavaScript attributes are reserved keywords in ReScript, consequently, they are postfixed by _.

For example, the attribute type is type_.

Interface inheritance

🔜 In the incoming ReScript 11.0, using record type spread will allows to factorizes interface inheritance.

Sponsors

This library has been developed during a research project funded by the mission logiciels libres et communs numériques of the direction interministérielle du numérique in collaboration with the Catala project.