@mcptoolshop/registry-stats 0.4.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.es.md +110 -60
  2. package/README.fr.md +151 -63
  3. package/README.hi.md +113 -63
  4. package/README.it.md +111 -61
  5. package/README.ja.md +109 -59
  6. package/README.md +37 -3
  7. package/README.pt-BR.md +107 -57
  8. package/README.zh.md +109 -59
  9. package/assets/logo.png +0 -0
  10. package/package.json +1 -1
package/README.hi.md CHANGED
@@ -3,78 +3,97 @@
3
3
  </p>
4
4
 
5
5
  <p align="center">
6
- <img src="assets/logo.png" alt="registry-stats लोगो" width="280" />
6
+ <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/registry-stats/readme.png" alt="registry-stats logo" width="400" />
7
7
  </p>
8
8
 
9
- <h1 align="center">@mcptoolshop/registry-stats</h1>
9
+ <p align="center">
10
+ One command. Five registries. All your download stats.
11
+ </p>
10
12
 
11
13
  <p align="center">
12
- एक कमांड। पाँच रजिस्ट्री। आपके सभी डाउनलोड आँकड़े।
14
+ <a href="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml"><img src="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg" alt="CI"></a>
15
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
16
+ <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
17
+ <a href="https://mcp-tool-shop-org.github.io/registry-stats/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
13
18
  </p>
14
19
 
15
20
  <p align="center">
16
- <a href="https://mcp-tool-shop-org.github.io/registry-stats/">डॉक्स</a> &middot;
17
- <a href="#इंस्टॉल">इंस्टॉल</a> &middot;
21
+ <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
22
+ <a href="#install">Install</a> &middot;
18
23
  <a href="#cli">CLI</a> &middot;
19
- <a href="#कॉन्फ़िग-फ़ाइल">कॉन्फ़िग</a> &middot;
20
- <a href="#प्रोग्रामैटिक-api">API</a> &middot;
21
- <a href="#rest-api-सर्वर">REST सर्वर</a> &middot;
22
- <a href="#लाइसेंस">लाइसेंस</a>
24
+ <a href="#config-file">Config</a> &middot;
25
+ <a href="#programmatic-api">API</a> &middot;
26
+ <a href="#rest-api-server">REST Server</a> &middot;
27
+ <a href="#license">License</a>
23
28
  </p>
24
29
 
25
30
  ---
26
31
 
27
- यदि आप npm, PyPI, NuGet, VS Code Marketplace, या Docker Hub पर पैकेज प्रकाशित करते हैं, तो "इस महीने मेरे कितने डाउनलोड हुए?" का जवाब देने के लिए आपको पाँच अलग-अलग API की आवश्यकता होती है। यह लाइब्रेरी सभी के लिए एक इंटरफ़ेस प्रदान करती है — CLI या प्रोग्रामैटिक API के रूप में।
32
+ यदि आप npm, PyPI, NuGet, VS Code मार्केटप्लेस या डॉकर हब पर कुछ प्रकाशित करते हैं, तो वर्तमान में आपको "इस महीने मुझे कितने डाउनलोड मिले?" यह जानने के लिए पांच अलग-अलग एपीआई की आवश्यकता होती है। यह लाइब्रेरी आपको सभी के लिए एक ही इंटरफ़ेस प्रदान करती है - या तो कमांड-लाइन इंटरफ़ेस (CLI) के रूप में या प्रोग्रामेटिक एपीआई के रूप में।
28
33
 
29
- शून्य निर्भरता। नेटिव `fetch()` का उपयोग। Node 18+.
34
+ शून्य निर्भरता। यह मूल `fetch()` का उपयोग करता है। Node 18 या उससे ऊपर।
30
35
 
31
- ## इंस्टॉल
36
+ ## इंस्टॉल करें
32
37
 
33
38
  ```bash
34
39
  npm install @mcptoolshop/registry-stats
35
40
  ```
36
41
 
37
- ## CLI
42
+ ## कमांड-लाइन इंटरफ़ेस (CLI)
38
43
 
