packageurl-js

What is packageurl-js?

The packageurl-js npm package is a JavaScript implementation of the Package URL (purl) specification. It allows you to parse, construct, and manipulate package URLs, which are used to identify and locate software packages in a standardized way.

What are packageurl-js's main functionalities?

Parsing a Package URL

This feature allows you to parse a package URL string into its components. The code sample demonstrates how to parse a package URL for the Angular core package.

const { PackageURL } = require('packageurl-js');
const purl = PackageURL.fromString('pkg:npm/%40angular/core@12.0.0');
console.log(purl);

Constructing a Package URL

This feature allows you to construct a package URL from its components. The code sample demonstrates how to create a package URL for the Angular core package.

const { PackageURL } = require('packageurl-js');
const purl = new PackageURL('npm', '@angular', 'core', '12.0.0', null, null);
console.log(purl.toString());

Manipulating a Package URL

This feature allows you to manipulate the components of a package URL. The code sample demonstrates how to change the version of an existing package URL.

const { PackageURL } = require('packageurl-js');
let purl = new PackageURL('npm', '@angular', 'core', '12.0.0', null, null);
purl.version = '12.1.0';
console.log(purl.toString());

Other packages similar to packageurl-js

url-parse

The url-parse npm package is a more general-purpose URL parsing library. While it can handle package URLs, it is not specifically designed for them and lacks some of the specialized features of packageurl-js.

parse-package-name

The parse-package-name npm package focuses on parsing package names and versions from strings. It provides some similar functionality but is more limited in scope compared to packageurl-js.

README

packageurl-js

Installing

To install packageurl-js in your project, simply run:

npm install packageurl-js

This command will download the packageurl-js npm package for use in your application.

Local Development

Clone the packageurl-js repo and cd into the directory.

Then run:

npm install

Testing

To run the test suite:

npm test

Usage Examples

Importing

As an ES6 module

import { PackageURL } from 'packageurl-js'

As a CommonJS module

const { PackageURL } = require('packageurl-js')

Parsing

const purlStr = 'pkg:maven/org.springframework.integration/spring-integration-jms@5.5.5'
console.log(PackageURL.fromString(purlStr))
console.log(new PackageURL(...PackageURL.parseString(purlStr)))

will both log

PackageURL {
    type: 'maven',
    name: 'spring-integration-jms',
    namespace: 'org.springframework.integration',
    version: '5.5.5',
    qualifiers: undefined,
    subpath: undefined
}

Constructing

const pkg = new PackageURL(
    'maven',
    'org.springframework.integration',
    'spring-integration-jms',
    '5.5.5'
)
console.log(pkg.toString())

=>

pkg:maven/org.springframework.integration/spring-integration-jms@5.5.5

Error Handling

try {
    PackageURL.fromString('not-a-purl')
} catch (e) {
    console.error(e.message)
}

=>

Invalid purl: missing required "pkg" scheme component

Helper Objects

Helpers for encoding, normalizing, and validating purl components and types can be imported directly from the module or found on the PackageURL class as static properties.

import {
    PackageURL,
    PurlComponent,
    PurlType
} from 'packageurl-js'

PurlComponent === PackageURL.Component // => true
PurlType === PackageURL.Type // => true

PurlComponent

Contains the following properties each with their own encode, normalize, and validate methods, e.g. PurlComponent.name.validate(nameStr):

• type
• namespace
• name
• version
• qualifiers
• qualifierKey
• qualifierValue
• subpath

PurlType

Contains the following properties each with their own normalize, and validate methods, e.g. PurlType.npm.validate(purlObj):

• alpm
• apk
• bitbucket
• bitnami
• composer
• conan
• cran
• deb
• github
• gitlab
• golang
• hex
• huggingface
• luarocks
• maven
• mlflow
• npm
• oci
• pub
• pypi
• qpkg
• rpm
• swift