@1001-digital/normalize-dweb-url

Normalize IPFS, IPNS, and Arweave URIs -- gateway detection, redundant path removal, raw CID handling.

npm install @1001-digital/normalize-dweb-url

Usage

import { normalizeUri, isResolvableUri } from '@1001-digital/normalize-dweb-url'

normalizeUri('https://gateway.pinata.cloud/ipfs/QmXxx')  // 'ipfs://QmXxx'
normalizeUri('https://bafyABC.ipfs.nftstorage.link')     // 'ipfs://bafyABC'
normalizeUri('https://arweave.net/txId123')               // 'ar://txId123'
normalizeUri('QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG')
// 'ipfs://QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG'

isResolvableUri('ipfs://QmXxx')  // true
isResolvableUri('ar://txId123')  // true
isResolvableUri('hello world')   // false

normalizeUri(uri: string): string

Converts gateway URLs and raw CIDs into their canonical protocol form.

| Input | Output | | --- | --- | | https://ipfs.io/ipfs/QmXxx | ipfs://QmXxx | | https://bafyABC.ipfs.w3s.link/meta.json | ipfs://bafyABC/meta.json | | https://ipfs.io/ipns/example.eth | ipns://example.eth | | https://arweave.net/txId123 | ar://txId123 | | ipfs://ipfs/QmXxx | ipfs://QmXxx | | ipfs://https://gateway.pinata.cloud/ipfs/QmXxx | ipfs://QmXxx | | QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG | ipfs://QmYwAPJzv5... | | data:application/json;base64,... | passed through | | https://example.com/image.png | passed through |

Handles:

• Path-based IPFS/IPNS gateways (/ipfs/..., /ipns/...)
• Subdomain IPFS/IPNS gateways (*.ipfs.nftstorage.link, *.ipns.dweb.link, etc.)
• Arweave gateways (arweave.net, ar-io.dev, ar-io.net, arweave.dev)
• Redundant path segments (ipfs://ipfs/Qm... -> ipfs://Qm...)
• Embedded gateway URLs (ipfs://https://gateway.pinata.cloud/ipfs/Qm...)
• Raw CIDv0 (Qm...) and CIDv1 (bafy...) strings
• Whitespace trimming

isResolvableUri(value: unknown): value is string

Type guard that returns true when the value is a string that looks like a resolvable URI: ipfs://, ipns://, ar://, http(s)://, data:, or a raw CID.

Rejects non-strings, strings shorter than 5 characters, and non-data: URIs longer than 2048 characters.

License

MIT