data-urls 7.0.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/data-urls@7.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/data-urls@7.0.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:24587515724d7707b36131a2c286a3b6e712cdad42c54267be8ac44be5ea6116","constraints":{"executionContext":"node"},"contract":["parseDataURL parses default plain text data URL and returns MIMEType and Uint8Array body","parseDataURL parses base64 encoded data URL and decodes bytes correctly","parseDataURL parses custom mime type with parameters","parseDataURL returns null for invalid data URLs or malformed base64","decodeDataURLText decodes text content using parsed charset or fallback","parseDataURLFromRecord parses WHATWG URL record correctly"],"goal":"verify pkg:npm/data-urls@7.0.0","kind":"HOW","packages":["pkg:npm/data-urls@7.0.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/data-urls@7.0.0"],"schemaVersion":1,"subject":"pkg:npm/data-urls@7.0.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-data-urls",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-data-urls",
      "version": "1.0.0",
      "dependencies": {
        "data-urls": "7.0.0"
      }
    },
    "node_modules/@exodus/bytes": {
      "version": "1.15.1",
      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.1.tgz",
      "integrity": "sha512-S6mL0yNB/Abt9Ei4tq8gDhcczc4S3+vQ4ra7vxnAf+YHC02srtqxKKZghx2Dq6p0e66THKwR6r8N6P95wEty7Q==",
      "license": "MIT",
      "engines": {
        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
      },
      "peerDependencies": {
        "@noble/hashes": "^1.8.0 || ^2.0.0"
      },
      "peerDependenciesMeta": {
        "@noble/hashes": {
          "optional": true
        }
      }
    },
    "node_modules/data-urls": {
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
      "license": "MIT",
      "dependencies": {
        "whatwg-mimetype": "^5.0.0",
        "whatwg-url": "^16.0.0"
      },
      "engines": {
        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
      }
    },
    "node_modules/punycode": {
      "version": "2.3.1",
      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/tr46": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
      "license": "MIT",
      "dependencies": {
        "punycode": "^2.3.1"
      },
      "engines": {
        "node": ">=20"
      }
    },
    "node_modules/webidl-conversions": {
      "version": "8.0.1",
      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=20"
      }
    },
    "node_modules/whatwg-mimetype": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
      "license": "MIT",
      "engines": {
        "node": ">=20"
      }
    },
    "node_modules/whatwg-url": {
      "version": "16.0.1",
      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
      "license": "MIT",
      "dependencies": {
        "@exodus/bytes": "^1.11.0",
        "tr46": "^6.0.0",
        "webidl-conversions": "^8.0.1"
      },
      "engines": {
        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
      }
    }
  }
}

{
  "name": "sample-data-urls",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of data-urls",
  "main": "src/index.js",
  "dependencies": {
    "data-urls": "7.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/data-urls@7.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/data-urls@7.0.0"
  ]
}

const parseDataURL = require('data-urls');
const { parseURL } = require('whatwg-url');

/**
 * Parse a data URL string.
 * @param {string} input - The data: URL string to parse.
 * @returns {{mimeType: object, body: Uint8Array} | null} Parsed data URL record or null if invalid.
 */
function parseData(input) {
  return parseDataURL(input);
}

/**
 * Parse a data URL and decode its body as a string.
 * Uses the charset parameter from the parsed MIME type, or falls back to the specified fallback encoding.
 * @param {string} input - The data: URL string.
 * @param {string} [fallbackEncoding='utf-8'] - Fallback encoding label if charset parameter is absent.
 * @returns {{mimeType: object, text: string} | null}
 */
function decodeDataURLText(input, fallbackEncoding = 'utf-8') {
  const result = parseDataURL(input);
  if (!result) {
    return null;
  }
  const charset = result.mimeType.parameters.get('charset') ?? fallbackEncoding;
  const decoder = new TextDecoder(charset);
  const text = decoder.decode(result.body);
  return {
    mimeType: result.mimeType,
    text
  };
}