39
44
  ```bash
40
- # एकल रजिस्ट्री क्वेरी
45
+ # Query a single registry
41
46
  registry-stats express -r npm
47
+ # npm | express
48
+ # month: 283,472,710 week: 67,367,773 day: 11,566,113
42
49
 
43
- # सभी रजिस्ट्री एक साथ क्वेरी
50
+ # Query all registries at once
44
51
  registry-stats express
45
52
 
46
- # मासिक ब्रेकडाउन + ट्रेंड के साथ टाइम सीरीज़
53
+ # Time series with monthly breakdown + trend
47
54
  registry-stats express -r npm --range 2025-01-01:2025-06-30
55
+ # 2025-01 142,359,021
56
+ # 2025-02 147,522,528
57
+ # ...
58
+ # Total: 448,383,383 Avg/day: 4,982,038 Trend: flat (-0.46%)
48
59
 
49
- # JSON आउटपुट
60
+ # Raw JSON output
50
61
  registry-stats express -r npm --json
51
62
 
52
- # अन्य रजिस्ट्री
63
+ # Other registries
53
64
  registry-stats requests -r pypi
54
65
  registry-stats Newtonsoft.Json -r nuget
55
66
  registry-stats esbenp.prettier-vscode -r vscode
56
67
  registry-stats library/node -r docker
57
68
 
58
- # कॉन्फ़िग फ़ाइल बनाएँ
69
+ # Create a config file
59
70
  registry-stats --init
60
71
 
61
- # कॉन्फ़िग से चलाएँ — सभी ट्रैक किए गए पैकेज प्राप्त करें
72
+ # Run with config — fetches all tracked packages
62
73
  registry-stats
63
74
 
64
- # रजिस्ट्री में तुलना करें
75
+ # Compare across registries
65
76
  registry-stats express --compare
66
-
67
- # CSV या चार्ट-फ्रेंडली JSON में एक्सपोर्ट
77
+ # express — comparison
78
+ #
79
+ # Metric npm pypi
80
+ # ─────────────────────────────────
81
+ # Total - -
82
+ # Month 283,472 47,201
83
+ # Week 67,367 11,800
84
+ # Day 11,566 1,686
85
+
86
+ # Export as CSV or chart-friendly JSON
68
87
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
69
88
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
70
89
 
71
- # REST API सर्वर शुरू करें
90
+ # Start a REST API server
72
91
  registry-stats serve --port 3000
73
92
  ```
74
93
 
75
- ## कॉन्फ़िग फ़ाइल
94
+ ## कॉन्फ़िगरेशन फ़ाइल
76
95
 
77
- अपने प्रोजेक्ट रूट में `registry-stats.config.json` बनाएँ (या `registry-stats --init` चलाएँ):
96
+ अपने प्रोजेक्ट के रूट में `registry-stats.config.json` फ़ाइल बनाएं (या `registry-stats --init` कमांड चलाएं):
78
97
 
79
98
  ```json
80
99
  {
@@ -95,85 +114,104 @@ registry-stats serve --port 3000
95
114
  }
96
115
  ```
97
116
 
98
- बिना तर्क के `registry-stats` चलाएँ और सभी कॉन्फ़िगर किए गए पैकेजों के आँकड़े प्राप्त करें। CLI वर्तमान डायरेक्टरी से ऊपर की ओर कॉन्फ़िग फ़ाइल खोजता है।
117
+ सभी कॉन्फ़िगर किए गए पैकेजों के आंकड़े प्राप्त करने के लिए बिना किसी तर्क के `registry-stats` कमांड चलाएं। CLI, कॉन्फ़िगरेशन फ़ाइल ढूंढने के लिए वर्तमान कार्यशील निर्देशिका (cwd) से ऊपर की ओर खोज करता है।
118
+
119
+ कॉन्फ़िगरेशन प्रोग्रामेटिक रूप से भी उपलब्ध है:
120
+
121
+ ```typescript
122
+ import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';
123
+
124
+ const config = loadConfig(); // finds nearest config file, or null
125
+ const defaults = defaultConfig(); // returns default Config object
126
+ const template = starterConfig(); // returns starter JSON string
127
+ ```
99
128
 
100
- ## प्रोग्रामैटिक API
129
+ ## प्रोग्रामेटिक एपीआई
101
130
 
