tessl/npm-data-urls

Parses data: URLs according to the WHATWG Fetch Standard

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Data URLs

Name: tessl/npm-data-urls
Author: tessl

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)

Install with Tessl CLI

npx tessl i tessl/npm-data-urls

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/data-urls@5.0.x
Publish Source: CLI
Badge