@socketregistry/packageurl-js

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.

What is a PURL?

A Package URL (purl) standardizes how to identify software packages:

pkg:npm/[email protected]
pkg:pypi/[email protected]
pkg:maven/org.springframework/[email protected]

Format breakdown:

  pkg:type/namespace/name@version?qualifiers#subpath
  │   │    │         │    │       │          │
  │   │    │         │    │       │          └─ Optional subpath
  │   │    │         │    │       └──────────── Optional key=value pairs
  │   │    │         │    └──────────────────── Optional version
  │   │    │         └───────────────────────── Required package name
  │   │    └─────────────────────────────────── Optional namespace/scope
  │   └──────────────────────────────────────── Required package type
  └──────────────────────────────────────────── Scheme (always "pkg:")

Supports 35+ ecosystems: npm, pypi, maven, gem, cargo, nuget, composer, golang, docker, and more.

Installation

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

Usage

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
}

Documentation

| Doc | Description | |-----|-------------| | Getting Started | Quick setup guide for contributors | | API Reference | Complete API documentation | | Examples | Common use cases and patterns | | Builder Pattern | Fluent builder guide |

Development

pnpm install   # Install dependencies
pnpm build     # Build
pnpm test      # Test
pnpm check     # Lint + typecheck