TypeScript Package URL (purl) parser and builder. Drop-in replacement for packageurl-js with full type safety, zero dependencies, and spec compliance with the Package URL specification.
pnpm install @socketregistry/packageurl-jsDrop-in replacement via package override:
{
"pnpm": {
"overrides": {
"packageurl-js": "npm:@socketregistry/packageurl-js@^1"
}
}
}Requirements: Node >= 18.20.4
Parse purls:
import { PackageURL } from '@socketregistry/packageurl-js'
const purl = PackageURL.fromString('pkg:npm/[email protected]')
console.log(purl.name) // 'lodash'
console.log(purl.version) // '4.17.21'Build purls:
import { PackageURLBuilder } from '@socketregistry/packageurl-js'
// npm packages
PackageURLBuilder.npm().name('lodash').version('4.17.21').build()
// -> 'pkg:npm/[email protected]'
// Python packages
PackageURLBuilder.pypi().name('requests').version('2.28.1').build()
// -> 'pkg:pypi/[email protected]'
// Maven with namespace and qualifiers
PackageURLBuilder.maven()
.namespace('org.springframework')
.name('spring-core')
.version('5.3.21')
.qualifier('classifier', 'sources')
.build()
// -> 'pkg:maven/org.springframework/[email protected]?classifier=sources'Constructor API:
import { PackageURL } from '@socketregistry/packageurl-js'
new PackageURL('npm', null, 'express', '4.18.2')
// -> 'pkg:npm/[email protected]'
// With namespace and subpath
new PackageURL('npm', '@babel', 'runtime', '7.18.6', null, 'helpers/typeof.js')
// -> 'pkg:npm/%40babel/[email protected]#helpers/typeof.js'Convert to URLs:
import { UrlConverter } from '@socketregistry/packageurl-js'
UrlConverter.toRepositoryUrl(purl)
// -> 'https://github.com/lodash/lodash'
UrlConverter.toDownloadUrl(purl)
// -> 'https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz'Use type-safe PURL types:
import { PURL_Type, EcosystemString } from '@socketregistry/packageurl-js'
// Type-safe enum values
console.log(PURL_Type.NPM) // 'npm'
console.log(PURL_Type.PYPI) // 'pypi'
console.log(PURL_Type.MAVEN) // 'maven'
// Use in type annotations
function processPurl(type: EcosystemString) {
// type is constrained to valid PURL type strings
}→ API Reference - Complete API documentation
→ Examples - Common use cases
→ Builders - Builder pattern guide
pnpm install # Install dependencies
pnpm build # Build
pnpm test # Test
pnpm check # Lint + typecheck