Class PackageResource

Represents an npm package resource, providing access to package metadata, versions, dist-tags, and download statistics.

Implements PromiseLike<NpmPackument> so it can be awaited directly to fetch the full packument, while also exposing sub-resource methods.

Example

// Await directly to get full package metadata
const pkg = await npm.package('react');

// Get a specific version
const v18 = await npm.package('react').version('18.2.0');

// Get dist-tags
const tags = await npm.package('react').distTags();

// Get download stats for last month
const stats = await npm.package('react').downloads();

// Get daily download breakdown for a custom date range
const range = await npm.package('react').downloadRange('2024-01-01:2024-01-31');

Implements

PromiseLike<NpmPackument>

Index

Methods

cdnStats distTags downloadRange downloads get latest maintainers score size then version versions

Methods

cdnStats

cdnStats(
    groupBy?: JsdelivrGroupBy,
    period?: JsdelivrPeriod,
    signal?: AbortSignal,
): Promise<JsdelivrStats>
Fetches CDN usage statistics for this package from jsDelivr.

CDN stats reflect real browser/frontend usage, complementing npm download counts which measure install-time usage.

GET /package/npm/{name}/stats/{groupBy}/{period} (via data.jsdelivr.com/v1)
Parameters
- groupBy: JsdelivrGroupBy = 'version'
  Group results by 'version' (default) or 'date'
- period: JsdelivrPeriod = 'month'
  Time period: 'day', 'week', 'month' (default), or 'year'
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<JsdelivrStats>
CDN hit counts, bandwidth, rank, and breakdown by version or date
Example
```
const stats = await npm.package('react').cdnStats();
console.log(stats.rank);   // 1
console.log(stats.total);  // 1234567890
```
- Defined in src/resources/PackageResource.ts:278

distTags

distTags(signal?: AbortSignal): Promise<NpmDistTags>
Fetches all dist-tags for this package.

GET /-/package/{name}/dist-tags
Parameters
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmDistTags>
A map of tag names to version strings
Example
```
const tags = await npm.package('react').distTags();
// { latest: '18.2.0', next: '19.0.0-beta.1' }
```
- Defined in src/resources/PackageResource.ts:154

downloadRange

downloadRange(
period?: NpmDownloadPeriod,
signal?: AbortSignal,
): Promise<NpmDownloadRange>
Fetches the per-day download breakdown for this package over a given period.

GET /downloads/range/{period}/{name} (via api.npmjs.org)
Parameters
- period: NpmDownloadPeriod = 'last-month'
  Named period or date range (default: 'last-month')
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmDownloadRange>
Download range data with a per-day array
Example
```
const range = await npm.package('react').downloadRange('2024-01-01:2024-01-31');
range.downloads.forEach(d => console.log(d.day, d.downloads));
```
- Defined in src/resources/PackageResource.ts:197

downloads

downloads(
period?: NpmDownloadPeriod,
signal?: AbortSignal,
): Promise<NpmDownloadPoint>
Fetches the total download count for this package over a given period.

GET /downloads/point/{period}/{name} (via api.npmjs.org)
Parameters
- period: NpmDownloadPeriod = 'last-month'
  Named period or date range (default: 'last-month')
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmDownloadPoint>
Download point data including total count and date range
Example
```
const stats = await npm.package('react').downloads('last-week');
console.log(stats.downloads); // 12345678
```
- Defined in src/resources/PackageResource.ts:173

get

get(signal?: AbortSignal): Promise<NpmPackument>
Fetches the full packument (all versions metadata) for this package.

GET /{name}
Parameters
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmPackument>
The full packument object
- Defined in src/resources/PackageResource.ts:61

latest

latest(): VersionResource
Returns a VersionResource for the latest dist-tag.

Shorthand for .version('latest').

Returns VersionResource
A chainable version resource pointing to latest
Example
```
const manifest = await npm.package('react').latest();
```
- Defined in src/resources/PackageResource.ts:93

maintainers

maintainers(signal?: AbortSignal): Promise<NpmPerson[]>
Fetches the current maintainers of this package.

Internally fetches the packument and returns the maintainers array.

