Skip to content

Commit af2f50a

Browse files
committed
docs(readme): document VERS, immutable updates, result-based parsing
Update feature list and examples to reflect existing APIs: Vers/VersConstraint/VersWildcard, withVersion/withNamespace/withQualifier(s)/withSubpath, tryFromString/tryFromJSON/tryFromObject/isValid/fromUrl. Bump registry count to 17 and include the conda/docker/vscode-extension existence checkers in the registry example.
1 parent 2f5f3bf commit af2f50a

1 file changed

Lines changed: 46 additions & 2 deletions

File tree

README.md

Lines changed: 46 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,10 @@ pkg:maven/org.springframework/spring-core@5.3.21
4545
-**100% test coverage** - Over 1,000 passing tests
4646
-**Multiple APIs** - Functional, class-based, and builder patterns
4747
-**URL conversion** - Convert to repository and download URLs
48-
-**Registry checks** - Verify package existence across 14 registries
48+
-**Registry checks** - Verify package existence across 17 registries
49+
-**VERS support** - First-class implementation of the VERS companion spec (`Vers`, `VersConstraint`, `VersWildcard`)
50+
-**Immutable updates** - `withVersion`, `withNamespace`, `withQualifier`, `withQualifiers`, `withSubpath`
51+
-**Result-based parsing** - `tryFromString`, `tryFromJSON`, `tryFromObject`, `isValid`, `fromUrl`
4952

5053
## Install
5154

@@ -161,7 +164,48 @@ await npmExists('lodash', undefined, '4.17.21') // validate version
161164
// npmExists, pypiExists, cargoExists, gemExists,
162165
// mavenExists, nugetExists, golangExists, packagistExists,
163166
// cocoapodsExists, pubExists, hexExists, cpanExists,
164-
// cranExists, hackageExists
167+
// cranExists, hackageExists, condaExists, dockerExists,
168+
// vscodeExtensionExists
169+
```
170+
171+
### VERS (Version Range Specifier)
172+
173+
First-class implementation of the [VERS companion spec](https://github.com/package-url/purl-spec/blob/main/VERSION-RANGE-SPEC.rst):
174+
175+
```javascript
176+
import { Vers } from '@socketregistry/packageurl-js'
177+
178+
const range = Vers.parse('vers:npm/>=1.0.0|<2.0.0')
179+
range.contains('1.5.0') // -> true
180+
range.contains('2.0.0') // -> false
181+
```
182+
183+
### Immutable updates
184+
185+
`PackageURL` instances are immutable; `with*` methods return a new instance:
186+
187+
```javascript
188+
const next = purl
189+
.withVersion('5.0.0')
190+
.withQualifier('repository_url', 'https://github.com/lodash/lodash')
191+
```
192+
193+
### Result-based parsing
194+
195+
Parse untrusted input without try/catch:
196+
197+
```javascript
198+
import { PackageURL } from '@socketregistry/packageurl-js'
199+
200+
const result = PackageURL.tryFromString(userInput)
201+
if (result.isOk()) {
202+
use(result.value)
203+
} else {
204+
log(result.error)
205+
}
206+
207+
PackageURL.isValid(userInput) // -> boolean
208+
PackageURL.fromUrl('https://github.com/lodash/lodash') // infers purl from URL
165209
```
166210

167211
### TypeScript Types

0 commit comments

Comments
 (0)