fast-uri 3.1.9: fastUri.equal, fastUri.normalize, fastUri.parse

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@3.1.9
Kind: HOW

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

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:8face37ab92d44ece441fea26980971440a609aecbc006ace71446b486b337de","contract":["fastUri.parse parses full URI strings into lowercased scheme, userinfo, lowercased host, numeric port, path, query, fragment, and reference type","fastUri.parse classifies scheme-with-path, path-only, and fragment-only inputs into absolute, relative, and same-document references","fastUri.parse and fastUri.serialize handle wss resourceName/secure flags and urn:uuid components","fastUri.parse populates the error property when given a literal backslash in authority, an out-of-range port, or malformed percent-encoding","fastUri.serialize formats URIComponent objects into RFC 3986 URI strings with dot-segment removal and default HTTP port elision","fastUri.resolve resolves relative paths and query references against a base URI and throws an Error on malformed authority 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, eliding default ports, and decoding unreserved percent-encoded octets","fastUri.equal returns true for canonically equivalent URIs and false for distinct or malformed authority URIs"],"goal":"verify pkg:npm/fast-uri@3.1.9","kind":"HOW","packages":["pkg:npm/fast-uri@3.1.9"],"schemaVersion":1,"symbols":["fastUri.equal","fastUri.normalize","fastUri.parse","fastUri.resolve","fastUri.resolveComponent","fastUri.serialize"]},"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@3.1.9"],"schemaVersion":1,"subject":"pkg:npm/fast-uri@3.1.9","symbols":["fastUri.equal","fastUri.normalize","fastUri.parse","fastUri.resolve","fastUri.resolveComponent","fastUri.serialize"],"verifierAdapter":"node-typescript@1"}

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

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

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

import assert from 'node:assert/strict'
import fastUri from 'fast-uri'

// 1. fastUri.parse: full URI parsing and reference classification
const parsedFull = fastUri.parse('HTTP://client:pass@Example.COM:8080/a/b?k=1#sec')
assert.equal(parsedFull.scheme, 'http')
assert.equal(parsedFull.userinfo, 'client:pass')
assert.equal(parsedFull.host, 'example.com')
assert.equal(parsedFull.port, 8080)
assert.equal(parsedFull.path, '/a/b')
assert.equal(parsedFull.query, 'k=1')
assert.equal(parsedFull.fragment, 'sec')
assert.equal(parsedFull.reference, 'uri')
assert.equal(parsedFull.error, undefined)

const parsedAbsolute = fastUri.parse('https://example.com/items')
assert.equal(parsedAbsolute.reference, 'absolute')

const parsedRelative = fastUri.parse('sub/path?x=2')
assert.equal(parsedRelative.reference, 'relative')
assert.equal(parsedRelative.path, 'sub/path')
assert.equal(parsedRelative.query, 'x=2')

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

// 2. fastUri.parse & fastUri.serialize: scheme handlers (wss and urn:uuid)
const parsedWss = fastUri.parse('wss://example.com:443/stream?ch=1')
assert.equal(parsedWss.scheme, 'wss')
assert.equal(parsedWss.secure, true)
assert.equal(parsedWss.resourceName, '/stream?ch=1')
assert.equal(
  fastUri.serialize({
    scheme: 'ws',
    host: 'example.com',
    port: 443,
    secure: true,
    resourceName: '/stream?ch=1'
  }),
  'wss://example.com/stream?ch=1'
)

const sampleUuid = 'f81d4fae-7dec-11d0-a765-00a0c91e6bf6'
const parsedUrnUuid = fastUri.parse(`urn:uuid:${sampleUuid.toUpperCase()}`)
assert.equal(parsedUrnUuid.scheme, 'urn')
assert.equal(parsedUrnUuid.nid, 'uuid')
assert.equal(parsedUrnUuid.uuid, sampleUuid.toUpperCase())
assert.equal(parsedUrnUuid.error, undefined)
assert.equal(
  fastUri.serialize({
    scheme: 'urn',
    nid: 'uuid',
    uuid: sampleUuid.toUpperCase()
  }),
  `urn:uuid:${sampleUuid}`
)

// 3. fastUri.parse: error reporting on malformed inputs
const errBackslash = fastUri.parse('http://example.com\\admin')
assert.ok(typeof errBackslash.error === 'string' && errBackslash.error.length > 0)

const errPort = fastUri.parse('http://example.com:70000/path')
assert.equal(errPort.error, 'URI port is malformed.')

const errPercent = fastUri.parse('http://example.com/%ZZ')
assert.equal(errPercent.error, 'URI contains malformed percent-encoding.')

// 4. fastUri.serialize: RFC 3986 formatting, dot-segment removal, default port elision
const serializedHttp = fastUri.serialize({
  scheme: 'http',
  host: 'example.com',
  port: 80,
  path: '/a/b/../c/./d',
  query: 'q=1',
  fragment: 'top'
})
assert.equal(serializedHttp, 'http://example.com/a/c/d?q=1#top')

// 5. fastUri.resolve & fastUri.resolveComponent
const resolvedPath = fastUri.resolve('http://example.com/dir/sub/page.html', '../other.html?v=2#end')
assert.equal(resolvedPath, 'http://example.com/dir/other.html?v=2#end')

const resolvedQuery = fastUri.resolve('http://example.com/dir/page.html?v=1', '?v=2')
assert.equal(resolvedQuery, 'http://example.com/dir/page.html?v=2')

assert.throws(() => {
  fastUri.resolve('http://example.com/base', 'http://example.com\\bad')
}, Error)

const resolvedComp = fastUri.resolveComponent(
  fastUri.parse('http://example.com/a/b/c'),
  fastUri.parse('../d?k=9')
)
assert.equal(resolvedComp.scheme, 'http')
assert.equal(resolvedComp.host, 'example.com')
assert.equal(resolvedComp.path, '/a/d')
assert.equal(resolvedComp.query, 'k=9')

// 6. fastUri.normalize: string and component normalization
const normalizedStr = fastUri.normalize('HTTP://Example.COM:80/a/b/../%7Eitem/?x=1#frag')
assert.equal(normalizedStr, 'http://example.com/a/~item/?x=1#frag')

const normalizedComp = fastUri.normalize({
  scheme: 'HTTPS',
  host: 'EXAMPLE.COM',
  port: 443,
  path: '/x/./y/../z'
})
assert.equal(normalizedComp.scheme, 'https')
assert.equal(normalizedComp.host, 'example.com')
assert.equal(normalizedComp.port, undefined)
assert.equal(normalizedComp.path, '/x/z')

// 7. fastUri.equal: canonical equivalence and rejection of malformed URIs
assert.equal(
  fastUri.equal('HTTP://EXAMPLE.COM:80/%7Eitem/a/../b', 'http://example.com/~item/b'),
  true
)
assert.equal(
  fastUri.equal('http://example.com/a', 'http://example.com/b'),
  false
)
assert.equal(
  fastUri.equal('http://example.com\\bad', 'http://example.com\\bad'),
  false
)