GET /{name}
Parameters
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmPerson[]>
Array of maintainer entries (name, email, url)
Example
```
const maintainers = await npm.package('typescript').maintainers();
maintainers.forEach(m => console.log(m.name, m.email));
```
- Defined in src/resources/PackageResource.ts:135

score

score(signal?: AbortSignal): Promise<NpmsScore>
Fetches the quality, maintenance, and popularity score for this package from npms.io.

Returns a detailed breakdown of each score component, including test coverage, release frequency, community interest, and dependent package count.

GET /package/{name} (via api.npms.io/v2)
Parameters
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmsScore>
Detailed score and evaluation data
Example
```
const score = await npm.package('react').score();
console.log(score.score.final);                         // 0.97
console.log(score.evaluation.popularity.dependentsCount); // 15000
```
- Defined in src/resources/PackageResource.ts:224

size

size(signal?: AbortSignal): Promise<PackagephobiaSize>
Fetches the publish size and full install size (including all transitive dependencies) for the latest version of this package from Packagephobia.

GET /v2/api.json?p={name} (via packagephobia.com)
Parameters
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<PackagephobiaSize>
Publish and install size in bytes, file counts, and human-readable strings
Example
```
const size = await npm.package('react').size();
console.log(size.install.pretty); // "300 kB"
console.log(size.install.bytes);  // 307200
```
- Defined in src/resources/PackageResource.ts:249

then

then<TResult1 = NpmPackument, TResult2 = never>(
    onfulfilled?:
        | null
        | (value: NpmPackument) => TResult1 | PromiseLike<TResult1>,
    onrejected?: null | (reason: unknown) => TResult2 | PromiseLike<TResult2>,
): PromiseLike<TResult1 | TResult2>
Allows the resource to be awaited directly, resolving with the full packument. Delegates to PackageResource.get.
Type Parameters
- TResult1 = NpmPackument
- TResult2 = never
Parameters
- Optionalonfulfilled: null | (value: NpmPackument) => TResult1 | PromiseLike<TResult1>
- Optionalonrejected: null | (reason: unknown) => TResult2 | PromiseLike<TResult2>
Returns PromiseLike<TResult1 | TResult2>
Implementation of PromiseLike.then
- Defined in src/resources/PackageResource.ts:46

version

version(ver: string): VersionResource
Returns a VersionResource for a specific version, which can be awaited directly or chained.
Parameters
- ver: string
  Version string (e.g. '18.2.0') or dist-tag (e.g. 'latest')
Returns VersionResource
A chainable version resource
Example
```
const manifest = await npm.package('react').version('18.2.0');
```
- Defined in src/resources/PackageResource.ts:77

versions

versions(signal?: AbortSignal): Promise<NpmPackageVersion[]>
Fetches all published versions of this package as an ordered array.

Internally fetches the packument and converts the versions map to an array sorted from oldest to newest.

GET /{name}
Parameters
- Optionalsignal: AbortSignal
  Optional AbortSignal to cancel the request
Returns Promise<NpmPackageVersion[]>
Array of version manifests sorted by publication order
Example
```
const versions = await npm.package('typescript').versions();
console.log(versions.map(v => v.version).join(', '));
```
- Defined in src/resources/PackageResource.ts:114

Class PackageResource

Example

Implements

Index

Methods

Methods

cdnStats

Parameters

Returns Promise<JsdelivrStats>

Example

distTags

Parameters

Returns Promise<NpmDistTags>

Example

downloadRange

Parameters

Returns Promise<NpmDownloadRange>

Example

downloads

Parameters

Returns Promise<NpmDownloadPoint>

Example

get

Parameters

Returns Promise<NpmPackument>

latest

Returns VersionResource

Example

maintainers

Parameters

Returns Promise<NpmPerson[]>

Example

score

Parameters

Returns Promise<NpmsScore>

Example

size

Parameters

Returns Promise<PackagephobiaSize>

Example

then

Type Parameters

Parameters

Returns PromiseLike<TResult1 | TResult2>

version

Parameters

Returns VersionResource

Example

versions

Parameters

Returns Promise<NpmPackageVersion[]>

Example

Settings

On This Page