# packageurl-js

> JavaScript library to parse and build "purl" aka. package URLs. This is a microlibrary implementing the purl spec at https://github.com/package-url

Latest version **2.0.1** (published 2024-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install packageurl-js
pnpm add packageurl-js
yarn add packageurl-js
bun add packageurl-js
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2024-09-04 |
| First published | 2018-08-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 55.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | the purl authors |
| Maintainers | majurg |
| Keywords | package, url |

## Links

- npm: https://www.npmjs.com/package/packageurl-js
- Repository: https://github.com/package-url/packageurl-js
- Homepage: https://github.com/package-url/packageurl-js#readme
- Issues: https://github.com/package-url/packageurl-js/issues
- npm.io page: https://npm.io/package/packageurl-js

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2024-09-04
- 2.0.0 — 2024-08-16
- 1.2.1 — 2023-11-06
- 1.2.0 — 2023-10-18
- 1.1.1 — 2023-09-25
- 1.1.0 — 2023-09-25
- 1.0.2 — 2023-04-03
- 1.0.1 — 2023-03-07
- 1.0.0 — 2022-09-09
- 0.0.7 — 2022-07-22
- 0.0.6 — 2022-03-29
- 0.0.5 — 2021-05-18
- 0.0.4 — 2021-01-12
- 0.0.3 — 2021-01-08
- 0.0.2 — 2020-05-27
- … 1 more at https://npm.io/package/packageurl-js/versions

## README

# packageurl-js

### Installing

To install `packageurl-js` in your project, simply run:
```bash
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:
```bash
npm install
```

### Testing

To run the test suite:
```bash
npm test
```

### Usage Examples

#### Importing

As an ES6 module
```js
import { PackageURL } from 'packageurl-js'
```

As a CommonJS module
```js
const { PackageURL } = require('packageurl-js')
```

#### Parsing

```js
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

```js
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

```js
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.
```js
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

---
_Source: https://npm.io/package/packageurl-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._