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'sMIMEType
class. - The
body
property is aUint8Array
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.