Custom-X

Custom-X is a TypeScript library that simplifies storing JavaScript objects in Office Custom XML parts. It provides functions to add, retrieve, parse, and remove custom XML data associated with a unique key.

Features

• Store Data as XML: Convert JavaScript objects to XML and encapsulate them in a custom XML part.
• Retrieve & Parse: Fetch and parse stored XML data to retrieve JavaScript objects.
• Namespace Handling: Sanitize and use keys as namespaces ensuring consistency.
• Seamless Office Integration: Works with Office.js to manage Custom XML Parts in Office documents.

Installation

Install the package via npm:

npm install custom-x

Usage

Below is a simple example:

import { setCustomXmlPartByValue, getCustomXmlPartValue, removeCustomXmlPart } from 'custom-x';

// Set a custom XML part.
await setCustomXmlPartByValue("myData", { foo: "bar" });

// Retrieve and parse the custom XML part.
const myData = await getCustomXmlPartValue("myData");
console.log(myData); // { foo: "bar" }

// Remove the custom XML part.
await removeCustomXmlPart("myData");

API Reference

• setCustomXmlPartByValue(key: string, value: any): Promise
  Converts a JavaScript object into XML and stores it as a custom XML part. If a part with the same key exists, it is first removed.

• getCustomXmlPart(key: string): Promise<Office.CustomXmlPart | null>
  Retrieves the custom XML part associated with the key.

• getCustomXmlPartValue(key: string): Promise<any | null>
  Retrieves and parses the XML content of the custom XML part back into a JavaScript object.

• removeCustomXmlPart(key: string): Promise
  Deletes the custom XML part corresponding to the specified key.

Building & Testing

This project uses TypeScript and Jest for testing.

To build the project, run:

npm run build

To execute the tests, run:

npm test

The tests can be found in the tests directory.

License

Distributed under the MIT License. See LICENSE for more information.

Contributing

Contributions are welcome! Please open issues and submit pull requests for bug fixes or feature enhancements.

Support

For support, please refer to the GitHub repository.

Custom-X © 2025 D'Arcy Rittich