README

npm-registry

MIT DEP size

API created to GET informations from the official NPM API registry.

⛔️ You may need to consider the following package before: pacote

Why ?

Retrieve complete informations (with no filtering).
Clean TypeScript definition

Requirements

Node.js v12 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @slimio/npm-registry
# or
$ yarn add @slimio/npm-registry

Usage example

const Registry = require("@slimio/npm-registry");

async function main() {
    const npmReg = new Registry();

    // Retrieve meta data
    const metaData = await npmReg.metaData();
    console.log(metaData);

    // Search a given package
    const pkg = await npmReg.package("@slimio/is");
    console.log(pkg.lastVersion);

    // Search full-text
    const results = await npmReg.search({
        text: "author:fraxken"
    });
    console.log(JSON.stringify(results, null, 2));
}
main().catch(console.error);

Env required for testing

NPM_TOKEN=
NPM_AUTH=

API

Registry API

API for Registry Instance.

new Registry(URL: string)

Create a new registry instance with a given URL (Registry root url). Is no value is provided, the default value will be the official NPM registry https://registry.npmjs.org.

const Registry = require("@slimio/npm-registry");
const { strictEqual } = require("assert");

const reg = new Registry();
strictEqual(reg.url, Registry.DEFAULT_URL);

metaData(): Promise< Registry.Meta >

API endpoint to get metadata of the given registry URL. Returned value is a Plain Object with all meta data.

interface Meta {
    db_name: string;
    doc_count: number;
    doc_del_count: number;
    update_seq: number;
    purge_seq: number;
    compact_running: boolean;
    disk_size: number;
    data_size: number;
    instance_start_time: string;
    disk_format_version: number;
    committed_update_seq: number;
}

Initialize header Authorization

const reg = new Registry()

reg.login("username:password");
// or
reg.login("token");
// use API

logout(auth: string): void

Remove header Authorization

const reg = new Registry()

reg.login("username:password");
// use API
reg.logout();

package(packageName: string, version?: string): Promise< Package >

Search a given package by his name (and optionally his version). It will return a new Package instance.

const reg = new Registry();

const ava = await reg.package("ava");
console.log(ava.lastVersion);
console.log(ava.versions);
console.log(ava.homepage);

// Retrieve a given version
const lastVer = ava.version(ava.lastVersion);
console.log(lastVer.dependencies);

userPackages(userName: string): Promise< UserPackages >

Find all packages for a given user. Returned value is a plain Object.

const reg = new Registry();

const fraxPackages = await reg.userPackages("fraxken");
console.log(JSON.stringify(fraxPackages, null, 2));

TypeScript definition for UserPackages:

interface UserPackages {
    [packageName: string]: "write" | "read";
}

search(options: SearchOptions): Promise< Registry.SearchResult >

Full-text search API. Please take a look at the official documentation.

Available Options:

interface SearchOptions {
    text: string;
    size?: number;
    from?: number;
    quality?: number;
    popularity?: number;
    maintenance?: number;
}

Usage example:

const reg = new Registry();

const { total, objects } = await reg.search({ text: "author:fraxken" });
if (total === 0) {
    console.log(`Total of packages retrieved: ${total}`);
}
for (const { package } of objects) {
    console.log(package.name);
}

membership(scope: string, auth?: string): Promise< Roster >

Get memberships of an organisation. Auth parameter is an optional HTTP Authorization header username:password.

If the organisation is private, you need to be logged to see memberships.

interface Roster {
    [username: string]: "developer" | "admin" | "owner"
}

Usage example:

const reg = new Registry();

const members = await reg.membership("npm");
for (const [username, role] of Object.entries(members)) {
    console.log(`${username}: ${role}`);
}

downloads(packageName: string, options?: DownloadOptions): Promise< DownloadPoint | DownloadRange >

Get npm downloads counts in a given range. Options is described by the following interface:

type Period = "last-day" | "last-week" | "last-month";
interface DownloadOptions {
    period?: Period;
    type?: "point" | "range";
}

Example, retrieve the downloads count for express in the last-month:

const { downloads } = await reg.downloads("express", { period: "last-month" });
console.log(downloads);

The returned value will depend on the type point or range. Default type is point.

Package API

API for Package class.

declare class Package {
    version(version: string): Version;
    tag(tagName: string): string;
    publishedAt(version: string): Date;

    public readme: {
        file: string;
        content: string;
    };
    public readonly id: string;
    public readonly rev: string;
    public readonly name: string;
    public readonly description: string;
    public readonly author: Registry.Human;
    public readonly maintainers: Registry.Human[];
    public readonly tags: string[];
    public readonly lastVersion: string;
    public readonly versions: string[];
    public readonly keywords: string[];
    public readonly createdAt: Date;
    public readonly updatedAt: Date;
    public readonly homepage: string;
    public readonly license: string;
    public readonly bugsURL: string;
}

version(version: string): Version

Return a Version class instance.

tag(tagName: string): string

Get a given tag value.

publishedAt(version: string): Date

Get the publication date of a given version.

const date = pkg.version(pkg.lastVersion);

Dependencies

Name	Refactoring	Security Risk	Usage
@slimio/is	Minor	Low	TBC
httpie	Minor	Low	TBC

License

MIT

Usage no npm install needed!