npms-io-client

A universal typed npms.io api client.

Uses cross-fetch to support both node and browser environments.

Installation

yarn add npms-io-client

npm install npms-io-client

API

• Search
• Suggestions
• Package
• Packages

Search

import { getSearch } from "npms-io-client";

getSearch({ terms: "chalk" }).then((result) => {
  console.log(result);
  // {
  //   total: 423,
  //   results: [{
  //     package: {
  //       name: 'chalk',
  //       scope: 'unscoped',
  //       version: '4.1.0',
  //       ...
  //     },
  //     ...
  //   ]
  // }
});

Types:

getSearch(query: SearchQuery, from?: number, size?: number) => Promise<SearchResponse>;

type SearchQuery = {
  terms?: string | string[];
} & SearchQueryQualifiers;

type SearchQueryQualifiers = {
  scope?: string;             // Filter by scope
  author?: string;            // Filter by author
  maintainer?: string;        // Filter by maintainer
  keywords?: string;          // Filter by keywords (Separate multiple keywords with commas. You may also exclude keywords e.g: -framework).
  deprecated?: boolean;       // Filter by deprecated / not deprecated
  unstable?: boolean;         // Filter by unstable (< 1.0.0) / stable (> 1.0.0)
  insecure?: boolean;         // Filter packages with vulnerabilities
  boostExact?: boolean;       // Boost exact matches. Defaults to true.
  scoreEffect?: number;       // Set the effect that package scores have for the final search score, defaults to 15.3
  qualityWeight?: number;     // Set the weight that quality has for the each package score, defaults to 1.95
  popularityWeight?: number;  // Set the weight that popularity has for the each package score, defaults to 3.3
  maintenanceWeight?: number; // Set the weight that the quality has for the each package score, defaults to 2.05
}

type SearchResponse = {
  total: number;
  results: SearchResult[];
}

type SearchResult = {
  package: Package;
  score: Score;
  searchScore: number;
}

Suggestions

import { getSuggestions } from "npms-io-client";

getSuggestions("chal").then((results) => {
  console.log(results);
  // [
  //   {
  //     package: {
  //       name: 'chalk',
  //       scope: 'unscoped',
  //       version: '4.1.0',
  //       ...
  //     }
  //   },
  //   ...
  // ]
})

Types:

getSuggestions(query: string, size?: number) => Promise<SuggestionsResponse>;

Package

import { getPackage } from "npms-io-client";

getPackage("chalk").then((result) => {
  console.log(result);
  // {
  //   "analyzedAt": "2020-08-03T09:35:15.248Z",
  //   "collected": { "metadata": { ... }, "npm": { ... }, ... },
  //   "evaluation": { "quality": { ... }, "popularity": { ... }, ... }
  //   "score": { "final": 0.966624747619474, "detail": { "quality": 0.9545507877497884, "popularity": 0.9437035852952291, ... } }
  // }
});

Types:

getPackage(name: string) => Promise<PackageResult>;

type PackageResult = {
  analyzedAt: string;
  collected: PackageCollected;
  evaluation: PackageEvaluation;
  score: Score;
}

Packages

import { getPackages } from "npms-io-client";

getPackages(["chalk", "react"]).then((results) => {
  console.log(results);
  // {
  //   chalk: {
  //     analyzedAt: '2020-08-03T09:35:15.248Z',
  //     collected: {
  //       metadata: { ... },
  //       npm: { ... },
  //       github: { ... },
  //       source: { ... }
  //     },
  //     evaluation: { quality: { ... }, popularity: { ... }, maintenance: { ... } },
  //     score: { final: 0.966624747619474, detail: { ... } }
  //   },
  //   react: {
  //     analyzedAt: '2020-08-28T11:38:05.049Z',
  //     collected: {
  //       metadata: { ... },
  //       npm: { ... },
  //       github: { ... },
  //       source: { ... }
  //     },
  //     evaluation: { quality: { ... }, popularity: { ... }, maintenance: { ... } },
  //     score: { final: 0.9387208252920034, detail: { ... } }
  //   }
  // }
});

Types:

getPackages(packages: string[]): Promise<PackagesResponse>;

type PackagesResponse = PackageResult[];

Dependencies

• cross-fetch: Universal WHATWG Fetch API for Node, Browsers and React Native
• stringify-json-object: Stringify and format a JSON object.
• url-join: Join urls and normalize as in path.join.

Dev Dependencies

• @bconnorwhite/bob: Bob builds and watches typescript projects.
• @types/url-join: TypeScript definitions for url-join

License

MIT