102
131
  ```typescript
103
132
  import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
104
133
 
105
- // एकल रजिस्ट्री
134
+ // Single registry
106
135
  const npm = await stats('npm', 'express');
107
136
  const pypi = await stats('pypi', 'requests');
137
+ const nuget = await stats('nuget', 'Newtonsoft.Json');
138
+ const vscode = await stats('vscode', 'esbenp.prettier-vscode');
139
+ const docker = await stats('docker', 'library/node');
108
140
 
109
- // सभी रजिस्ट्री (Promise.allSettled का उपयोग — कभी एरर नहीं फेंकता)
141
+ // All registries at once (uses Promise.allSettled — never throws)
110
142
  const all = await stats.all('express');
111
143
 
112
- // बल्क — कई पैकेज, सीमित कंकरेंसी (डिफ़ॉल्ट: 5)
144
+ // Bulk — multiple packages, concurrency-limited (default: 5)
113
145
  const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
114
146
 
115
- // टाइम सीरीज़ (केवल npm + pypi)
147
+ // Time series (npm + pypi only)
116
148
  const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
117
149
 
118
- // गणनाएँ
119
- calc.total(daily); // कुल डाउनलोड
120
- calc.avg(daily); // दैनिक औसत
150
+ // Calculations
151
+ calc.total(daily); // sum of all downloads
152
+ calc.avg(daily); // daily average
153
+ calc.groupTotals(calc.monthly(daily)); // { '2025-01': 134982, ... }
121
154
  calc.trend(daily); // { direction: 'up', changePercent: 8.3 }
122
- calc.movingAvg(daily, 7); // 7-दिन मूविंग एवरेज
123
- calc.popularity(daily); // 0-100 लॉग-स्केल स्कोर
155
+ calc.movingAvg(daily, 7); // 7-day moving average
156
+ calc.popularity(daily); // 0-100 log-scale score
124
157
 
125
- // एक्सपोर्ट फ़ॉर्मेट
126
- calc.toCSV(daily); // CSV स्ट्रिंग
127
- calc.toChartData(daily, 'express'); // { labels: [...], datasets: [...] }
158
+ // Export formats
159
+ calc.toCSV(daily); // "date,downloads\n2025-01-01,1234\n..."
160
+ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ label, data }] }
128
161
 
129
- // तुलना — रजिस्ट्री में एक ही पैकेज
162
+ // Comparison — same package across registries
130
163
  const comparison = await stats.compare('express');
131
- await stats.compare('express', ['npm', 'pypi']);
164
+ // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
165
+ await stats.compare('express', ['npm', 'pypi']); // specific registries only
132
166
 
133
- // कैश (5 मिनट TTL, इन-मेमोरी)
167
+ // Caching (5 min TTL, in-memory)
134
168
  const cache = createCache();
135
- await stats('npm', 'express', { cache });
169
+ await stats('npm', 'express', { cache }); // fetches
170
+ await stats('npm', 'express', { cache }); // cache hit
136
171
  ```
137
172
 
138
- ## रजिस्ट्री सपोर्ट
173
+ ## रजिस्ट्री समर्थन
139
174
 
140
- | रजिस्ट्री | पैकेज फ़ॉर्मेट | टाइम सीरीज़ | उपलब्ध डेटा |
141
- |-----------|---------------|------------|-------------|
142
- | `npm` | `express`, `@scope/pkg` | हाँ (549 दिन) | lastDay, lastWeek, lastMonth |
143
- | `pypi` | `requests` | हाँ (180 दिन) | lastDay, lastWeek, lastMonth, total |
144
- | `nuget` | `Newtonsoft.Json` | नहीं | total |
145
- | `vscode` | `publisher.extension` | नहीं | total (इंस्टॉल), rating, trends |
146
- | `docker` | `namespace/repo` | नहीं | total (पुल), stars |
175
+ | रजिस्ट्री | पैकेज प्रारूप | समय श्रृंखला | उपलब्ध डेटा |
176
+ | ---------- | --------------- | ------------- | ---------------- |
177
+ | `npm` | `express`, `@scope/pkg` | हाँ (549 दिन) | अंतिम दिन, अंतिम सप्ताह, अंतिम महीना |
178
+ | `pypi` | `requests` | हाँ (180 दिन) | अंतिम दिन, अंतिम सप्ताह, अंतिम महीना, कुल |
179
+ | `nuget` | `Newtonsoft.Json` | No | कुल |
180
+ | `vscode` | `publisher.extension` | No | कुल (इंस्टॉलेशन), रेटिंग, रुझान |
181
+ | `docker` | `namespace/repo` | No | कुल (डाउनलोड), सितारे |
147
182
 
