data-url-kit

Parse, validate and inspect data: URLs with typed diagnostics.

data-url-kit is a small clean-room toolkit for apps, docs tools and support dashboards that need to explain why a data URL is valid or invalid. It returns MIME information, parameters, byte length, decoded bytes, decoded text when possible, and diagnostics that are easy to show in a UI.

Links: Demo · npm · GitHub

Use data-urls when you need a mature WHATWG-oriented parser for platform-level behavior. Use data-url-kit when you need a lightweight inspector, validator or playground with readable errors.

Package quality

• TypeScript types are generated from the source.
• ESM-only package with no runtime dependencies.
• Marked as side-effect free for bundlers.
• CI runs npm ci, typecheck, build, and test.
• Tested on Node.js 20 and 22 with GitHub Actions.
• Browser-friendly implementation with Uint8Array output.

Install

npm install data-url-kit

Quick Start

import { parseDataUrl } from "data-url-kit";

const result = parseDataUrl("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D");

if (result.ok) {
  result.value.mediaType;
  // "text/plain"

  result.value.isBase64;
  // true

  result.value.text;
  // "Hello, World!"

  result.value.byteLength;
  // 13
} else {
  result.diagnostics;
}

Why not just another data URL parser?

The common alternatives are good at either validating or parsing:

• valid-data-url returns a boolean.
• parse-data-url returns a parsed object.
• data-urls is the best fit for WHATWG/platform-level parsing.

data-url-kit focuses on inspection:

• typed diagnostics instead of only true / false;
• warnings that can be displayed without rejecting the URL;
• explicit byte length for preview limits;
• decoded Uint8Array for browser and Node usage;
• decoded text when bytes are valid UTF-8;
• safe helpers for forms, playgrounds and docs dashboards.

API

parseDataUrl(input, options?)

Returns a discriminated result.

import { parseDataUrl } from "data-url-kit";

const result = parseDataUrl("data:,Hello%20World");

if (result.ok) {
  console.log(result.value);
} else {
  console.log(result.diagnostics);
}

ok: true means no blocking error was found. The diagnostics array can still contain warnings such as duplicated parameters or ignored empty metadata segments.

Result shape:

type DataUrlResult =
  | {
      ok: true;
      input: string;
      header: string;
      diagnostics: DataUrlDiagnostic[];
      value: DataUrlInfo;
    }
  | {
      ok: false;
      input: string;
      header?: string;
      diagnostics: DataUrlDiagnostic[];
    };

Parsed value:

type DataUrlInfo = {
  mediaType: string;
  type: string;
  subtype: string;
  parameters: Record<string, string>;
  parameterList: Array<{ name: string; value: string }>;
  isBase64: boolean;
  data: string;
  byteLength: number;
  bytes: Uint8Array;
  text?: string;
};

Options:

| Option | Default | Description | | --- | --- | --- | | maxBytes | none | Reject decoded payloads larger than this byte limit. | | allowBase64Whitespace | true | Strip whitespace before base64 validation. |

Invalid runtime options return an INVALID_OPTIONS diagnostic instead of applying a misleading limit or coercion.

isDataUrl(input, options?)

Returns a boolean.

import { isDataUrl } from "data-url-kit";

isDataUrl("data:,Hello");
// true

explainDataUrl(input, options?)

Returns only diagnostics.

import { explainDataUrl } from "data-url-kit";

explainDataUrl("data:text/plain,Hello%XX");
// [{ code: "INVALID_PERCENT_ENCODING", severity: "error", ... }]

getDataUrlMediaType(input, options?)

Returns the parsed media type, or undefined when the input is invalid.

import { getDataUrlMediaType } from "data-url-kit";

getDataUrlMediaType("data:image/svg+xml,%3Csvg%2F%3E");
// "image/svg+xml"

isBase64DataUrl(input, options?)

Returns true only when the input is a valid data URL with a ;base64 flag.

import { isBase64DataUrl } from "data-url-kit";

isBase64DataUrl("data:text/plain;base64,SGVsbG8=");
// true

parseDataUrlOrThrow(input, options?)

Returns the parsed value or throws DataUrlParseError.

import { parseDataUrlOrThrow } from "data-url-kit";

const info = parseDataUrlOrThrow("data:,Hello");

Diagnostics

Diagnostics are designed for UI display.

| Code | Severity | Meaning | | --- | --- | --- | | NOT_A_STRING | error | Runtime input was not a string. | | MISSING_DATA_SCHEME | error | Input does not start with data:. | | MISSING_COMMA | error | Metadata and data are not separated by a comma. | | EMPTY_MEDIA_TYPE_SEGMENT | warning | An empty metadata segment was ignored. | | INVALID_MEDIA_TYPE | error | MIME type is malformed. | | INVALID_PARAMETER | error | Media type parameter is malformed. | | DUPLICATE_PARAMETER | warning | A repeated parameter keeps the last value. | | DUPLICATE_BASE64_FLAG | error | ;base64 appears more than once. | | INVALID_PERCENT_ENCODING | error | Percent encoding is malformed. | | INVALID_BASE64 | error | Base64 payload is malformed. | | DATA_TOO_LARGE | error | Decoded payload exceeds maxBytes. |

Notes

• This package does not fetch or execute data URLs.
• It is intentionally pragmatic and inspector-oriented, not a full browser URL implementation.
• text is decoded as UTF-8 when possible; use bytes when exact binary data matters.
• Default media type follows the common text/plain;charset=US-ASCII behavior for data:,....
• Use data-urls if you need a broader WHATWG parser.
• The implementation is clean-room and does not copy code from valid-data-url, parse-data-url, data-urls or related packages.

License

MPL-2.0