data-urls

What is data-urls?

The data-urls npm package is used to parse and serialize data URLs as per the WHATWG specification. It allows you to work with data URLs in a structured way, extracting components like MIME type, base64 encoding, and the actual data.

What are data-urls's main functionalities?

Parsing Data URLs

This feature allows you to parse a data URL into its components. The `parse` function takes a data URL string and returns an object containing the MIME type, whether it's base64 encoded, and the actual data.

const { parse } = require('data-urls');
const dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';
const parsed = parse(dataUrl);
console.log(parsed);

Serializing Data URLs

This feature allows you to serialize data into a data URL. The `serialize` function takes an object with MIME type and data, and returns a data URL string.

const { serialize } = require('data-urls');
const data = Buffer.from('Hello, World!');
const mimeType = 'text/plain';
const serialized = serialize({ mimeType, body: data });
console.log(serialized);

Other packages similar to data-urls

datauri

The datauri package is used to convert file paths or buffers to data URLs. It provides a simple API for encoding files or buffers into data URLs, but it does not offer as detailed parsing capabilities as data-urls.

dataurl

The dataurl package provides utilities for parsing and generating data URLs. It offers similar functionality to data-urls but with a different API design. It is less focused on strict adherence to the WHATWG specification.

data-uri-to-buffer

The data-uri-to-buffer package is focused on converting data URLs to buffers. It is useful for extracting the binary data from a data URL but does not provide serialization capabilities.

README

Parse data: URLs

This package helps you parse data: URLs according to the WHATWG Fetch Standard:

const parseDataURL = require("data-urls");

const textExample = parseDataURL("data:,Hello%2C%20World!");
console.log(textExample.mimeType.toString()); // "text/plain;charset=US-ASCII"
console.log(textExample.body);                // Uint8Array(13) [ 72, 101, 108, 108, 111, 44, … ]

const htmlExample = parseDataURL("data:text/html,%3Ch1%3EHello%2C%20World!%3C%2Fh1%3E");
console.log(htmlExample.mimeType.toString()); // "text/html"
console.log(htmlExample.body);                // Uint8Array(22) [ 60, 104, 49, 62, 72, 101, … ]

const pngExample = parseDataURL("data:image/png;base64,iVBORw0KGgoAAA" +
                                "ANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4" +
                                "//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU" +
                                "5ErkJggg==");
console.log(pngExample.mimeType.toString()); // "image/png"
console.log(pngExample.body);                // Uint8Array(85) [ 137, 80, 78, 71, 13, 10, … ]

API

This package's main module's default export is a function that accepts a string and returns a { mimeType, body } object, or null if the result cannot be parsed as a data: URL.

• The mimeType property is an instance of whatwg-mimetype's MIMEType class.
• The body property is a Uint8Array instance.

As shown in the examples above, you can easily get a stringified version of the MIME type using its toString() method. Read on for more on getting the stringified version of the body.

Decoding the body

To decode the body bytes of a parsed data URL, you'll need to use the charset parameter of the MIME type, if any. This contains an encoding label; there are various possible labels for a given encoding. We suggest using the whatwg-encoding package as follows:

const parseDataURL = require("data-urls");
const { labelToName, decode } = require("whatwg-encoding");

const dataURL = parseDataURL(arbitraryString);

// If there's no charset parameter, let's just hope it's UTF-8; that seems like a good guess.
const encodingName = labelToName(dataURL.mimeType.parameters.get("charset") || "utf-8");
const bodyDecoded = decode(dataURL.body, encodingName);

This is especially important since the default, if no parseable MIME type is given, is "US-ASCII", aka windows-1252, not UTF-8 like you might asume. So for example given an arbitraryString of "data:,Héllo!", the above code snippet will correctly produce a bodyDecoded of "Héllo!" by using the windows-1252 decoder, whereas if you used a UTF-8 decoder you'd get back "Héllo!".

Advanced functionality: parsing from a URL record

If you are using the whatwg-url package, you may already have a "URL record" object on hand, as produced by that package's parseURL export. In that case, you can use this package's fromURLRecord export to save a bit of work:

const { parseURL } = require("whatwg-url");
const dataURLFromURLRecord = require("data-urls").fromURLRecord;

const urlRecord = parseURL("data:,Hello%2C%20World!");
const dataURL = dataURLFromURLRecord(urlRecord);

In practice, we expect this functionality only to be used by consumers like jsdom, which are using these packages at a very low level.