148
- ## अंतर्निर्मित विश्वसनीयता
183
+ ## अंतर्निहित विश्वसनीयता
149
184
 
150
- - 429/5xx त्रुटियों पर एक्सपोनेंशियल बैकऑफ़ के साथ स्वचालित रीट्राई
151
- - `Retry-After` हेडर का सम्मान
152
- - बल्क अनुरोधों के लिए कंकरेंसी सीमा
153
- - वैकल्पिक TTL कैश (प्लगेबल — `StatsCache` इंटरफ़ेस के माध्यम से Redis/फ़ाइल बैकएंड)
185
+ - 429/5xx त्रुटियों पर स्वचालित पुनः प्रयास, जिसमें घातीय बैकऑफ़ शामिल है।
186
+ - `Retry-After` हेडर का सम्मान करता है।
187
+ - बल्क अनुरोधों के लिए समवर्ती सीमा।
188
+ - वैकल्पिक TTL कैश (प्लग करने योग्य - `StatsCache` इंटरफ़ेस के माध्यम से अपना Redis/फ़ाइल बैकएंड प्रदान करें)।
154
189
 
155
- ## REST API सर्वर
190
+ ## REST एपीआई सर्वर
156
191
 
157
- माइक्रोसर्विस के रूप में चलाएँ, या अपने सर्वर में एम्बेड करें:
192
+ इसे एक माइक्रोसर्विस के रूप में चलाएं या इसे अपने सर्वर में एम्बेड करें:
158
193
 
159
194
  ```bash
195
+ # CLI
160
196
  registry-stats serve --port 3000
161
197
  ```
162
198
 
163
199
  ```
164
- GET /stats/:package # सभी रजिस्ट्री
165
- GET /stats/:registry/:package # एकल रजिस्ट्री
200
+ GET /stats/:package # all registries
201
+ GET /stats/:registry/:package # single registry
166
202
  GET /compare/:package?registries=npm,pypi
167
203
  GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
168
204
  ```
169
205
 
206
+ कस्टम सर्वरों या सर्वरलेस वातावरण के लिए प्रोग्रामेटिक उपयोग:
207
+
170
208
  ```typescript
171
209
  import { createHandler, serve } from '@mcptoolshop/registry-stats';
172
210
 
173
- // क्विक स्टार्ट
211
+ // Option 1: Quick start
174
212
  serve({ port: 3000 });
175
213
 
176
- // कस्टम सर्वर
214
+ // Option 2: Bring your own server
177
215
  import { createServer } from 'node:http';
178
216
  const handler = createHandler();
179
217
  createServer(handler).listen(3000);
@@ -202,6 +240,18 @@ registerProvider(cargo);
202
240
  await stats('cargo', 'serde');
203
241
  ```
204
242
 
243
+ ## वेबसाइट
244
+
245
+ दस्तावेज़/लैंडिंग पृष्ठ `site/` में स्थित है।
246
+
247
+ - विकास: `npm run site:dev`
248
+ - बिल्ड: `npm run site:build`
249
+ - पूर्वावलोकन: `npm run site:preview`
250
+
205
251
  ## लाइसेंस
206
252
 
207
253
  MIT
254
+
255
+ ---
256
+
257
+ यह <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> द्वारा बनाया गया है।
package/README.it.md CHANGED
@@ -3,30 +3,35 @@
3
3
  </p>
4
4
 
5
5
  <p align="center">
6
- <img src="assets/logo.png" alt="logo registry-stats" width="280" />
6
+ <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/registry-stats/readme.png" alt="registry-stats logo" width="400" />
7
7
  </p>
8
8
 
9
- <h1 align="center">@mcptoolshop/registry-stats</h1>
9
+ <p align="center">
10
+ One command. Five registries. All your download stats.
11
+ </p>
10
12
 
11
13
  <p align="center">
