davidwindham.com
forked from
npmx.dev/npmx.dev
[READ-ONLY]
a fast, modern browser for the npm registry
1/**
2 * Version Downloads Distribution Types
3 * Types for version download statistics and grouping.
4 *
5 * These types support fetching per-version download counts from npm API
6 * and grouping them by major/minor versions for distribution analysis.
7 */
8
9/**
10 * Download data for a single package version
11 */
12export interface VersionDownloadPoint {
13 /** Semantic version string (e.g., "1.2.3") */
14 version: string
15 /** Download count for this version */
16 downloads: number
17 /** Percentage of total downloads (0-100) */
18 percentage: number
19}
20
21/**
22 * Aggregated download data for a version group (major or minor)
23 */
24export interface VersionGroupDownloads {
25 /** Group identifier (e.g., "1.x" for major, "1.2.x" for minor) */
26 groupKey: string
27 /** Human-readable label (e.g., "v1.x", "v1.2.x") */
28 label: string
29 /** Total downloads for all versions in this group */
30 downloads: number
31 /** Percentage of total downloads (0-100) */
32 percentage: number
33 /** Individual versions in this group */
34 versions: VersionDownloadPoint[]
35}
36
37/**
38 * Mode for grouping versions
39 * - 'major': Group by major version (1.x, 2.x)
40 * - 'minor': Group by minor version (1.2.x, 1.3.x)
41 */
42export type VersionGroupingMode = 'major' | 'minor'
43
44/**
45 * API response for version download distribution
46 */
47export interface VersionDistributionResponse {
48 /** Package name */
49 package: string
50 /** Grouping mode used */
51 mode: VersionGroupingMode
52 /** Total downloads across all versions */
53 totalDownloads: number
54 /** Grouped version data */
55 groups: VersionGroupDownloads[]
56 /** ISO 8601 timestamp when data was fetched */
57 timestamp: string
58 /** List of version strings published within the last year (only present when filterOldVersions=true) */
59 recentVersions?: string[]
60}