Registry / serialization / packageurl-js

packageurl-js

library2.0.1jsnpmunverified

The `packageurl-js` library provides a JavaScript implementation for parsing, constructing, and validating Package URLs (purls) according to the official purl specification (https://github.com/package-url/purl-spec). Currently at version 2.0.1, it is a microlibrary focused solely on handling purl strings and objects. It offers a `PackageURL` class for object-oriented manipulation, static methods for string parsing, and helper objects like `PurlComponent` and `PurlType` for component-level validation and normalization. Its primary differentiator is strict adherence to the purl specification, ensuring consistent and correct handling of package identifiers across different ecosystems. Given its nature as a specification implementation, release cadence is typically driven by updates to the purl specification itself or critical bug fixes.

serialization

npm install packageurl-js

github ↗package ↗

INSTALL

IMPORT

SIG · PACKAGEURL-JS

packageurl-js

serializationjavascriptv2.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PackageURL

✓ import { PackageURL } from 'packageurl-js'

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

The `PackageURL` class is a named export. For CommonJS, ensure destructuring: `const { PackageURL } = require('packageurl-js')`.

PurlComponent

✓ import { PurlComponent } from 'packageurl-js'

✗ import { Component } from 'packageurl-js'

A helper object for validating and normalizing individual purl components. Also accessible as `PackageURL.Component`.

PurlType

✓ import { PurlType } from 'packageurl-js'

✗ import { Type } from 'packageurl-js'

A helper object containing specific purl type validators and normalizers (e.g., `PurlType.npm`). Also accessible as `PackageURL.Type`.

Demonstrates parsing a Package URL string, constructing a `PackageURL` object programmatically, converting it back to a string, and robust error handling for invalid purl inputs.

import { PackageURL } from 'packageurl-js'; // Example 1: Parsing a PURL string into an object const purlStr = 'pkg:maven/org.springframework.integration/spring-integration-jms@5.5.5?repository_url=https://repo.maven.apache.org/maven2&arch=amd64#subpath/file'; const parsedPurl = PackageURL.fromString(purlStr); console.log('Parsed PURL object:', parsedPurl); console.log('PURL type:', parsedPurl.type); console.log('PURL version:', parsedPurl.version); // Example 2: Constructing a PackageURL object programmatically const newPkg = new PackageURL( 'npm', 'my-scope', 'my-package', '1.2.3', { os: 'linux', dist: 'es2020' }, 'dist/main.js' ); console.log('Constructed PURL string:', newPkg.toString()); // Example 3: Error handling for invalid PURL inputs try { PackageURL.fromString('not-a-valid-purl-string'); } catch (e: any) { console.error('Error parsing invalid PURL:', e.message); }

Debug

Known issues

gotchaThe `packageurl-js` library strictly adheres to the purl specification. Malformed or non-standard inputs, even those that might appear similar to valid purls, will result in parsing errors. This is by design to ensure correctness but can be a gotcha for users expecting more lenient parsing.

fix

Ensure all input strings strictly follow the purl specification (https://github.com/package-url/purl-spec). Always use `try...catch` blocks for robust error handling when processing external inputs.

affects: >=1.0.0

gotchaThe library primarily uses named exports and does not provide a default export. Attempting to import it as such in ESM or incorrectly requiring it in CommonJS will result in `undefined` exports or runtime errors.

fix

Always use named imports: `import { PackageURL } from 'packageurl-js'` for ESM. For CommonJS, ensure destructuring: `const { PackageURL } = require('packageurl-js')`. Do not attempt `import PackageURL from 'packageurl-js'` or `const PackageURL = require('packageurl-js')` without destructuring.

affects: >=1.0.0

Errors

Common errors & fixes

Invalid purl: missing required "pkg" scheme component

The input string is not a valid PURL; it does not start with 'pkg:' or is otherwise malformed according to the purl specification.

fix

Verify that the input string is a well-formed PURL. Ensure it begins with 'pkg:' and follows the specified syntax for type, namespace, name, version, qualifiers, and subpath.

TypeError: PackageURL is not a constructor

The `PackageURL` class was not correctly imported, often due to attempting a default import in ESM or incorrect CommonJS `require` without destructuring.

fix

Correct your import statement. For ESM, use `import { PackageURL } from 'packageurl-js'`. For CommonJS, use `const { PackageURL } = require('packageurl-js')`.

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/package-url/packageurl-js ↗

packagehttps://www.npmjs.com/package/packageurl-js ↗