12
- Un comando. Cinque registri. Tutte le tue statistiche di download.
14
+ <a href="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml"><img src="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg" alt="CI"></a>
15
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
16
+ <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
17
+ <a href="https://mcp-tool-shop-org.github.io/registry-stats/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
13
18
  </p>
14
19
 
15
20
  <p align="center">
16
21
  <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
17
- <a href="#installazione">Installazione</a> &middot;
22
+ <a href="#install">Install</a> &middot;
18
23
  <a href="#cli">CLI</a> &middot;
19
- <a href="#file-di-configurazione">Configurazione</a> &middot;
20
- <a href="#api-programmatica">API</a> &middot;
21
- <a href="#server-rest-api">Server REST</a> &middot;
22
- <a href="#licenza">Licenza</a>
24
+ <a href="#config-file">Config</a> &middot;
25
+ <a href="#programmatic-api">API</a> &middot;
26
+ <a href="#rest-api-server">REST Server</a> &middot;
27
+ <a href="#license">License</a>
23
28
  </p>
24
29
 
25
30
  ---
26
31
 
27
- Se pubblichi su npm, PyPI, NuGet, VS Code Marketplace o Docker Hub, attualmente hai bisogno di cinque API diverse per rispondere a "quanti download ho avuto questo mese?" Questa libreria offre un'interfaccia unificata — come CLI o API programmatica.
32
+ Se pubblicate su npm, PyPI, NuGet, VS Code Marketplace o Docker Hub, attualmente avete bisogno di cinque API diverse per rispondere alla domanda "quanti download ho avuto questo mese?". Questa libreria vi offre un'unica interfaccia per tutte, sia come interfaccia a riga di comando (CLI) che come API programmatica.
28
33
 
29
- Zero dipendenze. Usa `fetch()` nativo. Node 18+.
34
+ Nessuna dipendenza. Utilizza la funzione nativa `fetch()`. Node 18 o superiore.
30
35
 
31
36
  ## Installazione
32
37
 
@@ -34,47 +39,61 @@ Zero dipendenze. Usa `fetch()` nativo. Node 18+.
34
39
  npm install @mcptoolshop/registry-stats
35
40
  ```
36
41
 
37
- ## CLI
42
+ ## CLI (Interfaccia a riga di comando)
38
43
 
39
44
  ```bash
40
- # Interrogare un singolo registro
45
+ # Query a single registry
41
46
  registry-stats express -r npm
47
+ # npm | express
48
+ # month: 283,472,710 week: 67,367,773 day: 11,566,113
42
49
 
43
- # Interrogare tutti i registri
50
+ # Query all registries at once
44
51
  registry-stats express
45
52
 
46
- # Serie temporale con ripartizione mensile + tendenza
53
+ # Time series with monthly breakdown + trend
47
54
  registry-stats express -r npm --range 2025-01-01:2025-06-30
55
+ # 2025-01 142,359,021
56
+ # 2025-02 147,522,528
57
+ # ...
58
+ # Total: 448,383,383 Avg/day: 4,982,038 Trend: flat (-0.46%)
48
59
 
49
- # Output JSON
60
+ # Raw JSON output
50
61
  registry-stats express -r npm --json
51
62
 
52
- # Altri registri
63
+ # Other registries
53
64
  registry-stats requests -r pypi
54
65
  registry-stats Newtonsoft.Json -r nuget
55
66
  registry-stats esbenp.prettier-vscode -r vscode
56
67
  registry-stats library/node -r docker
57
68
 
58
- # Creare file di configurazione
69
+ # Create a config file
59
70
  registry-stats --init
60
71
 
61
- # Eseguire con configurazione — recupera tutti i pacchetti tracciati
72
+ # Run with config — fetches all tracked packages
62
73
  registry-stats
63
74
 
64
- # Confrontare tra registri
75
+ # Compare across registries
65
76
  registry-stats express --compare
66
-
67
- # Esportare come CSV o JSON per grafici
77
+ # express — comparison
78
+ #
79
+ # Metric npm pypi
80
+ # ─────────────────────────────────
81
+ # Total - -
82
+ # Month 283,472 47,201
83
+ # Week 67,367 11,800
84
+ # Day 11,566 1,686
85
+
86
+ # Export as CSV or chart-friendly JSON
68
87
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
69
88
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
70
89
 
