Have ideas to improve npm?Join in the discussion! »

    data-urls
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/data-urls package

    2.0.0 • Public • Published

    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.toString());     // "Hello, World!"
     
    const htmlExample = dataURL("data:text/html,%3Ch1%3EHello%2C%20World!%3C%2Fh1%3E");
    console.log(htmlExample.mimeType.toString()); // "text/html"
    console.log(htmlExample.body.toString());     // <h1>Hello, World!</h1>
     
    const pngExample = parseDataURL("data:image/png;base64,iVBORw0KGgoAAA" +
                                    "ANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4" +
                                    "//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU" +
                                    "5ErkJggg==");
    console.log(pngExample.mimeType.toString()); // "image/png"
    console.log(pngExample.body);                // <Buffer 89 50 4e 47 0d ... >

    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 Node.js Buffer instance.

    As shown in the examples above, both of these have useful toString() methods for manipulating them as string values. However…

    A word of caution on string decoding

    Because Node.js's Buffer.prototype.toString() assumes a UTF-8 encoding, simply doing dataURL.body.toString() may not work correctly if the data: URL's contents were not originally written in UTF-8. This includes if the encoding is "US-ASCII", aka windows-1252, which is notable for being the default in many cases.

    A more complete decoding example would use the whatwg-encoding package as follows:

    const parseDataURL = require("data-urls");
    const { labelToName, decode } = require("whatwg-encoding");
     
    const dataURL = parseDataURL(arbitraryString);
    const encodingName = labelToName(dataURL.mimeType.parameters.get("charset"));
    const bodyDecoded = decode(dataURL.body, encodingName);

    For example, given an arbitraryString of data:,Hello!, this will produce a bodyDecoded of "Hello!", as expected. But given an arbitraryString of "data:,Héllo!", this will correctly produce a bodyDecoded of "Héllo!", whereas just doing dataURL.body.toString() will give back "Héllo!".

    In summary, only use dataURL.body.toString() when you are very certain your data is inside the ASCII range (i.e. code points within the range U+0000 to U+007F).

    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.

    Install

    npm i data-urls

    DownloadsWeekly Downloads

    11,055,331

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    8.08 kB

    Total Files

    5

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar