fast-uri 4.2.2

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/fast-uri@4.2.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fast-uri@4.2.2

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:4f1235e00da168e71781d876452abc1ecd4f35c324fabb3fc1681f78683ef43c","contract":["fastUri.parse parses full URI strings into lowercased scheme, host, numeric port, path, query, fragment, and reference type","fastUri.parse classifies path-only and fragment-only inputs as relative and same-document references","fastUri.parse extracts ipv6Zone from bracketed zoned IPv6 literals and fastUri.serialize uses ipv6Zone to disambiguate zone prefixes starting with 25","fastUri.parse populates the error property when given malformed percent-encoding or literal backslashes in authority","fastUri.serialize formats URI component objects into complete RFC 3986 URI strings with dot-segment removal","fastUri.resolve resolves relative paths and query references against a base URI and throws an Error on malformed URI inputs","fastUri.resolveComponent resolves a parsed relative URIComponent against a parsed base URIComponent","fastUri.normalize normalizes both URI strings and URIComponent objects by folding case, removing dot-segments, and decoding unreserved percent-encoded octets","fastUri.equal returns true for canonically equivalent URIs and false for distinct or malformed URIs"],"goal":"verify pkg:npm/fast-uri@4.2.2","kind":"HOW","packages":["pkg:npm/fast-uri@4.2.2"],"schemaVersion":1,"symbols":["fastUri.parse","fastUri.serialize","fastUri.resolve","fastUri.resolveComponent","fastUri.normalize","fastUri.equal"]},"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/fast-uri@4.2.2"],"schemaVersion":1,"subject":"pkg:npm/fast-uri@4.2.2","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-fast-uri",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fast-uri",
      "version": "1.0.0",
      "dependencies": {
        "fast-uri": "4.2.2"
      }
    },
    "node_modules/fast-uri": {
      "version": "4.2.2",
      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-4.2.2.tgz",
      "integrity": "sha512-EwVpUMzLVNOmcWW0zi5G3JJwkopB6XXjnVvNBGfqrMMsVew2hkQWl5e/pe/CfYUeS6jt4cIO2MnamEW7v/7wPw==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/fastify"
        },
        {
          "type": "opencollective",
          "url": "https://opencollective.com/fastify"
        }
      ],
      "license": "BSD-3-Clause"
    }
  }
}

{
  "name": "sample-fast-uri",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "fast-uri": "4.2.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/fast-uri@4.2.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/fast-uri@4.2.2"
  ]
}

import fastUri from 'fast-uri'

export function parseUriSample (uri, options) {
  return fastUri.parse(uri, options)
}

export function serializeUriSample (components, options) {
  return fastUri.serialize(components, options)
}

export function resolveUriSample (baseUri, relativeUri, options) {
  return fastUri.resolve(baseUri, relativeUri, options)
}

export function resolveComponentSample (baseComponent, relativeComponent, options, skipNormalization) {
  return fastUri.resolveComponent(baseComponent, relativeComponent, options, skipNormalization)
}

export function normalizeUriSample (input, options) {
  return fastUri.normalize(input, options)
}

export function equalUriSample (uriA, uriB, options) {
  return fastUri.equal(uriA, uriB, options)
}

import assert from 'node:assert/strict'
import fastUri from 'fast-uri'
import {
  parseUriSample,
  serializeUriSample,
  resolveUriSample,
  resolveComponentSample,
  normalizeUriSample,
  equalUriSample
} from '../src/index.mjs'

// 1. fastUri.parse: full URI with scheme, host, port, path, query, and fragment
const parsedFull = parseUriSample('HTTPS://EXAMPLE.COM:8443/v1/items?limit=10&sort=asc#top')
assert.equal(parsedFull.scheme, 'https')
assert.equal(parsedFull.host, 'example.com')
assert.equal(parsedFull.port, 8443)
assert.equal(parsedFull.path, '/v1/items')
assert.equal(parsedFull.query, 'limit=10&sort=asc')
assert.equal(parsedFull.fragment, 'top')
assert.equal(parsedFull.reference, 'uri')
assert.equal(parsedFull.error, undefined)

// 2. fastUri.parse: relative reference and same-document reference
const parsedRelative = parseUriSample('../catalog/search?q=uri')
assert.equal(parsedRelative.scheme, undefined)
assert.equal(parsedRelative.host, undefined)
assert.equal(parsedRelative.path, '../catalog/search')
assert.equal(parsedRelative.query, 'q=uri')
assert.equal(parsedRelative.reference, 'relative')

const parsedSameDoc = parseUriSample('#section-2')
assert.equal(parsedSameDoc.reference, 'same-document')
assert.equal(parsedSameDoc.fragment, 'section-2')

// 3. fastUri.parse & fastUri.serialize: zoned IPv6 literal with ipv6Zone support
const parsedZonedIpv6 = parseUriSample('http://[fe80::1%25eth0]:8080/health')
assert.equal(parsedZonedIpv6.scheme, 'http')
assert.equal(parsedZonedIpv6.host, 'fe80::1%eth0')
assert.equal(parsedZonedIpv6.ipv6Zone, 'eth0')
assert.equal(parsedZonedIpv6.port, 8080)
assert.equal(parsedZonedIpv6.path, '/health')

const serializedAmbiguousZone = serializeUriSample({
  scheme: 'http',
  host: 'fe80::1%25eth0',
  ipv6Zone: '25eth0',
  path: '/status'
})
assert.equal(serializedAmbiguousZone, 'http://[fe80::1%2525eth0]/status')

// 4. fastUri.parse: malformed inputs populate error property
const parsedBadPercent = parseUriSample('http://example.com/path%2G')
assert.equal(typeof parsedBadPercent.error, 'string')
assert.ok(parsedBadPercent.error.length > 0)

const parsedBackslash = parseUriSample('http://example.com\\other/path')
assert.equal(typeof parsedBackslash.error, 'string')
assert.ok(parsedBackslash.error.length > 0)

// 5. fastUri.serialize: component object to URI string
const serializedFull = serializeUriSample({
  scheme: 'https',
  host: 'localhost',
  port: 3000,
  path: '/api/a/../b/list',
  query: 'page=1',
  fragment: 'results'
})
assert.equal(serializedFull, 'https://localhost:3000/api/b/list?page=1#results')

// 6. fastUri.resolve & fastUri.resolveComponent: RFC 3986 relative resolution and error on malformed input
assert.equal(
  resolveUriSample('http://example.com/dir/sub/file.html', '../other/index.html?x=1#frag'),
  'http://example.com/dir/other/index.html?x=1#frag'
)
assert.equal(
  resolveUriSample('http://example.com/dir/sub/file.html?old=1', '?new=2'),
  'http://example.com/dir/sub/file.html?new=2'
)
assert.throws(() => {
  resolveUriSample('http://example.com/bad%2G', 'next')
}, /malformed/i)

const resolvedComp = resolveComponentSample(
  fastUri.parse('http://example.com/a/b/c'),
  fastUri.parse('../d?k=v#end'),
  undefined,
  true
)
assert.equal(resolvedComp.scheme, 'http')
assert.equal(resolvedComp.host, 'example.com')
assert.equal(resolvedComp.path, '/a/d')
assert.equal(resolvedComp.query, 'k=v')
assert.equal(resolvedComp.fragment, 'end')

// 7. fastUri.normalize: string and URIComponent normalization
const normalizedStr = normalizeUriSample('HTTP://EXAMPLE.COM/a/b/../c/%7Eitem?x=1#top')
assert.equal(normalizedStr, 'http://example.com/a/c/~item?x=1#top')

const normalizedComp = normalizeUriSample({
  scheme: 'HTTP',
  host: 'EXAMPLE.COM',
  path: '/x/./y/../z'
})
assert.equal(normalizedComp.scheme, 'http')
assert.equal(normalizedComp.host, 'example.com')
assert.equal(normalizedComp.path, '/x/z')

// 8. fastUri.equal: URI equivalence comparison
assert.equal(
  equalUriSample('http://EXAMPLE.COM/a/b/../c/%7Etest', 'http://example.com/a/c/~test'),
  true
)
assert.equal(
  equalUriSample('http://example.com/a/c', 'http://example.com/a/d'),
  false
)
assert.equal(
  equalUriSample('http://example.com/bad%2G', 'http://example.com/bad%2G'),
  false
)