71
- # Avviare server REST API
90
+ # Start a REST API server
72
91
  registry-stats serve --port 3000
73
92
  ```
74
93
 
75
- ## File di Configurazione
94
+ ## File di configurazione
76
95
 
77
- Crea un `registry-stats.config.json` nella root del progetto (o esegui `registry-stats --init`):
96
+ Create un file `registry-stats.config.json` nella directory principale del vostro progetto (oppure eseguite `registry-stats --init`):
78
97
 
79
98
  ```json
80
99
  {
@@ -95,91 +114,110 @@ Crea un `registry-stats.config.json` nella root del progetto (o esegui `registry
95
114
  }
96
115
  ```
97
116
 
98
- Esegui `registry-stats` senza argomenti per ottenere le statistiche di tutti i pacchetti configurati. Il CLI cerca il file di configurazione risalendo dalla directory corrente.
117
+ Eseguite `registry-stats` senza argomenti per ottenere le statistiche per tutti i pacchetti configurati. La CLI cerca il file di configurazione a partire dalla directory corrente.
118
+
119
+ La configurazione è disponibile anche tramite API programmatica:
120
+
121
+ ```typescript
122
+ import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';
123
+
124
+ const config = loadConfig(); // finds nearest config file, or null
125
+ const defaults = defaultConfig(); // returns default Config object
126
+ const template = starterConfig(); // returns starter JSON string
127
+ ```
99
128
 
100
- ## API Programmatica
129
+ ## API programmatica
101
130
 
102
131
  ```typescript
103
132
  import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
104
133
 
105
- // Registro singolo
134
+ // Single registry
106
135
  const npm = await stats('npm', 'express');
107
136
  const pypi = await stats('pypi', 'requests');
137
+ const nuget = await stats('nuget', 'Newtonsoft.Json');
138
+ const vscode = await stats('vscode', 'esbenp.prettier-vscode');
139
+ const docker = await stats('docker', 'library/node');
108
140
 
109
- // Tutti i registri (usa Promise.allSettled — non lancia mai errori)
141
+ // All registries at once (uses Promise.allSettled — never throws)
110
142
  const all = await stats.all('express');
111
143
 
112
- // In massa — più pacchetti, concorrenza limitata (predefinito: 5)
144
+ // Bulk — multiple packages, concurrency-limited (default: 5)
113
145
  const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);
114
146
 
115
- // Serie temporale (solo npm + pypi)
147
+ // Time series (npm + pypi only)
116
148
  const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');
117
149
 
118
- // Calcoli
119
- calc.total(daily); // totale download
120
- calc.avg(daily); // media giornaliera
150
+ // Calculations
151
+ calc.total(daily); // sum of all downloads
152
+ calc.avg(daily); // daily average
153
+ calc.groupTotals(calc.monthly(daily)); // { '2025-01': 134982, ... }
121
154
  calc.trend(daily); // { direction: 'up', changePercent: 8.3 }
122
- calc.movingAvg(daily, 7); // media mobile 7 giorni
123
- calc.popularity(daily); // punteggio 0-100 scala logaritmica
155
+ calc.movingAvg(daily, 7); // 7-day moving average
156
+ calc.popularity(daily); // 0-100 log-scale score
124
157
 
125
- // Formati di esportazione
126
- calc.toCSV(daily); // stringa CSV
127
- calc.toChartData(daily, 'express'); // { labels: [...], datasets: [...] }
158
+ // Export formats
159
+ calc.toCSV(daily); // "date,downloads\n2025-01-01,1234\n..."
160
+ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ label, data }] }
128
161
 
129
- // Confronto — stesso pacchetto tra registri
162
+ // Comparison — same package across registries
130
163
  const comparison = await stats.compare('express');
131
- await stats.compare('express', ['npm', 'pypi']);
164
+ // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
165
+ await stats.compare('express', ['npm', 'pypi']); // specific registries only
132
166
 
133
- // Cache (TTL 5 min, in memoria)
167
+ // Caching (5 min TTL, in-memory)
134
168
  const cache = createCache();
135
- await stats('npm', 'express', { cache });
169
+ await stats('npm', 'express', { cache }); // fetches
170
+ await stats('npm', 'express', { cache }); // cache hit
136
171
  ```
137
172
 
138
- ## Supporto Registri
173
+ ## Supporto per i registri
139
174
 
140
- | Registro | Formato pacchetto | Serie temporale | Dati disponibili |
141
- |----------|------------------|-----------------|-----------------|
142
- | `npm` | `express`, `@scope/pkg` | Sì (549 giorni) | lastDay, lastWeek, lastMonth |
143
- | `pypi` | `requests` | Sì (180 giorni) | lastDay, lastWeek, lastMonth, total |
144
- | `nuget` | `Newtonsoft.Json` | No | total |
145
- | `vscode` | `publisher.extension` | No | total (installazioni), rating, trends |
146
- | `docker` | `namespace/repo` | No | total (pull), stars |
175
+ | Registro | Formato del pacchetto | Serie temporali | Dati disponibili |
176
+ | ---------- | --------------- | ------------- | ---------------- |
177
+ | `npm` | `express`, `@scope/pkg` | Sì (549 giorni) | giorno precedente, settimana precedente, mese precedente |
178
+ | `pypi` | `requests` | Sì (180 giorni) | giorno precedente, settimana precedente, mese precedente, totale |
179
+ | `nuget` | `Newtonsoft.Json` | No | totale |
180
+ | `vscode` | `publisher.extension` | No | totale (installazioni), valutazione, tendenze |
181
+ | `docker` | `namespace/repo` | No | totale (download), stelle |
147
182
 
148
- ## Affidabilità Integrata
183
+ ## Affidabilità integrata
149
184
 
150
- - Retry automatico con backoff esponenziale su errori 429/5xx
185
+ - Tentativi automatici con backoff esponenziale in caso di errori 429/5xx
151
186
  - Rispetta le intestazioni `Retry-After`
152
- - Limitazione della concorrenza per richieste in massa
153
- - Cache TTL opzionale (estensibile — usa Redis/file tramite interfaccia `StatsCache`)
187
+ - Limitazione della concorrenza per richieste di massa
188
+ - Cache TTL opzionale (configurabile: potete fornire la vostra implementazione Redis/file tramite l'interfaccia `StatsCache`)
154
189
 
155
- ## Server REST API
190
+ ## Server API REST
156
191
 
157
- Esegui come microservizio o integra nel tuo server:
192
+ Eseguite come microservizio o integrate nel vostro server:
158
193
 
159
194
  ```bash
195
+ # CLI
160
196
  registry-stats serve --port 3000
161
197
  ```
162
198
 
163
199
  ```
164
- GET /stats/:package # tutti i registri
165
- GET /stats/:registry/:package # registro singolo
200
+ GET /stats/:package # all registries
201
+ GET /stats/:registry/:package # single registry
166
202
  GET /compare/:package?registries=npm,pypi
167
203
  GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
168
204
  ```
169
205
 
206
+ Utilizzo programmatica per server personalizzati o serverless:
207
+
170
208
  ```typescript
171
209
  import { createHandler, serve } from '@mcptoolshop/registry-stats';
172
210
 
173
- // Avvio rapido
211
+ // Option 1: Quick start
174
212
  serve({ port: 3000 });
175
213
 
176
- // Server personalizzato
214
+ // Option 2: Bring your own server
177
215
  import { createServer } from 'node:http';
178
216
  const handler = createHandler();
179
217
  createServer(handler).listen(3000);
180
218
  ```
181
219
 
182
- ## Registri Personalizzati
220
+ ## Registri personalizzati
183
221
 
184
222
  ```typescript
185
223
  import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
@@ -202,6 +240,18 @@ registerProvider(cargo);
202
240
  await stats('cargo', 'serde');
203
241
  ```
204
242
 
243
+ ## Sito web
244
+
245
+ Il sito web e la documentazione si trovano nella directory `site/`.
246
+
247
+ - Sviluppo: `npm run site:dev`
248
+ - Build: `npm run site:build`
249
+ - Anteprima: `npm run site:preview`
250
+
205
251
  ## Licenza
206
252
 
207
253
  MIT
254
+
255
+ ---
256
+
257
+ Creato da <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>