or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-data-urls

Parses data: URLs according to the WHATWG Fetch Standard

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/data-urls@5.0.x

To install, run

npx @tessl/cli install tessl/npm-data-urls@5.0.0

index.mddocs/

Data URLs

Data URLs is a JavaScript library that parses data: URLs according to the WHATWG Fetch Standard. It handles various data formats including text, HTML, and binary data (like PNG images), properly decodes base64-encoded content, and provides utilities for charset handling and encoding detection.

Package Information

  • Package Name: data-urls
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install data-urls

Core Imports

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

Basic Usage

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

// Parse text data URL
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, ... ]

// Parse HTML data URL
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, ... ]

// Parse base64-encoded binary data
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, ... ]

Capabilities

Data URL Parsing

Parses a data: URL string and returns an object with the parsed MIME type and body data.

/**
 * Parses a data: URL string and returns parsed object with MIME type and body
 * @param {string} stringInput - The data: URL string to parse
 * @returns {{ mimeType: MIMEType, body: Uint8Array } | null} Parsed data or null if invalid
 */
function parseDataURL(stringInput);

Parameters:

  • stringInput (string): The data: URL string to parse

Returns:

  • Object with mimeType (MIMEType instance from whatwg-mimetype) and body (Uint8Array), or null if parsing fails

Usage Examples:

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

// Basic text
const result1 = parseDataURL("data:,Hello%20World");
// result1.mimeType.toString() === "text/plain;charset=US-ASCII"
// result1.body === Uint8Array with decoded bytes

// With explicit MIME type
const result2 = parseDataURL("data:application/json,{\"name\":\"test\"}");
// result2.mimeType.toString() === "application/json"

// Base64 encoded
const result3 = parseDataURL("data:text/plain;base64,SGVsbG8gV29ybGQ=");
// result3.body contains decoded "Hello World" bytes

// Invalid URL returns null
const result4 = parseDataURL("https://example.com");
// result4 === null

URL Record Parsing

Parses a data: URL from a pre-parsed URL record object, useful when working with the whatwg-url package.

/**
 * Parses a data: URL from a pre-parsed URL record object
 * @param {URLRecord} urlRecord - URL record object from whatwg-url parseURL function
 * @returns {{ mimeType: MIMEType, body: Uint8Array } | null} Parsed data or null if invalid
 */
function fromURLRecord(urlRecord);

Parameters:

  • urlRecord (URLRecord): URL record object from whatwg-url parseURL function

Returns:

  • Object with mimeType (MIMEType instance) and body (Uint8Array), or null if parsing fails or URL is not a data: URL

Usage Examples:

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

// Parse using URL record
const urlRecord = parseURL("data:,Hello%2C%20World!");
const dataURL = dataURLFromURLRecord(urlRecord);
// dataURL.mimeType.toString() === "text/plain;charset=US-ASCII"
// dataURL.body === Uint8Array with decoded bytes

// Non-data URLs return null
const httpRecord = parseURL("https://example.com/");
const result = dataURLFromURLRecord(httpRecord);
// result === null

Types

Return Value Structure

/**
 * Object returned by successful parsing operations
 * @typedef {Object} DataURLResult
 * @property {MIMEType} mimeType - MIME type object from whatwg-mimetype package
 * @property {Uint8Array} body - Raw decoded body content as byte array
 */

MIMEType

The mimeType property uses the MIMEType class from the whatwg-mimetype package:

/**
 * MIME type representation from whatwg-mimetype package
 * @class MIMEType
 */
class MIMEType {
  /** Convert MIME type to string representation */
  toString();
  
  /** Map of MIME type parameters */
  parameters; // Map<string, string>
}

Decoding Body Content

To decode the body bytes into text, use the charset parameter from the MIME type:

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

const dataURL = parseDataURL("data:text/plain;charset=utf-8,Hello%20World");

// Get encoding name (defaults to utf-8 if no charset specified)
const encodingName = labelToName(dataURL.mimeType.parameters.get("charset") || "utf-8");
const bodyDecoded = decode(dataURL.body, encodingName);
console.log(bodyDecoded); // "Hello World"

Important: The default charset is "US-ASCII" (windows-1252), not UTF-8. Always check the charset parameter for proper decoding.

Error Handling

  • Returns null for invalid input or parsing failures
  • Does not throw exceptions under normal usage
  • Handles malformed base64 gracefully by returning null
  • Falls back to "text/plain;charset=US-ASCII" for invalid MIME types
  • Returns null for non-data: URLs

Dependencies

This package depends on:

  • whatwg-mimetype: For MIME type parsing and representation
  • whatwg-url: For URL parsing utilities (parseURL, serializeURL, percentDecodeString)