voxpelli / list-dependents

Lists all dependents of a project, using npm or ecosyste.ms

list-dependents

Lists all dependents of a project, using npm and ecosyste.ms

Usage

Simple

import { fetchEcosystemDependents } from 'list-dependents';

const result = fetchEcosystemDependents(name);

for await (const { downloads, name, pkg } of fetchEcosystemDependents('npm-run-all2')) {
  console.log(downloads, name, pkg.description);
}

Advanced

See examples/cli.js

API

fetchEcosystemDependents()

Uses the ecosyste.ms API to resolve packages of dependents

Syntax

fetchEcosystemDependents(name, [options]) => AsyncGenerator<EcosystemDependentsItem>

Arguments

• name – string The name of the package to do the lookup for
• options – EcosystemDependentsOptions – optional options

EcosystemDependentsOptions

• filter – (meta: EcosystemDependentsMeta) => boolean – function given EcosystemDependentsMeta and should return true for the package to be included
• logger – BunyanLite– a logger instance
• maxAge – number – the maximum age of latest release to uinclude
• maxPages – number – the maximum number of source pages to fetch (there are perPage items per page)
• minDownloadsLastMonth = 400 – number – the minimum amount of downloads needed to be returned
• perPage = 36 – number – how many items per page to lookup
• skipPkg – boolean – when set skips resolving package.json

Returns

An AsyncGenerator that yields EcosystemDependentsItem objects

fetchEcosystemPackage()

Uses the ecosyste.ms API to resolve a package

Syntax

fetchEcosystemPackage(name, [options]) => Promise<EcosystemDependentsItem|false|undefined>

Arguments

• name – string – The name of the package to do the lookup for
• options – PackageLookupOptions – optional options

PackageLookupOptions

• client – got – a client to use for HTTP requests
• ecosystemsClient – got – a client to use for HTTP requests to ecosyste.ms
• dependentOn – string – ensure the package depends on this module. Only works when package.json is fetched.
• filter – (meta: EcosystemDependentsMeta) => boolean – function given EcosystemDependentsMeta and should return true for the package to be included
• logger – BunyanLite– a logger instance
• skipPkg – boolean | (meta: EcosystemDependentsMeta) => boolean – when true skips resolving package.json
• userAgent – string – an additional more specific user agent to preceed the built in one in the User-Agent header of requests

Returns

A promise resolving to false if the package is actively excluded, undefined if it couldn't be resolved and else EcosystemDependentsItem

createPackageFetchQueue()

Returns a fetchEcosystemPackage equivalent that enforces a maximum concurrent fetches to npm + shares the back-off between all fetches, respecting the Retry-After response headers.

Syntax

const fetchPackage = createPackageFetchQueue([queueOptions]);
const package = await fetchPackage(name, [options]);

Arguments

• queueOptions – PackageFetchQueueOptions – optional options

PackageFetchQueueOptions

• client – got – a client to use for HTTP requests
• logger – BunyanLite– a logger instance
• userAgent – string – an additional more specific user agent to preceed the built in one in the User-Agent header of requests

Returns

A function equal to fetchEcosystemPackage except that the client, ecosystemClient, logger and userAgent is overriden by the values sent in when it was created

Types

DependentsMeta

export interface DependentsMeta {
  downloads: number;
  name: string;
}

DependentsItem

import type { NormalizedPackageJson } from 'read-pkg';

export interface DependentsItem extends DependentsMeta {
  pkg?: NormalizedPackageJson | undefined;
  targetVersion?: string | undefined,
}

EcosystemDependentsMeta

export interface EcosystemDependentsMeta extends DependentsMeta {
  dependentCount: number | undefined,
  firstRelease: string | undefined,
  latestRelease: string | undefined,
  latestVersion: string | undefined,
  repositoryUrl: string | undefined;
}

EcosystemDependentsItem

export interface EcosystemDependentsItem extends DependentsItem, EcosystemDependentsMeta {}

Similar modules

• dependents – uses npm-dependants together with the npm API and GitHub API to deliver a functionality similar to fetchEcosystemDependents() / fetchNpmDependents()
• list-installed – sister module to this module – similar API but resolves locally installed modules rather than remote dependents
• npm-dependants – similar in functionality to fetchNpmDependentList()