Socket Badge CI - @socketregistry/packageurl-js
Follow @SocketSecurity Follow @socket.dev on Bluesky
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-js
Drop-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/lodash@4.17.21') 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/lodash@4.17.21' // Python packages PackageURLBuilder.pypi().name('requests').version('2.28.1').build() // -> 'pkg:pypi/requests@2.28.1' // 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/spring-core@5.3.21?classifier=sources'
Constructor API:
import { PackageURL } from '@socketregistry/packageurl-js' new PackageURL('npm', null, 'express', '4.18.2') // -> 'pkg:npm/express@4.18.2' // With namespace and subpath new PackageURL('npm', '@babel', 'runtime', '7.18.6', null, 'helpers/typeof.js') // -> 'pkg:npm/%40babel/runtime@7.18.6#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