mdurl 2.1.0: decode

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 mdurl.decode in pkg:npm/mdurl@2.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/mdurl@2.1.0
Demonstrate these symbols/APIs:
  - mdurl.decode

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:b6463c31a54bd78715af852c721821f9ee4609b5117d9f8b8bace7ae7a259b5d","contract":["mdurl.decode decodes ASCII percent-encoded characters","mdurl.decode preserves reserved URL characters specified by defaultChars when exclude is omitted","mdurl.decode decodes all percent-encoded characters when componentChars is used as the exclusion set","mdurl.decode respects custom exclusion string characters during decoding","mdurl.decode correctly decodes multi-byte UTF-8 percent-encoded sequences","mdurl.decode replaces invalid or overlong UTF-8 percent-encoded byte sequences with replacement characters","mdurl.decode preserves unencoded characters and incomplete percent sequences unchanged"],"goal":"verify mdurl.decode in pkg:npm/mdurl@2.1.0","kind":"HOW","packages":["pkg:npm/mdurl@2.1.0"],"schemaVersion":1,"symbols":["mdurl.decode"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/mdurl@2.1.0"],"schemaVersion":1,"subject":"pkg:npm/mdurl@2.1.0","symbols":["mdurl.decode"],"verifierAdapter":"node-typescript@1"}

import { decode } from 'mdurl';

/**
 * Decode percent-encoded string.
 *
 * @param {string} string - The string to decode.
 * @param {string} [exclude] - Characters to preserve encoded. Defaults to mdurl.decode.defaultChars (';/?:@&=+$,#').
 * @returns {string} The decoded string.
 */
export function decodeUrl(string, exclude) {
  return decode(string, exclude);
}

export { decode };
export default decode;

{
  "name": "sample-mdurl-decode",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-mdurl-decode",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "mdurl": "2.1.0"
      }
    },
    "node_modules/mdurl": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.1.0.tgz",
      "integrity": "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-mdurl-decode",
  "version": "1.0.0",
  "type": "module",
  "description": "Clean-room code sample for mdurl decode",
  "main": "index.mjs",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "mdurl": "2.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify mdurl.decode in pkg:npm/mdurl@2.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/mdurl@2.1.0"
  ],
  "symbols": [
    "mdurl.decode"
  ]
}

import assert from 'node:assert/strict';
import { decode as mdurlDecode } from 'mdurl';
import { decode, decodeUrl } from '../index.mjs';

// 1. mdurl.decode decodes ASCII percent-encoded characters
{
  assert.equal(typeof decode, 'function');
  assert.equal(decode, mdurlDecode);
  assert.equal(decode('hello%20world%21'), 'hello world!');
  assert.equal(decode('%3Ctest%3E'), '<test>');
  assert.equal(decode('%61%62%63'), 'abc');
  assert.equal(decodeUrl('foo%20bar'), 'foo bar');
}

// 2. mdurl.decode preserves reserved URL characters specified by defaultChars when exclude is omitted
{
  assert.equal(decode.defaultChars, ';/?:@&=+$,#');
  const input = '%3B%2F%3F%3A%40%26%3D%2B%24%2C%23';
  assert.equal(decode(input), input);
  assert.equal(decode('path%2Fto%3Fquery%3D1%26b%3D2%23hash'), 'path%2Fto%3Fquery%3D1%26b%3D2%23hash');
}

// 3. mdurl.decode decodes all percent-encoded characters when componentChars is used as the exclusion set
{
  assert.equal(decode.componentChars, '');
  assert.equal(decode('path%2Fto%3Fquery%3D1%26b%3D2%23hash', decode.componentChars), 'path/to?query=1&b=2#hash');
  assert.equal(decode('%3B%2F%3F%3A%40%26%3D%2B%24%2C%23', decode.componentChars), ';/?:@&=+$,#');
}

// 4. mdurl.decode respects custom exclusion string characters during decoding
{
  assert.equal(decode('%20%21%22', '!'), ' %21"');
  assert.equal(decode('%3Cfoo%3E', '<>'), '%3Cfoo%3E');
}

// 5. mdurl.decode correctly decodes multi-byte UTF-8 percent-encoded sequences
{
  assert.equal(decode('%C3%A9'), 'é');
  assert.equal(decode('%E6%BC%A2'), '漢');
  assert.equal(decode('%F0%9F%98%80'), '😀');
}

// 6. mdurl.decode replaces invalid or overlong UTF-8 percent-encoded byte sequences with replacement characters
{
  assert.equal(decode('%FF'), '\ufffd');
  assert.equal(decode('%C0%AF'), '\ufffd\ufffd');
  assert.equal(decode('%E0%80%AF'), '\ufffd\ufffd\ufffd');
  assert.equal(decode('%ED%A0%80'), '\ufffd\ufffd\ufffd');
}

// 7. mdurl.decode preserves unencoded characters and incomplete percent sequences unchanged
{
  assert.equal(decode('plain text 123'), 'plain text 123');
  assert.equal(decode('%'), '%');
  assert.equal(decode('%2'), '%2');
  assert.equal(decode('%2G'), '%2G');
  assert.equal(decode(''), '');
}

console.log('All mdurl.decode contract tests passed successfully.');