{"record":{"id":"899d4767bbc5aa05","repo":"jackwener/OpenCLI","slug":"npm-downloads","errorCode":null,"errorMessage":"npm downloads","messagePattern":"npm downloads","errorType":"exception","errorClass":"EmptyResultError","httpStatus":null,"severity":"warning","filePath":"clis/npm/downloads.js","lineNumber":50,"sourceCode":"    name: 'downloads',\n    access: 'read',\n    description: 'Daily download counts for an npm package over a window',\n    domain: 'api.npmjs.org',\n    strategy: Strategy.PUBLIC,\n    browser: false,\n    args: [\n        { name: 'name', positional: true, required: true, help: 'npm package name (e.g. \"react\", \"@vercel/og\")' },\n        { name: 'period', default: 'last-week', help: 'last-day / last-week / last-month / last-year, or YYYY-MM-DD:YYYY-MM-DD' },\n    ],\n    columns: ['rank', 'package', 'day', 'downloads'],\n    func: async (args) => {\n        const name = requirePackageName(args.name);\n        const period = requirePeriod(args.period);\n        const url = `${NPM_API}/downloads/range/${period}/${name}`;\n        const body = await npmFetch(url, `npm downloads ${name}`);\n        const days = Array.isArray(body?.downloads) ? body.downloads : [];\n        if (!days.length) {\n            throw new EmptyResultError('npm downloads', `npm has no download stats for \"${name}\" in window ${period}.`);\n        }\n        return days.map((row, i) => ({\n            rank: i + 1,\n            package: String(body.package ?? name),\n            day: String(row.day ?? ''),\n            downloads: row.downloads != null ? Number(row.downloads) : null,\n        }));\n    },\n});\n","sourceCodeStart":32,"sourceCodeEnd":60,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/npm/downloads.js#L32-L60","documentation":"Thrown by the `npm downloads` command when the npm downloads API (api.npmjs.org/downloads/range) responds successfully but returns an empty downloads array for the requested package and period. The library raises EmptyResultError instead of returning an empty list so callers get an explicit, labeled signal that the query produced no data.","triggerScenarios":"Calling the downloads command for a package with zero recorded downloads in the requested period (e.g. a brand-new, unpublished, or valid-but-obscure name), or a narrow range window before/after any downloads occurred. The HTTP call itself succeeds (2xx); this is a data-emptiness condition, not a network failure.","commonSituations":"Querying a package published minutes ago; typos like 'reacct' that are still valid name syntax; requesting a historical range from before the package existed; scoped names with wrong casing; low-traffic packages with no hits in 'last-day'.","solutions":["Verify the package name is spelled exactly as on npmjs.org and exists (check https://registry.npmjs.org/<name>).","Use a wider period such as 'last-month' or 'last-year' instead of 'last-day' or a narrow range.","If the package is brand new, wait until it accumulates downloads before querying.","In automation, treat EmptyResultError as 'no data in window' — skip or widen the window rather than retrying the identical query."],"exampleFix":"// before\ncli.run('npm downloads', { name: 'my-new-pkg', period: 'last-day' }); // EmptyResultError\n// after\nconst period = pkgPublishedRecently ? 'last-month' : 'last-week';\ntry {\n  await cli.run('npm downloads', { name: 'my-new-pkg', period });\n} catch (e) {\n  if (e.name === 'EmptyResultError') return { downloads: 0, note: 'no data in window' };\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"const name = (args.name ?? '').trim();\nif (!name) throw new Error('name is required');\nconst period = args.period ?? 'last-week';\n// emptiness cannot be proven pre-call; validate inputs and handle the empty case","typeGuard":"function hasDownloads(body) {\n  return !!body && Array.isArray(body.downloads) && body.downloads.length > 0;\n}","tryCatchPattern":"try {\n  return await npmDownloads({ name, period });\n} catch (e) {\n  if (e.name === 'EmptyResultError') return []; // or widen the period and retry once\n  throw e;\n}","preventionTips":["Validate the package exists via the registry before querying downloads.","Prefer wider periods (last-month/last-year) for new or low-traffic packages.","Treat EmptyResultError as a data condition, not a bug — skip or widen the window.","Cache known-good (name, period) pairs to avoid repeated empty queries."],"tags":["npm","empty-result","downloads-api","no-data"],"backgroundTag":"empty-result-set","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}