/**
 * Parse a data URL from a WHATWG URL record.
 * @param {object} urlRecord - Parsed URL record from whatwg-url.
 * @returns {{mimeType: object, body: Uint8Array} | null}
 */
function parseDataURLFromRecord(urlRecord) {
  return parseDataURL.fromURLRecord(urlRecord);
}

module.exports = {
  parseDataURL,
  parseData,
  decodeDataURLText,
  parseDataURLFromRecord,
  parseURL
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  parseDataURL,
  parseData,
  decodeDataURLText,
  parseDataURLFromRecord,
  parseURL
} = require('../src/index.js');

// 1. Export verification & default plain text data URL parsing
assert.strictEqual(typeof parseDataURL, 'function', 'parseDataURL should be a function');
assert.strictEqual(typeof parseData, 'function', 'parseData should be a function');
assert.strictEqual(typeof decodeDataURLText, 'function', 'decodeDataURLText should be a function');
assert.strictEqual(typeof parseDataURLFromRecord, 'function', 'parseDataURLFromRecord should be a function');

const textResult = parseData('data:,Hello%2C%20World!');
assert.ok(textResult !== null, 'textResult should not be null');
assert.strictEqual(textResult.mimeType.toString(), 'text/plain;charset=US-ASCII');
assert.strictEqual(textResult.mimeType.type, 'text');
assert.strictEqual(textResult.mimeType.subtype, 'plain');
assert.strictEqual(textResult.mimeType.parameters.get('charset'), 'US-ASCII');
assert.ok(textResult.body instanceof Uint8Array, 'body should be Uint8Array');
const decodedDefault = new TextDecoder('utf-8').decode(textResult.body);
assert.strictEqual(decodedDefault, 'Hello, World!');

// 2. Parse base64 encoded data URL and decode bytes correctly
const base64Data = 'data:text/plain;base64,U29tZSBkYXRhIHRvIHZlcmlmeQ==';
const base64Result = parseData(base64Data);
assert.ok(base64Result !== null, 'base64Result should not be null');
assert.strictEqual(base64Result.mimeType.essence, 'text/plain');
const decodedBase64 = new TextDecoder('utf-8').decode(base64Result.body);
assert.strictEqual(decodedBase64, 'Some data to verify');

// 3. Parse custom MIME type with parameters
const jsonResult = parseData('data:application/json;charset=utf-8,%7B%22status%22%3A%22ok%22%7D');
assert.ok(jsonResult !== null, 'jsonResult should not be null');
assert.strictEqual(jsonResult.mimeType.essence, 'application/json');
assert.strictEqual(jsonResult.mimeType.parameters.get('charset'), 'utf-8');
const jsonText = new TextDecoder('utf-8').decode(jsonResult.body);
assert.deepStrictEqual(JSON.parse(jsonText), { status: 'ok' });

// 4. Return null for invalid data URLs or malformed base64
assert.strictEqual(parseData('not a data url'), null);
assert.strictEqual(parseData('https://example.com'), null);
assert.strictEqual(parseData('data:text/plain;base64,invalid!base64!@@@'), null);
assert.strictEqual(decodeDataURLText('https://example.com'), null);

// 5. decodeDataURLText decodes text content using parsed charset or fallback
const decodedTextResult = decodeDataURLText('data:text/plain;charset=utf-8,Clean%20Room%20Testing');
assert.ok(decodedTextResult !== null);
assert.strictEqual(decodedTextResult.text, 'Clean Room Testing');

// 6. parseDataURLFromRecord parses WHATWG URL record correctly
const urlRecord = parseURL('data:image/svg+xml,%3Csvg%3E%3C%2Fsvg%3E');
assert.ok(urlRecord !== null, 'urlRecord should not be null');
const recordResult = parseDataURLFromRecord(urlRecord);
assert.ok(recordResult !== null, 'recordResult should not be null');
assert.strictEqual(recordResult.mimeType.essence, 'image/svg+xml');
assert.strictEqual(new TextDecoder('utf-8').decode(recordResult.body), '<svg></svg>');

console.log('Contract tests passed successfully.');