npm-registry

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.

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);

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

Remove header Authorization

const reg = new Registry()

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

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);

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";
}

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);
}

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}`);
}

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;
}

Return a Version class instance.

Get a given tag value.

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