diff --git a/README.md b/README.md index 7497775..77c193e 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,43 @@ # query-registry -[![Build status](https://img.shields.io/github/actions/workflow/status/velut/node-query-registry/main.yml?branch=main)](https://github.com/velut/node-query-registry/actions?query=workflow%3ACI) -[![Coverage](https://img.shields.io/codecov/c/gh/velut/node-query-registry)](https://codecov.io/gh/velut/node-query-registry) +[![Build status](https://img.shields.io/github/actions/workflow/status/velut/query-registry/main.yml?branch=main)](https://github.com/velut/query-registry/actions?query=workflow%3ACI) +[![Coverage](https://img.shields.io/codecov/c/gh/velut/query-registry)](https://codecov.io/gh/velut/query-registry) [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/query-registry) -![Language](https://img.shields.io/github/languages/top/velut/node-query-registry) +![Language](https://img.shields.io/github/languages/top/velut/query-registry) [![npm bundle size](https://img.shields.io/bundlephobia/min/query-registry)](https://bundlephobia.com/result?p=query-registry) [![npm](https://img.shields.io/npm/v/query-registry)](https://www.npmjs.com/package/query-registry) -[![License](https://img.shields.io/github/license/velut/node-query-registry)](https://github.com/velut/node-query-registry/blob/main/LICENSE) +[![License](https://img.shields.io/github/license/velut/query-registry)](https://github.com/velut/query-registry/blob/main/LICENSE) -This package exports several functions to query the [npm registry](https://www.npmjs.com) (or one of its mirrors) through one of its [endpoints](https://github.com/npm/registry/blob/master/docs/REGISTRY-API.md). +`query-registry` is an API wrapper for the [npm registry API](https://github.com/npm/registry/blob/master/docs/REGISTRY-API.md). ## Features - Provides functions to: - - Get registry metadata - - Get packuments (package documents) and their abbreviated form - - Get package manifests - - Get download counts (packages and registry) - - Search packages -- Usable in the browser -- Fully typed API and response data -- Supports mirrors of the npm registry -- Supports caching network requests -- Well documented and tested - -## API & Package Info + - Get registry metadata. + - Get registry public keys. + - Get packuments (package documents) with full package metadata. + - Get abbreviated packuments with installation data only. + - Get package manifests for each version of a package. + - Get download counts for the registry and for packages. + - Search packages by name and other specific criteria. +- Works in the browser. +- Validates registry responses with [zod](https://www.npmjs.com/package/zod). +- Automatically caches registry responses for a short time. +- Supports third-party npm-compatible registries. + +## Useful resources - [**Explore the API on jsDocs.io**](https://www.jsdocs.io/package/query-registry) - View package contents on [**unpkg**](https://unpkg.com/query-registry/) -- View repository on [**GitHub**](https://github.com/velut/node-query-registry) -- Read the changelog on [**GitHub**](https://github.com/velut/node-query-registry/blob/main/CHANGELOG.md) +- View repository on [**GitHub**](https://github.com/velut/query-registry) +- Read the changelog on [**GitHub**](https://github.com/velut/query-registry/blob/main/CHANGELOG.md) ## Install Using `npm`: ``` -npm i query-registry +npm add query-registry ``` Using `yarn`: @@ -45,92 +46,122 @@ Using `yarn`: yarn add query-registry ``` -## Usage Examples +Using `pnpm`: -Get the metadata for the npm registry: +``` +pnpm add query-registry +``` + +Using `bun`: + +``` +bun add query-registry +``` + +## Usage examples + +### Registry + +Get the metadata about the npm registry itself, if available: ```typescript import { getRegistryMetadata } from "query-registry"; -(async () => { - const metadata = await getRegistryMetadata(); - - // Output: 'registry' - console.log(metadata.db_name); -})(); +const metadata = await getRegistryMetadata(); ``` -Get the latest manifest for package `query-registry` from the npm registry: +Get the public signing keys for the npm registry: ```typescript -import { getPackageManifest } from "query-registry"; +import { getRegistrySigningKeys } from "query-registry"; -(async () => { - const manifest = await getPackageManifest({ name: "query-registry" }); - - // Output: 'query-registry' - console.log(manifest.name); -})(); +const { keys } = await getRegistrySigningKeys(); ``` -Get the abbreviated packument for package `query-registry` from the npm registry: +### Packuments (Package documents) + +Get the abbreviated packument containing only the necessary data to install the `react` package: ```typescript import { getAbbreviatedPackument } from "query-registry"; -(async () => { - const packument = await getAbbreviatedPackument({ name: "query-registry" }); +const abbrPackument = await getAbbreviatedPackument("react"); +``` + +Get the full packument containing all the data available about the `react` package: + +```typescript +import { getPackument } from "query-registry"; - // Output: 'query-registry' - console.log(packument.name); -})(); +const packument = await getPackument("react"); ``` -Get the weekly downloads for package `query-registry` from the npm registry: +### Package manifests + +Get the manifest containing the original `package.json` data plus additional registry metadata for the `latest` version of the `react` package: ```typescript -import { getPackageDownloads } from "query-registry"; +import { getPackageManifest } from "query-registry"; + +const manifest = await getPackageManifest("react"); +``` -(async () => { - const downloads = await getPackageDownloads({ name: "query-registry" }); +Get the manifest for `react@18.2.0` (semver version): - // Output: 'query-registry' - console.log(downloads.package); +```typescript +import { getPackageManifest } from "query-registry"; - // Output: 'number' - console.log(typeof downloads.downloads); -})(); +const manifest = await getPackageManifest("react", "18.2.0"); ``` -Get the search results for text query `query-registry` from the npm registry: +Get the manifest for `react@next` (distribution tag): + +```typescript +import { getPackageManifest } from "query-registry"; + +const manifest = await getPackageManifest("react", "next"); +``` + +### Search packages + +Search packages related to `react` (e.g., `react`, `react-dom`, ...): ```typescript import { searchPackages } from "query-registry"; -(async () => { - const results = await searchPackages({ - query: { text: "query-registry" }, - }); +const results = await searchPackages({ text: "react" }); +``` - // Output: 'query-registry' - console.log(results.objects[0].package.name); -})(); +### Download counts + +Get the total number of downloads for package `react` for the last month: + +```typescript +import { getPackageDownloads } from "query-registry"; + +const { downloads } = await getPackageDownloads("react", "last-month"); ``` -## Debug +There are also these other download counts functions available: `getBulkDailyPackageDownloads`, `getBulkPackageDownloads`, `getDailyPackageDownloads`, `getDailyRegistryDownloads` and `getPackageVersionsDownloads`. -Debug messages are available in non production environments when the `DEBUG` environment variable is set to `query-registry`: +### Cache -```bash -DEBUG="query-registry" +Clear the internal cache. + +```typescript +import { cache } from "query-registry"; + +cache.clear(); ``` -For more information, see the [debug package](https://www.npmjs.com/package/debug). +See the [quick-lru](https://www.npmjs.com/package/quick-lru) package for the cache API. ## License -MIT License +``` +MIT +``` -Copyright (c) 2021 Edoardo Scibona +Copyright (c) 2024 Edoardo Scibona -See LICENSE file. +See [LICENSE](./LICENSE) file.