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

2.0.1

Bug Fix

• Fix decoding problems around the % character #75 (fix contributed by @jdalton)

2.0.0

• Significant refactor based on code from @jdalton
• Numerous bug fixes and improvements the community was asking for
  • See closed issues and PRs for details (too many to list here)

1.2.1

Bug Fixes

• purls with + in versions are now valid #52 (contributed by @satanshiro)
• purl names staring with : are now accepted #45 (contributed by @aniruth37)

1.2.0

Features

• Add pub parsing for Dart and Flutter packages (contributed by @topaztee)

1.1.1

Bug Fix

• publish errors

1.1.0

Features

• Verify entire version string is properly encoded (contributed by @mcombuechen, @topaztee)

1.0.2

Bug Fixes

• Normalize metafiles (contributed by @smorimoto)

Chores

• Bumped various dependencies

1.0.1

Bug Fixes

• Hardened encoding/decoding of URL special chars like @ and # #37

1.0.0

Features

• Add enum-like static readonly property KnownQualifierNames to reflect known qualifier names #34

0.0.7

Bug Fixes

• Keep license texts in comment headers, even after minification #27
• Fix a bug in golang purls that was adding additional slashes to the string #30

0.0.6

Bug Fixes

• Properly replace all underscore values for PyPI packages #23

0.0.5

Changes

• update deps via npm audit fix

Bug Fixes

• Handle forward slash in namespace for go purls

0.0.4

Bug Fixes

• Properly handle PyPI purl values per the purl-spec #18

0.0.3

Bug Fixes

• Properly handle undefined or null qualifier values #16

0.0.2

Features

• TypeScript: type-definitions #6

Bug fixes

• fromString(): version is used outside of block scope #5
• fromString(): qualifiers extracted as string, constructor expects object #7

BREAKING CHANGES

• the main module previously exported the PackageURL class directly
• this prevents that additional classes can be added in the future and doesn't work nicely together with the ES6 module system
• the root module now exports an object containing the classes

Before

const PackageURL = require('packageurl-js');

After

const PackageURL = require('packageurl-js').PackageURL;
// or
const { PackageURL } = require('packageurl-js');
// or ES6 / Typescript
import { PackageURL } from 'packageurl-js';

0.0.1

• Initial release